@Retention(value=RUNTIME) @Target(value=METHOD) public @interface Compensate
If a resource method executes in the context of an LRA and if the containing
class has a method annotated with @Compensate
then this
method will be invoked if the LRA is cancelled. The resource should attempt to
compensate for 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
Compensate method will be invoked, just that it will eventually be called.
In the case where the ability to compensate 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()
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 LRA 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 the header value will be of type URI
.
If the annotated method is not a JAX-RS resource method then the LRA context 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,
@Compensate
public void compensate(URI lraId, URI parentId) { ...}
would be a valid compensation 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 compensate immediately then it must report that the
compensation request was received and that the compensation 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.Compensating
(see the specification
document for more details).
Note that according to the state model defined by LRAStatus
, it is not possible
to receive compensation notifications after an LRA has been asked to cancel.
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 compensate for will be unavailable.
If the method is a JAX-RS resource method (or is a non JAX-RS method
annotated with @Compensate
with return type
javax.ws.rs.core.Response
) then the following are the only
valid response codes:
Code | Response Body | Meaning |
---|---|---|
200 | Empty | The resource has successfully compensated |
202 | Empty | The resource is still attempting compensation |
409 | ParticipantStatus enum value |
The resource has failed to compensate.
The payload contains the reason for the failure.
A participant MUST remember this state until its
The actual value is not important but it MUST
correspond to a valid
Note that the
actual state as reported by the |
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 Compensate method as a result of the LRA being cancelled and the participant returns the code 410, the implementation assumes that the action is compensated and the participant returned 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
compensate method twice and the status method is as follows:
Copyright © 2018 – 2021 Eclipse Foundation. All rights reserved.
Use is subject to license terms.