.. _UC41:

Use Case 41 - Archive an Object
-------------------------------

.. index:: Use Case 41, archive, UC41


Goal
~~~~

Archive an object so that it is no longer discoverable, but remains accessible
by those that already have a reference to it. 

Summary 
~~~~~~~

A content owner or manager would like to prevent further discovery of an 
object though ensure that references to the object (using its identifier) 
remain valid.

Transition to an archived state is not reversible.

Functionally, archiving an object sets the :attr:`Types.SystemMetadata.archived`
property of the associated System Metadata to *True*. The operation is performed
by calling :func:`MNStorage.archive` or :func:`CNCore.archive`. Since this
operation is an update to System Metadata, :doc:`42_uc` is invoked and the
change is propogated through the system.

Actors
~~~~~~

- Client, a content manager or owner (must have *write* permission)
- Coordinating Node
- Member Node

.. uml::

  @startuml images/41_uc.png
  actor "Owner" as client
  usecase "12. Authentication" as authen
  note top of authen
    Authentication may be provided 
    by an external service
  end note

  actor "<<Coordinating Node>>" as CN
  actor "<<Member Node>>" as MN
  usecase "13. Authorization" as author
  usecase "41. Archive Object" as archive
  usecase "42. Update System Metadata" as update
  client -- archive
  CN -- archive
  MN -- archive
  archive ..> author: <<includes>>
  archive ..> authen: <<includes>>
  archive ..> update: <<includes>>   
  @enduml

**Figure 1.** Use case 41 diagram showing actors and components involved in this
action.


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

- Client has authenticated to the desired level
- Client has write permission on the object
- Object has been synchronized by the Coordinating Nodes
- The object may be replicated to other Member Nodes


Triggers
~~~~~~~~

- A user with write permission calls :func:`CNCore.archive`


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

- The *archive* property of :class:`Types.SystemMetadata` is set to "true"
- System metadata for all replicas of the object is updated
- Search indices are updated to remove the object


Process
~~~~~~~

.. uml::

   @startuml images/41_seq.png
   Actor "Client" as app_client << Application >>
   participant "Replica" as mn <<Member Node>>
   participant "Coordinating Node" as cn <<Coordinating Node>>
   app_client -> app_client: Use Case 12.\nAuthenticate
   note right of mn
     System Metadata
     serialVersion = 1
     dateSyMetadataModified = t1
   end note
   app_client -> mn:archive(PID)
   activate app_client
   activate mn
   mn -> mn: check write access
   mn -> mn: archive=true\ndatesysMetadataModified = now()
   note right of mn
     System Metadata
     serialVersion = 1
     dateSyMetadataModified = t2
   end note

   mn -> app_client: ack
   deactivate app_client
   deactivate mn
   ... __Possibly Long Wait__ ...
   note right of cn
     Coordinating Node detects newere version of 
     System Metadata during the synchronization process,
     retrieves the updated information, verifies 
     acceptable changes, then updates own copy. 
     This process is documented in Use Case 06.
   end note
   mn -> cn: Use Case 06, Synchronization
   cn ->o]: Use Case 42, Update System Metadata
   note right of cn
     The CN ensures that the System Metadata for 
     replicas is updated with the current revision.
     This is documented in Use Case 42.
   end note
   @enduml


*Figure 2.* Sequence diagram for Use Case 41 illustrating the high level 
sequence of operations associated with archiving an object.


Example
~~~~~~~

Using ``curl`` to archive an object. ``ANODE`` can be any Member or Coordinating
Node that has a copy of the object:

.. code-block:: bash

   # The member node base URL
   NODE="https://my.mn.org/base/url"

   # A client certificate with a subject that has write permission on the object
   CERT="my_client_certificate.pem"

   # The identifier of the object to be archived. 
   PID="object.identifier"

   # The provided identifier must be properly URL path encoded
   EPID=URL_Encode(PID)   

   # Invoke the archive operation on the identifier
   curl -E ${CERT} -X PUT "$NODE/V1/archive/${EPID}"