SystemMetadata (DataONE Java Client Library 1.3.0-SNAPSHOT API)

java.lang.Object
- org.dataone.service.types.v1.SystemMetadata

All Implemented Interfaces:: Serializable

public class SystemMetadata
extends Object
implements Serializable

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. Schema fragment(s) for this class:

 <xs:complexType xmlns:ns="http://ns.dataone.org/service/types/v1" xmlns:xs="http://www.w3.org/2001/XMLSchema" name="SystemMetadata">
   <xs:sequence>
     <xs:element type="xs:long" name="serialVersion" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:Identifier" name="identifier"/>
     <xs:element type="ns:ObjectFormatIdentifier" name="formatId"/>
     <xs:element type="xs:long" name="size"/>
     <xs:element type="ns:Checksum" name="checksum"/>
     <xs:element type="ns:Subject" name="submitter" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:Subject" name="rightsHolder"/>
     <xs:element type="ns:AccessPolicy" name="accessPolicy" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:ReplicationPolicy" name="replicationPolicy" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:Identifier" name="obsoletes" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:Identifier" name="obsoletedBy" minOccurs="0" maxOccurs="1"/>
     <xs:element type="xs:boolean" name="archived" minOccurs="0" maxOccurs="1"/>
     <xs:element type="xs:dateTime" name="dateUploaded" minOccurs="0" maxOccurs="1"/>
     <xs:element type="xs:dateTime" name="dateSysMetadataModified" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:NodeReference" name="originMemberNode" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:NodeReference" name="authoritativeMemberNode" minOccurs="0" maxOccurs="1"/>
     <xs:element type="ns:Replica" name="replica" minOccurs="0" maxOccurs="unbounded"/>
   </xs:sequence>
 </xs:complexType>

See Also:: Serialized Form

Constructor Summary

Constructors
Constructor and Description

SystemMetadata()

Constructors
Constructor and Description
`SystemMetadata()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addReplica(Replica item)` Add a 'replica' element item.
`void`	`clearReplicaList()` Remove all 'replica' element items.
`AccessPolicy`	`getAccessPolicy()` Get the 'accessPolicy' element value.
`Boolean`	`getArchived()` Get the 'archived' element value.
`NodeReference`	`getAuthoritativeMemberNode()` Get the 'authoritativeMemberNode' element value.
`Checksum`	`getChecksum()` Get the 'checksum' element value.
`Date`	`getDateSysMetadataModified()` Get the 'dateSysMetadataModified' element value.
`Date`	`getDateUploaded()` Get the 'dateUploaded' element value.
`ObjectFormatIdentifier`	`getFormatId()` Get the 'formatId' element value.
`Identifier`	`getIdentifier()` Get the 'identifier' element value.
`Identifier`	`getObsoletedBy()` Get the 'obsoletedBy' element value.
`Identifier`	`getObsoletes()` Get the 'obsoletes' element value.
`NodeReference`	`getOriginMemberNode()` Get the 'originMemberNode' element value.
`Replica`	`getReplica(int index)` Get 'replica' element item by position.
`List<Replica>`	`getReplicaList()` Get the list of 'replica' element items.
`ReplicationPolicy`	`getReplicationPolicy()` Get the 'replicationPolicy' element value.
`Subject`	`getRightsHolder()` Get the 'rightsHolder' element value.
`BigInteger`	`getSerialVersion()` Get the 'serialVersion' element value.
`BigInteger`	`getSize()` Get the 'size' element value.
`Subject`	`getSubmitter()` Get the 'submitter' element value.
`void`	`setAccessPolicy(AccessPolicy accessPolicy)` Set the 'accessPolicy' element value.
`void`	`setArchived(Boolean archived)` Set the 'archived' element value.
`void`	`setAuthoritativeMemberNode(NodeReference authoritativeMemberNode)` Set the 'authoritativeMemberNode' element value.
`void`	`setChecksum(Checksum checksum)` Set the 'checksum' element value.
`void`	`setDateSysMetadataModified(Date dateSysMetadataModified)` Set the 'dateSysMetadataModified' element value.
`void`	`setDateUploaded(Date dateUploaded)` Set the 'dateUploaded' element value.
`void`	`setFormatId(ObjectFormatIdentifier formatId)` Set the 'formatId' element value.
`void`	`setIdentifier(Identifier identifier)` Set the 'identifier' element value.
`void`	`setObsoletedBy(Identifier obsoletedBy)` Set the 'obsoletedBy' element value.
`void`	`setObsoletes(Identifier obsoletes)` Set the 'obsoletes' element value.
`void`	`setOriginMemberNode(NodeReference originMemberNode)` Set the 'originMemberNode' element value.
`void`	`setReplicaList(List<Replica> list)` Set the list of 'replica' element items.
`void`	`setReplicationPolicy(ReplicationPolicy replicationPolicy)` Set the 'replicationPolicy' element value.
`void`	`setRightsHolder(Subject rightsHolder)` Set the 'rightsHolder' element value.
`void`	`setSerialVersion(BigInteger serialVersion)` Set the 'serialVersion' element value.
`void`	`setSize(BigInteger size)` Set the 'size' element value.
`void`	`setSubmitter(Subject submitter)` Set the 'submitter' element value.
`int`	`sizeReplicaList()` Get the number of 'replica' element items.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - SystemMetadata
```
public SystemMetadata()
```
- Method Detail
  - getSerialVersion
