@Retention(RUNTIME) @Target(METHOD) public @interface Complete

If a resource method executes in the context of an LRA and if the containing class has a method annotated with @Complete (as well as method annotated with @Compensate) then this Complete method will be invoked if the LRA is closed. The resource should attempt to perform any clean up activities relating to any actions it performed in the context of the LRA. If the annotation is present on more than one method then an arbitrary one will be chosen. The LRA specification makes no guarantees about when the Complete method will be invoked, just that it will eventually be called.

In the case where the ability to complete the Long Running Action is time bounded, you can limit the lifespan of the Long Running action by providing values for the LRA.timeLimit() and LRA.timeUnit() timeUnit} attributes. When the time limit is reached the LRA becomes eligible for automatic cancellation.

If the annotation is applied to a JAX-RS resource method then the request method MUST be PUT. The id 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 the header value will be of type URI.

If the annotated method is not a JAX-RS resource method then the id of the currently running LRA and its parent LRA (if it is nested) can be obtained by adhering to predefined method signatures as defined in the LRA specification document. For example,

     
        @Complete
        public void complete(URI lraId, URI parentId) { ...}

would be a valid completion 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 cannot complete immediately then it must report that completion is in progress by either returning a future (such as CompletionStage) which will eventually report one of the final states, or a 202 Accepted JAX-RS response code or, in the case of non JAX-RS resource methods, by returning ParticipantStatus.Completing (see the specification document for more details).

Note that according to the state model defined by LRAStatus, it is not possible to receive completion notifications after an LRA has been asked to close. Therefore combining this annotation with an @LRA annotation that does not start a new LRA will result in a 412 PreCondition Failed JAX-RS response code. On the other hand, combining it with an @LRA annotation that begins a new LRA can in certain use cases make sense, but in this case the LRA that this method is being asked to complete for will be unavailable.

If the method is a JAX-RS resource method (or is a non JAX-RS method annotated with @Complete with return type jakarta.ws.rs.core.Response) then the following are the only valid response codes:

JAX-RS Completion Response Codes
Code	Response Body	Meaning
200	Empty	The resource has successfully completed
202	Empty	The resource is still attempting completion
409	`ParticipantStatus` enum value	The resource has failed to complete. The payload contains the reason for the failure. A participant MUST remember this state until its `Forget` method is called. The actual value is not important but it MUST correspond to a valid `ParticipantStatus` enum value. For example, if completion was not possible because the resource already compensated (without being asked to) then a value such as `ParticipantStatus.Compensated` would be appropriate or if it was due to a generic failure then `ParticipantStatus.FailedToComplete` would be valid. If the response body does not contain a valid status then the implementation MUST either reinvoke the method or discover the status using the `Status` annotation if present. Note that the actual state as reported by the `Status` method MUST be `ParticipantStatus.FailedToComplete`
410	Empty	The resource 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 Complete method as a result of the LRA being closed and the participant returns the code 410, the implementation assumes that the action is completed and participant returns a 410 since participant is allowed to forget about an action which is completely handled by the participant.

If any other code is returned (or, in the 409 case, the body does not correspond to a valid state) then the implementation SHOULD either keep retrying or attempt to discover the status by calling the Status method if present or a combination of both. If the implementation stops retrying then it SHOULD log a warning. An example scenario where the implementation might attempt to invoke the complete method twice and the status method is as follows:

The implementation invokes the complete method via JAX-RS.
The JAX-RS server returns a 500 code (i.e., the notification does not reach the participant).
If there is a status method then the implementation uses that to get the current state of the participant. If the status is Active then the implementation may infer that the original request never reached the participant so it is safe to reinvoke the complete method.

Annotation Type Complete