.. Warning: this file is automatically generated. Edits will be lost .. list-table:: Functions defined in :mod:`CNReplication` :widths: 3 3 10 10 30 :header-rows: 1 * - Tier - Version - REST - Function - Parameters * - Tier 4 - 1.0, (2.0) - ``PUT /replicaNotifications/{pid}`` - :func:`setReplicationStatus` - (:class:`session`, :class:`pid`, :class:`nodeRef`, :class:`status`, :class:`failure`) ``->`` boolean * - Tier 4 - 1.0, (2.0) - ``PUT /replicaMetadata/{pid}`` - :func:`updateReplicationMetadata` - (:class:`session`, :class:`pid`, :class:`replicaMetadata`, ``serialVersion``) ``->`` boolean * - Tier 4 - 1.0, 2.0 - ``PUT /replicaPolicies/{id}`` - :func:`setReplicationPolicy` - (:class:`session`, :class:`id`, :class:`policy`, ``serialVersion``) ``->`` boolean * - Tier 4 - 1.0, (2.0) - ``GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject}`` - :func:`isNodeAuthorized` - (:class:`session`, :class:`targetNodeSubject`, :class:`pid`) ``->`` boolean * - - 1.0, (2.0) - ``PUT /removeReplicaMetadata/{pid}`` - :func:`deleteReplicationMetadata` - (:class:`session`, :class:`pid`, :class:`nodeId`, ``serialVersion``) ``->`` boolean .. function:: setReplicationStatus(session,pid,nodeRef,status,failure) -> boolean Update the replication status of the system metadata, ensuring that the change is appropriate for the given state of system metadata. For example, a MN can not change the status to *COMPLETED* unless the CN previously requested replication of the object and the replications status of the object (as indicated in the system metadata) is set to *QUEUED*. Successful completion of this operation is indicated by a HTTP response status code of 200. Unsuccessful completion of this operation MUST be indicated by returning an appropriate exception. The nodeRef, status, and failure parameters are transmitted as part of the HTTP request body encoded as a MIME Multipart/form-data encoded payload. This method can be only called by Coordinating Nodes and trusted Member Nodes. :Version: 1.0, (2.0) :Use Cases: :doc:`UC09 ` :REST URL: ``PUT /replicaNotifications/{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 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: Identifier of the object to be replicated between Member Nodes. Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :param nodeRef: Reference to the Node which made the setReplicationStatus call. If this is a Member Node, the checksum must be compared with that of the authoritative Member Node. If not, this step can be ignored as the call is not signifying a replication is complete. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type nodeRef: :class:`Types.NodeReference` :param status: Replication status. See system metadata schema for possible values. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type status: :class:`Types.ReplicationStatus` :param failure: A BaseException object or one of it's subclasses, or null. If the status is set to 'failed', this exception object can provide more detail. Appropriate sub-classes include InsufficientResource, NotAuthorized, ServiceFailure, etc. 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 failure: :class:`Types.BaseException` :returns: True if the operation is allowed and expected, otherwise an exception should be raised. :rtype: boolean :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4700)`` :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4701)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4710)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4720)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4730)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4740)`` .. function:: updateReplicationMetadata(session,pid,replicaMetadata,serialVersion) -> boolean Replaces the replica with matching nodeRef in the system metadata of the specified object. Adds a new replica if the nodeRef of passed in Replica is not already present. Changes the date sys meta modified. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. This method can be only called by Coordinating Nodes. :Version: 1.0, (2.0) :REST URL: ``PUT /replicaMetadata/{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. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :param replicaMetadata: 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 replicaMetadata: :class:`Types.Replica` :param serialVersion: The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type serialVersion: unsigned long :returns: True on success :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4850)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4851)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4852)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4853)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4854)`` The specified pid does not exist :raises Exceptions.VersionMismatch: ``(errorCode=409, detailCode=4855)`` The serialVersion supplied with the request does not match the serialVersion of the target :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4856)`` .. function:: setReplicationPolicy(session,id,policy,serialVersion) -> boolean Updates the replication policy entry for an object by updating the system metadata. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. v2.0: The identifier may be a :term:`PID` or :term:`SID`. :Version: 1.0, 2.0 :REST URL: ``PUT /replicaPolicies/{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 policy being updated. May be either a PID or a SID, the latter acting only on the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly. :type id: :class:`Types.Identifier` :param policy: 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 policy: :class:`Types.ReplicationPolicy` :param serialVersion: The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type serialVersion: unsigned long :returns: True on success :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4880)`` :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4881)`` :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4882)`` :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4883)`` :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4884)`` :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4885)`` :raises Exceptions.VersionMismatch: ``(errorCode=409, detailCode=4886)`` The serialVersion supplied with the request does not match the serialVersion of the target .. function:: isNodeAuthorized(session,targetNodeSubject,pid) -> boolean Verifies that a replication event was initiated by a CN by comparing the target node's identifiying subject with a known list of scheduled replication tasks. Successful completion of the operation is indicated by returning a HTTP status of 200. Failure of the operation MUST be indicated by returning an appropriate exception. :Version: 1.0, (2.0) :REST URL: ``GET /replicaAuthorizations/{pid}?targetNodeSubject={targetNodeSubject}`` :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 targetNodeSubject: The subject that identifies the target node, with a value extracted from the X.509 certificate passed in during the call to MNReplication.replicate(). Transmitted as a URL query parameter, and so must be escaped accordingly. :type targetNodeSubject: :class:`Types.Subject` :param pid: The identifier of the object to be replicated. Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :returns: True on success :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4870)`` The method functionality is not implemented. :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4871)`` Replication of PID is not authorized for the subject listed. :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4872)`` An internal server error occurred. :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4873)`` The replication request is invalid. :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4874)`` The PID does not exist as an existing object. :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4875)`` The session information is invalid. .. function:: deleteReplicationMetadata(session,pid,nodeId,serialVersion) -> boolean Removes the replication information for the specified node from the object system metadata identified by *pid*. Removal of replication metadata is necessary if the Member Node goes offline permanently or for an extended period, or when it is deeemed prudent to migrate an object from one node to another to address resource management issues. This method can be only called by Coordinating Nodes. :Version: 1.0, (2.0) :REST URL: ``PUT /removeReplicaMetadata/{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 MUST be a Coordinating Node. Transmitted as part of the SSL handshake process. :type session: :class:`Types.Session` :param pid: The identifier of the object whose replication metadata is being modified. Transmitted as part of the URL path and must be escaped accordingly. :type pid: :class:`Types.Identifier` :param nodeId: The identifier of the node replication information that is being removed from the system metadata record. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type nodeId: :class:`Types.NodeReference` :param serialVersion: The :attr:`Types.SystemMetadata.serialVersion` of the system metadata being updated. This MUST match the latest version of system metadata available for the object on the Coordinating Node. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message. :type serialVersion: unsigned long :returns: True if the replication metadata was successfully deleted. :rtype: boolean :raises Exceptions.NotImplemented: ``(errorCode=501, detailCode=4950)`` The method functionality if not fully implemented :raises Exceptions.ServiceFailure: ``(errorCode=500, detailCode=4951)`` An internal server error occurred that prevented the operation from completing. :raises Exceptions.InvalidRequest: ``(errorCode=400, detailCode=4952)`` The request parameters are malformed :raises Exceptions.InvalidToken: ``(errorCode=401, detailCode=4953)`` The supplied session is invalid :raises Exceptions.NotFound: ``(errorCode=404, detailCode=4956)`` The object identified by *pid* or the node reference specified by *nodeId* could not be located in the system metadata for the object. :raises Exceptions.NotAuthorized: ``(errorCode=401, detailCode=4954)`` The subject identified by the *session* information does not have appropriate priviledges for modifiying the content or accessing the service. :raises Exceptions.VersionMismatch: ``(errorCode=409, detailCode=4955)`` The *serialVersion* does not match the current :attr:`Types.SystemMetadata.serialVersion` value of the object system metadata.