Package org.jboss.jbossts.star.client

Class SRAClient

java.lang.Object

org.jboss.jbossts.star.client.SRAClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, SRAClientAPI

@RequestScoped
public class SRAClient
extends java.lang.Object
implements SRAClientAPI, java.io.Closeable

A utility class for controlling the lifecycle of Long Running Actions (SRAs) but the prefered mechanism is to use the annotation in the org.jboss.jbossts.star.annotation package

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	CLIENT_ID_PARAM_NAME
static java.lang.String	COMMIT
static java.lang.String	COORDINATOR_URL_PROP
static long	DEFAULT_TIMEOUT_MILLIS
static java.lang.String	ONEPHASECOMMIT
static java.lang.String	PARENT_SRA_PARAM_NAME
static java.lang.String	PREPARE
static java.lang.String	ROLLBACK
static java.lang.String	RTS_HTTP_CONTEXT_HEADER
static java.lang.String	RTS_HTTP_RECOVERY_HEADER
static java.lang.String	STATUS
static java.lang.String	TIMELIMIT_PARAM_NAME
static java.lang.String	TX_COMMITTED
static java.lang.String	TX_ROLLBACK_ONLY
static java.lang.String	TX_ROLLEDBACK

Constructor Summary

Constructors

Constructor	Description
SRAClient()

Method Summary

Modifier and Type	Method	Description
java.lang.String	cancelSRA(java.net.URL sraId)	Attempt to cancel an SRA Trigger the compensation of the SRA.
void	close()
java.lang.String	commitSRA(java.net.URL sraId)	Attempt to close an SRA Trigger the successful completion of the SRA.
static java.lang.String	encodeURL(java.net.URL sraId, java.lang.String message)
java.util.List<SRAInfo>	getActiveSRAs()	Lookup active SRAs
java.util.List<SRAInfo>	getAllSRAs()	Returns all SRAs Gets both active and recovering SRAs
java.net.URL	getCurrent()	checks whether there is an SRA associated with the calling thread
java.util.List<SRAInfo>	getRecoveringSRAs()	List recovering Long Running Actions Returns SRAs that are recovering (ie some compensators still need to be ran)
java.util.List<java.lang.String>	getResponseData(java.net.URL sraId)
static java.lang.String	getSRAId(java.lang.String sraId)
java.util.Map<java.lang.String,java.lang.String>	getTerminationUris(java.net.URL aaId, java.lang.Class<?> compensatorClass, javax.ws.rs.core.UriInfo uriInfo, boolean validate)
java.lang.String	getUrl()
java.lang.Boolean	isActiveSRA(java.net.URL sraId)	Indicates whether an SRA is active
java.lang.Boolean	isCompensatedSRA(java.net.URL sraId)	Indicates whether an SRA was compensated
java.lang.Boolean	isCompletedSRA(java.net.URL sraId)	Indicates whether an SRA is complete
void	joinSRA(java.net.URL sraId, java.lang.Long timelimit, java.lang.String compensatorUrl)	A SRAParticipant can join with the SRA at any time prior to the completion of an activity
java.lang.String	joinSRA(java.net.URL sraId, java.lang.Long timelimit, java.lang.String compensateUrl, java.lang.String completeUrl, java.lang.String leaveUrl, java.lang.String statusUrl)	Similar to SRAClientAPI.joinSRA(URL, Long, String) but the various compensator urls are passed in explicitly
java.lang.String	joinSRAWithLinkHeader(java.net.URL sraUrl, java.lang.Long timelimit, java.lang.String linkHeader)
void	postConstruct()
void	setCurrentSRA(java.net.URL coordinatorUrl)	Update the clients notion of the current coordinator.
static java.net.URL	sraToURL(java.lang.String sraId)
static java.net.URL	sraToURL(java.lang.String sraId, java.lang.String message)
java.net.URL	startSRA(java.lang.String clientID, java.lang.Long timeout)
java.net.URL	startSRA(java.net.URL parentSRA, java.lang.String clientID, java.lang.Long timeout, java.util.concurrent.TimeUnit unit)
static java.lang.String	stripUid(java.net.URL url)
java.net.URL	toURL(java.lang.String sraId)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RTS_HTTP_CONTEXT_HEADER