```
public BigInteger getSerialVersion()
```
    Get the 'serialVersion' element value. 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.
    
    Returns:
    value
  - setSerialVersion
```
public void setSerialVersion(BigInteger serialVersion)
```
    Set the 'serialVersion' element value. 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.
    
    Parameters:
    serialVersion -
  - getIdentifier
```
public Identifier getIdentifier()
```
    Get the 'identifier' element value. 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
    
    Returns:
    value
  - setIdentifier
```
public void setIdentifier(Identifier identifier)
```
    Set the 'identifier' element value. 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
    
    Parameters:
    identifier -
  - getFormatId
```
public ObjectFormatIdentifier getFormatId()
```
    Get the 'formatId' element value. 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.
    
    Returns:
    value
  - setFormatId
```
public void setFormatId(ObjectFormatIdentifier formatId)
```
    Set the 'formatId' element value. 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.
    
    Parameters:
    formatId -
  - getSize
```
public BigInteger getSize()
```
    Get the 'size' element value. The size of the object in octets (8-bit bytes).
    
    Returns:
    value
  - setSize
```
public void setSize(BigInteger size)
```
    Set the 'size' element value. The size of the object in octets (8-bit bytes).
    
    Parameters:
    size -
  - getChecksum
```
public Checksum getChecksum()
```
    Get the 'checksum' element value. 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.
    
    Returns:
    value
  - setChecksum
```
public void setChecksum(Checksum checksum)
```
    Set the 'checksum' element value. 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.
    
    Parameters:
    checksum -
  - getSubmitter
```
public Subject getSubmitter()
```
    Get the 'submitter' element value. :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.
    
    Returns:
    value
  - setSubmitter
```
public void setSubmitter(Subject submitter)
```
    Set the 'submitter' element value. :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.
    
    Parameters:
    submitter -
  - getRightsHolder
```
public Subject getRightsHolder()
```
    Get the 'rightsHolder' element value. :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.
    
    Returns:
    value
  - setRightsHolder
```
public void setRightsHolder(Subject rightsHolder)
```
    Set the 'rightsHolder' element value. :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.
    
    Parameters:
    rightsHolder -
  - getAccessPolicy
```
public AccessPolicy getAccessPolicy()
```
    Get the 'accessPolicy' element value. 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.
    
    Returns:
    value
  - setAccessPolicy
```
public void setAccessPolicy(AccessPolicy accessPolicy)
```
    Set the 'accessPolicy' element value. 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.
    
    Parameters:
    accessPolicy -
  - getReplicationPolicy
```
public ReplicationPolicy getReplicationPolicy()
```
    Get the 'replicationPolicy' element value. 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.
    
    Returns:
    value
  - setReplicationPolicy
```
public void setReplicationPolicy(ReplicationPolicy replicationPolicy)
```
    Set the 'replicationPolicy' element value. 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.
    
    Parameters:
    replicationPolicy -
  - getObsoletes
