.. _UC36:

Use Case 36 - Resolve an Object Location
----------------------------------------

.. index:: Use Case 36, UC36, resolve

Revisions
  View document revision history_.

Goal
  Communicate the locations where a DataONE object can be found

Summary 
  Within DataONE, a registered object may be held on one or more Member Nodes
  (depending on replication policy) and in the case of science metadata, on
  Coordinating Nodes. Clients must be able to ask a Coordinating Node for
  those locations.

  The response to this query is a list of member node identifiers and
  the URL endpoint of their DataONE API implementation.

  The client will need to retrieve information about the node from the node
  registry (Use case 35) in order to accurately determine the URL that can be used to
  retrieve the object bytes (Use case 01).

Actors
  - Coordinating Node
  - Client requesting info

Preconditions 
  - Coordinating Nodes are operational
  - Client has an identifier for an object
  - Object exists in the DataONE system and has been recorded by the
    Coordinating Nodes

Triggers
  - Request by client

Post Conditions
  - Client has more information about the location of the object.


.. 
   @startuml images/36_uc.png

   actor "User" as client
   usecase "12. Authentication" as authen

   package "DataONE"
     actor "Coordinating Node" as CN
     usecase "13. Authorization" as author
     usecase "36. Resolve Object" as resolve
     client -- resolve
     CN -- resolve
     resolve ..> author: <<includes>>
     resolve ..> authen: <<includes>>
   @enduml

.. image::  images/36_uc.png

*Figure 1.* Use case diagram for Use Case 36.


.. 
   @startuml images/36_seq.png
   participant "Client" as itk <<Investigator Toolkit>>
   participant "CRUD API" as c_crud << Coordinating Node >>
   participant "Authorization API" as c_authorize << Coordinating Node >>
   participant "Object Store" as c_store << Coordinating Node >>
   itk -> c_crud: resolve(token, pid)
   activate c_crud
   c_crud -> c_authorize: isAuthorized(token, pid, READ)
   c_crud <- c_authorize: True, False, Err.NotFound
   alt False
     c_crud -> itk: Err.NotAuthorized
   else Err.NotFound
     c_crud -> itk: Err.NotFound
   else OK
     c_crud -> c_store: getSystemMetadata(pid)
     c_store -> c_crud: SystemMetadata
     c_crud -> c_crud: extract object locations
     c_crud -> itk: objectLocations
   end
   deactivate c_crud
   @enduml

.. image::  images/36_seq.png

*Figure 2.* Sequence diagram for implementation of use case 36.

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