org.jboss.jbossts.star.service

Class Coordinator

java.lang.Object

org.jboss.jbossts.star.service.Coordinator

@Path(value="/tx/")
public class Coordinator
extends Object

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.jboss.logging.Logger	log

Constructor Summary

Constructors

Constructor and Description
Coordinator()

Method Summary

Modifier and Type	Method and Description
javax.ws.rs.core.Response	beginTransaction(javax.ws.rs.core.UriInfo info, javax.ws.rs.core.HttpHeaders headers, String content) Performing a POST on Transaction Manager URL @see TxSupport.TX_SEGMENT with no content as shown below will start a new transaction with a default timeout.
javax.ws.rs.core.Response	deleteParticipant(String enlistmentId) Performing DELETE on participant's recovery URL removes participant from the transaction.
javax.ws.rs.core.Response	deleteTransaction(String id) Performing a DELETE on the transaction-coordinator URL will return a 403.
javax.ws.rs.core.Response	enlistParticipant(String linkHeader, javax.ws.rs.core.UriInfo info, String txId, String content) Register a participant in a tx
javax.ws.rs.core.Response	enlistVolatileParticipant(String linkHeader, javax.ws.rs.core.UriInfo info, String txId) Register a volatile participant in a tx
javax.ws.rs.core.Response	getAllTransactions(javax.ws.rs.core.UriInfo info) Performing a GET on the transaction-manager returns a list of all transaction URIs known to the coordinator (active and in recovery) separated by the @see TxSupport.URI_SEPARATOR character
javax.ws.rs.core.Response	getTransactionExtStatus(javax.ws.rs.core.UriInfo info, String id) Performing a GET on the transaction URL with media type application/txstatusext+xml returns extended information about the transaction, such as its status, number of participants, and their individual URIs.
org.jboss.jbossts.star.util.media.txstatusext.TransactionManagerElement	getTransactionManagerInfo(javax.ws.rs.core.UriInfo info) Performing a GET on the transaction-manager URI with media type application/txstatusext+xml returns extended information about the transaction-manager resource such as how long it has been up and all transaction-coordinator URIs.
org.jboss.jbossts.star.util.media.txstatusext.TransactionStatisticsElement	getTransactionStatistics() Performing a GET on the transaction-manager URI sufficed with /statistics returns statistics of the transaction manager.
javax.ws.rs.core.Response	getTransactionStatus(javax.ws.rs.core.UriInfo info, String id) Performing a GET on the transaction url returns its status
javax.ws.rs.core.Response	getTransactionURIs(javax.ws.rs.core.UriInfo info, String id) Obtain the transaction terminator and participant enlistment URIs for the specified transaction id.
javax.ws.rs.core.Response	lookupParticipant(String txId, String enlistmentId) Get the participant url (registered during enlistParticipant) corresponding to a resource reference if the coordinator crashes - the participant list will be empty but this is ok if commit hasn't been called since the TM uses presumed abort semantics.
javax.ws.rs.core.Response	postParticipant(String enlistmentId)
void	removeTxState(int status, Transaction tx, Collection<String> enlistmentIds)
javax.ws.rs.core.Response	replaceParticipant(String linkHeader, String txId, String enlistmentId) PUT /recovery-coordinator/_RecCoordId_/_new participant URL_ - overwrite the old participant URL with new participant URL (as with JTS, this will also trigger off a recovery attempt on the associated transaction) A participant may use this url to notifiy the coordinator that he has moved to a new location.
javax.ws.rs.core.Response	terminateTransaction(String txId, String fault, String content) The client can control the outcome of the transaction by by PUTing to the terminator URL returned as a response to the original transaction create request.
javax.ws.rs.core.Response	tt1(String txId)
javax.ws.rs.core.Response	tt2(String txId)
javax.ws.rs.core.Response	tt3(String txId)
javax.ws.rs.core.Response	tt4(String txId)
javax.ws.rs.core.Response	tt5(String txId)

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.jboss.logging.Logger log

Constructor Detail

Coordinator

public Coordinator()

Method Detail

getAllTransactions

@GET
 @Path(value="transaction-manager/")
 @Produces(value="application/txlist")
public javax.ws.rs.core.Response getAllTransactions(@Context
                                                                                                                                        javax.ws.rs.core.UriInfo info)

Performing a GET on the transaction-manager returns a list of all transaction URIs known to the coordinator (active and in recovery) separated by the @see TxSupport.URI_SEPARATOR character

Parameters:

info - http context of the request

Returns:

JSON representation of active transactions and HTTP status code

getTransactionManagerInfo

@GET
 @Path(value="transaction-manager/")
 @Produces(value="application/txstatusext+xml")
