..
WARNING! This file is automatically generated. Edits will be lost.
Data Types in CICore
--------------------
.. module:: Types
:synopsis: Catalog of data types (structures) used by the DataONE cicore.
**Quick Reference**
- :class:`Types.AccessPolicy`
- :class:`Types.AccessRule`
- :class:`Types.Checksum`
- :class:`Types.ChecksumAlgorithm`
- :class:`Types.ChecksumAlgorithmList`
- :class:`Types.CrontabEntry`
- :class:`Types.CrontabEntrySeconds`
- :class:`Types.Event`
- :class:`Types.Group`
- :class:`Types.Identifier`
- :class:`Types.Log`
- :class:`Types.LogEntry`
- :class:`Types.Node`
- :class:`Types.NodeList`
- :class:`Types.NodeReference`
- :class:`Types.NodeReplicationPolicy`
- :class:`Types.NodeState`
- :class:`Types.NodeType`
- :class:`Types.NonEmptyNoWhitespaceString800`
- :class:`Types.NonEmptyString`
- :class:`Types.NonEmptyString800`
- :class:`Types.ObjectFormat`
- :class:`Types.ObjectFormatIdentifier`
- :class:`Types.ObjectFormatList`
- :class:`Types.ObjectInfo`
- :class:`Types.ObjectList`
- :class:`Types.ObjectLocation`
- :class:`Types.ObjectLocationList`
- :class:`Types.Permission`
- :class:`Types.Person`
- :class:`Types.Ping`
- :class:`Types.Replica`
- :class:`Types.ReplicationPolicy`
- :class:`Types.ReplicationStatus`
- :class:`Types.Schedule`
- :class:`Types.Service`
- :class:`Types.ServiceMethodRestriction`
- :class:`Types.ServiceName`
- :class:`Types.ServiceVersion`
- :class:`Types.Services`
- :class:`Types.Session`
- :class:`Types.Slice`
- :class:`Types.Subject`
- :class:`Types.SubjectInfo`
- :class:`Types.SubjectList`
- :class:`Types.Synchronization`
- :class:`Types.SystemMetadata`
.. image:: images/classes_combined.png
..
@startuml images/classes_combined.png
ChecksumAlgorithm --|> xs.string
CrontabEntry --|> xs.token
CrontabEntrySeconds --|> xs.token
enum Event
Event : create
Event : read
Event : update
Event : delete
Event : replicate
Event : synchronization_failed
Event : replication_failed
enum NodeState
NodeState : up
NodeState : down
NodeState : unknown
enum NodeType
NodeType : mn
NodeType : cn
NodeType : Monitor
NonEmptyString --|> xs.string
ObjectFormatIdentifier --|> NonEmptyString
NonEmptyString800 --|> NonEmptyString
NonEmptyNoWhitespaceString800 --|> NonEmptyString800
enum Permission
Permission : read
Permission : write
Permission : changePermission
enum ReplicationStatus
ReplicationStatus : queued
ReplicationStatus : requested
ReplicationStatus : completed
ReplicationStatus : failed
ReplicationStatus : invalidated
ServiceName --|> NonEmptyString
ServiceVersion --|> NonEmptyString
class AccessPolicy {
+ allow : AccessRule[1..*]
}
AccessPolicy .. AccessRule
class AccessRule {
+ subject : Subject[1..*]
+ permission : Permission[1..*]
}
AccessRule .. Subject
AccessRule .. Permission
class Checksum {
+ algorithm : ChecksumAlgorithm
}
Checksum .. ChecksumAlgorithm
Checksum --|> xs.string
class ChecksumAlgorithmList {
+ algorithm : ChecksumAlgorithm[1..*]
}
ChecksumAlgorithmList .. ChecksumAlgorithm
class Group {
+ subject : Subject[1..1]
+ groupName : NonEmptyString[1..1]
+ hasMember : Subject[0..*]
+ rightsHolder : Subject[1..*]
}
Group .. Subject
Group .. NonEmptyString
class Identifier {
}
Identifier --|> NonEmptyNoWhitespaceString800
class Log {
+ logEntry : LogEntry[0..*]
}
Log .. LogEntry
Log --|> Slice
class LogEntry {
+ entryId : NonEmptyString[1..1]
+ identifier : Identifier[1..1]
+ ipAddress : xs.string[1..1]
+ userAgent : xs.string[1..1]
+ subject : Subject[1..1]
+ event : Event[1..1]
+ dateLogged : xs.dateTime[1..1]
+ nodeIdentifier : NodeReference[1..1]
}
LogEntry .. NonEmptyString
LogEntry .. Identifier
LogEntry .. xs.string
LogEntry .. Subject
LogEntry .. Event
LogEntry .. xs.dateTime
LogEntry .. NodeReference
class Node {
+ identifier : NodeReference[1..1]
+ name : NonEmptyString[1..1]
+ description : NonEmptyString[1..1]
+ baseURL : xs.anyURI[1..1]
+ services : Services[0..1]
+ synchronization : Synchronization[0..1]
+ nodeReplicationPolicy : NodeReplicationPolicy[0..1]
+ ping : Ping[0..1]
+ subject : Subject[0..*]
+ contactSubject : Subject[1..*]
+ replicate : xs.boolean[1.. 1]
+ synchronize : xs.boolean[1.. 1]
+ type : NodeType[1.. 1]
+ state : NodeState[1.. 1]
}
Node .. NodeReference
Node .. NonEmptyString
Node .. xs.anyURI
Node .. Services
Node .. Synchronization
Node .. NodeReplicationPolicy
Node .. Ping
Node .. Subject
Node .. xs.boolean
Node .. NodeType
Node .. NodeState
class NodeReplicationPolicy {
+ maxObjectSize : xs.unsignedLong[0..1]
+ spaceAllocated : xs.unsignedLong[0..1]
+ allowedNode : NodeReference[0..*]
+ allowedObjectFormat : ObjectFormatIdentifier[0..*]
}
NodeReplicationPolicy .. xs.unsignedLong
NodeReplicationPolicy .. NodeReference
NodeReplicationPolicy .. ObjectFormatIdentifier
class NodeList {
+ node : Node[1..*]
}
NodeList .. Node
class NodeReference {
}
NodeReference --|> NonEmptyString
class ObjectFormat {
+ formatId : ObjectFormatIdentifier[1..1]
+ formatName : xs.string[1..1]
+ formatType : xs.string[1..1]
}
ObjectFormat .. ObjectFormatIdentifier
ObjectFormat .. xs.string
class ObjectFormatList {
+ objectFormat : ObjectFormat[1..*]
}
ObjectFormatList .. ObjectFormat
ObjectFormatList --|> Slice
class ObjectInfo {
+ identifier : Identifier[1..1]
+ formatId : ObjectFormatIdentifier[1..1]
+ checksum : Checksum[1..1]
+ dateSysMetadataModified : xs.dateTime[1..1]
+ size : xs.unsignedLong[1..1]
}
ObjectInfo .. Identifier
ObjectInfo .. ObjectFormatIdentifier
ObjectInfo .. Checksum
ObjectInfo .. xs.dateTime
ObjectInfo .. xs.unsignedLong
class ObjectList {
+ objectInfo : ObjectInfo[0..*]
}
ObjectList .. ObjectInfo
ObjectList --|> Slice
class ObjectLocation {
+ nodeIdentifier : NodeReference[1..1]
+ baseURL : xs.anyURI[1..1]
+ version : ServiceVersion[1..*]
+ url : xs.anyURI[1..1]
+ preference : xs.int[0..1]
}
ObjectLocation .. NodeReference
ObjectLocation .. xs.anyURI
ObjectLocation .. ServiceVersion
ObjectLocation .. xs.int
class ObjectLocationList {
+ identifier : Identifier[1..1]
+ objectLocation : ObjectLocation[0..*]
}
ObjectLocationList .. Identifier
ObjectLocationList .. ObjectLocation
class Person {
+ subject : Subject[1..1]
+ givenName : NonEmptyString[1..*]
+ familyName : NonEmptyString[1..1]
+ email : NonEmptyString[0..*]
+ isMemberOf : Subject[0..*]
+ equivalentIdentity : Subject[0..*]
+ verified : xs.boolean[0..1]
}
Person .. Subject
Person .. NonEmptyString
Person .. xs.boolean
class Ping {
+ success : xs.boolean[0..1]
+ lastSuccess : xs.dateTime[0..1]
}
Ping .. xs.boolean
Ping .. xs.dateTime
class Replica {
+ replicaMemberNode : NodeReference[1..1]
+ replicationStatus : ReplicationStatus[1..1]
+ replicaVerified : xs.dateTime[1..1]
}
Replica .. NodeReference
Replica .. ReplicationStatus
Replica .. xs.dateTime
class ReplicationPolicy {
+ preferredMemberNode : NodeReference[0..*]
+ blockedMemberNode : NodeReference[0..*]
+ replicationAllowed : xs.boolean[0.. 1]
+ numberReplicas : xs.int[0.. 1]
}
ReplicationPolicy .. NodeReference
ReplicationPolicy .. xs.boolean
ReplicationPolicy .. xs.int
class Service {
+ restriction : ServiceMethodRestriction[0..*]
+ name : ServiceName[1.. 1]
+ version : ServiceVersion[1.. 1]
+ available : xs.boolean[0.. 1]
}
Service .. ServiceMethodRestriction
Service .. ServiceName
Service .. ServiceVersion
Service .. xs.boolean
class ServiceMethodRestriction {
}
ServiceMethodRestriction --|> SubjectList
class Services {
+ service : Service[1..*]
}
Services .. Service
class Session {
+ subject : Subject[1..1]
+ subjectInfo : SubjectInfo[0..1]
}
Session .. Subject
Session .. SubjectInfo
class Schedule {
+ hour : CrontabEntry[1..1]
+ mday : CrontabEntry[1..1]
+ min : CrontabEntry[1..1]
+ mon : CrontabEntry[1..1]
+ sec : CrontabEntrySeconds[1..1]
+ wday : CrontabEntry[1..1]
+ year : CrontabEntry[1..1]
}
Schedule .. CrontabEntry
Schedule .. CrontabEntrySeconds
class Slice {
+ count : xs.int[1..1]
+ start : xs.int[1..1]
+ total : xs.int[1..1]
}
Slice .. xs.int
class Synchronization {
+ schedule : Schedule[1..1]
+ lastHarvested : xs.dateTime[0..1]
+ lastCompleteHarvest : xs.dateTime[0..1]
}
Synchronization .. Schedule
Synchronization .. xs.dateTime
class Subject {
}
Subject --|> NonEmptyString
class SubjectInfo {
+ person : Person[0..*]
+ group : Group[0..*]
}
SubjectInfo .. Person
SubjectInfo .. Group
class SubjectList {
+ subject : Subject[0..*]
}
SubjectList .. Subject
class SystemMetadata {
+ serialVersion : xs.unsignedLong[0..1]
+ identifier : Identifier[1..1]
+ formatId : ObjectFormatIdentifier[1..1]
+ size : xs.unsignedLong[1..1]
+ checksum : Checksum[1..1]
+ submitter : Subject[0..1]
+ rightsHolder : Subject[1..1]
+ accessPolicy : AccessPolicy[0..1]
+ replicationPolicy : ReplicationPolicy[0..1]
+ obsoletes : Identifier[0..1]
+ obsoletedBy : Identifier[0..1]
+ archived : xs.boolean[0..1]
+ dateUploaded : xs.dateTime[0..1]
+ dateSysMetadataModified : xs.dateTime[0..1]
+ originMemberNode : NodeReference[0..1]
+ authoritativeMemberNode : NodeReference[0..1]
+ replica : Replica[0..*]
}
SystemMetadata .. xs.unsignedLong
SystemMetadata .. Identifier
SystemMetadata .. ObjectFormatIdentifier
SystemMetadata .. Checksum
SystemMetadata .. Subject
SystemMetadata .. AccessPolicy
SystemMetadata .. ReplicationPolicy
SystemMetadata .. xs.boolean
SystemMetadata .. xs.dateTime
SystemMetadata .. NodeReference
SystemMetadata .. Replica
@enduml
.. include:: Types_include.txt
.. ######
.. class:: ChecksumAlgorithm
The cryptographic hash algorithm used to calculate a checksum. DataONE recognizes the Library of Congress list of cryptographic hash algorithms that can be used as names in this field, and specifically uses the *madsrdf:authoritativeLabel* field as the name of the algorithm in this field. See: `Library of Congress Cryptographic Algorithm Vocabulary`_. All compliant implementations must support at least SHA-1 and MD5, but may support other algorithms as well.
Valid entries include: SHA-1, MD5
The default checksum is *SHA-1*.
.. _Library of Congress Cryptographic Algorithm Vocabulary: http://id.loc.gov/vocabulary/cryptographicHashFunctions.rdf
.. code-block:: xml
.. image:: images/class_ChecksumAlgorithm.png
..
@startuml images/class_ChecksumAlgorithm.png
ChecksumAlgorithm --|> xs.string
@enduml
.. ######
.. class:: CrontabEntry
A single value in the series of values that together form a single crontab entry. The format follows the syntax conventions defined by the `Quartz Scheduler`_, as excerpted here under the Apache 2 license:
.. _Quartz Scheduler: http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html
.. include:: Types_crontabentry.txt
.. code-block:: xml
.. image:: images/class_CrontabEntry.png
..
@startuml images/class_CrontabEntry.png
CrontabEntry --|> xs.token
@enduml
.. ######
.. class:: CrontabEntrySeconds
A restriction on the seconds field in a single Schedule entry, following the syntax conventions defined by the `Quartz Scheduler`_.
The wildcard character value is not allowed in this (seconds) field as this would create an impractical synchronization schedule
.. _Quartz Scheduler: http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html
.. code-block:: xml
.. image:: images/class_CrontabEntrySeconds.png
..
@startuml images/class_CrontabEntrySeconds.png
CrontabEntrySeconds --|> xs.token
@enduml
.. ######
.. class:: Event
The controlled list of events that are logged, which will include *create*, *update*, *delete*, *read*, *replicate*, *synchronization_failed* and *replication_failed* events.
.. code-block:: xml
.. image:: images/class_Event.png
..
@startuml images/class_Event.png
enum Event
Event : create
Event : read
Event : update
Event : delete
Event : replicate
Event : synchronization_failed
Event : replication_failed
@enduml
.. ######
.. class:: NodeState
An indicator of the current node accessibility. Nodes that are marked *down* are inaccessible for service operations, those that are *up* are in the normal accessible state, and *unknown* indicates that the state has not been determined yet.
.. code-block:: xml
.. image:: images/class_NodeState.png
..
@startuml images/class_NodeState.png
enum NodeState
NodeState : up
NodeState : down
NodeState : unknown
@enduml
.. ######
.. class:: NodeType
The type of this node, which is either *mn* for Member Nodes, or *cn* for Coordinating Nodes.
.. code-block:: xml
.. image:: images/class_NodeType.png
..
@startuml images/class_NodeType.png
enum NodeType
NodeType : mn
NodeType : cn
NodeType : Monitor
@enduml
.. ######
.. class:: NonEmptyString
A derived string type with at least length 1 and it must contain non-whitespace.
.. code-block:: xml
.. image:: images/class_NonEmptyString.png
..
@startuml images/class_NonEmptyString.png
NonEmptyString --|> xs.string
@enduml
.. ######
.. class:: ObjectFormatIdentifier
A string used to identify an instance of :class:`Types.ObjectFormat` and MUST be unique within an instance of :class:`Types.ObjectFormatList`.
.. code-block:: xml
.. image:: images/class_ObjectFormatIdentifier.png
..
@startuml images/class_ObjectFormatIdentifier.png
ObjectFormatIdentifier --|> NonEmptyString
@enduml
.. ######
.. class:: NonEmptyString800
An NonEmptyString800 is a NonEmptyString string with a maximum length of 800 characters.
.. code-block:: xml
.. image:: images/class_NonEmptyString800.png
..
@startuml images/class_NonEmptyString800.png
NonEmptyString800 --|> NonEmptyString
@enduml
.. ######
.. class:: NonEmptyNoWhitespaceString800
A NonEmptyNoWhitespaceString800 is a NonEmptyString800 string that doesn't allow whitespace characters (space, tab, newline, carriage return). Unicode whitespace characters outside of the ASCII character set need to be checked programmatically.
.. code-block:: xml
.. image:: images/class_NonEmptyNoWhitespaceString800.png
..
@startuml images/class_NonEmptyNoWhitespaceString800.png
NonEmptyNoWhitespaceString800 --|> NonEmptyString800
@enduml
.. ######
.. class:: Permission
A string value indicating the set of actions that can be performed on a resource as specified in an access policy. The set of permissions include the ability to read a resource (*read*), modify a resource (*write*), and to change the set of access control policies for a resource (*changePermission*). Permission levels are cumulative, in that write permission implicitly grants read access, and changePermission permission implicitly grants write access (and therefore read as well). If a subject is granted multiple permissions, the highest level of access applies.
.. code-block:: xml
.. image:: images/class_Permission.png
..
@startuml images/class_Permission.png
enum Permission
Permission : read
Permission : write
Permission : changePermission
@enduml
.. ######
.. class:: ReplicationStatus
An enumerated string value indicating the current state of a replica of an object. When an object identified needs to be replicated, it is added to the replication task queue and is marked as *queued*; a CN will pick up that task and request that it be replicated to a MN and marks that it as *requested*; when a MN finishes replicating the object, it informs the CN that it is finished and it is marked as *completed*.
If an MN is unable to complete replication, the replication status is marked as *failed*.
Periodically a CN checks each replica to be sure it is both available and valid (matching checksum with original), and if it is either inaccessible or invalid then it marks it as *invalidated*, which indicates that the object replication needs to be invoked again.
The replication process is described in Use Case 09 (:doc:`/design/UseCases/09_uc`).
.. code-block:: xml
.. image:: images/class_ReplicationStatus.png
..
@startuml images/class_ReplicationStatus.png
enum ReplicationStatus
ReplicationStatus : queued
ReplicationStatus : requested
ReplicationStatus : completed
ReplicationStatus : failed
ReplicationStatus : invalidated
@enduml
.. ######
.. class:: ServiceName
The name of a service that is available on a Node.
.. code-block:: xml
.. image:: images/class_ServiceName.png
..
@startuml images/class_ServiceName.png
ServiceName --|> NonEmptyString
@enduml
.. ######
.. class:: ServiceVersion
The version of a service provided by a Node. Service versions are expressed as version labels such as "v1", "v2". DataONE services are released only as major service versions; patches to services are not indicated in this version label.
.. code-block:: xml
.. image:: images/class_ServiceVersion.png
..
@startuml images/class_ServiceVersion.png
ServiceVersion --|> NonEmptyString
@enduml
.. ######
.. class:: AccessPolicy
A set of rules that specifies as a whole the allowable permissions that a given user, group, or system has for accessing a resource, including data, metadata, resource map, and service resources. An access policy consists of a sequence of allow rules that grant permissions to principals, which can be individual users, groups of users, symbolic users, or systems and services.
.. attribute:: allow
Type: :class:`Types.AccessRule`
.. code-block:: xml
.. image:: images/class_AccessPolicy.png
..
@startuml images/class_AccessPolicy.png
class AccessPolicy {
+ allow : AccessRule[1..*]
}
AccessPolicy .. AccessRule
@enduml
.. ######
.. class:: AccessRule
A rule that is used to allow a :term:`subject` to perform an action (such as read or write) on an object in DataONE. Rules are tuples (subject, permission) specifying which permissions are allowed for the subjects(s). If a subject is granted multiple permissions, the highest level of access applies. The resource on which the access control rules are being applied is determined by the containing :term:`SystemMetadata` document, or in the case of methods such as :func:`CNAuthorization.setAccessPolicy`, by the :term:`pid` in the method parameters.
Access control rules are specified by the :term:`Origin Member Node` when the object is first registered in DataONE. If no rules are specified at that time, then the object is deemed to be private and the only user with access to the object (read, write, or otherwise) is the :term:`Rights Holder`.
.. attribute:: subject
Type: :class:`Types.Subject`
.. attribute:: permission
Type: :class:`Types.Permission`
.. code-block:: xml
.. image:: images/class_AccessRule.png
..
@startuml images/class_AccessRule.png
class AccessRule {
+ subject : Subject[1..*]
+ permission : Permission[1..*]
}
AccessRule .. Subject
AccessRule .. Permission
@enduml
.. ######
.. class:: Checksum
Represents the value of a computed :term:`checksum` expressed as a hexadecimal formatted version of the message digest. Note that these hex values should be treated as case-insensitive strings, in that leading zeros must be preserved, and digests can use a mixture of upper and lower case letters to represent the hex values. Comparison algorithms MUST be able to handle any variant of these representations (e.g., by performing a case-insensitive string match on hex digests from the same algorithm).
.. code-block:: xml
.. image:: images/class_Checksum.png
..
@startuml images/class_Checksum.png
class Checksum {
+ algorithm : ChecksumAlgorithm
}
Checksum .. ChecksumAlgorithm
Checksum --|> xs.string
@enduml
.. ######
.. class:: ChecksumAlgorithmList
Represents a list of :term:`checksum` algorithms.
.. attribute:: algorithm
Type: :class:`Types.ChecksumAlgorithm`
.. code-block:: xml
.. image:: images/class_ChecksumAlgorithmList.png
..
@startuml images/class_ChecksumAlgorithmList.png
class ChecksumAlgorithmList {
+ algorithm : ChecksumAlgorithm[1..*]
}
ChecksumAlgorithmList .. ChecksumAlgorithm
@enduml
.. ######
.. class:: Group
Group represents metadata about a :term:`Subject` that represents a collection of other Subjects. Groups provide a convenient mechanism to express access rules for certain roles that are not necessarily tied to particular :term:`principals` over time.
.. attribute:: subject
Type: :class:`Types.Subject`
The unique, immutable identifier of the :term:`group`. Group subjects must not be reused, and so they are both immutable and can not be deleted from the DataONE system.
.. attribute:: groupName
Type: :class:`Types.NonEmptyString`
The name of the Group.
.. attribute:: hasMember
Type: :class:`Types.Subject`
A :term:`Subject` that is a member of this group, expressed using the unique identifier for that Subject.
.. attribute:: rightsHolder
Type: :class:`Types.Subject`
Represents the list of owners of this :term:`group`. All groups are readable by anyone in the DataONE system, but can only be modified by subjects listed in *rightsHolder* fields. Designation as a :term:`rightsHolder` allows the subject, or their equivalent identities, to make changes to the mutable properties of the group, including its name, membership list and rights holder list. The subject of the group itself is immutable.
.. code-block:: xml
.. image:: images/class_Group.png
..
@startuml images/class_Group.png
class Group {
+ subject : Subject[1..1]
+ groupName : NonEmptyString[1..1]
+ hasMember : Subject[0..*]
+ rightsHolder : Subject[1..*]
}
Group .. Subject
Group .. NonEmptyString
@enduml
.. ######
.. class:: Identifier
An :term:`identifier` (:term:`PID`) in the DataONE system that is used to uniquely and globally identify an object. Identifiers can not be reused once assigned. Identifiers can not be deleted from the DataONE system.Identifiers are represented by a Unicode string of printable characters, excluding :term:`whitespace`. All representations of identifiers must be encoded in 7-bit ASCII or UTF-8.
Identifiers have a maximum length of 800 characters, and a variety of other properties designed for preservation and longevity. Some discussion on this is described in the `PID documentation`_ and in decision `ticket 577`_.
.. _ticket 577: https://redmine.dataone.org/issues/577
.. _PID documentation: http://mule1.dataone.org/ArchitectureDocs-current/design/PIDs.html
.. code-block:: xml
.. image:: images/class_Identifier.png
..
@startuml images/class_Identifier.png
class Identifier {
}
Identifier --|> NonEmptyNoWhitespaceString800
@enduml
.. ######
.. class:: Log
Represents a collection of :class:`Types.LogEntry` elements, used to transfer log information between DataONE components.
.. code-block:: xml
.. image:: images/class_Log.png
..
@startuml images/class_Log.png
class Log {
+ logEntry : LogEntry[0..*]
}
Log .. LogEntry
Log --|> Slice
@enduml
.. ######
.. class:: LogEntry
A single log entry as reported by a Member Node or Coordinating Node through the :func:`MNCore.getLogRecords` or :func:`CNCore.getLogRecords` methods.
.. attribute:: entryId
Type: :class:`Types.NonEmptyString`
A unique identifier for this log entry. The identifier should be unique for a particular node; This is not drawn from the same value space as other identifiers in DataONE, and so is not subjec to the same restrictions.
.. attribute:: identifier
Type: :class:`Types.Identifier`
The :term:`identifier` of the object that was the target of the operation which generated this log entry.
.. attribute:: ipAddress
Type: :class:`Types.xs.string`
The IP address, as reported by the service receiving the request, of the request origin.
.. attribute:: userAgent
Type: :class:`Types.xs.string`
The user agent of the client making the request, as reported in the User-Agent HTTP header.
.. attribute:: subject
Type: :class:`Types.Subject`
The :term:`Subject` used for making the request. This may be the DataONE :term:`public` user if the request is not authenticated, otherwise it will be the *Subject* of the certificate used for authenticating the request.
.. attribute:: event
Type: :class:`Types.Event`
An entry from the :class:`Types.Event` enumeration indicating the type of operation that triggered the log message.
.. attribute:: dateLogged
Type: :class:`Types.xs.dateTime`
A :class:`Types.DateTime` time stamp indicating when the event triggering the log message ocurred. Note that all time stamps in DataONE are in UTC.
.. attribute:: nodeIdentifier
Type: :class:`Types.NodeReference`
The unique identifier for the node where the log message was generated.
.. code-block:: xml
.. image:: images/class_LogEntry.png
..
@startuml images/class_LogEntry.png
class LogEntry {
+ entryId : NonEmptyString[1..1]
+ identifier : Identifier[1..1]
+ ipAddress : xs.string[1..1]
+ userAgent : xs.string[1..1]
+ subject : Subject[1..1]
+ event : Event[1..1]
+ dateLogged : xs.dateTime[1..1]
+ nodeIdentifier : NodeReference[1..1]
}
LogEntry .. NonEmptyString
LogEntry .. Identifier
LogEntry .. xs.string
LogEntry .. Subject
LogEntry .. Event
LogEntry .. xs.dateTime
LogEntry .. NodeReference
@enduml
.. ######
.. class:: Node
A set of values that describe a member or coordinating node, its Internet location, and the services it supports. Several nodes may exist on a single physical device or hostname.
.. attribute:: identifier
Type: :class:`Types.NodeReference`
A unique identifier for the node of the form ``urn:node:NODEID`` where NODEID is the node specific identifier. This value MUST NOT change for future implementations of the same node, whereas the *baseURL* may change in the future.
.. attribute:: name
Type: :class:`Types.NonEmptyString`
A human readable name of the Node. This name can be used as a label in many systems to represent the node, and thus should be short, but understandable.
.. attribute:: description
Type: :class:`Types.NonEmptyString`
Description of a Node, explaining the community it serves and other relevant information about the node, such as what content is maintained by this node and any other free style notes.
.. attribute:: baseURL
Type: :class:`Types.xs.anyURI`
The base URL of the node, indicating the protocol, fully qualified domain name, and path to the implementing service, excluding the version of the API. e.g. ``https://server.example.edu/app/d1/mn`` rather than ``https://server.example.edu/app/d1/mn/v1``
.. attribute:: services
Type: :class:`Types.Services`
A list of services that are provided by this node. Used in node descriptions so that nodes can provide metadata about each service they implement and support.
.. attribute:: synchronization
Type: :class:`Types.Synchronization`
Configuration information for the process by which content is harvested from Member Nodes to Coordinating Nodes. This includes the schedule on which harvesting should occur, and metadata about the last synchronization attempts for the node.
.. attribute:: nodeReplicationPolicy
Type: :class:`Types.NodeReplicationPolicy`
The replication policy for this node that expresses constraints on object size, total objects, source nodes, and object format types. A node may want to restrict replication from only certain peer nodes, may have file size limits, total allocated size limits, or may want to focus on being a replica target for domain-specific object formats.
.. attribute:: ping
Type: :class:`Types.Ping`
Stored results from the :func:`MNCore.ping` and :func:`CNCore.ping` methods.
.. attribute:: subject
Type: :class:`Types.Subject`
The :term:`Subject` of this node, which can be repeated as needed. The *Node.subject* represents the identifier of the node that would be found in X.509 certificates used to securely communicate with this node. Thus, it is an :term:`X.509 Distinguished Name` that applies to the host on which the Node is operating. When (and if) this hostname changes the new subject for the node would be added to the Node to track the subject that has been used in various access control rules over time.
.. attribute:: contactSubject
Type: :class:`Types.Subject`
The appropriate person or group to contact regarding the disposition, management, and status of this Member Node. The *Node.contactSubject* is an :term:`X.509 Distinguished Name` for a person or group that can be used to look up current contact details (e.g., name, email address) for the contact in the DataONE Identity service. DataONE uses the *contactSubject* to provide notices of interest to DataONE nodes, including information such as policy changes, maintenance updates, node outage notifications, among other information useful for administering a node. Each node that is registered with DataONE must provide at least one *contactSubject* that has been :term:`verified` with DataONE.
.. attribute:: replicate
Type: :class:`Types.xs.boolean`
Set to *true* if the node is willing to be a :term:`replication target`, otherwise *false*.
.. attribute:: synchronize
Type: :class:`Types.xs.boolean`
Set to *true* if the node should be :term:`synchronized` by a Coordinating Node, otherwise *false*.
.. attribute:: type
Type: :class:`Types.NodeType`
The type of the node (Coordinating, Member), chosen from the :class:`Types.NodeType` type.
.. attribute:: state
Type: :class:`Types.NodeState`
The state of the node (*up*, *down*), chosen from the :class:`Types.NodeState` type.
.. code-block:: xml
.. image:: images/class_Node.png
..
@startuml images/class_Node.png
class Node {
+ identifier : NodeReference[1..1]
+ name : NonEmptyString[1..1]
+ description : NonEmptyString[1..1]
+ baseURL : xs.anyURI[1..1]
+ services : Services[0..1]
+ synchronization : Synchronization[0..1]
+ nodeReplicationPolicy : NodeReplicationPolicy[0..1]
+ ping : Ping[0..1]
+ subject : Subject[0..*]
+ contactSubject : Subject[1..*]
+ replicate : xs.boolean[1.. 1]
+ synchronize : xs.boolean[1.. 1]
+ type : NodeType[1.. 1]
+ state : NodeState[1.. 1]
}
Node .. NodeReference
Node .. NonEmptyString
Node .. xs.anyURI
Node .. Services
Node .. Synchronization
Node .. NodeReplicationPolicy
Node .. Ping
Node .. Subject
Node .. xs.boolean
Node .. NodeType
Node .. NodeState
@enduml
.. ######
.. class:: NodeReplicationPolicy
The overall replication policy for the node that expresses constraints on object size, total objects, source nodes, and object format types. A node may choose to restrict replication from only certain peer nodes, may have file size limits, total allocated size limits, or may want to focus on being a :term:`replication target` for domain-specific object formats.
.. attribute:: maxObjectSize
Type: :class:`Types.xs.unsignedLong`
An optional statement of the maximum size in octets (8-bit bytes) of objects this node is willing to accept for replication.
.. attribute:: spaceAllocated
Type: :class:`Types.xs.unsignedLong`
An optional statement of the total space in bytes allocated for replication object storage on this node.
.. attribute:: allowedNode
Type: :class:`Types.NodeReference`
An optional, repeatable statement of a peer source node from which this node is willing to replicate content, expressed as a :class:`Types.NodeReference`.
.. attribute:: allowedObjectFormat
Type: :class:`Types.ObjectFormatIdentifier`
An optional, repeatable statement of an object format that this node is willing to replicate, expressed as a :class:`Types.ObjectFormatIdentifier`.
.. code-block:: xml
.. image:: images/class_NodeReplicationPolicy.png
..
@startuml images/class_NodeReplicationPolicy.png
class NodeReplicationPolicy {
+ maxObjectSize : xs.unsignedLong[0..1]
+ spaceAllocated : xs.unsignedLong[0..1]
+ allowedNode : NodeReference[0..*]
+ allowedObjectFormat : ObjectFormatIdentifier[0..*]
}
NodeReplicationPolicy .. xs.unsignedLong
NodeReplicationPolicy .. NodeReference
NodeReplicationPolicy .. ObjectFormatIdentifier
@enduml
.. ######
.. class:: NodeList
A list of :class:`Types.Node` entries returned by :func:`CNCore.listNodes()`.
NodeList is described in :mod:`NodeList`.
.. attribute:: node
Type: :class:`Types.Node`
.. code-block:: xml
.. image:: images/class_NodeList.png
..
@startuml images/class_NodeList.png
class NodeList {
+ node : Node[1..*]
}
NodeList .. Node
@enduml
.. ######
.. class:: NodeReference
A unique identifier for a DataONE Node. The *NodeReference* must be unique across nodes, and must always be assigned to one Member or Coordinating Node instance even in the event of the *BaseURL* or other characteristics changing.
.. code-block:: xml
.. image:: images/class_NodeReference.png
..
@startuml images/class_NodeReference.png
class NodeReference {
}
NodeReference --|> NonEmptyString
@enduml
.. ######
.. class:: ObjectFormat
One value from the DataONE Object Format Vocabulary which is returned by :func:`CNCore.getFormat()`.
An *ObjectFormat* is the structure returned from the :func:`CNCore.getFormat()` method of the CN REST interface. It provides the unique identifier and the name associated with the object format. Future versions may contain additional structured content from external common typing systems.
.. attribute:: formatId
Type: :class:`Types.ObjectFormatIdentifier`
The unique identifier of the object format in the DataONE Object Format Vocabulary. The identifier should comply with DataONE Identifier rules, i.e. no whitespace, only UTF-8 or US-ASCII printable characters.
.. attribute:: formatName
Type: :class:`Types.xs.string`
For objects that are typed using a Document Type Definition, this lists the well-known and accepted named version of the DTD. In other cases, an appropriately unambiguous descriptive name should be chosen.
.. attribute:: formatType
Type: :class:`Types.xs.string`
A string field indicating whether or not this format is :term:`science data` (*DATA*), :term:`science metadata` (*METADATA*) or a :term:`resource map` (*RESOURCE*). If the format is a self-describing data format that includes science metadata, then the field should also be set to science metadata.
.. code-block:: xml
.. image:: images/class_ObjectFormat.png
..
@startuml images/class_ObjectFormat.png
class ObjectFormat {
+ formatId : ObjectFormatIdentifier[1..1]
+ formatName : xs.string[1..1]
+ formatType : xs.string[1..1]
}
ObjectFormat .. ObjectFormatIdentifier
ObjectFormat .. xs.string
@enduml
.. ######
.. class:: ObjectFormatList
An ObjectFormatList is the structure returned from the :func:`CNCore.listFormats()` method of the CN REST interface. It provides a list of named object formats defined in the DataONE system. Each :class:`Types.ObjectFormat` returned in the list describes the object format via its name, and future versions may contain additional structured content from common external typing systems.
.. code-block:: xml
.. image:: images/class_ObjectFormatList.png
..
@startuml images/class_ObjectFormatList.png
class ObjectFormatList {
+ objectFormat : ObjectFormat[1..*]
}
ObjectFormatList .. ObjectFormat
ObjectFormatList --|> Slice
@enduml
.. ######
.. class:: ObjectInfo
Metadata about an object, representing a subset of the metadata found in :class:`Types.SystemMetadata`.
.. attribute:: identifier
Type: :class:`Types.Identifier`
.. attribute:: formatId
Type: :class:`Types.ObjectFormatIdentifier`
.. attribute:: checksum
Type: :class:`Types.Checksum`
.. attribute:: dateSysMetadataModified
Type: :class:`Types.xs.dateTime`
.. attribute:: size
Type: :class:`Types.xs.unsignedLong`
.. code-block:: xml
.. image:: images/class_ObjectInfo.png
..
@startuml images/class_ObjectInfo.png
class ObjectInfo {
+ identifier : Identifier[1..1]
+ formatId : ObjectFormatIdentifier[1..1]
+ checksum : Checksum[1..1]
+ dateSysMetadataModified : xs.dateTime[1..1]
+ size : xs.unsignedLong[1..1]
}
ObjectInfo .. Identifier
ObjectInfo .. ObjectFormatIdentifier
ObjectInfo .. Checksum
ObjectInfo .. xs.dateTime
ObjectInfo .. xs.unsignedLong
@enduml
.. ######
.. class:: ObjectList
A list of object locations (nodes) from which the object can be retrieved.
.. code-block:: xml
.. image:: images/class_ObjectList.png
..
@startuml images/class_ObjectList.png
class ObjectList {
+ objectInfo : ObjectInfo[0..*]
}
ObjectList .. ObjectInfo
ObjectList --|> Slice
@enduml
.. ######
.. class:: ObjectLocation
Portion of an :class:`Types.ObjectLocationList` indicating the node from which the object can be retrieved. The principal information on each location is found in the *nodeIdentifier*, all other fields are provided for convenience, but could also be looked up from the :class:`Types.NodeList` information obtained from :func:`CNCore.listNodes`.
.. attribute:: nodeIdentifier
Type: :class:`Types.NodeReference`
Identifier of the :class:`Types.Node` (the same identifier used in the node registry for identifying the node).
.. attribute:: baseURL
Type: :class:`Types.xs.anyURI`
The current base URL (the *baseURL* element from the :class:`Types.Node` record) for services implemented on the target node. Used with service version to construct a URL for service calls to this node. Note that complete information on services available on a Node is available from the :func:`CNCore.listNodes` service.
.. attribute:: version
Type: :class:`Types.ServiceVersion`
The version of services implemented on the node. Used with base url to construct a URL for service calls to this node. Note that complete information on services available on a Node is available from the :func:`CNCore.listNodes` service.
.. attribute:: url
Type: :class:`Types.xs.anyURI`
The full (absolute) URL that can be used to retrieve the object using the get() method of the rest interface.
For example, if identifier was "ABX154", and the node had a base URL of ``http://mn1.dataone.org/mn`` then the value would be ``http://mn1.dataone.org/mn/v1/object/ABX154``
.. attribute:: preference
Type: :class:`Types.xs.int`
A weighting parameter that provides a hint to the caller for the relative preference for nodes from which the content should be retrieved. Higher values have higher preference.
.. code-block:: xml
.. image:: images/class_ObjectLocation.png
..
@startuml images/class_ObjectLocation.png
class ObjectLocation {
+ nodeIdentifier : NodeReference[1..1]
+ baseURL : xs.anyURI[1..1]
+ version : ServiceVersion[1..*]
+ url : xs.anyURI[1..1]
+ preference : xs.int[0..1]
}
ObjectLocation .. NodeReference
ObjectLocation .. xs.anyURI
ObjectLocation .. ServiceVersion
ObjectLocation .. xs.int
@enduml
.. ######
.. class:: ObjectLocationList
An *ObjectLocationList* is the structure returned from the :func:`CNRead.resolve` method of the CN REST interface. It provides a list of locations from which the specified object can be retrieved.
.. attribute:: identifier
Type: :class:`Types.Identifier`
The :term:`identifier` of the object being resolved.
.. attribute:: objectLocation
Type: :class:`Types.ObjectLocation`
List of nodes from which the object can be retrieved
.. code-block:: xml
.. image:: images/class_ObjectLocationList.png
..
@startuml images/class_ObjectLocationList.png
class ObjectLocationList {
+ identifier : Identifier[1..1]
+ objectLocation : ObjectLocation[0..*]
}
ObjectLocationList .. Identifier
ObjectLocationList .. ObjectLocation
@enduml
.. ######
.. class:: Person
*Person* represents metadata about a :term:`Principal` that is a person and that can be used by clients and nodes for :class:`Types.AccessPolicy` information. The mutable properties of a *Person* instance can only be changed by itself (i.e., the Subject identifying the Person instance) and by the Coordinating Node identity, but can be read by any identity in the DataONE system.
.. attribute:: subject
Type: :class:`Types.Subject`
The unique, immutable identifier for the *Person*.
.. attribute:: givenName
Type: :class:`Types.NonEmptyString`
The given name of the *Person*, repeatable if they have more than one given name.
.. attribute:: familyName
Type: :class:`Types.NonEmptyString`
The family name of the *Person*.
.. attribute:: email
Type: :class:`Types.NonEmptyString`
The email address of the *Person*, repeatable if they have more than one email address.
.. attribute:: isMemberOf
Type: :class:`Types.Subject`
A *group* or role in which the *Person* is a member, expressed using the unique :class:`Types.Subject` identifier for that :class:`Types.Group`, and repeatable if they are a member of more than one group.
.. attribute:: equivalentIdentity
Type: :class:`Types.Subject`
An alternative but equivalent identity for the :term:`principal` that has been used in alternate identity systems, repeatable if more than one equivalent identity applies.
.. attribute:: verified
Type: :class:`Types.xs.boolean`
*true* if the name and email address of the *Person* have been :term:`verified` to ensure that the *givenName* and *familyName* represent the real person's legal name, and that the email address is correct for that person and is in the control of the indicated individual. Verification occurs through an established procedure within DataONE as part of the Identity Management system. A Person can not change their own *verified* field, but rather must be verified and changed through this DataONE established process.
.. code-block:: xml
.. image:: images/class_Person.png
..
@startuml images/class_Person.png
class Person {
+ subject : Subject[1..1]
+ givenName : NonEmptyString[1..*]
+ familyName : NonEmptyString[1..1]
+ email : NonEmptyString[0..*]
+ isMemberOf : Subject[0..*]
+ equivalentIdentity : Subject[0..*]
+ verified : xs.boolean[0..1]
}
Person .. Subject
Person .. NonEmptyString
Person .. xs.boolean
@enduml
.. ######
.. class:: Ping
Store results from the :func:`MNCore.ping` method.
.. attribute:: success
Type: :class:`Types.xs.boolean`
A boolean flag indicating *true* if the node was reached by the last :func:`MNCore.ping` or :func:`CNCore.ping` call, otherwise *false*.
.. attribute:: lastSuccess
Type: :class:`Types.xs.dateTime`
The date time value (UTC) of the last time a successful ping was performed.
.. code-block:: xml
.. image:: images/class_Ping.png
..
@startuml images/class_Ping.png
class Ping {
+ success : xs.boolean[0..1]
+ lastSuccess : xs.dateTime[0..1]
}
Ping .. xs.boolean
Ping .. xs.dateTime
@enduml
.. ######
.. class:: Replica
Replica information that describes the existence of a replica of some object managed by the DataONE infrastructure, and its status.
.. attribute:: replicaMemberNode
Type: :class:`Types.NodeReference`
A reference to the Member Node that houses this replica, regardless of whether it has arrived at the Member Node or not. See *replicationStatus* to determine if the replica is completely transferred.
.. attribute:: replicationStatus
Type: :class:`Types.ReplicationStatus`
The current status of this replica, indicating the stage of replication process for the object. Only *completed* replicas should be considered as available.
.. attribute:: replicaVerified
Type: :class:`Types.xs.dateTime`
The last date and time on which the integrity of a replica was verified by the coordinating node. Verification occurs by checking that the checksum of the stored object matches the checksum recorded for the object in the system metadata.
.. code-block:: xml
.. image:: images/class_Replica.png
..
@startuml images/class_Replica.png
class Replica {
+ replicaMemberNode : NodeReference[1..1]
+ replicationStatus : ReplicationStatus[1..1]
+ replicaVerified : xs.dateTime[1..1]
}
Replica .. NodeReference
Replica .. ReplicationStatus
Replica .. xs.dateTime
@enduml
.. ######
.. class:: ReplicationPolicy
The *ReplicationPolicy* for an object defines if replication should be attempted for this object, and if so, how many replicas should be maintained. It also permits specification of preferred and blocked nodes as potential replication targets.
.. attribute:: preferredMemberNode
Type: :class:`Types.NodeReference`
Preferred Nodes are utilized over other nodes as replication targets, up to the number of replicas requested. If preferred nodes are unavailable, or if insufficient nodes are listed as preferred to meet the requested number of replicas, then the Coordinating Nodes will pick additional replica nodes for the content.
.. attribute:: blockedMemberNode
Type: :class:`Types.NodeReference`
The object MUST never be replicated to nodes listed as *blockedMemberNodes*. Where there is a conflict between a *preferredMemberNode* and a *blockedMemberNode* entry, the *blockedMemberNode* entry prevails.
.. attribute:: replicationAllowed
Type: :class:`Types.xs.boolean`
A boolean flag indicating if the object should be replicated (*true*, default) or not (*false*).
.. attribute:: numberReplicas
Type: :class:`Types.xs.int`
An integer indicating the number of replicas targeted for this object. Defaults to 3.
.. code-block:: xml
.. image:: images/class_ReplicationPolicy.png
..
@startuml images/class_ReplicationPolicy.png
class ReplicationPolicy {
+ preferredMemberNode : NodeReference[0..*]
+ blockedMemberNode : NodeReference[0..*]
+ replicationAllowed : xs.boolean[0.. 1]
+ numberReplicas : xs.int[0.. 1]
}
ReplicationPolicy .. NodeReference
ReplicationPolicy .. xs.boolean
ReplicationPolicy .. xs.int
@enduml
.. ######
.. class:: Service
The available Dataone Service APIs that are exposed on a Node. Without a restriction, all service methods are available to all callers. Restrictions may be placed on individual methods of the service to limit the service to a certain set of :term:`Subjects`. Enforcement of these service restrictions is incumbent on the Node service implementation.
.. attribute:: restriction
Type: :class:`Types.ServiceMethodRestriction`
A list of method names and :term:`Subjects` with permission to invoke those methods.
.. attribute:: name
Type: :class:`Types.ServiceName`
The name of the service. The valid list of entries for Member Nodes includes: *MNCore*, *MNRead*, *MNAuthorization*, *MNStorage*, and *MNReplication*. The valid list of entries for Coordinating Nodes includes: *CNCore*, *CNRead*, *CNAuthorization*, *CNIdentity*, *CNReplication*, and *CNRegister*.
.. attribute:: version
Type: :class:`Types.ServiceVersion`
Version of the service supported by the node. Version is expressed in whole steps, no minor version identifiers are used. For example, the version 1.0.0 API would be indicated by the value "v1"
.. attribute:: available
Type: :class:`Types.xs.boolean`
A boolean flag indicating if the service is available (*true*, default) or otherwise (*false*).
.. code-block:: xml
.. image:: images/class_Service.png
..
@startuml images/class_Service.png
class Service {
+ restriction : ServiceMethodRestriction[0..*]
+ name : ServiceName[1.. 1]
+ version : ServiceVersion[1.. 1]
+ available : xs.boolean[0.. 1]
}
Service .. ServiceMethodRestriction
Service .. ServiceName
Service .. ServiceVersion
Service .. xs.boolean
@enduml
.. ######
.. class:: ServiceMethodRestriction
Describes an optional restriction policy for a given method. If this element exists for a service method, its use is restricted, and only :term:`Subjects` listed in the list are allowed to invoke the method named in the *methodName* attribute.
.. code-block:: xml
.. image:: images/class_ServiceMethodRestriction.png
..
@startuml images/class_ServiceMethodRestriction.png
class ServiceMethodRestriction {
}
ServiceMethodRestriction --|> SubjectList
@enduml
.. ######
.. class:: Services
A list of services that are provided by a node. Used in Node descriptions so that Nodes can provide metadata about each service they implement and support.
.. attribute:: service
Type: :class:`Types.Service`
.. code-block:: xml
.. image:: images/class_Services.png
..
@startuml images/class_Services.png
class Services {
+ service : Service[1..*]
}
Services .. Service
@enduml
.. ######
.. class:: Session
Information about the authenticated session for a service transaction. Session data is retrieved from the SSL client certificate and populated in the *Session* object. The subject represents the person or system that authenticated successfully, and the *subjectInfo* contains a listing of alternate identities (both Persons and Groups) that are also valid identities for this user. The *subjectInfo* should include at least one :class:`Types.Person` or :class:`Types.Group` entry that provides the attributes of the subject that was authenticated.
.. attribute:: subject
Type: :class:`Types.Subject`
.. attribute:: subjectInfo
Type: :class:`Types.SubjectInfo`
.. code-block:: xml
.. image:: images/class_Session.png
..
@startuml images/class_Session.png
class Session {
+ subject : Subject[1..1]
+ subjectInfo : SubjectInfo[0..1]
}
Session .. Subject
Session .. SubjectInfo
@enduml
.. ######
.. class:: Schedule
The schedule on which :term:`synchronization` will run for a particular node. Syntax for each time slot follows the syntax conventions defined by the Quartz Scheduler (http://www.quartz-scheduler.org/api/2.1.0/org/quartz/CronExpression.html)
.. attribute:: hour
Type: :class:`Types.CrontabEntry`
.. attribute:: mday
Type: :class:`Types.CrontabEntry`
.. attribute:: min
Type: :class:`Types.CrontabEntry`
.. attribute:: mon
Type: :class:`Types.CrontabEntry`
.. attribute:: sec
Type: :class:`Types.CrontabEntrySeconds`
.. attribute:: wday
Type: :class:`Types.CrontabEntry`
.. attribute:: year
Type: :class:`Types.CrontabEntry`
.. code-block:: xml
.. image:: images/class_Schedule.png
..
@startuml images/class_Schedule.png
class Schedule {
+ hour : CrontabEntry[1..1]
+ mday : CrontabEntry[1..1]
+ min : CrontabEntry[1..1]
+ mon : CrontabEntry[1..1]
+ sec : CrontabEntrySeconds[1..1]
+ wday : CrontabEntry[1..1]
+ year : CrontabEntry[1..1]
}
Schedule .. CrontabEntry
Schedule .. CrontabEntrySeconds
@enduml
.. ######
.. class:: Slice
An abstract type used as a common base for other types that need to include *count*, *start*, and *total* attributes to indicate which slice of a list is represented by a set of records.
The first element in a list is always index 0, i.e. list indexes are zero-based.
.. attribute:: count
Type: :class:`Types.xs.int`
The number of entries in the slice.
.. attribute:: start
Type: :class:`Types.xs.int`
The zero-based index of the first element in the slice.
.. attribute:: total
Type: :class:`Types.xs.int`
The total number of entries in the source list from which the slice was extracted.
.. code-block:: xml
.. image:: images/class_Slice.png
..
@startuml images/class_Slice.png
class Slice {
+ count : xs.int[1..1]
+ start : xs.int[1..1]
+ total : xs.int[1..1]
}
Slice .. xs.int
@enduml
.. ######
.. class:: Synchronization
Configuration information for the process by which metadata is harvested from Member Nodes to Coordinating Nodes, including the schedule on which harvesting should occur, and information about the last :term:`synchronization` attempts for the node. Member Nodes providing *Synchronization* information only need to provide the *schedule*. Coordinating Nodes must set values for the *lastHarvested* and *lastCompleteHarvest* fields.
.. attribute:: schedule
Type: :class:`Types.Schedule`
An entry set by the Member Node indicating the frequency for which synchronization should occur. This setting will be influenced by the frequency with which content is updated on the Member Node and the acceptable latency for detection and subsequent processing of new content.
.. attribute:: lastHarvested
Type: :class:`Types.xs.dateTime`
The most recent modification date (UTC) of objects checked during the last harvest of the node.
.. attribute:: lastCompleteHarvest
Type: :class:`Types.xs.dateTime`
The last time (UTC) all the data from a node was pulled from a member node during a complete synchronization process.
.. code-block:: xml
.. image:: images/class_Synchronization.png
..
@startuml images/class_Synchronization.png
class Synchronization {
+ schedule : Schedule[1..1]
+ lastHarvested : xs.dateTime[0..1]
+ lastCompleteHarvest : xs.dateTime[0..1]
}
Synchronization .. Schedule
Synchronization .. xs.dateTime
@enduml
.. ######
.. class:: Subject
An identifier for a Person (user), Group, Organization, or System.
The :term:`Subject` is a string that provides a formal name to identify a user or group in the DataONE Identity Management Service. The *subject* is represented by a unique, persistent, non-reassignable identifier string that follows the same constraints as :class:`Types.Identifier`. Subjects are immutable and can not be deleted.
.. code-block:: xml
.. image:: images/class_Subject.png
..
@startuml images/class_Subject.png
class Subject {
}
Subject --|> NonEmptyString
@enduml
.. ######
.. class:: SubjectInfo
A list of :term:`Subjects`, including both :class:`Types.Person` and :class:`Types.Group` entries returned from the :func:`CNIdentity.getSubjectInfo` service and :func:`CNIdentity.listSubjects` services.
.. attribute:: person
Type: :class:`Types.Person`
.. attribute:: group
Type: :class:`Types.Group`
.. code-block:: xml
.. image:: images/class_SubjectInfo.png
..
@startuml images/class_SubjectInfo.png
class SubjectInfo {
+ person : Person[0..*]
+ group : Group[0..*]
}
SubjectInfo .. Person
SubjectInfo .. Group
@enduml
.. ######
.. class:: SubjectList
A list of :term:`Subjects` used for identity/group management
.. attribute:: subject
Type: :class:`Types.Subject`
.. code-block:: xml
.. image:: images/class_SubjectList.png
..
@startuml images/class_SubjectList.png
class SubjectList {
+ subject : Subject[0..*]
}
SubjectList .. Subject
@enduml
.. ######
.. class:: SystemMetadata
System metadata (often referred to as :term:`sysmeta`) is the information used by DataONE to track and manage objects across the distributed Coordinating and Member Nodes of the network. System metadata documents contain low level information (e.g. size, type, owner, access control rules) about managed objects such as science data, science metadata, and resource map objects and the relationships between objects (e.g. *obsoletes* and *obsoletedBy*).
The information is maintained dynamically by Coordinating Nodes and is mutable in that it reflects the current state of an object in the system. Initial properties of system metadata are generated by clients and Member Nodes. After object synchronization, the Coordinating Nodes hold authoritative copies of system metadata. Mirror copies of system metadata are maintained at each of the Coordinating nodes.
System metadata are considered operational information needed to run DataONE, and can be read by all Coordinating Nodes and Member Nodes in the course of service provision. In order to reduce issues with third-party tracking of data status information, users can read system metadata for an object if they have the access rights to read the corresponding object which a system metadata record describes.
System Metadata elements are partitioned into two classes: metadata elements that must be provided by client software to the DataONE system, and elements that are generated by DataONE itself in the course of managing objects.
.. attribute:: serialVersion
Type: :class:`Types.xs.unsignedLong`
A serial number maintained by the coordinating node to indicate when changes have occurred to *SystemMetadata* to avoid update conflicts. Clients should ensure that they have the most recent version of a *SystemMetadata* document before attempting to update, otherwise an error will be thrown to prevent conflicts. The Coordinating Node must set this optional field when it receives the system metadata document.
.. attribute:: identifier
Type: :class:`Types.Identifier`
The :term:`identifier` is a unique Unicode string that is used to canonically name and identify the object in DataONE. Each object in DataONE is immutable, and therefore all objects must have a unique Identifier. If two objects are related to one another (such as one object is a more recent version of another object), each of these two objects will have unique identifiers. The relationship among the objects is specified in other metadata fields (see *Obsoletes* and *ObsoletedBy*), but this does not preclude the inclusion of version information in the identifier string. However, DataONE treats all Identifiers as opaque and will not try to infer versioning semantics based on the content of the Identifiers -- rather, this information is found in the *Obsoletes* and *ObsoletedBy* fields. Note that identifiers are used in a number of REST API calls as parts of the URL path. As such, all special characters such as "/", " ", "+", "\", "%" must be properly encoded, e.g. "%2F", "%20", "%2B", "%5C", "%25" respectively when used in REST method calls. See RFC3896_ for more details. For example, the :func:`MNRead.get()` call for an object with identifier:
``http://some.location.name/mydata.cgi?id=2088``
would be:
``http://mn1.server.name/mn/v1/object/http:%2F%2Fsome.location.name%2Fmydata.cgi%3Fid%3D2088``
.. _RFC3896: http://www.ietf.org/rfc/rfc3896.txt
.. attribute:: formatId
Type: :class:`Types.ObjectFormatIdentifier`
Designation of the standard or format that should be used to interpret the contents of the object, drawn from controlled list of formats that are provided by the DataONE :class:`Types.ObjectFormat` service. DataONE maintains a list of formats in use and their canonical FormatIdentifiers. The format identifier for an object should imply its mime type for data objects and metadata type and serialization format for metadata objects. Examples include the namespace of the EML 2.1 metadata specification, the DOCTYPE of the Biological Data Profile, the mime type of ``text/csv`` files, and the canonical name of the NetCDF specification.
.. attribute:: size
Type: :class:`Types.xs.unsignedLong`
The size of the object in octets (8-bit bytes).
.. attribute:: checksum
Type: :class:`Types.Checksum`
A calculated hash value used to validate object integrity over time and after network transfers. The value is calculated using a standard hashing algorithm that is accepted by DataONE and that is indicated in the included *ChecksumAlgorithm* attribute.
.. attribute:: submitter
Type: :class:`Types.Subject`
:term:`Subject` who submitted the associated abject to the DataONE Member Node. The Member Node must set this field when it receives the system metadata document from a client (the field is optional from the client perspective, but is required when a MN creates an object). By default, the submitter lacks any rights to modify an object, so care must be taken to set *rightsHolder* and *accessPolicy* correctly with a reference to the subject of the submitter if the submitter is to be able to make further changes to the object.
.. attribute:: rightsHolder
Type: :class:`Types.Subject`
:term:`Subject` that has ultimate authority for the object and is authorized to make all decisions regarding the disposition and accessibility of the object. The *rightsHolder* has all rights to access the object, update the object, and grant permissions for the object, even if additional access control rules are not specified for the object. Typically, the *rightsHolder* field would be set to the name of the subject submitting an object, so that the person can make further changes later. By default, the *submitter* lacks any rights to modify an object, so care must be taken to set *rightsHolder* and *accessPolicy* correctly with a reference to the subject of the *submitter* if the *submitter* is to be able to make further changes to the object.
.. attribute:: accessPolicy
Type: :class:`Types.AccessPolicy`
The *accessPolicy* determines which :term:`Subjects` are allowed to make changes to an object in addition to the *rightsHolder* and *authoritativeMemberNode*. The *accessPolicy* is set for an object during a :func:`MNStorage.create` or :func:`MNStorage.update` call, or when *SystemMetadata* is updated on the Coordinating Node via various mechanisms. This policy replaces any existing policies that might exist for the object. Member Nodes that house an object are obligated to enforce the *accessPolicy* for that object.
.. attribute:: replicationPolicy
Type: :class:`Types.ReplicationPolicy`
A controlled list of policy choices that determine how many replicas should be maintained for a given object and any preferences or requirements as to which Member Nodes should be allowed to house the replicas. The policy determines whether replication is allowed, the number of replicas desired, the list of preferred nodes to hold the replicas, and a list of blocked nodes on which replicas must not exist.
.. attribute:: obsoletes
Type: :class:`Types.Identifier`
The :term:`Identifier` of an object that is a prior version of the object described in this system metadata record and that is obsoleted by this object. When an object is obsoleted, it is removed from all DataONE search indices but is still accessible from the :func:`CNRead.get` service.
.. attribute:: obsoletedBy
Type: :class:`Types.Identifier`
The :term:`Identifier` of an object that is a subsequent version of the object described in this system metadata record and that therefore obsoletes this object. When an object is obsoleted, it is removed from all DataONE search indices but is still accessible from the :func:`CNRead.get` service.
.. attribute:: archived
Type: :class:`Types.xs.boolean`
A boolean flag, set to *true* if the object has been classified as archived. An archived object does not show up in search indexes in DataONE, but is still accessible via the CNRead and MNRead services if associated access polices allow. The field is optional, and if absent, then objects are implied to not be archived, which is the same as setting archived to *false*.
.. attribute:: dateUploaded
Type: :class:`Types.xs.dateTime`
Date and time (UTC) that the object was uploaded into the DataONE system, which is typically the time that the object is first created on a Member Node using the :func:`MNStorage.create` operation. Note this is independent of the publication or release date of the object. The Member Node must set this optional field when it receives the system metadata document from a client.
.. attribute:: dateSysMetadataModified
Type: :class:`Types.xs.dateTime`
Date and time (UTC) that this system metadata record was last modified in the DataONE system. This is the same timestamp as *dateUploaded* until the system metadata is further modified. The Member Node must set this optional field when it receives the system metadata document from a client.
.. attribute:: originMemberNode
Type: :class:`Types.NodeReference`
A reference to the Member Node that originally uploaded the associated object. This value should never change, even if the Member Node ceases to exist.
.. attribute:: authoritativeMemberNode
Type: :class:`Types.NodeReference`
A reference to the Member Node that acts as the authoritative source for an object in the system. The *authoritativeMemberNode* will often also be the *originMemberNode*, unless there has been a need to transfer authority for an object to a new node, such as when a Member Node becomes defunct. The *authoritativeMemberNode* has all the rights of the *rightsHolder* to maintain and curate the object, including making any changes necessary.
.. attribute:: replica
Type: :class:`Types.Replica`
A container field used to repeatedly provide several metadata fields about each replica that exists in the system, or is being replicated. Note that a *replica* field exists even for the Authoritative/Origin Member Nodes so that the status of those objects can be tracked.
.. code-block:: xml
.. image:: images/class_SystemMetadata.png
..
@startuml images/class_SystemMetadata.png
class SystemMetadata {
+ serialVersion : xs.unsignedLong[0..1]
+ identifier : Identifier[1..1]
+ formatId : ObjectFormatIdentifier[1..1]
+ size : xs.unsignedLong[1..1]
+ checksum : Checksum[1..1]
+ submitter : Subject[0..1]
+ rightsHolder : Subject[1..1]
+ accessPolicy : AccessPolicy[0..1]
+ replicationPolicy : ReplicationPolicy[0..1]
+ obsoletes : Identifier[0..1]
+ obsoletedBy : Identifier[0..1]
+ archived : xs.boolean[0..1]
+ dateUploaded : xs.dateTime[0..1]
+ dateSysMetadataModified : xs.dateTime[0..1]
+ originMemberNode : NodeReference[0..1]
+ authoritativeMemberNode : NodeReference[0..1]
+ replica : Replica[0..*]
}
SystemMetadata .. xs.unsignedLong
SystemMetadata .. Identifier
SystemMetadata .. ObjectFormatIdentifier
SystemMetadata .. Checksum
SystemMetadata .. Subject
SystemMetadata .. AccessPolicy
SystemMetadata .. ReplicationPolicy
SystemMetadata .. xs.boolean
SystemMetadata .. xs.dateTime
SystemMetadata .. NodeReference
SystemMetadata .. Replica
@enduml