Status (MicroProfile LRA API)

@Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface Status

The LRA specification supports distributed communications amongst software components and due to the unreliable nature of networks, messages/requests can be lost, delayed, duplicated, etc., so the implementation component responsible for invoking Compensate and Complete annotated methods may lose track of the status of a participant. In this case, ideally it would just resend the completion or compensation notification but if the participant (the class that contains the Compensate and Complete annotations) does not support idempotency then it must be able to report its status by by annotating one of the methods with this @Status annotation. The annotated method should report the status according to one of the ParticipantStatus enum values.

If the annotation is applied to a JAX-RS resource method then the request method MUST be GET. The context of the currently running LRA can be obtained by inspecting the incoming JAX-RS headers. If this LRA is nested then the parent LRA MUST be present in the header with the name LRA.LRA_HTTP_PARENT_CONTEXT_HEADER and value is of type URI.

If the annotated method is not a JAX-RS resource method, the context of the currently running LRA can be obtained by adhering to a predefined method signature as defined in the LRA specification document. Similarly the method may determine whether or not it runs with a nested LRA by providing a parameter to hold the parent context. For example,

     
          @Status
          public void status(URI lraId, URI parentId) { ...}

would be a valid status method declaration. If an invalid signature is detected the implementation of this specification MUST prohibit successful startup of the application (e.g., with a runtime exception).

If the participant has already responded successfully to an invocation of the Compensate or Complete method then it may report 410 Gone HTTP status code or in case of non-JAX-RS method returning ParticipantStatus to return null.

Since the participant generally needs to know the id of the LRA in order to report its status there is generally no benefit to combining this annotation with the @LRA annotation (though it is not prohibited).

If the method is a JAX-RS resource method (or is a non JAX-RS method annotated with @Status with return type Response) then the following are the only valid response codes:

JAX-RS Response Codes For Status Methods
Code	Response Body	Meaning
200	`ParticipantStatus` enum value	The current status of the participant
202	Empty	The resource is attempting to determine the status and the caller should retry later
410	Empty	The method does not know about the LRA

The implementation will handle the return code 410 in the same way as the return code 200. Specifically, when the implementation calls the Status method after it has called the Complete or Compensated method and received a response which indicates that the process is in progress (with a return code 202, for example). The response code 410 which is received when calling this Status annotated method, MUST be interpreted by the implementation that the process is successfully completed and the participant already forgot about the LRA.

Annotation Type Status