Warning: These documents are under active development and subject to change (version 2.1.0-beta).
The latest release documents are at: https://purl.dataone.org/architecture

Use Case 01 - Get Object Identified by PID

Goal

Retrieve an object identified by PID.

Summary

A client has an identifier for some object within the DataONE system and is attempting to retrieve the referenced object from a node (Member Node or Coordinating Node). If the object exists on the node and the user has READ permission on the object, then the bytes of that object are returned, otherwise an error condition occurs.

This low level operation assumes that the client knows that the desired object is available on the target node. The normal process for retrieving an object given only the identifier is to first resolve the object, then retrieve the object from one of the identified nodes. Resolution is described in UC36.

Actors

  • Client requesting object
  • Coordinating Node
  • Member Node

Preconditions

  • Client has authenticated to the desired level (e.g. client may not have authenticated, so access might be anonymous).

Triggers

  • An object is requested from the DataONE system.

Post Conditions

  • The client has a copy of the object bytes (or an error message in the case of failure)
  • The node event log is updated with the results of the operation
  • Watchers are notified of the event.

@startuml images/01_uc.png actor "User" 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 "01. Get Object" as GET usecase "16. Log event" as log usecase "21. Notify subscribers" as subscribe usecase "36. Resolve object" as resolve client -- GET CN -- GET MN -- GET GET ..> author: <<includes>>\n[optional] GET ..> authen: <<includes>>\n[optional] GET ..> log: <<includes>> GET ..> subscribe: <<includes>> GET ..> resolve: <<includes>>\n[optional] @enduml

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

../../_images/01_seq.png

@startuml images/01_seq.png participant "Client" as app_client << Application >> participant "Read API" as n_crud << Node >> participant "Authorization API" as n_authorize << Node >> participant "Object Store" as n_ostore << Node >> app_client -> n_crud: get(session, PID) n_crud -> n_authorize: isAuthorized(session, PID, READ) n_crud <- n_authorize: True, False, Err.NotFound alt NotFound app_client <- n_crud: Err.NotFound else False app_client <- n_crud: Err.NotAuthorized else True n_crud -> n_ostore: read(PID) n_crud <- n_ostore: bytes n_crud --> n_crud: log(PID, READ) app_client <- n_crud: bytes end @enduml

Figure 2. Sequence diagram for Use Case 01 illustrating the sequence for retrieving an object identified by a PID from the DataONE system. No distinction is made between Member Node and Coordinating Node implementation as they are identical at this level of detail.

Notes

  1. For the GET operation, should isAuth() be performed only by CNs? Relying on the MN system metadata requires trusted implementation of the MN system and consistency of system metadata across all MNs (which will be the case, though with uncertain latency). Requiring all isAuth() operations to be performed by CNs will increase trust in the operation (assuming the operation is not spoofed by a MN) though will increase load on CNs. This should be specified in the Authorization use case.
  2. Data sent to watchers might include: timestamp, object identifier, user id, IP of client.

This material is based upon work supported by the National Science Foundation under Grant Numbers 083094 and 1430508.

Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.