Loading TOC...
REST Application Developer's Guide (PDF)

REST Application Developer's Guide — Chapter 6

Managing Transactions

The REST Client API provides transaction control through the /transactions service and a txid parameter available on document manipulation and search requests. This section covers the following topics:

Service Summary

Many of the services available through the REST Client API allow you to perform an operation in the context of a specific transaction by passing a transaction id in a txid parameter. The /transactions service supports the creation and administration of these transactions.

The /transactions service supports the following operations:

OperationMethodDescriptionMore Information
CreatePOSTCreate a multi-statement transaction. See Creating a Transaction.Creating a Transaction

The /transactions/{txid} service supports the following operations:

OperationMethodDescriptionMore Information
Commit or RollblackPOSTCommit or rollback an open transaction.Committing or Rolling Back a Transaction
StatusGETRetrieve transaction status in XML or JSON.Checking Transaction Status

Overview of RESTful Transactions

This section gives a brief introduction to the MarkLogic Server transaction model as it applies to the REST Client API. For a full discussion of the transaction model, see Understanding Transactions in MarkLogic Server in the Application Developer's Guide..

By default, each request to a REST Client API service is equivalent to a single statement transaction. That is, the request is evaluated as single transaction.

For example, when you update a document in the database by making a PUT request to the /documents service, the service effectively creates a new transaction, updates the document, commits the transaction, and then sends back a response. The update is immediately visible in the database and available to other requests.

The REST Client API also allows your application to take direct control of transaction boundaries so that multiple request are evaluated in the same transaction context. This is equivalent to the multi-statement transactions described in Multi-Statement Transaction Concept Summary in the Application Developer's Guide.

Using multi-statement transactions, you can make several update requests and commit them as a single transaction, ensuring either all or none of the updates appear in the database. The document manipulation and search capabilities of the REST Client API support multi-statement transactions.

To use multi-statement transactions:

  1. Create a multi-statement transaction by sending a POST request to the /transactions service. The service returns a transaction id. See Creating a Transaction.
  2. Evaluate one or more requests in the context of the transaction by including the transaction id in the txid request parameter. See Associating a Transaction with a Request.
  3. Commit or rollback the transaction by sending a POST request to the /transactions service. See Committing or Rolling Back a Transaction.

If your application interacts with MarkLogic Server through a load balancer, you might need to include a HostId cookie in your requests to preserve session affinity. For details, see Managing Transactions When Using a Load Balancer.

When you explicitly create a transaction, you must explicitly commit or roll it back. Failure to do so leaves the transaction open until the request or transaction timeout expires. Open transactions can hold locks and consume system resources.

If the request or transaction timeout expires before a transaction is committed, the transaction is automatically rolled back and all updates are discarded. Configure the request timeout of the App Server using the Admin UI. Configure the timeout of a single transaction by setting the timeLimit request parameter during transaction creation.

Note that if you're using multi-statement transactions, you must create, use, and commit (or rollback) on the transaction using the same database. You cannot create a transaction on one database and then attempt to perform an operation such as read, write, or search using the transaction id and a different database.

Creating a Transaction

To create a transaction, send a POST request to the /transactions service with a URL of the form:

http://host:port/version/transactions

The service responds with a transaction id in the Location response header. Use the transaction id to control the transaction in which MarkLogic Server evaluates future requests; see Associating a Transaction with a Request.

The transaction id returned in the Location header is of the form. You can use this resource path to subsequently commit or rollback the transaction, as described in Committing or Rolling Back a Transaction.

/version/transactions/txnid

For example:

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X POST -d "" --anyauth --user user:password \
    -H "Content-type: text/plain" \
    http://localhost:8000/LATEST/transactions
...
HTTP/1.1 303 See Created Transaction
Location: /v1/transactions/3148548124558550433

When supplying the transaction id to future requests, use only the txnid portion. For example:

$ curl -X PUT -T ./example.xml --anyauth --user user:password \
  'http://localhost:8000/LATEST/documents?uri=/xml/example.xml&txid=3148548124558550433'

Transactions created using the /transactions service must be explicitly committed or rolled back. Failure to commit or rollback the transaction before the request timeout expires causes an automatic rollback. You can assign a shorter time limit to a transaction using the timeLimit URL parameter:

http://host:port/version/transactions?timeLimit=seconds

As a convenience for identifying a transaction in server status reports, you can assign a name to the transaction. The default transaction name is 'client-txn'. To assign a transaction, add the name URL parameter to your request:

http://host:port/version/transactions?name=txn_name

Associating a Transaction with a Request

Once you create a transaction, as described in Creating a Transaction, you can evaluate document manipulation and search requests in that transaction by supplying the transaction id wherever a txid URL parameter is supported.

For example, to perform a document update in the context of a specific transaction, include the transaction id in a PUT request to the /documents service:

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X PUT -T ./example.xml --anyauth --user user:password \
  'http://localhost:8000/LATEST/documents?uri=/xml/example.xml&txid=3148548124558550433'

Updates associated with an explicit transaction are visible to other requests executed within the same transaction, but they are not visible outside the transaction until the transaction is committed. See Committing or Rolling Back a Transaction.

The database context in which you evaluate the request must be the same as the database context in which the transaction was created.

Committing or Rolling Back a Transaction