public static final java.lang.String RTS_HTTP_CONTEXT_HEADER

See Also:

Constant Field Values

RTS_HTTP_RECOVERY_HEADER

public static final java.lang.String RTS_HTTP_RECOVERY_HEADER

See Also:

Constant Field Values

COORDINATOR_URL_PROP

public static final java.lang.String COORDINATOR_URL_PROP

See Also:

Constant Field Values

COMMIT

public static final java.lang.String COMMIT

See Also:

Constant Field Values

PREPARE

public static final java.lang.String PREPARE

See Also:

Constant Field Values

ROLLBACK

public static final java.lang.String ROLLBACK

See Also:

Constant Field Values

STATUS

public static final java.lang.String STATUS

See Also:

Constant Field Values

ONEPHASECOMMIT

public static final java.lang.String ONEPHASECOMMIT

See Also:

Constant Field Values

TIMELIMIT_PARAM_NAME

public static final java.lang.String TIMELIMIT_PARAM_NAME

See Also:

Constant Field Values

CLIENT_ID_PARAM_NAME

public static final java.lang.String CLIENT_ID_PARAM_NAME

See Also:

Constant Field Values

PARENT_SRA_PARAM_NAME

public static final java.lang.String PARENT_SRA_PARAM_NAME

See Also:

Constant Field Values

DEFAULT_TIMEOUT_MILLIS

public static final long DEFAULT_TIMEOUT_MILLIS

See Also:

Constant Field Values

TX_COMMITTED

public static final java.lang.String TX_COMMITTED

See Also:

Constant Field Values

TX_ROLLEDBACK

public static final java.lang.String TX_ROLLEDBACK

See Also:

Constant Field Values

TX_ROLLBACK_ONLY

public static final java.lang.String TX_ROLLBACK_ONLY

See Also:

Constant Field Values

Constructor Detail

SRAClient

public SRAClient()
          throws java.net.URISyntaxException,
                 java.net.MalformedURLException

Throws:

java.net.URISyntaxException

java.net.MalformedURLException

Method Detail

postConstruct

@PostConstruct
public void postConstruct()

sraToURL

public static java.net.URL sraToURL(java.lang.String sraId)

sraToURL

public static java.net.URL sraToURL(java.lang.String sraId,
                                    java.lang.String message)

encodeURL

public static java.lang.String encodeURL(java.net.URL sraId,
                                         java.lang.String message)

getSRAId

public static java.lang.String getSRAId(java.lang.String sraId)

stripUid

public static java.lang.String stripUid(java.net.URL url)

toURL

public java.net.URL toURL(java.lang.String sraId)
                   throws InvalidSRAId

Throws:

InvalidSRAId

setCurrentSRA

public void setCurrentSRA(java.net.URL coordinatorUrl)

Update the clients notion of the current coordinator. Warning all further operations will be performed on the SRA manager that created the passed in coordinator.

Parameters:

coordinatorUrl - the full url of an SRA

startSRA

public java.net.URL startSRA(java.lang.String clientID,
                             java.lang.Long timeout)
                      throws GenericSRAException

Throws:

GenericSRAException

startSRA

public java.net.URL startSRA(java.net.URL parentSRA,
                             java.lang.String clientID,
                             java.lang.Long timeout,
                             java.util.concurrent.TimeUnit unit)
                      throws GenericSRAException

Specified by:

startSRA in interface SRAClientAPI

Parameters:

parentSRA - the parent SRA if this new SRA is nested

clientID - Each client is expected to have a unique identity (which can be a URL). (optional)

