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

Annotation Interface 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
    Response.Status[]
    cancelOn
    The cancelOn element can be set to indicate which HTTP response codes will cause the current LRA to cancel.
    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:

    • 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:

    • 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:

    • 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:

  • 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

      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

      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:
      {}