@Inherited @Retention(value=RUNTIME) @Target(value={TYPE,METHOD}) public @interface LRA
An annotation for controlling the lifecycle of Long Running Actions (LRAs).
This annotation MUST be combined with either the Compensate
or the AfterLRA
annotated methods in the
same bean class otherwise the deployment will be rejected.
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:
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 behavior, then the MicroProfile
Config value mp.lra.propagation.active
determines how the LRA is propagated. The default of this
parameter is true
which means that the LRA will be propagated to outgoing requests. 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.
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
The 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 an implementation of the LRA specification invokes any of the participant callbacks (namely
Compensate , Complete , Status , Forget , and AfterLRA ) in the context of a
nested LRA it must ensure that 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.
|
Modifier and Type | Optional Element and Description |
---|---|
jakarta.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.
|
jakarta.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
LRA.Type element of the LRA annotation indicates whether a resource method is to be executed within the
context of an LRA. |
public static final String LRA_HTTP_PARENT_CONTEXT_HEADER
Compensate
, Complete
, Status
, Forget
, and AfterLRA
) in the context of a
nested LRA it must ensure that the parent LRA is made available via an HTTP header field with the following name.
The value contains the parent LRA context associated with the HTTP request/response and it is of type
URI
.public abstract LRA.Type value
The LRA.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 also 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 runs in the context of an LRA then the application can control whether or not it is closed when the
method finishes 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
.
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.
public abstract ChronoUnit timeUnit
timeLimit()
element is measured in.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.
public abstract jakarta.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.
Response.Status.Family
status families that will cause cancellation of the
LRApublic abstract jakarta.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 a JAX-RS exception mappper.
Response.Status
HTTP status codes that will cause cancellation of the LRACopyright © 2018 – 2021 Eclipse Foundation. All rights reserved.
Use is subject to license terms.