timeout - Specifies the maximum time in seconds that the SRA will exist for. If the SRA is terminated because of a timeout, the SRA URL is deleted. All further invocations on the URL will return 404. The invoker can assume this was equivalent to a compensate operation. (optional, default to 0)

Returns:

the id of the new SRA

Throws:

GenericSRAException

cancelSRA

public java.lang.String cancelSRA(java.net.URL sraId)
                           throws GenericSRAException

Description copied from interface: SRAClientAPI

Attempt to cancel an SRA Trigger the compensation of the SRA. All compensators will be triggered by the coordinator (ie the compensate message will be sent to each compensators). Upon termination, the URL is implicitly deleted. The invoker cannot know for sure whether the sra completed or compensated without enlisting a io.narayana.sra.

Specified by:

cancelSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

Returns:

compensator sepcific data provided by the application for nested SRA the API implementation will combine compensator data into a JSON encoded array. This means that compensators MUST not return any data that starts with the JSON array start token (ie a '[' character)

Throws:

GenericSRAException - Comms error

commitSRA

public java.lang.String commitSRA(java.net.URL sraId)
                           throws GenericSRAException

Description copied from interface: SRAClientAPI

Attempt to close an SRA Trigger the successful completion of the SRA. All compensators will be dropped by the coordinator. The complete message will be sent to the compensators. Upon termination, the URL is implicitly deleted. The invoker cannot know for sure whether the sra completed or compensated without enlisting a io.narayana.sra.

Specified by:

commitSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

Returns:

compensator sepcific data provided by the application for nested SRA the API implementation will combine compensator data into a JSON encoded array. This means that compensators MUST not return any data that starts with the JSON array start token (ie a '[' character)

Throws:

GenericSRAException - Comms error

joinSRAWithLinkHeader

public java.lang.String joinSRAWithLinkHeader(java.net.URL sraUrl,
                                              java.lang.Long timelimit,
                                              java.lang.String linkHeader)
                                       throws GenericSRAException

Parameters:

sraUrl - the URL of the SRA to join

timelimit - how long the io.narayana.sra is prepared to wait for SRA completion

linkHeader - io.narayana.sra protocol URLs in link header format (RFC 5988)

Returns:

a recovery URL for this enlistment

Throws:

GenericSRAException - if the SRA coordinator failed to enlist the io.narayana.sra

joinSRA

public void joinSRA(java.net.URL sraId,
                    java.lang.Long timelimit,
                    java.lang.String compensatorUrl)
             throws GenericSRAException

Description copied from interface: SRAClientAPI

A SRAParticipant can join with the SRA at any time prior to the completion of an activity

Specified by:

joinSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

timelimit - The time limit (in seconds) that the SRAParticipant can guarantee that it can compensate the work performed by the io.narayana.sra.demo.service. After this time period has elapsed, it may no longer be possible to undo the work within the scope of this (or any enclosing) SRA. It may therefore be necessary for the application or io.narayana.sra.demo.service to start other activities to explicitly try to compensate this work. The application or coordinator may use this information to control the lifecycle of a SRA. (required)

compensatorUrl - The resource path that the SRA coordinator will use to drive the compensator. Performing a GET on the compensator URL will return the current status of the compensator, or 404 if the compensator is no longer present. The following types must be returned by Compensators to indicate their current status: - Compensating: the SRAParticipant is currently compensating for the SRA; - Compensated: the SRAParticipant has successfully compensated for the SRA. - FailedToCompensate: the SRAParticipant was not able to compensate for the SRA. It must maintain information about the work it was to compensate until the coordinator sends it a forget message. - Completing: the SRAParticipant is tidying up after being told to complete. - Completed: the coordinator/io.narayana.sra has confirmed. - FailedToComplete: the SRAParticipant was unable to tidy-up. Performing a POST on URL/compensate will cause the compensator to compensate the work that was done within the scope of the SRA. Performing a POST on URL/complete will cause the compensator to tidy up and it can forget this SRA. (optional)

