@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 |
---|---|
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
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 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.
Response.Status.Family
status families that will cause
cancellation of the LRApublic 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 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.