public org.jboss.jbossts.star.util.media.txstatusext.TransactionManagerElement getTransactionManagerInfo(@Context
                                                                                                                                                                                                      javax.ws.rs.core.UriInfo info)

Performing a GET on the transaction-manager URI with media type application/txstatusext+xml returns extended information about the transaction-manager resource such as how long it has been up and all transaction-coordinator URIs.

Parameters:

info - Request context

Returns:

TransactionManagerElement

getTransactionStatistics

@GET
 @Path(value="transaction-manager/statistics")
 @Produces(value="application/txstatusext+xml")
public org.jboss.jbossts.star.util.media.txstatusext.TransactionStatisticsElement getTransactionStatistics()

Performing a GET on the transaction-manager URI sufficed with /statistics returns statistics of the transaction manager. Numbers of active, prepared, committed, and aborted transactions are returned.

Returns:

TransactionStatisticsElement

getTransactionURIs

@HEAD
 @Path(value="transaction-manager/{id}")
 @Produces(value="application/txlist")
public javax.ws.rs.core.Response getTransactionURIs(@Context
                                                                                                                                             javax.ws.rs.core.UriInfo info,
                                                                                                                                             @PathParam(value="id")
                                                                                                                                             String id)

Obtain the transaction terminator and participant enlistment URIs for the specified transaction id. These are returned in link headers in the same way they were returned when the transaction was started @see Coordinator#beginTransaction

Parameters:

info - request context

id - URL template parameter for the transaction id

Returns:

http response

getTransactionStatus

@GET
 @Path(value="transaction-manager/{id}")
 @Produces(value="application/txstatus")
public javax.ws.rs.core.Response getTransactionStatus(@Context
                                                                                                                                                javax.ws.rs.core.UriInfo info,
                                                                                                                                                @PathParam(value="id")
                                                                                                                                                String id)

Performing a GET on the transaction url returns its status

Parameters:

info - request context

id - URL template parameter for the id of the transaction

Returns:

content representing the status of the transaction

See Also:

etc for the format of the returned content

getTransactionExtStatus

@GET
 @Path(value="transaction-manager/{id}")
 @Produces(value="application/txstatusext+xml")
public javax.ws.rs.core.Response getTransactionExtStatus(@Context
                                                                                                                                                          javax.ws.rs.core.UriInfo info,
                                                                                                                                                          @PathParam(value="id")
                                                                                                                                                          String id)

Performing a GET on the transaction URL with media type application/txstatusext+xml returns extended information about the transaction, such as its status, number of participants, and their individual URIs.

Parameters:

info - Request context

id - URL template parameter for the id of the transaction

Returns:

HTTP response representing extended transaction status information

deleteTransaction

@DELETE
 @Path(value="transaction-manager/{id}")
public javax.ws.rs.core.Response deleteTransaction(@PathParam(value="id")
                                                                                                      String id)

Performing a DELETE on the transaction-coordinator URL will return a 403.

Parameters:

id - transaction id

Returns:

403

tt1

@HEAD
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response tt1(@PathParam(value="TxId")
                                                                                                   String txId)

tt2

@GET
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response tt2(@PathParam(value="TxId")
                                                                                                  String txId)

tt3

@POST
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response tt3(@PathParam(value="TxId")
                                                                                                   String txId)

tt4

@DELETE
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response tt4(@PathParam(value="TxId")
                                                                                                     String txId)

tt5

@OPTIONS
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response tt5(@PathParam(value="TxId")
                                                                                                      String txId)

beginTransaction

@POST
 @Path(value="transaction-manager/")
 @Consumes(value="application/x-www-form-urlencoded")
public javax.ws.rs.core.Response beginTransaction(@Context
                                                                                                                                                      javax.ws.rs.core.UriInfo info,
                                                                                                                                                      @Context
                                                                                                                                                      javax.ws.rs.core.HttpHeaders headers,
                                                                                                                                                      @DefaultValue(value="")
                                                                                                                                                      String content)

Performing a POST on Transaction Manager URL @see TxSupport.TX_SEGMENT with no content as shown below will start a new transaction with a default timeout. A successful invocation will return 201 and the Location header MUST contain the URI of the newly created transaction resource, which we will refer to as the transaction-coordinator in the rest of this specification. Two related URLs MUST also be returned, one for use by the terminator of the transaction (typically referred to as the client) and one used for registering durable participation in the transaction (typically referred to as the server). These linked URLs can be of arbitrary format. The rel names for the links are:

Parameters:

info - uri context

headers - http headers

