|
Size: 12915
Comment:
|
← Revision 14 as of 2010-03-17 13:08:52 ⇥
Size: 12409
Comment: converted to 1.6 markup
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| === API-M (Fedora Management service API) === [[Anchor(anchor_addDatastream)]] ==== addDatastream ==== |
## page was renamed from Fedora 3.0 API/Managment = API-M (Fedora Management service API) = <<TableOfContents>> == Datastream managment == <<Anchor(addDatastream)>> === addDatastream === |
| Line 8: | Line 12: |
| If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. | If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. |
| Line 20: | Line 24: |
| * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). ''Only Active and Deleted are used in DOMS. Inactive objects are not used in DOMS, as an inactive object would not be in the Triple Store. We need to be able to make queries about it, so that is unacceptable. Rather, we use the special STATE datastream, see FedoraTransactionsReplacement.'' | * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). |
| Line 32: | Line 36: |
| [[Anchor(anchor_addRelationship)]] ==== addRelationship ==== Creates a new relationship in the object. Adds the specified relationship to the object's RELS-EXT Datastream. If the Resource Index is enabled, the relationship will be added to the Resource Index. If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. Input parameters: * {{{String pid}}} The PID of the object. * {{{String relationship}}} The predicate. * {{{String object}}} The object. * {{{boolean isLiteral}}} A boolean value indicating whether the object is a literal. * {{{String datatype}}} The datatype of the literal. Optional. Returns: * {{{boolean}}} True if and only if the relationship was added. Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_compareDatastreamChecksum)]] ==== compareDatastreamChecksum ==== Verifies that the Datastream content has not changed since the checksum was initially computed. Input parameters: * {{{String pid}}} The PID of the object. * {{{String dsID}}} The datastream ID. * {{{String versionDate}}} A dateTime indicating the version of the datastream to verify. If null, Fedora will use the most recent version. Returns: * {{{String}}} The checksum if there is no difference, a message indicating checksum failure otherwise. Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_getDatastream)]] ==== getDatastream ==== |
<<Anchor(getDatastream)>> === getDatastream === |
| Line 78: | Line 47: |
| * {{{Datastream}}} The specified datastream. (See definition of [#anchor_Datastream Datastream] under Data structures below) Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_getDatastreams)]] ==== getDatastreams ==== Gets all versions of a datastream, sorted from most to least recent. |
* {{{Datastream}}} * {{{DatastreamControlGroup controlGroup}}} - String restricted to the values of "X", "M", "R", or "E" (Inline *X*ML, *M*anaged Content, *R*edirect, or *E*xternal Referenced). * {{{String ID}}} - The datastream ID (64 characters max). * {{{String versionID}}} - The ID of the most recent datastream version * {{{String[] altIDs}}} - Alternative IDs for the datastream, if any. * {{{String label}}} - The Label of the datastream. * {{{boolean versionable}}} - Whether the datastream is versionable. * {{{String MIMEType}}} - The mime-type for the datastream, if set. * {{{String formatURI}}} - The format uri for the datastream, if set. * {{{String createDate}}} - The date the first version of the datastream was created. * {{{long size}}} - The size of the datastream in Fedora. Not the size of any referenced contents, but only the fedora stored xml. TODO: What for Managed? * {{{String state}}} - The state of the datastream. Will be "A" (active), "I" (inactive) or "D" (deleted). * {{{String location}}} - If the datastream is an external reference or redirect, the url to the contents. TODO: Managed? * {{{String checksumType}}} - The algorithm used to compute the checksum. One of "DEFAULT", "DISABLED", "MD5", "SHA-1", "SHA-256", "SHA-385", "SHA-512", "HAVAL", "TIGER", "WHIRLPOOL". * {{{String checksum}}} - The value of the checksum represented as a hexadecimal string. Throws: * {{{java.rmi.RemoteException}}} <<Anchor(getDatastreams)>> === getDatastreams === Gets all datastreams in the object |
| Line 91: | Line 75: |
| * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). ''Only Active and Deleted are used in DOMS. Inactive objects are not used in DOMS, as an inactive object would not be in the Triple Store. We need to be able to make queries about it, so that is unacceptable. Rather, we use the special STATE datastream, see FedoraTransactionsReplacement.'' # dsState is not mentioned as a parameter in Fedora's own documentation, but in their code, it is there. Returns: * {{{Datastream[]}}} All versions of a datastream, sorted from most to least recent. (See definition of [#anchor_Datastream Datastream] under Data structures below) Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_getRelationships)]] ==== getRelationships ==== Get the relationships asserted in the object's RELS-EXT Datastream that match the given criteria. Input parameters: * {{{String pid}}} The PID of the object. * {{{String relationship}}} The predicate to match. A null value matches all predicates. Returns: * {{{RelationshipTuple[]}}} An array of !RelationshipTuples, each containing the subject, predicate and object matching the search criteria. (See definition of [#anchor_RelationshipTuple RelationshipTuple] under Data structures below) Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_ingest)]] ==== ingest ==== Creates a new digital object in the repository. The object's initial state will be A (active). If the XML document does not specify the OBJID attribute of the root element, the repository will generate and return a new pid for the object resulting from this request. That pid will have the namespace of the repository. If the XML document specifies a pid, it will be assigned to the digital object provided that 1. it conforms to the Fedora pid Syntax, 2. it uses a namespace that matches the "retainPIDs" value configured for the repository, and 3. it does not collide with an existing pid of an object in the repository. If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. Input parameters: * {{{byte[] objectXML}}} The digital object in an XML submission format. * {{{String format}}} The XML format of objectXML, e.g. "info:fedora/fedora-system:FOXML-1.1", "info:fedora/fedora-system:FOXML-1.0", "info:fedora/fedora-system:METSFedoraExt-1.1", or "info:fedora/fedora-system:ATOM-1.0". * {{{String logMessage}}} A log message. Returns: * {{{String}}} The pid of the newly created object. Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_modifyDatastreamByReference)]] ==== modifyDatastreamByReference ==== If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. |
* {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). Returns: * {{{Datastream[]}}} See [[#getDatastream|getDatastream]] Throws: * {{{java.rmi.RemoteException}}} <<Anchor(anmodifyDatastreamByReference)>> === modifyDatastreamByReference === If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. |
| Line 159: | Line 111: |
| [[Anchor(anchor_modifyDatastreamByValue)]] ==== modifyDatastreamByValue ==== |
<<Anchor(modifyDatastreamByValue)>> === modifyDatastreamByValue === |
| Line 163: | Line 115: |
| If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. | If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. |
| Line 185: | Line 137: |
| [[Anchor(anchor_modifyObject)]] ==== modifyObject ==== Modify an object. If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. Input parameters: * {{{String pid}}} The PID of the object. * {{{String state}}} The new state, "A", "I" or "D". Null means leave unchanged. ''Only Active and Deleted are used in DOMS. Inactive objects are not used in DOMS, as an inactive object would not be in the Triple Store. We need to be able to make queries about it, so that is unacceptable. Rather, we use the special STATE datastream, see FedoraTransactionsReplacement.'' * {{{String label}}} the new label. Null means leave unchanged. * {{{String ownerId}}} The ownerId for the object. * {{{String logMessage}}} A log message. Returns: * {{{String}}} The timestamp of the operation according to the server, in ISO8601 format. Throws: * {{{java.rmi.RemoteException}}} [[Anchor(anchor_purgeRelationship)]] ==== purgeRelationship ==== |
<<Anchor(setDatastreamState)>> === setDatastreamState === Sets the state of a Datastream to the specified state value. If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. Input parameters: * {{{String pid}}} The PID of the object. * {{{String dsID}}} The datastream ID. * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). * {{{String logMessage}}} A log message. Returns: * {{{String}}} The timestamp of the operation according to the server, in ISO8601 format. Throws: * {{{java.rmi.RemoteException}}} <<Anchor(compareDatastreamChecksum)>> === compareDatastreamChecksum === Verifies that the Datastream content has not changed since the checksum was initially computed. Input parameters: * {{{String pid}}} The PID of the object. * {{{String dsID}}} The datastream ID. * {{{String versionDate}}} A dateTime indicating the version of the datastream to verify. If null, Fedora will use the most recent version. Returns: * {{{String}}} The checksum if there is no difference, a message indicating checksum failure otherwise. Throws: * {{{java.rmi.RemoteException}}} === (getDatastreamHistory)? === == Relationship managment == <<Anchor(addRelationship)>> === addRelationship === Creates a new relationship in the object. Adds the specified relationship to the object's RELS-EXT Datastream. If the Resource Index is enabled, the relationship will be added to the Resource Index. A rdf tuple consist of an object, having a predicate relating it to a subject. The subject can either be a literal value, or another object. If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. Input parameters: * {{{String pid}}} The PID of the object. * {{{String relationship}}} The predicate. * {{{String object}}} The object. * {{{boolean isLiteral}}} A boolean value indicating whether the object is a literal. * {{{String datatype}}} The datatype of the literal. Optional. Returns: * {{{boolean}}} True if and only if the relationship was added. Throws: * {{{java.rmi.RemoteException}}} <<Anchor(anchor_getRelationships)>> === getRelationships === Get the relationships asserted in the object's RELS-EXT Datastream that match the given criteria. Input parameters: * {{{String pid}}} The PID of the object. * {{{String relationship}}} The predicate to match. A null value matches all predicates. Returns: * {{{RelationshipTuple[]}}} * {{{String subject}}} - The subject of the relation. Either a Fedora PID or a literal value. * {{{String predicate}}} - The predicate relating the subject and the object. Includes the namespace of the relation. * {{{String object}}} - The PID of the object of the relation * {{{boolean isLiteral}}} - If true, the subject should be read as a literal value, not a PID * {{{String datatype}}} - If the subject is a literal, the datatype to parse the value as. Optional. Throws: * {{{java.rmi.RemoteException}}} <<Anchor(purgeRelationship)>> === purgeRelationship === |
| Line 209: | Line 223: |
| If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. | If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. |
| Line 225: | Line 239: |
| [[Anchor(anchor_setDatastreamState)]] ==== setDatastreamState ==== Sets the state of a Datastream to the specified state value. If, after the call to this method, the object in question would have state "published" in its STATE datastream, then this method will perform validation of the object. In case of a failed validation, an exception will be thrown. Input parameters: * {{{String pid}}} The PID of the object. * {{{String dsID}}} The datastream ID. * {{{String dsState}}} One of "A", "D", or "I" (Active, Deleted, or Inactive). ''Only Active and Deleted are used in DOMS. Inactive objects are not used in DOMS, as an inactive object would not be in the Triple Store. We need to be able to make queries about it, so that is unacceptable. Rather, we use the special STATE datastream, see FedoraTransactionsReplacement.'' * {{{String logMessage}}} A log message. Returns: * {{{String}}} The timestamp of the operation according to the server, in ISO8601 format. Throws: * {{{java.rmi.RemoteException}}} ==== (export) ==== ==== (getDatastreamHistory)? ==== ==== (getObjectXML)? ==== |
== Object Management == <<Anchor(ingest)>> === ingest === Creates a new digital object in the repository. The object's initial state should be I (inactive). If the XML document does not specify the OBJID attribute of the root element, the repository will generate and return a new pid for the object resulting from this request. That pid will have the namespace of the repository. If the XML document specifies a pid, it will be assigned to the digital object provided that 1. it conforms to the Fedora pid Syntax, 2. it uses a namespace that matches the "retainPIDs" value configured for the repository, and 3. it does not collide with an existing pid of an object in the repository. If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects. Input parameters: * {{{byte[] objectXML}}} The digital object in an XML submission format. * {{{String format}}} The XML format of objectXML, e.g. "info:fedora/fedora-system:FOXML-1.1", "info:fedora/fedora-system:FOXML-1.0", "info:fedora/fedora-system:METSFedoraExt-1.1", or "info:fedora/fedora-system:ATOM-1.0". * {{{String logMessage}}} A log message. Returns: * {{{String}}} The pid of the newly created object. Throws: * {{{java.rmi.RemoteException}}} <<Anchor(modifyObject)>> === modifyObject === Modify an object. If this alters an object that was hitherto "Inactive" or "Deleted" to have state "Active", validation will be performed on the object to check the object to be valid, and the call will fail otherwise. See FedoraState for details. Input parameters: * {{{String pid}}} The PID of the object. * {{{String state}}} The new state, "A", "I" or "D". See FedoraState for usage. * {{{String ownerId}}} The ownerId for the object. * {{{String logMessage}}} A log message. Returns: * {{{String}}} The timestamp of the operation according to the server, in ISO8601 format. Throws: * {{{java.rmi.RemoteException}}} === (export) === === (getObjectXML)? === |
API-M (Fedora Management service API)
Contents
Datastream managment
addDatastream
Creates a new Datastream in the object.
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String dsID The datastream ID (64 characters max). If null, Fedora will generate the value.
String[] altIDs Alternate identifiers for the datastream.
String dsLabel The label for the datastream.
boolean versionable Enable versioning of the datastream. This should be on for DOMS GUI usages.
String MIMEType The mime-type of the datastream.
String formatURI The format URI of the datastream.
String dsLocation Location of managed, redirect, or external referenced datastream content.
String controlGroup One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced). For DOMS GUI, use Inline XML or External Referenced.
String dsState One of "A", "D", or "I" (Active, Deleted, or Inactive).
String checksumType The algorithm used to compute the checksum. For DOMS GUI usage, may take value "DISABLED" or "MD5".
String checksum The value of the checksum represented as a hexadecimal string.
String logMessage A log message.
Returns:
String The datastreamID of the newly added datastream.
Throws:
java.rmi.RemoteException
getDatastream
Gets the specified datastream.
Input parameters:
String pid The pid of the object.
String dsID The datastream ID.
String asOfDateTime The date/time stamp specifying the desired version of the object. If null, the current version of the object (the most recent time) is assumed.
Returns:
Datastream
DatastreamControlGroup controlGroup - String restricted to the values of "X", "M", "R", or "E" (Inline *X*ML, *M*anaged Content, *R*edirect, or *E*xternal Referenced).
String ID - The datastream ID (64 characters max).
String versionID - The ID of the most recent datastream version
String[] altIDs - Alternative IDs for the datastream, if any.
String label - The Label of the datastream.
boolean versionable - Whether the datastream is versionable.
String MIMEType - The mime-type for the datastream, if set.
String formatURI - The format uri for the datastream, if set.
String createDate - The date the first version of the datastream was created.
long size - The size of the datastream in Fedora. Not the size of any referenced contents, but only the fedora stored xml. TODO: What for Managed?
String state - The state of the datastream. Will be "A" (active), "I" (inactive) or "D" (deleted).
String location - If the datastream is an external reference or redirect, the url to the contents. TODO: Managed?
String checksumType - The algorithm used to compute the checksum. One of "DEFAULT", "DISABLED", "MD5", "SHA-1", "SHA-256", "SHA-385", "SHA-512", "HAVAL", "TIGER", "WHIRLPOOL".
String checksum - The value of the checksum represented as a hexadecimal string.
Throws:
java.rmi.RemoteException
getDatastreams
Gets all datastreams in the object
Input parameters:
String pid The pid of the object.
String asOfDateTime The date/time stamp specifying the desired version of the object. If null, the current version of the object (the most recent time) is assumed.
String dsState One of "A", "D", or "I" (Active, Deleted, or Inactive).
Returns:
Datastream[] See getDatastream
Throws:
java.rmi.RemoteException
modifyDatastreamByReference
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String dsID The datastream ID.
String[] altIDs Alternate identifiers for the datastream, if any.
String dsLabel The label for the datastream.
String MIMEType The mime type.
String formatURI Optional format URI of the datastream.
String dsLocation Location of managed, redirect, or external referenced datastream content.
String checksumType The algorithm used to compute the checksum. For DOMS GUI usage, may take value "DISABLED" or "MD5".
String checksum The value of the checksum represented as a hexadecimal string.
String logMessage A log message.
boolean force Force the update even if it would break a data contract.
Returns:
String The timestamp of the operation according to the server, in ISO8601 format.
Throws:
java.rmi.RemoteException
modifyDatastreamByValue
Modifies an existing Datastream in an object, by value. This operation is only valid for Inline XML Datastreams (i.e. controlGroup "X").
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String dsID The datastream ID.
String[] altIDs Alternate identifiers for the datastream, if any.
String dsLabel The label for the datastream.
String MIMEType The mime type.
String formatURI Optional format URI of the datastream.
byte[] dsContent The content of the datastream.
String checksumType The algorithm used to compute the checksum. For DOMS GUI usage, may take value "DISABLED" or "MD5".
String checksum The value of the checksum represented as a hexadecimal string.
String logMessage A log message.
boolean force Force the update even if it would break a data contract.
Returns:
String The timestamp of the operation according to the server, in ISO8601 format.
Throws:
java.rmi.RemoteException
setDatastreamState
Sets the state of a Datastream to the specified state value.
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String dsID The datastream ID.
String dsState One of "A", "D", or "I" (Active, Deleted, or Inactive).
String logMessage A log message.
Returns:
String The timestamp of the operation according to the server, in ISO8601 format.
Throws:
java.rmi.RemoteException
compareDatastreamChecksum
Verifies that the Datastream content has not changed since the checksum was initially computed.
Input parameters:
String pid The PID of the object.
String dsID The datastream ID.
String versionDate A dateTime indicating the version of the datastream to verify. If null, Fedora will use the most recent version.
Returns:
String The checksum if there is no difference, a message indicating checksum failure otherwise.
Throws:
java.rmi.RemoteException
(getDatastreamHistory)?
Relationship managment
addRelationship
Creates a new relationship in the object. Adds the specified relationship to the object's RELS-EXT Datastream. If the Resource Index is enabled, the relationship will be added to the Resource Index.
A rdf tuple consist of an object, having a predicate relating it to a subject. The subject can either be a literal value, or another object.
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String relationship The predicate.
String object The object.
boolean isLiteral A boolean value indicating whether the object is a literal.
String datatype The datatype of the literal. Optional.
Returns:
boolean True if and only if the relationship was added.
Throws:
java.rmi.RemoteException
getRelationships
Get the relationships asserted in the object's RELS-EXT Datastream that match the given criteria.
Input parameters:
String pid The PID of the object.
String relationship The predicate to match. A null value matches all predicates.
Returns:
RelationshipTuple[]
String subject - The subject of the relation. Either a Fedora PID or a literal value.
String predicate - The predicate relating the subject and the object. Includes the namespace of the relation.
String object - The PID of the object of the relation
boolean isLiteral - If true, the subject should be read as a literal value, not a PID
String datatype - If the subject is a literal, the datatype to parse the value as. Optional.
Throws:
java.rmi.RemoteException
purgeRelationship
Delete the specified relationship. This method will remove the specified relationship(s) from the RELS-EXT datastream. If the Resource Index is enabled, this will also delete the corresponding triples from the Resource Index.
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
String pid The PID of the object.
String relationship The predicate, null matches any predicate.
String object The object, null matches any object.
boolean isLiteral A boolean value indicating whether the object is a literal.
String datatype The datatype of the literal. Optional.
Returns:
boolean True if and only if the relationship was purged.
Throws:
java.rmi.RemoteException
Object Management
ingest
Creates a new digital object in the repository. The object's initial state should be I (inactive). If the XML document does not specify the OBJID attribute of the root element, the repository will generate and return a new pid for the object resulting from this request. That pid will have the namespace of the repository. If the XML document specifies a pid, it will be assigned to the digital object provided that 1. it conforms to the Fedora pid Syntax, 2. it uses a namespace that matches the "retainPIDs" value configured for the repository, and 3. it does not collide with an existing pid of an object in the repository.
If the object has state "Active" this method will fail. It is only allowed on Inactive and Deleted objects.
Input parameters:
byte[] objectXML The digital object in an XML submission format.
String format The XML format of objectXML, e.g. "info:fedora/fedora-system:FOXML-1.1", "info:fedora/fedora-system:FOXML-1.0", "info:fedora/fedora-system:METSFedoraExt-1.1", or "info:fedora/fedora-system:ATOM-1.0".
String logMessage A log message.
Returns:
String The pid of the newly created object.
Throws:
java.rmi.RemoteException
modifyObject
Modify an object.
If this alters an object that was hitherto "Inactive" or "Deleted" to have state "Active", validation will be performed on the object to check the object to be valid, and the call will fail otherwise. See FedoraState for details.
Input parameters:
String pid The PID of the object.
String state The new state, "A", "I" or "D". See FedoraState for usage.
String ownerId The ownerId for the object.
String logMessage A log message.
Returns:
String The timestamp of the operation according to the server, in ISO8601 format.
Throws:
java.rmi.RemoteException
(export)