```
public Identifier getObsoletes()
```
    Get the 'obsoletes' element value. 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.
    
    Returns:
    value
  - setObsoletes
```
public void setObsoletes(Identifier obsoletes)
```
    Set the 'obsoletes' element value. 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.
    
    Parameters:
    obsoletes -
  - getObsoletedBy
```
public Identifier getObsoletedBy()
```
    Get the 'obsoletedBy' element value. 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.
    
    Returns:
    value
  - setObsoletedBy
```
public void setObsoletedBy(Identifier obsoletedBy)
```
    Set the 'obsoletedBy' element value. 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.
    
    Parameters:
    obsoletedBy -
  - getArchived
```
public Boolean getArchived()
```
    Get the 'archived' element value. 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*.
    
    Returns:
    value
  - setArchived
```
public void setArchived(Boolean archived)
```
    Set the 'archived' element value. 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*.
    
    Parameters:
    archived -
  - getDateUploaded
```
public Date getDateUploaded()
```
    Get the 'dateUploaded' element value. 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.
    
    Returns:
    value
  - setDateUploaded
```
public void setDateUploaded(Date dateUploaded)
```
    Set the 'dateUploaded' element value. 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.
    
    Parameters:
    dateUploaded -
  - getDateSysMetadataModified
```
public Date getDateSysMetadataModified()
```
    Get the 'dateSysMetadataModified' element value. 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.
    
    Returns:
    value
  - setDateSysMetadataModified
```
public void setDateSysMetadataModified(Date dateSysMetadataModified)
```
    Set the 'dateSysMetadataModified' element value. 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.
    
    Parameters:
    dateSysMetadataModified -
  - getOriginMemberNode
```
public NodeReference getOriginMemberNode()
```
    Get the 'originMemberNode' element value. 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.
    
    Returns:
    value
  - setOriginMemberNode
```
public void setOriginMemberNode(NodeReference originMemberNode)
```
    Set the 'originMemberNode' element value. 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.
    
    Parameters:
    originMemberNode -
  - getAuthoritativeMemberNode
```
public NodeReference getAuthoritativeMemberNode()
```
    Get the 'authoritativeMemberNode' element value. 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.
    
    Returns:
    value
  - setAuthoritativeMemberNode
```
public void setAuthoritativeMemberNode(NodeReference authoritativeMemberNode)
```
    Set the 'authoritativeMemberNode' element value. 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.
    
    Parameters:
    authoritativeMemberNode -
  - getReplicaList
```
public List<Replica> getReplicaList()
```
    Get the list of 'replica' element items. 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.
    
    Returns:
    list
  - setReplicaList
```
public void setReplicaList(List<Replica> list)
```
    Set the list of 'replica' element items. 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.
    
    Parameters:
    list -
  - sizeReplicaList
```
public int sizeReplicaList()
```
    Get the number of 'replica' element items.
    
    Returns:
    count
  - addReplica
```
public void addReplica(Replica item)
```
    Add a 'replica' element item.
    
    Parameters:
    item -
  - getReplica
```
public Replica getReplica(int index)
```
    Get 'replica' element item by position.
    
    Parameters:
    index -
    
    Returns:
    item
  - clearReplicaList
```
public void clearReplicaList()
```
    Remove all 'replica' element items.

Class SystemMetadata

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SystemMetadata

Method Detail

getSerialVersion

setSerialVersion

getIdentifier

setIdentifier

getFormatId

setFormatId

getSize

setSize

getChecksum

setChecksum

getSubmitter

setSubmitter

getRightsHolder

setRightsHolder

getAccessPolicy

setAccessPolicy

getReplicationPolicy

setReplicationPolicy

getObsoletes

setObsoletes

getObsoletedBy

setObsoletedBy

getArchived

setArchived

getDateUploaded

setDateUploaded

getDateSysMetadataModified

setDateSysMetadataModified

getOriginMemberNode

setOriginMemberNode

getAuthoritativeMemberNode

setAuthoritativeMemberNode

getReplicaList

setReplicaList

sizeReplicaList

addReplica

getReplica

clearReplicaList