org.eclipse.microprofile.lra.annotation.ws.rs

Annotation Type LRA

@Inherited
 @Retention(value=RUNTIME)
 @Target(value={TYPE,METHOD})
public @interface LRA

An annotation for controlling the lifecycle of Long Running Actions (LRAs).

The annotation SHOULD be applied to JAX-RS annotated methods otherwise it MAY have no effect. The annotation determines whether or not the annotated method will run in the context of an LRA and controls whether or not:

• any incoming context should be suspended and if so if a new one should be started
• to start a new LRA
• to end any LRA context when the method ends
• to return a error status code without running the annotated method if there should have been an LRA context present on method entry
• to cancel the LRA context when the method returns particular HTTP status codes

Newly created LRAs are uniquely identified and the id is referred to as the LRA context. The context is passed around using a JAX-RS request/response header called "Long-Running-Action". The implementation (of the LRA specification) is expected to manage this context and the application developer is expected to declaratively control the creation, propagation and destruction of LRAs using this LRA annotation. When a JAX-RS resource method is invoked in the context of an LRA, any JAX-RS client requests that it performs will carry the same header so that the receiving resource knows that it is inside an LRA context. The behaviour may be overridden by manually setting the context header.

If an LRA is propagated to a resource that is not annotated with any particular LRA behaviour then the LRA will be suspended (ie the context will not be available to the resource). But if this resource then performs an outgoing JAX-RS request then the suspended LRA must be propagated on this second outgoing request. For example, suppose resource A starts an LRA and then performs a JAX-RS request to resource B which does not contain any LRA annotations. If resource B then performs a JAX-RS request to a third service, C say, which does contain LRA annotations then the LRA context started at A must be propagated to C (for example if C uses an annotation to join the LRA, then C must be enlisted in the LRA that was started at A).

Resource methods can access the LRA context id by inspecting the request headers using standard JAX-RS mechanisms, ie @Context or by injecting it via the JAX-RS HeaderParam annotation with value "Long-Running-Action". This may be useful, for example, for associating business work with an LRA.

Field Summary

Fields

Modifier and Type	Fields and Description
static String	LRA_HTTP_CONTEXT_HEADER When a JAX-RS invocation is made with an active LRA it is made available via an HTTP header field with the following name.
static String	LRA_HTTP_ENDED_CONTEXT_HEADER Header name holding the LRA context of an LRA that has finished - to be used in conjunction with the AfterLRA annotation.
static String	LRA_HTTP_PARENT_CONTEXT_HEADER When a JAX-RS invocation is made with an active LRA which is nested, the parent LRA is made available via an HTTP header field with the following name.
static String	LRA_HTTP_RECOVERY_HEADER the name of the HTTP header field that contains a recovery URI corresponding to a participant enlistment in an LRA.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
javax.ws.rs.core.Response.Status[]	cancelOn The cancelOn element can be set to indicate which HTTP response codes will cause the current LRA to cancel.
javax.ws.rs.core.Response.Status.Family[]	cancelOnFamily The cancelOnFamily element can be set to indicate which families of HTTP response codes will cause the current LRA to cancel.
boolean	end If the annotated method runs with an LRA context then this element determines whether or not it is closed when the method returns.
long	timeLimit If the annotated method runs with an LRA context then this element determines the period for which the LRA will remain valid.
ChronoUnit	timeUnit
LRA.Type	value The Type element of the LRA annotation indicates whether a resource method is to be executed within the context of an LRA.

Field Detail

LRA_HTTP_CONTEXT_HEADER

public static final String LRA_HTTP_CONTEXT_HEADER

When a JAX-RS invocation is made with an active LRA it is made available via an HTTP header field with the following name. The value contains the LRA id associated with the HTTP request/response and is of type URI.

LRA_HTTP_ENDED_CONTEXT_HEADER

public static final String LRA_HTTP_ENDED_CONTEXT_HEADER

Header name holding the LRA context of an LRA that has finished - to be used in conjunction with the AfterLRA annotation.

LRA_HTTP_PARENT_CONTEXT_HEADER

public static final String LRA_HTTP_PARENT_CONTEXT_HEADER

When a JAX-RS invocation is made with an active LRA which is nested, the parent LRA is made available via an HTTP header field with the following name. The value contains the parent LRA id associated with the HTTP request/response and is of type URI.

