===== Transaction Control =====

The Open-ILS Storage server supports database level transactions that are performed within one OpenSRF Session.  This transaction control allows atomic updates of multiple objects to be applied simultaniously without the worry of users getting broken or incomplete data due to timing issues or errors unrelated to their own queries and transactions.  In order to support truely atomic transactions the database that backs the Storage server must support tranactions, but if it does not these methods will become a no-op.

Because the Storage server needs to support different types of replication systems (Multi-master, Single-master multi-slave, XA-base distributed transactions, etc.), you should wrap all write calls, such as **create**, **update** and **delete**, in a transaction.  This will allow the Driver to detect when it should be directing a query to the master database in a single-master replication scheme.

==== open-ils.storage.transaction.begin ====

Starts a database transaction if supported by the current Storage Driver.

  * [[osrf-devel:terms#opensrf_api-level|API Level]]: 1
  * [[osrf-devel:terms#opensrf_server_class|Server Class]]: open-ils.storage
  * Implementation Method: [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods//OpenILS/Application/Storage.pm|OpenILS::Application::Storage::begin_xaction]]
  * Streaming [[osrf-devel:terms#opensrf_method|Method]]: No
  * Cachable [[osrf-devel:terms#opensrf_method|Method]]: No

  * **Returns:**
    * //Success//\\ Returns **1** on success
    * //Failure//\\ Throws an exception uppon failure


==== open-ils.storage.transaction.commit ====

Commits the current transaction to the database.

  * [[osrf-devel:terms#opensrf_api-level|API Level]]: 1
  * [[osrf-devel:terms#opensrf_server_class|Server Class]]: open-ils.storage
  * Implementation Method: [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods//OpenILS/Application/Storage.pm|OpenILS::Application::Storage::commit_xaction]]
  * Streaming [[osrf-devel:terms#opensrf_method|Method]]: No
  * Cachable [[osrf-devel:terms#opensrf_method|Method]]: No

  * **Returns:**
    * //Success//\\ Returns **1** on success
    * //Failure//\\ Throws an exception uppon failure


==== open-ils.storage.transaction.current ====

Retrieves the current transaction ID.  This is generally Driver dependant.

  * [[osrf-devel:terms#opensrf_api-level|API Level]]: 1
  * [[osrf-devel:terms#opensrf_server_class|Server Class]]: open-ils.storage
  * Implementation Method: [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods//OpenILS/Application/Storage.pm|OpenILS::Application::Storage::current_xact]]
  * Streaming [[osrf-devel:terms#opensrf_method|Method]]: No
  * Cachable [[osrf-devel:terms#opensrf_method|Method]]: No

  * **Returns:**
    * //Success//\\ Returns the transaction ID for the currently executing transaction
    * //Failure//\\ Returns an empty result on failure


==== open-ils.storage.transaction.rollback ====

Rolls back the current database transaction.

  * [[osrf-devel:terms#opensrf_api-level|API Level]]: 1
  * [[osrf-devel:terms#opensrf_server_class|Server Class]]: open-ils.storage
  * Implementation Method: [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods//OpenILS/Application/Storage.pm|OpenILS::Application::Storage::rollback_xaction]]
  * Streaming [[osrf-devel:terms#opensrf_method|Method]]: No
  * Cachable [[osrf-devel:terms#opensrf_method|Method]]: No

  * **Returns:**
    * //Success//\\ Returns **1** on success
    * //Failure//\\ Throws an exception uppon failure


----

==== TODO ====

  * Add a XA/2PC/distributed transaction manager service
  * Add interface Prepared Transactions\\ This will allow cross-session transaction support and non-database participation in transactions.