Skip to main content

Developing with XCC

Overview

Use the following procedure to use multi-statement, explicitly committed transactions with XCC:

  1. Create a Session object in the usual way.

  2. Call Session.setAutoCommit with a value of false. The next transaction created in the session will run as a multi-statement, explicit commit transaction.

  3. Optionally, call Session.setUpdate to specify an explicit transaction type. By default, MarkLogic determines the transaction type through static analysis of the first statement in a request, but you can explicitly set the transaction type to update or query using Session.setUpdate.

  4. Call Session.submitRequest as usual to operate on your data. All requests run in the same transaction until the transaction is committed or rolled back.

  5. Call Session.commit or Session.rollback to commit or rollback the transaction. If the session ends or times out without explicitly commit or rolling back, the transaction is rolled back.

  6. To restore a session to the default, single-statement transaction model, call Session.setAutoCommit with a value of true and Session.setUpdate with a value of AUTO.

Note that the transaction configuration defined by setAutoCommit and setUpdate remain in effect for all transactions created by a session until explicitly changed. If you override the transaction configuration in an ad hoc query, the override applies only to the current transaction.

Multi-statement query transactions allow all the statements in a transaction to share the same point-in-time view of the database, as discussed in Point-In-Time Queries.

In a multi-statement update transaction, updates performed by one statement (or request) are visible to subsequent statements in the same transaction, without being visible to other transactions.

A multi-statement transaction remains open until it is committed or rolled back. Use Session.commit. to commit a multi-statement transaction and make the changes visible in the database. Use Session.rollback to roll back a multi-statement transaction, discarding any updates. Multi-statement transactions are implicitly rolled back when the containing session ends or the transaction times out. Failure to explicitly commit or rollback a multi-statement update transaction can tie up resources, hold locks unnecessarily, and increase the chances of deadlock.

Note

You may receive a java.lang.IllegalStateException if you call Session.commit from an exception handler when there are no pending updates in the current transaction. Committing from a handler is not recommended.

For a detailed discussion of multi-statement transactions, see Understanding Transactions in MarkLogic Server in the Application Developer’s Guide.

Multi-statement transactions impose special re-try semantics on XCC applications. For details, see Retrying Multi-statement Transactions.

In this section: