org.eclipse.microprofile.lra.client

Interface LRAClient

public interface LRAClient

Field Summary

Fields

Modifier and Type	Field and Description
static String	LRA_COORDINATOR_HOST_KEY Key for looking up the config property that specifies which host a coordinator is running on
static String	LRA_COORDINATOR_PATH_KEY Key for looking up the config property that specifies which JAX-RS path a coordinator is running on
static String	LRA_COORDINATOR_PORT_KEY Key for looking up the config property that specifies which port a coordinator is running on
static String	LRA_HTTP_HEADER the name of the HTTP header field that contains the LRA id associated with a request/response
static String	LRA_HTTP_RECOVERY_HEADER the name of the HTTP header field that contains a recovery URL corresponding to a participant enlistment in an LRA updateCompensator(java.net.URL, java.net.URL, java.net.URL, java.net.URL, java.net.URL, java.lang.String)
static String	LRA_RECOVERY_HOST_KEY Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on
static String	LRA_RECOVERY_PATH_KEY Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on
static String	LRA_RECOVERY_PORT_KEY Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on

Method Summary

Modifier and Type	Method and Description
String	cancelLRA(URL lraId) Attempt to cancel an LRA Trigger compensation of all participants enlisted with the LRA (ie the compensate message will be sent to each participant).
void	close() Explicitly dispose of all resources.
String	closeLRA(URL lraId) Attempt to close an LRA Tells the LRA to close normally.
List<LRAInfo>	getActiveLRAs() Lookup active LRAs
List<LRAInfo>	getAllLRAs() Returns all (both active and recovering) LRAs
URL	getCurrent() checks whether there is an LRA associated with the calling thread (this method provides an alternative to relying on the presence of the LRA_HTTP_HEADER HTTP header fields since not all users of the API are being called in the context of JAX-RS resource requests).
List<LRAInfo>	getRecoveringLRAs() List recovering Long Running Actions
Optional<CompensatorStatus>	getStatus(URL lraId) Lookup the status of an LRA
Boolean	isActiveLRA(URL lraId) Indicates whether an LRA is active.
Boolean	isCompensatedLRA(URL lraId) Indicates whether an LRA was compensated.
Boolean	isCompletedLRA(URL lraId) Indicates whether an LRA is complete.
String	joinLRA(URL lraId, Class<?> resourceClass, URI baseUri, String compensatorData) Join an LRA passing in a class that will act as the participant.
String	joinLRA(URL lraId, Long timelimit, URL compensateUrl, URL completeUrl, URL forgetUrl, URL leaveUrl, URL statusUrl, String compensatorData) A participant can join with the LRA at any time prior to the completion of an activity.
void	leaveLRA(URL lraId, String body) A Compensator can resign from the LRA at any time prior to the completion of an activity
void	renewTimeLimit(URL lraId, long limit, TimeUnit unit) LRAs can be created with timeouts after which they are cancelled.
void	setCoordinatorURI(URI uri) Set the endpoint on which the coordinator is available
void	setCurrentLRA(URL lraId) Update the clients notion of the current coordinator.
void	setRecoveryCoordinatorURI(URI uri) Set the endpoint on which the recovery coordinator is available
URL	startLRA(String clientID, Long timeout, TimeUnit unit) Start a top level LRA (ie similar to startLRA(URL, String, Long, TimeUnit)
URL	startLRA(URL parentLRA, String clientID, Long timeout, TimeUnit unit) Start a new LRA If the LRA was started during a JAX-RS resource method invocation then the id of the new LRA will be made available as the JAX-RS response header LRA_HTTP_HEADER
URL	updateCompensator(URL recoveryUrl, URL compensateUrl, URL completeUrl, URL forgetUrl, URL statusUrl, String compensatorData) Change the endpoints that a participant can be contacted on.

Field Detail

LRA_HTTP_HEADER

static final String LRA_HTTP_HEADER

the name of the HTTP header field that contains the LRA id associated with a request/response

See Also:

Constant Field Values

LRA_HTTP_RECOVERY_HEADER

static final String LRA_HTTP_RECOVERY_HEADER

the name of the HTTP header field that contains a recovery URL corresponding to a participant enlistment in an LRA updateCompensator(java.net.URL, java.net.URL, java.net.URL, java.net.URL, java.net.URL, java.lang.String)

See Also:

Constant Field Values

LRA_COORDINATOR_HOST_KEY

static final String LRA_COORDINATOR_HOST_KEY

Key for looking up the config property that specifies which host a coordinator is running on

See Also:

Constant Field Values

LRA_COORDINATOR_PORT_KEY

static final String LRA_COORDINATOR_PORT_KEY

Key for looking up the config property that specifies which port a coordinator is running on

See Also:

Constant Field Values

LRA_COORDINATOR_PATH_KEY

static final String LRA_COORDINATOR_PATH_KEY

Key for looking up the config property that specifies which JAX-RS path a coordinator is running on

See Also:

Constant Field Values

LRA_RECOVERY_HOST_KEY

static final String LRA_RECOVERY_HOST_KEY

Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on

See Also:

Constant Field Values

LRA_RECOVERY_PORT_KEY

static final String LRA_RECOVERY_PORT_KEY

Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on

See Also:

Constant Field Values

LRA_RECOVERY_PATH_KEY

static final String LRA_RECOVERY_PATH_KEY

Key for looking up the config property that specifies which JAX-RS path a recovery coordinator is running on

See Also:

Constant Field Values

Method Detail

setCoordinatorURI

void setCoordinatorURI(URI uri)

Set the endpoint on which the coordinator is available

Parameters:

uri - the url of the LRA coordinator

setRecoveryCoordinatorURI

void setRecoveryCoordinatorURI(URI uri)

Set the endpoint on which the recovery coordinator is available

Parameters:

uri - the url of the LRA recovery coordinator

close

void close()

Explicitly dispose of all resources. After this call the instance may no longer be useable

startLRA

URL startLRA(URL parentLRA,
             String clientID,
             Long timeout,
             TimeUnit unit)
      throws GenericLRAException

Start a new LRA If the LRA was started during a JAX-RS resource method invocation then the id of the new LRA will be made available as the JAX-RS response header LRA_HTTP_HEADER

Parameters:

parentLRA - The parent of the LRA that is about to start. If null then the new LRA will be top level

clientID - The client may provide a (preferably) unique identity which will be reported back when the LRA is queried.

timeout - Specifies the maximum time that the LRA will exist for. If the LRA is terminated because of a timeout it will be cancelled.

unit - Specifies the unit that the timeout is measured in

Returns:

the identifier of the new LRA

Throws:

javax.ws.rs.NotFoundException - if the parent LRA is known to no longer exist

GenericLRAException - a new LRA could not be started. The specific reason is available in GenericLRAException.getStatusCode()

startLRA

URL startLRA(String clientID,
             Long timeout,
             TimeUnit unit)
      throws GenericLRAException

Start a top level LRA (ie similar to startLRA(URL, String, Long, TimeUnit)

Parameters:

clientID - The client may provide a (preferably) unique identity which will be reported back when the LRA is queried.

timeout - Specifies the maximum time that the LRA will exist for. If the LRA is terminated because of a timeout it will be cancelled.

unit - Specifies the unit that the timeout is measured in

Returns:

the identifier of the new LRA

Throws:

javax.ws.rs.NotFoundException - if the parent LRA is known to no longer exist

GenericLRAException - a new LRA could not be started. The specific reason is available in GenericLRAException.getStatusCode()

cancelLRA

String cancelLRA(URL lraId)
          throws GenericLRAException

Attempt to cancel an LRA Trigger compensation of all participants enlisted with the LRA (ie the compensate message will be sent to each participant).

Parameters:

lraId - The unique identifier of the LRA (required) Enum.name(). If the final status is not returned the client can still discover the final state using the getStatus(URL) method

Returns:

the response MAY contain the final status of the LRA as reported by

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - Communication error (the reason is availalbe via the GenericLRAException.getStatusCode() method

closeLRA

String closeLRA(URL lraId)
         throws GenericLRAException

Attempt to close an LRA Tells the LRA to close normally. All participants will be triggered by the coordinator (ie the complete message will be sent to each participant).

Parameters:

lraId - The unique identifier of the LRA (required) Enum.name(). If the final status is not returned the client can still discover the final state using the getStatus(URL) method

Returns:

the response MAY contain the final status of the LRA as reported by

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - Communication error (the reason is availalbe via the GenericLRAException.getStatusCode() method

getActiveLRAs

List<LRAInfo> getActiveLRAs()
                     throws GenericLRAException

Lookup active LRAs

Returns:

a list of active LRAs

Throws:

GenericLRAException - on error

getAllLRAs

List<LRAInfo> getAllLRAs()
                  throws GenericLRAException

Returns all (both active and recovering) LRAs

Returns:

a list of all LRAs known to this coordinator

Throws:

GenericLRAException - on error

getRecoveringLRAs

List<LRAInfo> getRecoveringLRAs()
                         throws GenericLRAException

List recovering Long Running Actions

Returns:

LRAs that are recovering (ie the participant is still attempting to complete or compensate

Throws:

GenericLRAException - on error

getStatus

Optional<CompensatorStatus> getStatus(URL lraId)
                               throws GenericLRAException

Lookup the status of an LRA

Parameters:

lraId - the LRA whose status is being requested

Returns:

the status or empty if the the LRA is still active (ie has not yet been closed or cancelled)

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

isActiveLRA

Boolean isActiveLRA(URL lraId)
             throws GenericLRAException

Indicates whether an LRA is active. The same information can be obtained via a call to getStatus(URL).

Parameters:

lraId - The unique identifier of the LRA (required)

Returns:

whether or not the specified LRA is active

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

isCompensatedLRA

Boolean isCompensatedLRA(URL lraId)
                  throws GenericLRAException

Indicates whether an LRA was compensated. The same information can be obtained via a call to getStatus(URL).

Parameters:

lraId - The unique identifier of the LRA (required)

Returns:

whether or not the specified LRA has been compensated

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

isCompletedLRA

Boolean isCompletedLRA(URL lraId)
                throws GenericLRAException

Indicates whether an LRA is complete. The same information can be obtained via a call to getStatus(URL).

Parameters:

lraId - The unique identifier of the LRA (required)

Returns:

whether or not the specified LRA has been completed

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

joinLRA

String joinLRA(URL lraId,
               Long timelimit,
               URL compensateUrl,
               URL completeUrl,
               URL forgetUrl,
               URL leaveUrl,
               URL statusUrl,
               String compensatorData)
        throws GenericLRAException

A participant can join with the LRA at any time prior to the completion of an activity. The participant provides end points on which it will listen for LRA related events.

Parameters:

lraId - The unique identifier of the LRA (required) to enlist with

timelimit - The time limit (in seconds) that the participant can guarantee that it can compensate the work performed while the LRA is active.

compensateUrl - the `compensatation URL`

completeUrl - the `completion URL`

forgetUrl - the `forget URL`

leaveUrl - the `leave URL`

statusUrl - the `status URL`

compensatorData - data that will be stored with the coordinator and passed back to the participant when the LRA is closed or cancelled

Returns:

a recovery URL for this enlistment

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

joinLRA

String joinLRA(URL lraId,
               Class<?> resourceClass,
               URI baseUri,
               String compensatorData)
        throws GenericLRAException

Join an LRA passing in a class that will act as the participant. Similar to joinLRA(URL, Class, URI, String) except that the various participant URLs are expressed as CDI annotations on the passed in resource class.

Parameters:

lraId - The unique identifier of the LRA (required)

resourceClass - An annotated class for the participant methods: Compensate, etc.

baseUri - Base uri for the participant endpoints

compensatorData - Compensator specific data that the coordinator will pass to the participant when the LRA is closed or cancelled

Returns:

a recovery URL for this enlistment

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

updateCompensator

URL updateCompensator(URL recoveryUrl,
                      URL compensateUrl,
                      URL completeUrl,
                      URL forgetUrl,
                      URL statusUrl,
                      String compensatorData)
               throws GenericLRAException

Change the endpoints that a participant can be contacted on.

Parameters:

recoveryUrl - the recovery URL returned from a participant join request

compensateUrl - the URL to invoke when the LRA is cancelled

completeUrl - the URL to invoke when the LRA is closed

statusUrl - if a participant cannot finish immediately then it provides this URL that the coordinator uses to monitor the progress

forgetUrl - used to inform the participant that can forget about this LRA

compensatorData - opaque data that returned to the participant when the LRA is closed or cancelled

Returns:

an updated recovery URL for this participant

Throws:

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

leaveLRA

void leaveLRA(URL lraId,
              String body)
       throws GenericLRAException

A Compensator can resign from the LRA at any time prior to the completion of an activity

Parameters:

lraId - The unique identifier of the LRA (required)

body - (optional)

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

javax.ws.rs.NotFoundException - if the LRA no longer exists

GenericLRAException - if the request to the coordinator failed. Throwable.getCause() and/or GenericLRAException.getStatusCode() may provide a more specific reason.

renewTimeLimit

void renewTimeLimit(URL lraId,
                    long limit,
                    TimeUnit unit)

LRAs can be created with timeouts after which they are cancelled. Use this method to update the timeout.

Parameters:

lraId - the id of the lra to update

limit - the new timeout period

unit - the time unit for limit

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists

getCurrent

URL getCurrent()

checks whether there is an LRA associated with the calling thread (this method provides an alternative to relying on the presence of the LRA_HTTP_HEADER HTTP header fields since not all users of the API are being called in the context of JAX-RS resource requests).

Returns:

the current LRA (can be null)

setCurrentLRA

void setCurrentLRA(URL lraId)

Update the clients notion of the current coordinator.

Parameters:

lraId - the id of the LRA (can be null)

Throws:

javax.ws.rs.NotFoundException - if the LRA no longer exists