LRA_HTTP_RECOVERY_HEADER

public static final String LRA_HTTP_RECOVERY_HEADER

the name of the HTTP header field that contains a recovery URI corresponding to a participant enlistment in an LRA. The value is of type URI.

Element Detail

value

public abstract LRA.Type value

The Type element of the LRA annotation indicates whether a resource method is to be executed within the context of an LRA.

If the method is to run in the context of an LRA and the annotated class also contains a method annotated with Compensate then the resource will be enlisted with the LRA. Enlisting with an LRA means that the resource MUST be notified when the current LRA is later cancelled. The resource can also receive notifications when the LRA is closed if it additionally defines a method annotated with Complete. The specification does not mandate when these notifications are issued but it does guarantee that they will eventually be sent. Under failure conditions the system will keep retrying until it is certain that all participants have been successfully notified.

If the method is to run in the context of an LRA and the annotated class also contains a method annotated with AfterLRA then the resource will be notified of the final state of the LRA.

The element values LRA.Type.REQUIRED and LRA.Type.REQUIRES_NEW can start new LRAs.

If the method does run in the context of an LRA then the application can control whether or not it is closed when the method returns using the end() element.

When an LRA is present its identifier is made available to the business logic in the JAX-RS request and response headers with the name "Long-Running-Action" of type URI.

Returns:

the type of behaviour expected when the annotated method is executed.

Default:

org.eclipse.microprofile.lra.annotation.ws.rs.LRA.Type.REQUIRED

timeLimit

public abstract long timeLimit

If the annotated method runs with an LRA context then this element determines the period for which the LRA will remain valid. When this period has elapsed the LRA becomes eligible for cancellation. The units are specified in the timeUnit() element. A value of zero indicates that the LRA will always remain valid.

Methods running with an active LRA context must be resilient to it being cancelled while the method is still executing.

Returns:

the period for which the LRA is guaranteed to run for before becoming eligible for cancellation.

Default:

0L

timeUnit

public abstract ChronoUnit timeUnit

Returns:

the unit of time that the timeLimit() element is measured in.

Default:

java.time.temporal.ChronoUnit.SECONDS

end

public abstract boolean end

If the annotated method runs with an LRA context then this element determines whether or not it is closed when the method returns. If the element has the value true then the LRA will be ended and all participants that have the @Complete annotation MUST eventually be asked to complete. If the element has the value false then the LRA will not be ended when the method finishes.

If the end value is set to false but the annotated method finishes with a status code that matches any of the values specified in the cancelOn() or cancelOnFamily() elements then the LRA will be cancelled. In other words the cancelOn() and cancelOnFamily() elements take precedence over the end element.

Returns:

true if an LRA that was active when the method ran should be closed when the method execution finishes.

Default:

true

cancelOnFamily

public abstract javax.ws.rs.core.Response.Status.Family[] cancelOnFamily

The cancelOnFamily element can be set to indicate which families of HTTP response codes will cause the current LRA to cancel. If the LRA has already been closed when the annotated method returns then this element is silently ignored, Cancelling an LRA means that all participants will eventually be asked to compensate (by having their @Compensate annotated method invoked).

If a JAX-RS method is annotated with this element and the method returns a response code which matches any of the specified families then the LRA will be cancelled. The method can return status codes in a Response or via a JAX-RS exception mappper.

Returns:

the Response.Status.Family status families that will cause cancellation of the LRA

Default:

{javax.ws.rs.core.Response.Status.Family.CLIENT_ERROR, javax.ws.rs.core.Response.Status.Family.SERVER_ERROR}

cancelOn

public abstract javax.ws.rs.core.Response.Status[] cancelOn

The cancelOn element can be set to indicate which HTTP response codes will cause the current LRA to cancel. If the LRA has already been closed when the annotated method returns then this element is silently ignored, Cancelling an LRA means that all participants will eventually be asked to compensate (by having their @Compensate annotated method invoked).

If a JAX-RS method is annotated with this element and the method returns a response code which matches any of the specified status codes then the LRA will be cancelled. The method can return status codes in a Response or via an exception mappper.

Returns:

the Response.Status HTTP status codes that will cause cancellation of the LRA

Default:

{}