_javadoc

Marks JAX-RS method which should run in LRA context and needs to be accompanied by at least minimal set of mandatory participant methods(Compensate or AfterLRA).

LRA options:

• value

  • REQUIRED join incoming LRA or create and join new

  • REQUIRES_NEW create and join new LRA

  • MANDATORY join incoming LRA or fail

  • SUPPORTS join incoming LRA or continue outside LRA context

  • NOT_SUPPORTED always continue outside LRA context

  • NEVER Fail with 412 if executed in LRA context

  • NESTED create and join new LRA nested in the incoming LRA context

• timeLimit max time limit before LRA gets cancelled automatically by coordinator

• timeUnit time unit if the timeLimit value

• end when false LRA is not closed after successful method execution

• cancelOn which HTTP response codes of the method causes LRA to cancel

• cancelOnFamily which family of HTTP response codes causes LRA to cancel

Method parameters:

• Header LRA_HTTP_CONTEXT_HEADER - id of the LRA transaction

@PUT
@LRA(LRA.Type.REQUIRES_NEW, timeLimit = 500, timeUnit = ChronoUnit.MILLIS)
@Path("start-example")
public Response startLra(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId, String data)

_javadoc

Compensate method is called by coordinator when LRA is cancelled, usually by error during execution of method body of @LRA annotated method. If the method responds with 500 or 202, coordinator will eventually try the call again. If participant has @Status annotated method, coordinator retrieves the status to find out if retry should be done.

JAX-RS variant with supported LRA context values:

@PUT
@Path("/compensate")
@Compensate
public Response compensateWork(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
                               @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parent){
    return LRAResponse.compensated();
}

Non JAX-RS variant with supported LRA context values:

@Compensate
public void compensate(URI lraId)

_javadoc

Complete method is called by coordinator when LRA is successfully closed. If the method responds with 500 or 202, coordinator will eventually try the call again. If participant has @Status annotated method, coordinator retrieves the status to find out if retry should be done.

JAX-RS variant with supported LRA context values:

@PUT
@Path("/complete")
@Complete
public Response complete(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
                         @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parentLraId)

Non JAX-RS variant with supported LRA context values:

@Complete
public void complete(URI lraId)

_javadoc

Complete and compensate methods can fail(500) or report that compensation/completion is in progress(202). In such case participant needs to be prepared to report its status over @Status annotated method to coordinator. When coordinator decides all the participants have finished, method annotated with @Forget is called.

JAX-RS variant with supported LRA context values:

@DELETE
@Path("/forget")
@Forget
public Response forget(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
                       @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parent)

Non JAX-RS variant with supported LRA context values:

@Forget
public void forget(URI lraId)
}

_javadoc

Method annotated with @Leave called with LRA context(with header LRA_HTTP_CONTEXT_HEADER) informs coordinator that current participant is leaving the LRA. Method body is executed after leave signal is sent. As a result, participant methods complete and compensate won’t be called when the particular LRA ends.

• Header LRA_HTTP_CONTEXT_HEADER - id of the LRA transaction

@PUT
@Path("/leave")
@Leave
public Response leaveLRA(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraIdtoLeave)

_javadoc

If the coordinator’s call to the particpant’s method fails, then it will retry the call. If the participant is not idempotent, then it may need to report its state to coordinator by declaring method annotated with @Status for reporting if previous call did change participant status. Coordinator can call it and decide if compensate or complete retry is needed.

JAX-RS variant with supported LRA context values:

@GET
@Path("/status")
@Status
public Response reportStatus(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId) {
    return Response.status(ParticipantStatus.FailedToCompensate).build();
}

Non JAX-RS variant with supported LRA context values:

@Status
public Response reportStatus(URI lraId){
    return Response.ok(ParticipantStatus.FailedToCompensate).build();
}

_javadoc

Method annotated with @AfterLRA in the same class as the one with @LRA annotation gets invoked after particular LRA finishes.

JAX-RS variant with supported LRA context values:

@PUT
@Path("/finished")
@AfterLRA
public Response whenLRAFinishes(@HeaderParam(LRA_HTTP_ENDED_CONTEXT_HEADER) URI lraId,
                                @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parentLraId,
                                LRAStatus status)

Non JAX-RS variant with supported LRA context values:

public void whenLRAFinishes(URI lraId, LRAStatus status)