diff --git a/rts/docs/at/en-US/RESTAT_Guide.xml b/rts/docs/at/en-US/RESTAT_Guide.xml index 39f4c4ca..ce3032dd 100644 --- a/rts/docs/at/en-US/RESTAT_Guide.xml +++ b/rts/docs/at/en-US/RESTAT_Guide.xml @@ -36,7 +36,7 @@ Preface -This guide covers the REST interfaces to the Narayana Transaction Manager. The actual protocol implemented by RESTAT described in this book is taken from the draft RESTAT specification https://github.com/jbosstm/documentation/blob/master/rest-tx/docs/RESTAT-v2-latest.pdf. The specification is still evolving but has reached a stability level such that it can be used in real world environments. +This guide covers the REST interfaces to the Narayana Transaction Manager. The actual protocol implemented by RESTAT described in this book is taken from the draft RESTAT specification https://github.com/jbosstm/documentation/blob/master/rest-tx/docs/RESTAT-v2-latest.pdf. The specification is still evolving but has reached a stability level such that it can be used in real world environments. Overview @@ -120,7 +120,7 @@ Participant: a resource that manages the state changes performed by the service
The Transaction Manager Resource -The transaction manager is represented by a URI (referred to as the transaction-manager URI). It enables clients to create new transaction resources and to query the list of current transactions. The actual URI depends upon how RESTAT is deployed and will be discussed later. +The transaction manager is represented by a URI (referred to as the transaction-manager URI). It enables clients to create new transaction resources and to query the list of current transactions. The actual URI depends upon how RESTAT is deployed and will be discussed later.
@@ -128,7 +128,7 @@ Participant: a resource that manages the state changes performed by the service The RESTAT client is responsible for creating and terminating transaction resources.
Starting a Transaction -Performing a POST on the transaction-manager URI with header as shown below will start a new transaction with a default timeout. A successful invocation returns a 201 HTTP status code and the Location header contains the URI of the newly created transaction resource, which we refer to as transaction-coordinator in the rest of this book. At least two related URLs will also be returned, one for use by the transaction terminator (typically referred to as the client) and one used for registering durable participation in the transaction (typically referred to as the server). These URIs are referred to as the transaction-terminator and transaction-enlistment URIs, respectively. Although uniform URL structures are used in the examples, these linked URLs can be of arbitrary format. +Performing a POST on the transaction-manager URI with header as shown below will start a new transaction with a default timeout. A successful invocation returns a 201 HTTP status code and the Location header contains the URI of the newly created transaction resource, which we refer to as transaction-coordinator in the rest of this book. At least two related URLs will also be returned, one for use by the transaction terminator (typically referred to as the client) and one used for registering durable participation in the transaction (typically referred to as the server). These URIs are referred to as the transaction-terminator and transaction-enlistment URIs, respectively. Although uniform URL structures are used in the examples, these linked URLs can be of arbitrary format. POST /transaction-manager HTTP/1.1 From: foo@bar.com The corresponding response would be: @@ -144,12 +144,12 @@ Content-Type: text/plain Content-Length: -- timeout=1000 -Performing a HEAD on the transaction-coordinator URI returns the same link information. -Performing a DELETE on the transaction-coordinator or transaction-enlistment URIs are not allowed (and an attempt to do so will result in a 403 status code). +Performing a HEAD on the transaction-coordinator URI returns the same link information. +Performing a DELETE on the transaction-coordinator or transaction-enlistment URIs are not allowed (and an attempt to do so will result in a 403 status code).
Obtaining The Transaction Status -Performing a GET on the transaction-coordinator URI returns the current status of the transaction: +Performing a GET on the transaction-coordinator URI returns the current status of the transaction: GET /transaction-coordinator/1234 HTTP/1.1 Accept: application/txstatus With an example response: @@ -165,7 +165,10 @@ txstatus=TransactionActive
Propagating the Context -When making an invocation on a resource that needs to participate in a transaction, either the transaction-coordinator URI or the transaction-enlistment URI (/transaction-coordinator/1234/participant in the previous example) needs to be transmitted to the resource. How this happens is private to the service writer but the following OPTIONAL approach is recommended: +When making an invocation on a resource that needs to participate in a transaction, either the transaction-coordinator URI or the transaction-enlistment URI (/transaction-coordinator/1234/participant in the previous example) needs to be transmitted to the resource. +Alternatively, if the client knows which endpoints the service will use to cancel or commit its work, it can +do the registration and skip this requirement to propagate the context). +If the context is to be propagated then the mechanism is private to the service writer but the following OPTIONAL approach is recommended: @@ -181,19 +184,19 @@ The URI is passed as a Link header with the relevant service interaction.
Discovering Existing Transactions -Performing a GET on the transaction-manager URI with media type application/txlist returns a list of all transaction-coordinator URIs known to the coordinator (active and in recovery). The returned response includes a link header with rel attribute "statistics" linking to a resource that contains statistical information such as the number of transactions that have committed and aborted. -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. +Performing a GET on the transaction-manager URI with media type application/txlist returns a list of all transaction-coordinator URIs known to the coordinator (active and in recovery). The returned response includes a link header with rel attribute statistics linking to a resource that contains statistical information such as the number of transactions that have committed and aborted. +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.
Ending the Transaction -The client can PUT a document containing the desired transaction status to the transaction-terminator URI in order to control the outcome of the transaction. Upon termination, the resource and all associated resources are implicitly deleted. If the client wishes to commit the transaction it sends the following request: +The client can PUT a document containing the desired transaction status to the transaction-terminator URI in order to control the outcome of the transaction. Upon termination, the resource and all associated resources are implicitly deleted. If the client wishes to commit the transaction it sends the following resource update request: PUT /transaction-coordinator/1234/terminator HTTP/1.1 From: foo@bar.com Content-Type: application/txstatus Content-Length: -- txstatus=TransactionCommitted -The response body contains the transaction outcome. The state of the transaction must be TransactionActive for this operation to succeed otherwise a 412 status code is returned. +The response body contains the transaction outcome. The state of the transaction resource must be TransactionActive for this operation to succeed otherwise a 412 status code is returned. The transaction may be told to rollback with the following PUT request: PUT /transaction-coordinator/1234/terminator HTTP/1.1 From: foo@bar.com @@ -205,25 +208,25 @@ txstatus=TransactionRolledBack Service Responsibilities -Once a resource has the transaction or enlistment URI, it can register participation in the transaction. Each participant must be uniquely identified to the transaction coordinator in order that the protocol can guarantee consistency and atomicity in the event of failure and recovery. The participant is free to use whatever URI structure it desires for uniquely identifying itself; in the rest of this manual we shall assume it is /participant-resource and refer to it as the participant-resource URI. +Once a resource has the transaction or enlistment URI, it can register participation in the transaction (or, alternatively, as mentioned earlier it is possible for the client to register the service directly with the coordinator if it knows the services cancel and commit endpoints). Each participant must be uniquely identified to the transaction coordinator in order that the protocol can guarantee consistency and atomicity in the event of failure and recovery. The participant is free to use whatever URI structure it desires for uniquely identifying itself; in the rest of this manual we shall assume it is /participant-resource and refer to it as the participant-resource URI.
Joining the Transaction
Two Phase Aware Participants -A participant is registered with the transaction-coordinator using POST on the participant-enlistment URI obtained when the transaction was originally created. The request must include two link headers: one to uniquely identify the participant to the coordinator and one to provide a terminator resource (referred to as the participant-terminator URI) that the coordinator will use to terminate the participant. If the rel attributes of the link are not participant and terminator the implementation will return 400. Note, the following URIs are only examples, and an implementation is free to use whatever structure/format it likes: +A participant is registered with the transaction-coordinator using POST on the participant-enlistment URI obtained when the transaction was originally created. The request must include two link headers: one to uniquely identify the participant to the coordinator and one to provide a terminator resource (referred to as the participant-terminator URI) that the coordinator will use to terminate the participant. If the rel attributes of the link are not participant and terminator the implementation will return 400. Note, the following URIs are only examples, and an implementation is free to use whatever structure/format it likes: POST /transaction-coordinator/1234/participant HTTP/1.1 From: foo@bar.com Link:</participant-resource>; rel=”participant”, </participant-resource/terminator>; rel=”terminator” Content-Length: 0 -Performing a HEAD on the participant-resource URI will return the terminator reference, as shown below: +Performing a HEAD on the participant-resource URI will return the terminator reference, as shown below: HEAD /participant-resource HTTP/1.1 From: foo@bar.com HTTP/1.1 200 OK Link:</participant-resource/terminator>; rel=”terminator” -If the transaction is not TransactionActive when registration is attempted, then the implementation returns a 412 status code. If the implementation has seen this participant URI before then it returns 400. Otherwise the operation is considered a success and the implementation will return 201 and uses the Location header to give a participant specific URI that the participant may use later during prepare or for recovery purposes. The lifetime of this URI is the same as the transaction-coordinator URI. In the rest of this specification we shall refer to this as the participant-recovery URI (not to be confused with the participant-resource URI). An example response from the transaction-coordinator to a successful enlistment request is: +If the transaction is not TransactionActive when registration is attempted, then the implementation returns a 412 status code. If the implementation has seen this participant URI before then it returns 400. Otherwise the operation is considered a success and the implementation will return 201 and uses the Location header to give a participant specific URI that the participant may use later during prepare or for recovery purposes. The lifetime of this URI is the same as the transaction-coordinator URI. In the rest of this specification we shall refer to this as the participant-recovery URI (not to be confused with the participant-resource URI). An example response from the transaction-coordinator to a successful enlistment request is: HTTP/1.1 201 Created Location: /participant-recovery/1234
@@ -254,7 +257,7 @@ Link:</participant-resource/prepare>; rel=”prepare”,
Obtaining the Participant Status -Performing an HTTP GET request on the participant-resource URI must return the current status of the participant in the same way as for the transaction-coordinator URI discussed earlier. Determining the status of a participant whose URI has been removed is similar to that discussed for the transaction-coordinator URI: +Performing an HTTP GET request on the participant-resource URI must return the current status of the participant in the same way as for the transaction-coordinator URI discussed earlier. Determining the status of a participant whose URI has been removed is similar to that discussed for the transaction-coordinator URI: GET /participant-resource HTTP/1.1 Accept: application/txstatus With an example response: @@ -267,11 +270,11 @@ txstatus=TransactionActive
Leaving the Transaction -A participant can leave the transaction at any time by sending a DELETE request to the coordinator using the URI it obtain during registration (i.e., the participant-recovery URI). Alternatively, it can respond to a prepare request from the coordinator with content body containing txstatus=TransactionReadOnly (in which case the transaction-coordinator will remove it from further participation in the transaction). Otherwise it is the participants responsibility to participate in the transaction termination protocol . +A participant can leave the transaction at any time by sending a DELETE request to the coordinator using the URI it obtained during registration (i.e., the participant-recovery URI). Alternatively, it can respond to a prepare request from the coordinator with content body containing txstatus=TransactionReadOnly (in which case the transaction coordinator will remove it from further participation in the transaction). Otherwise it is the participants responsibility to participate in the transaction termination protocol .
Preparing and Committing Work -The coordinator drives the participant through the two-phase commit protocol by sending a PUT request to the participant terminator URI, provided to the coordinator during enlistment, with the desired transaction outcome as the content (TransactionPrepared, TransactionCommitted, TransactionRolledBack or TransactionCommittedOnePhase). For instance, here is how the prepare phase would be driven: +The coordinator drives the participant through the two-phase commit protocol by sending a PUT request to the participant-terminator URI, provided to the coordinator during enlistment, with the desired transaction outcome as the content (TransactionPrepared, TransactionCommitted, TransactionRolledBack or TransactionCommittedOnePhase). For instance, here is how the prepare phase would be driven: PUT /participant-resource/terminator HTTP/1.1 From: foo@bar.com Content-Type: application/txstatus @@ -279,18 +282,18 @@ Content-Length: -- txstatus=TransactionPrepared If PUT is successful then the implementation returns 200. A subsequent GET on the URI will return the current status of the participant as described previously. It is not always necessary to enquire as to the status of the participant once the operation has been successful. -If PUT fails, e.g., the participant cannot be prepared, then the service writer must return 409. Depending upon the point in the two-phase commit protocol where such a failure occurs the transaction will roll back, e.g., because we use presumed abort semantics, failures prior to the end of the prepare phase always result in a roll back. If the participant is not in the correct state for the requested operation, e.g., TransactionPrepared when it has been already been prepared, then the service writer will return 412. -If the transaction coordinator receives any response other than 200 for Prepare then the transaction always rolls back. -After a request to change the resource state using TransactionRolledBack, TransactionCommitted or TransactionCommittedOnePhase, any subsequent PUT request will return a 409 or 410 code. +If PUT fails, e.g., the participant cannot be prepared, then the service writer must return 409. Depending upon the point in the two-phase commit protocol where such a failure occurs the transaction will roll back, e.g., because we use presumed abort semantics, failures prior to the end of the prepare phase always result in a rollback. If the participant is not in the correct state for the requested operation, e.g., TransactionPrepared when it has already been prepared, then the service writer will return 412. +If the transaction coordinator receives any response other than 200 then the transaction always rolls back. +After a request to change the resource state using TransactionRolledBack, TransactionCommitted or TransactionCommittedOnePhase, any subsequent PUT request will return a 409 or 410 code. The usual rules of heuristic decisions apply here (i.e., the participant cannot forget the choice it made until it is told to by the coordinator). -Performing a DELETE on the participant-resource URI will cause the participant to forget any heuristic decision it made on behalf of the transaction. If the operation succeeds then 200 will be returned and the implementation will delete the resource; a subsequent PUT or GET request returns 410. Any other response means the coordinator will keep retrying. +Performing a DELETE on the participant-resource URI will cause the participant to forget any heuristic decision it made on behalf of the transaction. If the operation succeeds then 200 will be returned and the implementation will delete the resource; a subsequent PUT or GET request returns 410. Any other response means the coordinator will keep retrying.
Recovery -In general it is assumed that failed actors in this protocol, i.e., coordinator or participants, will recover on the same URI as they had prior to the failure. HTTP provides a number of options to support temporary or permanent changes of address, including 301 (Moved Permanently) and 307 (Temporary Redirect). If that is not possible then these endpoints are expected to return a 301 status code or some other way of indicating that the participant has moved elsewhere. HTTP response codes such as 307 are also acceptable if a temporary redirection is used. +In general it is assumed that failed actors in this protocol, i.e., coordinator or participants, will recover on the same URI as they had prior to the failure. HTTP provides a number of options to support temporary or permanent changes of address, including 301 (Moved Permanently) and 307 (Temporary Redirect), if the actor is unable to recover on the same URI then requests to the original endpoints should return an HTTP status code of 301 (Moved Permanently), 307 (Temporary Redirect) is also acceptable. However, sometimes it is possible that a participant may crash and recover on a different URI, e.g., the original machine is unavailable, or that for expediency it is necessary to move recovery to a different machine. In that case it may be the case that the transaction coordinator is unable to complete the transaction, even during recovery. As a result this protocol defines a way for a recovering server to update the information maintained by the coordinator on behalf of these participants. -If the recovering participant uses the participant-recovery URI returned by the coordinator during enlistment then a GET on the participant-recovery URI will return the participant resource and terminator as link headers that the participant used during the original registration. -Performing a PUT on the participant-recovery URI will overwrite the old participant URI with the new one supplied. This operation is equivalent to re-enlisting the participant. This will also trigger off a recovery attempt on the associated transaction using the new participant URI. For example to update location URIs, a two phase aware participant would PUT the following document: +If the recovering participant uses the participant-recovery URI returned by the coordinator during enlistment then a GET on the participant-recovery URI will return the participant resource and terminator as link headers that the participant used during the original registration. +Performing a PUT on the participant-recovery URI will overwrite the old participant URI with the new one supplied. This operation is equivalent to re-enlisting the participant. This will also trigger off a recovery attempt on the associated transaction using the new participant URI. For example to update location URIs, a two phase aware participant would PUT the following document: PUT /participant-recovery/1234 HTTP/1.1 From: foo@bar.com Link:</new-participant-resource>; rel=”participant”, @@ -298,32 +301,32 @@ Link:</new-participant-resource>; rel=”participant”, Content-Length: 0 Similarly for a two phase unaware participant. -If, after performing the PUT request to the participant-recovery URI, the participant is not asked to complete (within an implementation dependent period) then the protocol requires that the participant reissue the PUT request. +If, after performing the PUT request to the participant-recovery URI, the participant is not asked to complete (within an implementation dependent period) then the protocol requires that the participant re-issue the PUT request.
Pre- and Post- Two-Phase Commit Processing Most modern transaction processing systems allow the creation of participants that do not take part in the two-phase commit protocol, but are informed before it begins and after it has completed. They are called Synchronizations, and are typically employed to flush volatile (cached) state, which may be being used to improve performance of an application, to a recoverable object or database prior to the transaction committing. This additional protocol is accomplished by supporting an additional two-phase commit protocol that encloses the protocol already discussed. This will be termed the Volatile Two Phase Commit protocol, as the participants involved in it are not required to be durable for the purposes of data consistency, whereas the other protocol will be termed the Durable Two Phase Commit protocol. The coordinator will not record any durable information on behalf of Volatile participants. -In this enclosing protocol the Volatile prepare phase executes prior to the Durable prepare. The transaction-coordinator sends a PUT request to the registered volatile-participant: only if this prepare succeeds will the Durable protocol be executed. The volatile-participant has to indicate success by returning a 200 status code (any other code indicates failure). If the Durable protocol completes then this may be communicated to the Volatile participants through the commit or rollback phases. -In this case the transaction-coordinator sends a PUT request to the registered volatile-participant with the outcome in the request body (using content type application/txstatus). However, because the coordinator does not maintain any information about these participants and the Durable protocol has completed, this is a best-effort approach only, i.e., such participants should not assume they will be informed about the transaction outcome. If that is a necessity then they should register with the Durable protocol instead. -The primary difference between the Volatile and Durable protocols is that there is no recovery associated with the Volatile protocol so enlistment of volatile participants does not return a participant-recovery URI. In addition there can be no heuristic outcomes associated with the Volatile protocol. Once the Durable protocol has started no more registration in the Volatile protocol are allowed. And finally, there is no one-phase commit optimization for the Volatile protocol. +In this enclosing protocol the Volatile prepare phase executes prior to the Durable prepare. The transaction-coordinator sends a PUT request to the registered volatile-participant: only if this prepare succeeds will the Durable protocol be executed. The volatile-participant has to indicate success by returning a 200 status code (any other code indicates failure). If the Durable protocol completes then this may be communicated to the Volatile participants through the commit or rollback phases. +In this case the transaction-coordinator sends a PUT request to the registered volatile-participant with the outcome in the request body (using content type application/txstatus). However, because the coordinator does not maintain any information about these participants and the Durable protocol has completed, this is a best-effort approach only, i.e., such participants should not assume they will be informed about the transaction outcome. If that is a necessity then they should register with the Durable protocol instead. +The primary difference between the Volatile and Durable protocols is that there is no recovery associated with the Volatile protocol so enlistment of volatile participants does not return a participant-recovery URI. In addition there can be no heuristic outcomes associated with the Volatile protocol. Once the Durable protocol has started no more registration in the Volatile protocol are allowed. And finally, there is no one-phase commit optimization for the Volatile protocol.
Container Integration -The RESTAT protocol described here is implemented as a JAX-RS service, deploys as a Servlet 3.0 application and depends on the Narayana TM as the back-end transaction engine. JAX-RS is the Java language support for building REST based applications - it is both an annotation-based API for defining resources and a run-time for mapping HTTP requests to Java methods. Thus any container supporting these two requirements (servlet 3.0 and the Narayana TM) will work. +The RESTAT protocol described here is implemented as a JAX-RS service, deploys as a Servlet 3.0 application and depends on the Narayana TM as the back-end transaction engine. JAX-RS is the Java language support for building REST based applications - it is both an annotation-based API for defining resources and a run-time for mapping HTTP requests to Java methods. Thus any container supporting these two requirements (servlet 3.0 and the Narayana TM) can be used.
Deploying as a Wildfly Subsystem -The RESTAT coordinator is integrated with the 8.0.0.Alpha3 release of the Wildfly application server (http://www.wildfly.org/download/) as a subsystem (called RTS) so you do not have to explicitly deploy it. You do, however, need to start the application server using an optional server configuration: +The RESTAT coordinator is integrated with the 8.0.0.Alpha3 and subsequent releases of the Wildfly application server (http://www.wildfly.org/download/) as a subsystem (called RTS) so you do not have to explicitly deploy it. You do, however, need to start the application server using an optional server configuration: change directory to where the application server is installed Linux: ./bin/standalone.sh --server-config=../../docs/examples/configs/standalone-rts.xml Windows: bin\standalone.bat --server-config=..\..\docs\examples\configs\standalone-rts.xml -For this mode of deployment the transaction-manager URI is http://<host>:<port>/rest-at-coordinator/tx/transaction-manager +For this mode of deployment the transaction-manager URI is http://<host>:<port>/rest-at-coordinator/tx/transaction-manager
Deploying into a Servlet Container -For other versions of the applications server you will need to deploy the coordinator as a war archive using the standard war deployment mechanism appropriate to your particular container. The archive is contained in the bin folder of the narayana download (restat-web.war). If you are building from source the archive is located in rts/at/webservice/target/restat-web-<version>.war. -For this mode of deployment the transaction-manager URI is http://<host>:<port>/rest-tx/tx/transaction-manager +For other versions of the application server you will need to deploy the coordinator as a war archive using the standard war deployment mechanism appropriate to your particular container. The archive is contained in the bin folder of the narayana download (restat-web.war). If you are building from source the archive is located in rts/at/webservice/target/restat-web-<version>.war. +For this mode of deployment the transaction-manager URI is http://<host>:<port>/rest-tx/tx/transaction-manager
@@ -413,7 +416,7 @@ In order to enable bridging, service writer has to annotate either JAX-RS resour Transaction Statuses -Resources return the following status values in response to GET requests on the appropriate transaction-coordinator or participant-resource URI: +Resources return the following status values in response to GET requests on the appropriate transaction-coordinator or participant-resource URI: