.. _UC42:

Use Case 42 - Update System Metadata Properties
-----------------------------------------------

.. index:: Use Case 42, update system metadata, UC42

Goal
~~~~

Alter mutable properties of System Metadata.

Summary
~~~~~~~

System Metadata provides low level information about each object in DataONE and
inlcudes properties that are immutable and others that may be mutated by
different agents.

This use case desribes the general pattern of updating System Metadata
properties by agents with authority to do so.

In version 1.x of the DataONE infrastructure, System Metadata may only be
altered through Coordinating Nodes (after creation and synchronization).

In version 2.x of the DataONE infrastructure, properties of System Metadata are
managed by the Authoritative Member Node with the exception of Replica
information, which is managed by the Coordinating Nodes. In version 2.x, the
System Metadata serialVersion property is only updated by Coordinating Nodes
during replication processing. Only the Authoritative Member Node can update
dataSysMetadataModified.


Actors
~~~~~~

- A content owner
- Coordinating Node
- Member Node
- Replication target Member Node


Preconditions
~~~~~~~~~~~~~

- Object exists within the DataONE system


Triggers
~~~~~~~~

- A user or agent wishes to alter mutable properties of System Metadata for an
  object.


Post Conditions
~~~~~~~~~~~~~~~

- The properties of System Metadata are altered
- All replicas of System Metadata are in sync
- Search indices are updated to reflect the change


Process
~~~~~~~

.. uml::

  autonumber
  actor Bob
  participant "Authoritative" as MN <<Member Node>>
  participant "Coordinating Node" as CN <<Coordinating Node>>
  participant "Replica" as MN_repl <<Member Node>>
  note right of CN
    System Metadata
    Serial Version = 1
    dateSysMetadataModified = t1
  end note
  note right of MN
    System Metadata
    Serial Version = 1
    dateSysMetadataModified = t1
  end note
  note right of MN_repl
    System Metadata
    Serial Version = 1
    dateSysMetadataModified = t1
  end note
  Bob -> CN : Alter Property
  activate CN
  CN -> CN : update property\nserialVersion++\ndateSysMetadataModified = now()
  note right of CN
    System Metadata
    Serial Version = 2
    dateSysMetadataModified = t2
  end note
  CN ->] : <<internal>> Notify System Metadata Changed
  note right of CN
    Indexing and other CN services
    are notified of the change
  end note
  CN -> Bob: ack
  deactivate CN

  group Update All Member Nodes
  CN -> MN: systemMetadataChanged
  activate MN
  CN->MN_repl: systemMetadataChanged
  activate MN_repl
  MN -> CN: getSystemMetadata
  activate CN
  CN -> MN: SystemMetadata
  deactivate CN
  MN -> MN : update property
  note right of MN
    System Metadata
    Serial Version = 2
    dateSysMetadataModified = t2
  end note
  deactivate MN
  MN_repl -> CN: getSystemMetadata
  activate CN
  CN -> MN_repl: SystemMetadata
  deactivate CN
  MN_repl -> MN_repl : update property
  note right of MN_repl
    System Metadata
    Serial Version = 2
    dateSysMetadataModified = t2
  end note
  deactivate MN_repl
  end
  @enduml


**Figure 2a.** Sequence diagram for Use Case 42 illustrating the high level
sequence of operations associated with altering system metadata of an object for
version 1.x infrastructure where Coordinating Nodes are the authoritative source
for System Metadata. In this scenario, user Bob updates properties of System
Metadata (e.g. Access Policy) for an object, and that change is propogated to
copies throughout the federation.


.. uml::

  autonumber
  actor Bob
  participant "Authoritative" as MN <<Member Node>>
  participant "Coordinating Node" as CN <<Coordinating Node>>
  participant "Replica" as MN_repl <<Member Node>>
  Bob -> MN: getSystemMetadata
  note right of MN
   System Metadata
   serialVersion = 10
   dateSysMetadataModified = t1
  end note
  note right of CN
   System Metadata
   serialVersion = 10
   dateSysMetadataModified = t1
  end note
  note right of MN_repl
   System Metadata
   serialVersion = 10
   dateSysMetadataModified = t1
  end note
  activate MN
  MN -> Bob: dateSysMetadataModified = t1
  deactivate MN
  Bob -> MN : updateSystemMetadata\ndateSysMetadataModified=t1
  activate MN
  MN -> MN: check dateSysMetadataModified == t1
  MN -> MN: update properties\ndateSysMetadataModified = now()
  note right of MN
    System Metadata
    serialVersion = 10
    dateSysMetadataModified = t2

    Mutable properties other than Replica
    entries may be updated by a user
    with appropriate permission.
  end note
  MN -> CN: synchronize
  activate CN
  CN -> CN: schedule update
  CN -> MN: ack
  deactivate CN
  MN -> Bob: ack
  deactivate MN

  ... __Potentially long delay__ ...

  CN -> MN : getSystemMetadata
  activate CN
  activate MN
  MN -> CN: systemMetadata
  deactivate MN
  CN -> CN: update properties
  note right of CN
   System Metadata
   serialVersion = 10
   dateSysMetadataModified = t2
  end note
  CN ->] : <<internal>> Notify System Metadata Changed
  note right of CN
    Indexing and other CN services
    are notified of the change
  end note

  group Update only replica nodes
  CN -> MN_repl: systemMetadataChanged
  activate MN_repl
  deactivate CN

  MN_repl -> CN: getSystemMetadata
  activate CN
  CN -> MN_repl: SystemMetadata
  deactivate CN
  note right of MN_repl
   System Metadata
   serialVersion = 10
   dateSysMetadataModified = t2

   On replica MNs, all mutable System
   Metadata properties may be updated
   by a CN
  end note
  MN_repl -> MN_repl: update properties
  deactivate MN_repl
  end
  @enduml


**Figure 2b.** Sequence diagram for Use Case 42 illustrating the high level
sequence of operations associated with altering system metadata of an object for
version 2.x infrastructure where Member Nodes are the authoritative source
for System Metadata except for replication information (for which Coordinating
Nodes are authoritative). In this scenario, user Bob updates properties of
System Metadata (e.g. Access Policy) for an object, and that change is
propogated to copies throughout the federation.