.. Warning: this file is automatically generated. Edits will be lost .. list-table:: Functions defined in :mod:`MNStorage` :widths: 3 3 10 10 30 :header-rows: 1 * - Tier - Version - REST - Function - Parameters * - Tier 3 - 1.0 - ``POST /object`` - :func:`create` - (:class:`session`, :class:`pid`, ``object``, :class:`sysmeta`) ``->`` :class:`Types.Identifier` * - Tier 3 - 1.0 - ``PUT /object/{pid}`` - :func:`update` - (:class:`session`, :class:`pid`, ``object``, :class:`newPid`, :class:`sysmeta`) ``->`` :class:`Types.Identifier` * - Tier 3 - 1.0 - ``POST /generate`` - :func:`generateIdentifier` - (:class:`session`, ``scheme``, ``[fragment]``) ``->`` :class:`Types.Identifier` * - Tier 3 - 1.0 - ``DELETE /object/{id}`` - :func:`delete` - (:class:`session`, :class:`id`) ``->`` :class:`Types.Identifier` * - Tier 3 - 1.0 - ``PUT /archive/{id}`` - :func:`archive` - (:class:`session`, :class:`id`) ``->`` :class:`Types.Identifier` * - Tier 1 - 2.0 - ``PUT /meta`` - :func:`updateSystemMetadata` - (:class:`session`, :class:`pid`, :class:`sysmeta`) ``->`` boolean .. function:: create(session,pid,object,sysmeta) -> Identifier Called by a client to adds a new object to the Member Node. The *pid* must not exist in the DataONE system or should have been previously reserved using :func:`CNCore.reserveIdentifier`. A new, unique :attr:`Types.SystemMetadata.seriesId` may be included. The caller MUST have authorization to write or create content on the Member Node. :Version: 1.0 :Use Cases: :doc:`UC04 `, :doc:`UC09 `, :doc:`UC16 ` :REST URL: ``POST /object`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: The identifier that should be used in DataONE to identify and access the object. This is an Unicode string that follows the constraints on identifiers described in :doc:`/design/PIDs`. If the identifier is already in use, :exc:`Exceptions.IdentifierNotUnique` will be raised and the client SHOULD try again with a different, unique identifier. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type pid: :class:`Types.Identifier` :param object: The data bytes that are to be added to the Member Node. :type object: bytes :param sysmeta: The system metadata document that provides basic information about the object, including a reference to its identifier, access control information, etc. Attributes of the sysmeta that are the responsibility of the client MUST be set. Note that the obsoletes and obsoletedBy elements MUST not be set. It is the role of the update() method to ensure these are properly updated to ensure object lineage is as expected. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type sysmeta: :class:`Types.SystemMetadata` :returns: The identifier that was used to insert the document into the system. :rtype: :class:`Types.Identifier` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1100)`` The provided identity does not have permission to WRITE to the Member Node. :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=1120)`` The requested identifier is already used by another object and therefore can not be used for this object. Clients should choose a new identifier that is unique and retry the operation or use :func:`CNCore.reserveIdentifier` to reserve one. :raises Exceptions.UnsupportedType: ``(errorCode=400, detailCode=1140)`` The MN can not deal with the content specified in the data package. :raises Exceptions.InsufficientResources: ``(errorCode=413, detailCode=1160)`` The MN is unable to execute the transfer because it does not have sufficient storage space for example. :raises Exceptions.InvalidSystemMetadata: ``(errorCode=400, detailCode=1180)`` The supplied system metadata is invalid. This could be because some required field is not set, the metadata document is malformed, or the value of some field is not valid. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1190)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1110)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1101)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=1102)`` .. include:: /apis/examples/create.txt .. function:: update(session,pid,object,newPid,sysmeta) -> Identifier This method is called by clients to update objects on Member Nodes. Updates an existing object by creating a new object identified by *newPid* on the Member Node which explicitly obsoletes the object identified by *pid* through appropriate changes to the SystemMetadata of *pid* and *newPid*. The Member Node sets :attr:`Types.SystemMetadata.obsoletedBy` on the object being obsoleted to the *pid* of the new object. It then updates :attr:`Types.SystemMetadata.dateSysMetadataModified` on both the new and old objects. The modified system metadata entries then become available in :func:`MNRead.listObjects`. This ensures that a Coordinating Node will pick up the changes when filtering on :attr:`Types.SystemMetadata.dateSysMetadataModified`. The update operation MUST fail with :exc:`Exceptions.InvalidRequest` on objects that have the :attr:`Types.SystemMetadata.archived` property set to true. A new, unique :attr:`Types.SystemMetadata.seriesId` may be included when beginning a series, or a series may be extended if the newPid obsoletes the existing pid. :Version: 1.0 :Use Cases: :doc:`UC16 ` :REST URL: ``PUT /object/{pid}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: The identifier of the object that is being updated. If this identifier does not exist in the system, an error is raised and the operation does not cause any changes to the objects or their metadata. Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :param object: The bytes of the data or science metadata object that will be deprecating the exsting object. :type object: bytes :param newPid: The identifier that will become the replacement identifier for the existing object after the update. This identifier must have been previously reserved. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type newPid: :class:`Types.Identifier` :param sysmeta: A System Metadata document describing the new object. The :attr:`SystemMetadata.obsoletes` field must contain the identifier of the object being obsoleted. Other required client provided fields as described for :class:`Types.SystemMetadata` must be filled. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type sysmeta: :class:`Types.SystemMetadata` :returns: The identifier of the document that is replacing the original, which should be the same as *newPid*. :rtype: :class:`Types.Identifier` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=1200)`` :raises Exceptions.IdentifierNotUnique: ``(errorCode=409, detailCode=1220)`` The requested identifier is already used by another object and therefore can not be used for this object. Clients should choose a new identifier that is unique and retry the operation. :raises Exceptions.UnsupportedType: ``(errorCode=400, detailCode=1240)`` The MN can not deal with the object provided. :raises Exceptions.InsufficientResources: ``(errorCode=413, detailCode=1260)`` The MN is unable to execute the transfer because it does not have sufficient storage space for example. :raises Exceptions.NotFound: ``(errorCode=404, detailCode=1280)`` The update operation failed because the object which was supposed to be updated in the system (indicated via the *obsoletedPid* parameter) is not present in the DataONE system, so update is an illegal operation. :raises Exceptions.InvalidSystemMetadata: ``(errorCode=400, detailCode=1300)`` One or more required fields are not set, the metadata document is malformed or the value of some field is not valid. :attr:`SystemMetadata.obsoletes` is set by the client and does not match the *pid* of the object being obsoleted. :attr:`SystemMetadata.obsoletedBy` is set on the SystemMetadata of the new object provided by the client (a new object cannot be created in an obsoleted state). :attr:`SystemMetadata.obsoletedBy` is already set on the object being obsoleted (no branching is allowed in the obsolescence chain). :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=1310)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=1210)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=1201)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=1202)`` Raised when the request parameters are incorrect or the operation is not applicable to the current state of the object (e.g. an archived object can not be updated) .. function:: generateIdentifier(session,scheme,[fragment]) -> Identifier Given a scheme and optional fragment, generates an identifier with that scheme and fragment that is unique. Maybe be used for generating either PIDs or SIDs. The message body is encoded as MIME Multipart/form-data :Version: 1.0 :REST URL: ``POST /generate`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param scheme: The name of the identifier scheme to be used, drawn from a DataONE-specific vocabulary of identifier scheme names, including several common syntaxes such as DOI, ARK, LSID, UUID, and LSRN, among others. The first version of this method only supports the UUID scheme, and ignores the fragment parameter. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type scheme: string :param fragment: The optional fragment to include in the generated Identifier. This parameter is optional and may not be present in the message body. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type fragment: string :returns: The identifier that was generated :rtype: :class:`Types.Identifier` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2190)`` The supplied authentication token is not a proper certificate, or missing required fields, or otherwise proves invalid. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2191)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2192)`` Supplied credentials does not have WRITE permission :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=2193)`` The scheme requested is not a valid scheme accepted by this service :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2194)`` .. TODO:: Need to provide a list of recommended identifier schemes. .. function:: delete(session,id) -> Identifier Deletes an object managed by DataONE from the Member Node. Member Nodes MUST check that the caller (typically a Coordinating Node) is authorized to perform this function. The delete operation will be used primarily by Coordinating Nodes to help manage the number of replicas of an object that are present in the entire system. The operation removes the object from further interaction with DataONE services. The implementation may delete the object bytes, and in general should do so since a delete operation may be in response to a problem with the object (e.g. it contains malicious content, is innappropriate, or is the subject of a legal request). If the object does not exist on the node servicing the request, then an :exc:`Exceptions.NotFound` exception is raised. The message body of the exception SHOULD contain a hint as to the location of the :func:`CNRead.resolve` method. :Version: 1.0 :Use Cases: :doc:`UC16 ` :REST URL: ``DELETE /object/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: The identifier of the object to be deleted. May be either a PID or a SID. Will delete the HEAD PID when called with a SID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: The identifier of the object that was deleted. :rtype: :class:`Types.Identifier` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2900)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2901)`` The delete operation failed because the object is not present on the node servicing the request. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2902)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2903)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2904)`` .. function:: archive(session,id) -> Identifier Hides an object managed by DataONE from search operations, effectively preventing its discovery during normal operations. The operation does not delete the object bytes, but instead sets the :attr:`Types.SystemMetadata.archived` flag to True. This ensures that the object can still be resolved (and hence remain valid for existing citations and cross references), though will not appear in searches. Objects that are archived can not be updated through the :func:`MNStorage.update` operation. Archived objects can not be un-archived. This behavior may change in future versions of the DataONE API. Member Nodes MUST check that the caller is authorized to perform this function. If the object does not exist on the node servicing the request, then an :exc:`Exceptions.NotFound` exception is raised. The message body of the exception SHOULD contain a hint as to the location of the :func:`CNRead.resolve` method. :Version: 1.0 :REST URL: ``PUT /archive/{id}`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param id: The identifier of the object to be archived. May be either a PID or a SID. Will archive the HEAD PID when called with a SID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :returns: The identifier of the object that was archived. :rtype: :class:`Types.Identifier` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=2910)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=2911)`` The archive operation failed because the object is not present on the node servicing the request. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=2912)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=2913)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=2914)`` .. function:: updateSystemMetadata(session,pid,sysmeta) -> boolean Provides a mechanism for updating system metadata for any objects held on the Member Node where that Member Node is the authoritative Member Node. Coordinating Node can call this method on the non-authoritative Member Node. However, this is not a normal operation and is for the special case - the authoritative Member Node doesn't exist any more. Coordinating Node calling the method on the non-authoriative Memember Node in the normal operation can cause an unexpected consequence. This method is typically used by Authoritative Member Node or rights holder[s] to ensure system metadata quality. :Version: 2.0 :REST URL: ``PUT /meta`` :param session: Session information that contains the identity of the calling user as retrieved from the X.509 certificate which must be traceable to the CILogon service. The subject of the session defaults to the :term:`public user` if the certificate was not provided with the request. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type pid: :class:`Types.Identifier` :param sysmeta: Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message. :type sysmeta: :class:`Types.SystemMetadata` :returns: True if the update was successful. :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4866)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4867)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4868)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4869)`` :raises Exceptions.InvalidSystemMetadata: ``(errorCode=400, detailCode=4956)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4957)``