Package org.eclipse.microprofile.lra.annotation

# Annotation Type Status

@Retention(RUNTIME) @Target(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.