Throws:

GenericSRAException - Comms error

joinSRA

public java.lang.String joinSRA(java.net.URL sraId,
                                java.lang.Long timelimit,
                                java.lang.String compensateUrl,
                                java.lang.String completeUrl,
                                java.lang.String leaveUrl,
                                java.lang.String statusUrl)
                         throws GenericSRAException

Description copied from interface: SRAClientAPI

Similar to SRAClientAPI.joinSRA(URL, Long, String) but the various compensator urls are passed in explicitly

Specified by:

joinSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

timelimit - The time limit (in seconds) that the SRAParticipant can guarantee that it can compensate the work performed by the io.narayana.sra.demo.service

compensateUrl - Performing a POST onthis URL will cause the io.narayana.sra to compensate the work that was done within the scope of the SRA.

completeUrl - Performing a POST on this URL will cause the io.narayana.sra to tidy up and it can forget this transaction.

leaveUrl - Performing a PUT on this URL with cause the compensator to leave the SRA

statusUrl - Performing a GET on this URL will return the status of the compensator {@see joinSRA}

Throws:

GenericSRAException

getAllSRAs

public java.util.List<SRAInfo> getAllSRAs()
                                   throws GenericSRAException

Description copied from interface: SRAClientAPI

Returns all SRAs Gets both active and recovering SRAs

Specified by:

getAllSRAs in interface SRAClientAPI

Returns:

List

Throws:

GenericSRAException - Comms error

getActiveSRAs

public java.util.List<SRAInfo> getActiveSRAs()
                                      throws GenericSRAException

Description copied from interface: SRAClientAPI

Lookup active SRAs

Specified by:

getActiveSRAs in interface SRAClientAPI

Throws:

GenericSRAException - Comms error

getRecoveringSRAs

public java.util.List<SRAInfo> getRecoveringSRAs()
                                          throws GenericSRAException

Description copied from interface: SRAClientAPI

List recovering Long Running Actions Returns SRAs that are recovering (ie some compensators still need to be ran)

Specified by:

getRecoveringSRAs in interface SRAClientAPI

Throws:

GenericSRAException - Comms error

isActiveSRA

public java.lang.Boolean isActiveSRA(java.net.URL sraId)
                              throws GenericSRAException

Description copied from interface: SRAClientAPI

Indicates whether an SRA is active

Specified by:

isActiveSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

Throws:

GenericSRAException - Comms error

isCompensatedSRA

public java.lang.Boolean isCompensatedSRA(java.net.URL sraId)
                                   throws GenericSRAException

Description copied from interface: SRAClientAPI

Indicates whether an SRA was compensated

Specified by:

isCompensatedSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

Throws:

GenericSRAException - Comms error

isCompletedSRA

public java.lang.Boolean isCompletedSRA(java.net.URL sraId)
                                 throws GenericSRAException

Description copied from interface: SRAClientAPI

Indicates whether an SRA is complete

Specified by:

isCompletedSRA in interface SRAClientAPI

Parameters:

sraId - The unique identifier of the SRA (required)

Throws:

GenericSRAException - Comms error

getTerminationUris

public java.util.Map<java.lang.String,java.lang.String> getTerminationUris(java.net.URL aaId,
                                                                                 java.lang.Class<?> compensatorClass,
                                                                                 javax.ws.rs.core.UriInfo uriInfo,
                                                                                 boolean validate)

getUrl

public java.lang.String getUrl()

getCurrent

public java.net.URL getCurrent()

Description copied from interface: SRAClientAPI

checks whether there is an SRA associated with the calling thread

Specified by:

getCurrent in interface SRAClientAPI

Returns:

close

public void close()

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

getResponseData

public java.util.List<java.lang.String> getResponseData(java.net.URL sraId)

Specified by:

getResponseData in interface SRAClientAPI