To commit a transaction created by making a POST request to the /transactions service, send a POST request to the /transactions/{txid} service with a URL of the form:

http://host:port/version/transactions/txid?result=outcome

Where txid is a transaction id returned in the Location header of the transaction creation request response, and outcome is either commit or rollback.

MarkLogic Server responds with a 204 when a transaction is successfully committed or rolled back, or if the transaction no longer exists.

Transactions created using the /transactions service should be explicitly commited or rolled back. Failure to commit or rollback the transaction before the request timeout expires causes an automatic rollback. Leaving transactions open unnecessarily potentially holds locks on documents and consume system resources.

Checking Transaction Status

To query the status of a transaction, send a GET request to the /transactions service with a URL of the form:

http://host:port/version/transactions/txid

Where txid is a transaction id returned in the Location header of the transaction creation request response.

MarkLogic Server responds with transaction status information in XML or JSON, depending upon the format requested through the HTTP Accept header or the format URL parameter. The default format is XML. If both the Accept header and the format parameter are set, the format parameter takes precedence.

To request a specific format, set the Accept header to application/json or application/xml, or set the format URL parameter to xml or json. The following example requests JSON output using the Accept header:

# Windows users, see Modifying the Example Commands for Windows 
$ curl -X GET --anyauth --user user:password \
    -H "Accept: application/json" \
    http://localhost:8000/LATEST/transactions/216104635458437451

The XML status information returned in the response takes the following form:

<rapi:transaction-status xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:host>
    <rapi:host-id>1506593501555860493</rapi:host-id>
    <rapi:host-name>somehost</rapi:host-name>
  </rapi:host>
  <rapi:server>
    <rapi:server-id>17994162681305741146</rapi:server-id>
    <rapi:server-name>App-Services</rapi:server-name>
  </rapi:server>
  <rapi:database>
    <rapi:database-id>8896678293064963766</rapi:database-id>
    <rapi:database-name>Documents</rapi:database-name>
  </rapi:database>
  <rapi:transaction-id>216104635458437451</rapi:transaction-id>
  <rapi:transaction-name>client-txn</rapi:transaction-name>
  <rapi:transaction-mode>update</rapi:transaction-mode>
  <rapi:transaction-timestamp>0</rapi:transaction-timestamp>
  <rapi:transaction-state>idle</rapi:transaction-state>
  <rapi:canceled>false</rapi:canceled>
  <rapi:start-time>2012-08-18T17:23:00-07:00</rapi:start-time>
  <rapi:time-limit>600</rapi:time-limit>
  <rapi:max-time-limit>3600</rapi:max-time-limit>
  <rapi:user>7071164303237443533</rapi:user>
  <rapi:admin>true</rapi:admin>
</rapi:transaction-status>

The JSON status information returned in the response takes the following form:

{
  "rapi:transaction-status": {
    "rapi:host": {
      "rapi:host-id": "1506593501555860493",
      "rapi:host-name": "somehost"
    },
    "rapi:server": {
      "rapi:server-id": "17994162681305741146",
      "rapi:server-name": "App-Services"
    },
    "rapi:database": {
      "rapi:database-id": "8896678293064963766",
      "rapi:database-name": "Documents"
    },
    "rapi:transaction-id": "216104635458437451",
    "rapi:transaction-name": "client-txn",
    "rapi:transaction-mode": "update",
    "rapi:transaction-timestamp": "0",
    "rapi:transaction-state": "idle",
    "rapi:canceled": "false",
    "rapi:start-time": "2012-08-18T17:23:00-07:00",
    "rapi:time-limit": "600",
    "rapi:max-time-limit": "3600",
    "rapi:user": "7071164303237443533",
    "rapi:admin": "true"
  }
}

You can also check transaction status using the Admin Interface or xdmp:host-status.

Managing Transactions When Using a Load Balancer

This section applies only to client applications that use multi-statement transactions and interact with a MarkLogic Server cluster through a load balancer. Requests that include a transaction id (txid) request parameter are part of a multi-statement transaction.

When you use a load balancer, it is possible for requests from your application to MarkLogic Server to be routed to different hosts, even within the same session. This has no effect on most interactions with MarkLogic Server, but all requests that are part of the same multi-statement transaction must be routed to the same host within your MarkLogic cluster. This consistent routing through a load balancer is called session affinity.

To support session affinity, the REST API sets a HostId cookie on any response that creates or does work in the context of a multi-statement transaction. The cookie value is an unsigned long representation of the host identifier and does not include any session state.

The REST API supports session affinity through a HostId cookie, as follows:

  • When you create a transaction by making a POST request to the /transactions service, the response includes a transaction id in the Location header and a HostId cookie in the Set-cookie header.
  • When you use the same transaction id in subsequent requests, you should also include the same HostId cookie in the request headers.
  • If you configure your load balancer to use the HostId cookie for session affinity, all requests associated with the same transaction id will be routed to the same host.
  • When you commit or rollback an open transaction, you can discard the associated HostId cookie.

Most client applications do not need to persist the cookie or arrange for its expiration. The cookie does not include any session state. The cookie value is not used by the REST API.

The exact steps required to configure session affinity in the load balancer depend on the load balancer. Consult your load balancer documentation for details.

« Previous chapter
Next chapter »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy