java.lang.Object
- org.jboss.jbossts.star.service.Coordinator

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

Field Summary

Fields
Modifier and Type Field Description

protected static org.jboss.logging.Logger log

Constructor Summary

Constructors
Constructor Description

Coordinator()

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	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("transaction-manager/")
@Produces("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("transaction-manager/")
@Produces("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("transaction-manager/statistics")
@Produces("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("transaction-manager/{id}")
@Produces("application/txlist")
public javax.ws.rs.core.Response getTransactionURIs(@Context
                                                    javax.ws.rs.core.UriInfo info,
                                                    @PathParam("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("transaction-manager/{id}")
@Produces("application/txstatus")
public javax.ws.rs.core.Response getTransactionStatus(@Context
                                                      javax.ws.rs.core.UriInfo info,
                                                      @PathParam("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("transaction-manager/{id}")
@Produces("application/txstatusext+xml")
public javax.ws.rs.core.Response getTransactionExtStatus(@Context
                                                         javax.ws.rs.core.UriInfo info,
                                                         @PathParam("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("transaction-manager/{id}")
public javax.ws.rs.core.Response deleteTransaction(@PathParam("id")
                                                   String id)

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

Parameters:: id - transaction id
Returns:: 403

tt1

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

tt2

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

tt3

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

tt4

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

tt5

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

beginTransaction
```
@POST
@Path("transaction-manager/")
@Consumes("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("")
                                                  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("transaction-manager/{TxId}/terminator")
public javax.ws.rs.core.Response terminateTransaction(@PathParam("TxId")
                                                      String txId,
                                                      @QueryParam("fault") @DefaultValue("")
                                                      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("transaction-manager/{TxId}")
public javax.ws.rs.core.Response enlistParticipant(@HeaderParam("Link")
                                                   String linkHeader,
                                                   @Context
                                                   javax.ws.rs.core.UriInfo info,
                                                   @PathParam("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("transaction-manager/{TxId}/volatile-participant")
public javax.ws.rs.core.Response enlistVolatileParticipant(@HeaderParam("Link")
                                                           String linkHeader,
                                                           @Context
                                                           javax.ws.rs.core.UriInfo info,
                                                           @PathParam("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("recovery-coordinator/{TxId}/{RecCoordId}")
public javax.ws.rs.core.Response lookupParticipant(@PathParam("TxId")
                                                   String txId,
                                                   @PathParam("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("recovery-coordinator/{TxId}/{RecCoordId}")
public javax.ws.rs.core.Response replaceParticipant(@HeaderParam("Link")
                                                    String linkHeader,
                                                    @PathParam("TxId")
                                                    String txId,
                                                    @PathParam("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("recovery-coordinator/{RecCoordId}")
public javax.ws.rs.core.Response postParticipant(@PathParam("RecCoordId")
                                                 String enlistmentId)

deleteParticipant

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

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

Parameters:: enlistmentId - The resource reference
Returns:: HTTP status code

Class Coordinator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object