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

# Annotation Type LRA

@Inherited @Retention(RUNTIME) @Target({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:

- 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 an error status code without running the annotated method if there should have been an LRA context present on the method entry
- to cancel the LRA context when the method returns particular HTTP status codes

Some of the above defined LRA operations are performed before the execution proceeds to the LRA annotated business method. If any of these LRA operations cannot complete the implementation MUST return one of the defined HTTP status codes which means that the business method is not invoked. For the definition of the allowed status codes and condition in which they are returned please see the specification document.

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.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`LRA.Type`

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
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.

## Field Summary

Fields
Modifier and Type
Field
Description
`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.
`static final 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 final 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 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.

## Field Details

### LRA_HTTP_CONTEXT_HEADER

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 it is of type `URI`.

See Also:
  - Constant Field Values

### LRA_HTTP_ENDED_CONTEXT_HEADER

static final 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.

See Also:
  - Constant Field Values

### LRA_HTTP_PARENT_CONTEXT_HEADER

static final 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. The value contains the parent LRA context associated with the HTTP request/response and it is of type `URI`.

See Also:
  - Constant Field Values

### LRA_HTTP_RECOVERY_HEADER

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`.

See Also:
  - Constant Field Values

## Element Details

### value

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`.

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

Default:
  REQUIRED

### timeLimit

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

ChronoUnit timeUnit

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

Default:
  SECONDS

### end

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

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.

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

Default:
  {CLIENT_ERROR, SERVER_ERROR}

### cancelOn

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.

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

Default:
  {}