Action Semantics

The semantics() element describes whether the invocation modifies state of the system, and if so whether it does so idempotently. If the action invocation does not modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.

The semantics element was originally introduced for the RestfulObjects viewer in order that action invocations could be using the appropriate HTTP verb (GET, PUT and POST).

The table below summarizes the semantics:

Semantic Changes state Effect of multiple calls HTTP verb
(Restful Objects)

SAFE_AND_REQUEST_CACHEABLE

No

Will always return the same result each time invoked (within a given request scope)

GET

SAFE

No

Might result in different results each invocation

GET

IDEMPOTENT
IDEMPOTENT_ARE_YOU_SURE

Yes

Will make no further changes if called multiple times (eg sets a property or adds to a Set).
The "are you sure" variant requires that the user must explicitly confirm the action.

PUT

NON_IDEMPOTENT
NON_IDEMPOTENT_ARE_YOU_SURE

Yes

Might change the state of the system each time called (eg increments a counter or adds to a List).
The "are you sure" variant requires that the user must explicitly confirm the action.

POST

The actions' semantics are also used by the core runtime as part of the in-built concurrency checkng; invocation of a safe action (which includes request-cacheable) does not perform a concurrency check, whereas non-safe actions do perform a concurrency check.

For example:

public class Customer {

    @Action(semantics=SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)
    public CreditRating checkCredit() {
        // ...
    }

    @Action(semantics=SemanticsOf.IDEMPOTENT)
    public void changeOfAddress(Address address) {
        // ...
    }

    @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
    public Order placeNewOrder() {
        // ...
    }

    // ...
}

Actions that are safe and request-cacheable automatically use the QueryResultsCache service to cache the result of the method. Note though that the results of this caching will only be apparent if the action is invoked from another method using the WrapperFactory service.