content - empty if no transaction timeout is required otherwise the number of milliseconds after which the transaction is eligible for being timed out. The content should have the format TxSupport#TIMEOUT_PROPERTY milliseconds

Returns:

http status code

See Also:

and @see TxLinkNames#PARTICIPANT

terminateTransaction

@PUT
 @Path(value="transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response terminateTransaction(@PathParam(value="TxId")
                                                                                                                   String txId,
                                                                                                                   @QueryParam(value="fault") @DefaultValue(value="")
                                                                                                                   String fault,
                                                                                                                   String content)

The client can control the outcome of the transaction by by PUTing to the terminator URL returned as a response to the original transaction create request. Upon termination, the resource and all associated resources are implicitly deleted. For any subsequent invocation then an implementation MAY return 410 if the implementation records information about transactions that have completed, otherwise it should return 404 (not necessary for presumed rollback semantics) but at a minimum MUST return 401. The invoker can assume this was a rollback. In order for an interested party to know for sure the outcome of a transaction then it MUST be registered as a participant with the transaction coordinator.

Parameters:

txId - URL template component containing the transaction identifier

fault - mechanism for injecting faults TODO use byteman instead

content - body of the request indicating a commit or abort request

Returns:

http response code

See Also:

etc

removeTxState

public void removeTxState(int status,
                          Transaction tx,
                          Collection<String> enlistmentIds)

enlistParticipant

@POST
 @Path(value="transaction-manager/{TxId}")
public javax.ws.rs.core.Response enlistParticipant(@HeaderParam(value="Link")
                                                                                                      String linkHeader,
                                                                                                      @Context
                                                                                                      javax.ws.rs.core.UriInfo info,
                                                                                                      @PathParam(value="TxId")
                                                                                                      String txId,
                                                                                                      String content)

Register a participant in a tx

Parameters:

linkHeader - link header

info - URI info

txId - id of transaction

content - body of request containing URI for driving the participant through completion (the URI should be unique within the scope of txId)

Returns:

unique resource ref for the participant

enlistVolatileParticipant

@PUT
 @Path(value="transaction-manager/{TxId}/volatile-participant")
public javax.ws.rs.core.Response enlistVolatileParticipant(@HeaderParam(value="Link")
                                                                                                                                  String linkHeader,
                                                                                                                                  @Context
                                                                                                                                  javax.ws.rs.core.UriInfo info,
                                                                                                                                  @PathParam(value="TxId")
                                                                                                                                  String txId)

Register a volatile participant in a tx

Parameters:

linkHeader - link header

info - URI info

txId - id of transaction

Returns:

HTTP status code

lookupParticipant

@GET
 @Path(value="recovery-coordinator/{TxId}/{RecCoordId}")
public javax.ws.rs.core.Response lookupParticipant(@PathParam(value="TxId")
                                                                                                                   String txId,
                                                                                                                   @PathParam(value="RecCoordId")
                                                                                                                   String enlistmentId)

Get the participant url (registered during enlistParticipant) corresponding to a resource reference if the coordinator crashes - the participant list will be empty but this is ok if commit hasn't been called since the TM uses presumed abort semantics.

Parameters:

txId - transaction id that this recovery url belongs to

enlistmentId - the resource reference

Returns:

the participant url

replaceParticipant

@PUT
 @Path(value="recovery-coordinator/{TxId}/{RecCoordId}")
public javax.ws.rs.core.Response replaceParticipant(@HeaderParam(value="Link")
                                                                                                                    String linkHeader,
                                                                                                                    @PathParam(value="TxId")
                                                                                                                    String txId,
                                                                                                                    @PathParam(value="RecCoordId")
                                                                                                                    String enlistmentId)

PUT /recovery-coordinator/_RecCoordId_/_new participant URL_ - overwrite the old participant URL with new participant URL (as with JTS, this will also trigger off a recovery attempt on the associated transaction) A participant may use this url to notifiy the coordinator that he has moved to a new location.

Parameters:

linkHeader - link header containing participant links

txId - transaction id that this recovery url belongs to

enlistmentId - id by the participant is known

Returns:

http status code

postParticipant

@POST
 @Path(value="recovery-coordinator/{RecCoordId}")
public javax.ws.rs.core.Response postParticipant(@PathParam(value="RecCoordId")
                                                                                                           String enlistmentId)

deleteParticipant

@DELETE
 @Path(value="recovery-coordinator/{RecCoordId}")
public javax.ws.rs.core.Response deleteParticipant(@PathParam(value="RecCoordId")
                                                                                                               String enlistmentId)

Performing DELETE on participant's recovery URL removes participant from the transaction.

Parameters:

enlistmentId - The resource reference

Returns:

HTTP status code