.. _UC24:

Use Case 24 - MNs and CNs Support Transactions
----------------------------------------------

.. index:: Use Case 24, UC24, transaction, event granularity

Revisions
  View document revision history_.

Goal
  Transactions - CNs and MNs should support transaction sets where operations
  all complete successfully or get rolled back (e.g., upload both data and
  metadata records).

Summary 
  Transactions help ensure stability of the system, so that the chance of
  partial change to content is minimized.

  Note that this use case is really stated as a requirement of the DataONE
  system.

Actors
  - Member Nodes
  - Coordinating Nodes
  - Investigator toolkit

Preconditions 
  - DataONE operational

  - Some data / metadata transfer operation is due.

Triggers
  - Metadata transfer is in process and there is a network failure

Post Conditions
  - The transfer changes should be rolled back to the state before the operation.


.. 
   @startuml images/24_seq.png
   participant "CRUD API" as c_crud << Coordinating Node >>
   participant "Object Store" as c_ostore << Coordinating Node >>
   participant "CRUD API" as m_crud << Member Node >>
   c_crud -> c_ostore: beginTransaction() 
   c_ostore --> c_crud: transactionHandle
   c_crud -> m_crud: get(token, PID)
   alt Success
     m_crud --> c_crud: object
     c_crud -> c_ostore: commitTransaction(transactionHandle)
     c_crud -> c_ostore: updateSystemMetadata(PID)
   else Transfer failure
    c_crud -> c_ostore: rollbackTransaction(transactionHandle)
    c_ostore --> c_crud: ACK
   end  
   @enduml

.. image::  images/24_seq.png

*Figure 1.* Interactions for use case 24, Transfer Rollback due to Failure.
Simple transaction control around a get operation by a CN against and MN.

**Notes**

- Does this include just one service, or sets of services that can be included
  in a transaction?

- Can transactions span multiple MNs? MNs and CNs?

.. _history: https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/design/UseCases/24_uc.txt