From 4d5f3f59d982b302a5ba61d403c2521d0b8f80e8 Mon Sep 17 00:00:00 2001 From: Paul Pound Date: Tue, 4 Dec 2012 12:14:01 -0400 Subject: [PATCH] updated comments in fedora_item --- api/fedora_item.inc | 426 ++++++++++++++++++++++++++++++++------------ 1 file changed, 314 insertions(+), 112 deletions(-) diff --git a/api/fedora_item.inc b/api/fedora_item.inc index ae524fd9..afe24592 100644 --- a/api/fedora_item.inc +++ b/api/fedora_item.inc @@ -2,6 +2,7 @@ /** * @file * Fedora Item + * wrapper around Fedora's Soap api */ define('RELS_EXT_URI', 'info:fedora/fedora-system:def/relations-external#'); @@ -18,6 +19,7 @@ define("RELS_TYPE_DATETIME", 4); /** * Fedora Item Class + * includes wrapper functions for the most commonly used Fedora soap apis */ class Fedora_Item { @@ -102,23 +104,34 @@ class Fedora_Item { /** * Exists * - * @return type + * @return boolean + * returns TRUE if the object exists in Fedora and we have permission to + * access + * */ function exists() { return (!empty($this->objectProfile)); } /** - * Add datastream from file - * - * @param type $datastream_file - * @param type $datastream_id - * @param type $datastream_label - * @param type $datastream_mimetype - * @param type $controlGroup - * @param type $logMessage + * Add Fedora datastream from file + * + * @param string $datastream_file + * path to the file we want to add to fedora as a datastream + * @param string $datastream_id + * the id to give to the datastream + * @param string $datastream_label + * a label for the datastream + * @param string $datastream_mimetype + * mimetype of the content to be added + * @param string $controlGroup + * One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced) + * @param string $logMessage + * this will be written to the objects audit trail * - * @return type + * @return string + * returns the dsid of the newly added datastream + * */ function add_datastream_from_file($datastream_file, $datastream_id, $datastream_label = NULL, $datastream_mimetype = '', $controlGroup = 'M', $logMessage = NULL) { module_load_include('inc', 'fedora_repository', 'MimeClass'); @@ -152,16 +165,23 @@ class Fedora_Item { } /** - * Add datastream from url - * - * @param type $datastream_url - * @param type $datastream_id - * @param type $datastream_label - * @param type $datastream_mimetype - * @param type $controlGroup - * @param type $logMessage - * - * @return type + * Add a fedora datastream from url + * + * @param string $datastream_url + * a url that references the location of the content + * @param string $datastream_id + * the id to give to the datastream + * @param string $datastream_label + * a label for the datastream + * @param string $datastream_mimetype + * mimetype of the content to be added + * @param string $controlGroup + * One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced) + * @param string $logMessage + * this will be written to the objects audit trail + + * @return string + * returns the dsid of the newly added datastream */ function add_datastream_from_url($datastream_url, $datastream_id, $datastream_label = NULL, $datastream_mimetype = '', $controlGroup = 'M', $logMessage = NULL) { global $base_url; @@ -208,14 +228,22 @@ class Fedora_Item { /** * Add datastream from string * - * @param type $str - * @param type $datastream_id - * @param type $datastream_label - * @param type $datastream_mimetype - * @param type $controlGroup - * @param type $logMessage - * - * @return type + * @param string str + * a string containing the content for the new datastream + * @param string $datastream_id + * the id to give to the datastream + * @param string $datastream_label + * a label for the datastream + * @param string $datastream_mimetype + * mimetype of the content to be added + * @param string $controlGroup + * One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced) + * @param string $logMessage + * this will be written to the objects audit trail + + * @return string + * returns the dsid of the newly added datastream + */ function add_datastream_from_string($str, $datastream_id, $datastream_label = NULL, $datastream_mimetype = 'text/xml', $controlGroup = 'M', $logMessage = NULL) { $dir = file_directory_temp(); @@ -233,15 +261,25 @@ class Fedora_Item { * Wrapper to add new or modify existing datastream * * @global url $base_url + * drupal $base_url * * @param url $external_url * @param string $dsid + * datastream id * @param string $label + * datastream label * @param string $mime_type + * mimetype of the content to be added or modified * @param string $controlGroup + * One of "X", "M", "R", or "E" (Inline XML, Managed Content, Redirect, or External Referenced) * @param boolean $force + * DEPRECATED in the Fedora api-m soap api, the default is FALSE and should + * be left at FALSE in most cases. + * Force the update even if it would break the data contract * @param string $logMessage + * this will be written to the objects audit trail * @param boolean $quiet + * if TRUE will suppress drupal messages */ function add_or_modify_by_reference($external_url, $dsid, $label, $mime_type, $controlGroup = 'M', $force = FALSE, $logMessage = 'Modified by Islandora API', $quiet=FALSE) { global $base_url; @@ -256,9 +294,9 @@ class Fedora_Item { /** * - * @param unknown_type $el - * @param unknown_type $object - * @param unknown_type $type + * @param DomElement $el + * @param string $object + * @param string $type */ protected function buildRelsStatement(&$el, $object, $type) { if ($type > 0) { @@ -300,8 +338,8 @@ class Fedora_Item { * - 3: integer * - 4: dateTime * - * @return ??? - * Value returned from SOAP call for modify_datastream. + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function add_relationship($relationship, $object, $namespaceURI = RELS_EXT_URI, $literal_value = RELS_TYPE_URI) { static $relsextxml = NULL; @@ -357,9 +395,24 @@ RDF; /** * Extension of add_relationship(), which acts on RELS-INT. * - * @param $dsid + * @staticvar DomDocument $relsxml + * @param string $dsid * A string containing either the base dsid (EXAMPLE) * or URI to the datastream (info:fedora/pid/EXAMPLE) + * @param string $relationship + * The predicate/relationship tag to add + * @param string $object + * The object(s)/dsid to be related to. + * @param string $namespaceURI + * @param int $literal_value + * Used to type the value. + * - 0: URI + * - 1: plain literal + * - 2: string (explicitly typed) + * - 3: integer + * - 4: dateTime + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function add_dsid_relationship($dsid, $relationship, $object, $namespaceURI = RELS_EXT_URI, $literal_value = RELS_TYPE_URI) { static $relsxml = NULL; @@ -469,11 +522,22 @@ RDF; } /** - * Extension of purge_relationships, which acts on RELS-INT. - * + * Extension of purge_relationships, this function acts on RELS-INT. * @param string $dsid * A string containing either the base dsid (EXAMPLE) * or URI to the datastream (info:fedora/pid/EXAMPLE) + * @param string $relationship + * The predicate/relationship tag to delete + * @param string $object + * The object to be related to. (NULL/value for which empty() + * evaluates to true will remove all relations of the given type, + * ignoring $literal_value) + * @param string $namespaceURI + * The predicate namespace. + * @param int $literal_value + * Same as add_relationship. + * @return boolean + * returns TRUE if the RElS-INT was modified */ function purge_dsid_relationships($dsid, $relationship, $object, $namespaceURI = RELS_EXT_URI, $literal_value = FALSE) { $f_prefix = 'info:fedora/'; @@ -533,6 +597,8 @@ RDF; * Dropped in favour of purge_relationships, which follows the same paradigm as add_relationship. This function tries to figure out the predicate URI based on the prefix/predicate given, which requires specific naming... * @param string $relationship * @param string $object + * @return boolean + * True if object was modified */ function purge_relationship($relationship, $object) { $relsext = $this->get_datastream_dissemination('RELS-EXT'); @@ -590,7 +656,8 @@ RDF; /** * Export as foxml * - * @return type + * @return string + * xml */ function export_as_foxml() { $params = array( @@ -605,11 +672,15 @@ RDF; /** * Does a search using the "query" format followed by the Fedora REST APi. * - * @param string $pattern to search for, including wildcards. - * @param string $field The field to search on, e.g. pid, title, cDate. See http://www.fedora-commons.org/confluence/display/FCR30/REST+API#RESTAPI-findObjects for details - * @param int $max_results not used at this time + * @param string $pattern + * pattern to search for, including wildcards. + * @param string $field + * The field to search on, e.g. pid, title, cDate. See http://www.fedora-commons.org/confluence/display/FCR30/REST+API#RESTAPI-findObjects for details + * @param int $max_results + * not used at this time * - * @return Array of pid => title pairs that match the results + * @return Array + * pid => title pairs that match the results */ static function find_objects_by_pattern($pattern = '*', $field = 'pid', $max_results = 100, $resultFields = array()) { module_load_include('inc', 'fedora_repository', 'api/fedora_utils'); @@ -671,11 +742,18 @@ RDF; /** * Get datastream dissemination * - * @param type $dsid - * @param type $as_of_date_time + * @param string $dsid + * The DSID of the datastream to get the dissemination of. + * @param string $as_of_date_time + * 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. * @param type $quiet + * Squash errors? * - * @return null + * @return mixed + * NULL if the DS is not present in Fedora Item's datastream list. + * The content of the DS (NULL if empty) */ function get_datastream_dissemination($dsid, $as_of_date_time = "", $quiet=TRUE) { if (!array_key_exists($dsid, $this->datastreams)) { @@ -703,10 +781,29 @@ RDF; /** * Get datastream * - * @param type $dsid + * @param string $dsid + * datastream id * @param type $as_of_date_time + * 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. * * @return type + * a datastream object + * DatastreamControlGroup controlGroup - String restricted to the values of "X", "M", "R", or "E" (InlineXML,Managed Content,Redirect, or External 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. Only valid for inline XML metadata and managed content datastreams. + * 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". + * String checksum - The value of the checksum represented as a hexadecimal string. */ function get_datastream($dsid, $as_of_date_time = '', $quiet = TRUE) { if (!array_key_exists($dsid, $this->datastreams)) { @@ -724,10 +821,13 @@ RDF; /** * Get datastream history + * Gets all versions of a datastream, sorted from most to least recent. * - * @param type $dsid + * @param string $dsid + * the datastream id * - * @return type + * @return array + * array of datastreams */ function get_datastream_history($dsid) { $params = array( @@ -745,13 +845,18 @@ RDF; /** * Get dissemination + * Calls a Fedora disseminator * - * @param type $service_definition_pid - * @param type $method_name - * @param type $parameters - * @param type $as_of_date_time - * + * @param string $service_definition_pid + * the id of the service identifier object + * @param string $method_name + * The name of the method to be executed. + * @param array $parameters + * array of key value pairs + * @param string $as_of_date_time + * The versioning dateTime. If null, Fedora will use the most recent version. * @return string + * the content returned by the specified method */ function get_dissemination($service_definition_pid, $method_name, $parameters = array(), $as_of_date_time = NULL) { $params = array( @@ -776,7 +881,15 @@ RDF; * Retrieves and returns a SimpleXML list of this item's datastreams, * and stores them as an instance variable for caching purposes. * - * @return SimpleXMLElement + * @return array + * an array of datastream definitions each element in the array contains an + * object with + * - String ID The datastream id - "DC" for the DC datastream + * - String label The datastream label + * - String MIMEType The mimetype of the datastream, if any + * + * @todo verify this documentation, previous version of this documentation + * stated this function returned a simpleXML object */ function get_datastreams_list_as_SimpleXML() { //if ( empty( $this->datastreams_list ) ) { @@ -791,6 +904,7 @@ RDF; } /** + * gets information regarding a datastream including * DatastreamControlGroup controlGroup - String restricted to the values of "X", "M", "R", or "E" (InlineXML,Managed Content,Redirect, or External Referenced). * String ID - The datastream ID (64 characters max). * String versionID - The ID of the most recent datastream version @@ -868,7 +982,9 @@ RDF; * Returns a MIME type string for the given Datastream ID. * * @param string $dsid + * the datastream id * @return string + * the mime type */ function get_mimetype_of_datastream($dsid) { $this->get_datastreams_list_as_SimpleXML(); @@ -890,7 +1006,10 @@ RDF; * exception so we will parse the RELS-EXT ourselves and simulate the * documented behaviour. * - * @param String $relationship - filter the results to match this string. + * @param string $relationship + * - filter the results to match this string. + * @return array + * array of relationships */ function get_relationships($relationship = NULL) { $relationships = array(); @@ -969,14 +1088,22 @@ RDF; return $relationships; } + /** + * @todo test and verify that this function is in use + * wrapper for the get_relationships function + * @return array + * returns an array of relationships + */ function get_models() { //This is/was formerly just a copy/paste jobbie, without the parameter being passable... return $this->get_relationships(); } /** - * Creates a RELS-EXT XML stream from the supplied array and saves it to - * the item on the server. + * save_relationships + * This function looks like it does nothing except return false + * + * @todo complete function or remove function * * @param $relationships */ @@ -1000,7 +1127,15 @@ RDF; } /** - * Set the object to a deleted state + * Set the Fedora object's state to deleted (does not remove the object from + * the repository) + * + * @param string $log_message + * a log message, this will be written to the fedora objects audit trail + * @param boolean $quiet + * TRUE to suppress drupal error messages + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function move_to_trash($log_message = 'Flagged deleted using Islandora API.', $quiet = TRUE) { // Loop through the datastreams and mark them deleted. @@ -1022,10 +1157,12 @@ RDF; } /** - * Removes this object form the repository. - * @param type $log_message + * Permanently removes an object from the repository. + * @param string $log_message * @param type $force - * @return type + * force Force the purge, even if it would break a dependency + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function purge($log_message = 'Purged using Islandora API.', $force = FALSE) { @@ -1048,13 +1185,24 @@ RDF; /** * Purge datastream * - * @param type $dsID - * @param type $start_date - * @param type $end_date - * @param type $log_message - * @param type $force + * @param string $dsID + * the datastream id + * @param string $start_date + * The (inclusive) start date-time stamp of the range. If null, this is + * taken to be the lowest possible value, and thus, the entire version + * history up to the endDT be purged. * + * @param string $end_date + * The (inclusive) ending date-time stamp of the range. If null, this is + * taken to be the greatest possible value, and thus, the entire version + * history back to the startDT will be purged. + * @param string $log_message + * a log message, this will be written to the Fedora objects audit trail + * @param boolean $force + * force Deprecated. Force the update even if it would break a data contract. + * in most cases this should be left as FALSE * - * @return type + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function purge_datastream($dsID, $start_date = NULL, $end_date = NULL, $log_message = 'Purged datastream using Islandora API', $force = FALSE) { $params = array( @@ -1072,10 +1220,12 @@ RDF; } /** - * URL + * url * @global type $base_url + * drupal $base_url * - * @return type + * @return string + * A string containing a URL to the given path. */ function url() { return url('fedora/repository/' . $this->pid . (!empty($this->objectProfile) ? '/-/' . drupal_urlencode($this->objectProfile->objLabel) : ''), array( @@ -1086,9 +1236,10 @@ RDF; /** * Get Next PID in Namespace * - * @param $pid_namespace string + * @param string $pid_namespace * * @return string + * a new PID */ static function get_next_PID_in_namespace($pid_namespace = '', $number_of_pids = 1) { if (empty($pid_namespace)) { @@ -1116,7 +1267,7 @@ RDF; /** * ingest from FOXML * - * @param type $foxml + * @param DOMDocument $foxml * * @return Fedora_Item */ @@ -1133,9 +1284,10 @@ RDF; /** * ingest from FOXML file * - * @param type $foxml_file + * @param string $foxml_file + * well formed xml conforming to Fedora's FOXML schema * - * @return type + * @return Fedora_Item */ static function ingest_from_FOXML_file($foxml_file) { $foxml = new DOMDocument(); @@ -1144,9 +1296,10 @@ RDF; } /** - * ingest from FOXML files in directory + * batch ingest from FOXML files in directory * - * @param type $path + * @param string $path + * the path on the server to the foxml files */ static function ingest_from_FOXML_files_in_directory($path) { // Open the directory. @@ -1170,13 +1323,19 @@ RDF; /** * Modify Object * - * @param $label string - * @param $state string - * @param $ownerId string - * @param $logMessage string - * @param $quiet boolean + * @param string $label + * the objects label + * @param string $state + * The new state, "A", "I" or "D". Null leaves unchanged + * @param string $ownerId + * The ownerId for the object. + * @param string $logMessage + * a log message this will get written to the Fedora objects audit trail + * @param boolean $quiet + * If TRUE suppress drupal error message * - * @return type + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function modify_object($label = '', $state = NULL, $ownerId = NULL, $logMessage = 'Modified by Islandora API', $quiet=TRUE) { $params = array( @@ -1273,8 +1432,11 @@ RDF; * @param string $logMessage * A message for the audit log. * @param boolean $quiet - * Error suppression? Refer to soap_call for usage - * (just passed along here). + * if set to true will not do a drupal set message + * + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. + * if successfull */ function modify_datastream($filename_or_content, $dsid, $label, $mime_type, $force = FALSE, $logMessage='Modified by Islandora API', $quiet=FALSE) { $toReturn = NULL; @@ -1340,15 +1502,25 @@ RDF; /** * Modify datastream by reference * - * @param type $external_url - * @param type $dsid - * @param type $label - * @param type $mime_type - * @param type $force - * @param type $logMessage - * @param type $quiet + * @param string $external_url + * a url to pass to fedora so it can load the content + * @param string $dsid + * the datastreams id + * @param string $label + * the datastreams label + * @param string $mime_type + * contents mime type + * @param boolean $force + * DEPRECATED in the Fedora api-m soap api, the default is FALSE and should + * be left at FALSE in most cases. + * Force the update even if it would break the data contract + * @param string $logMessage + * a log message, this will get written to the fedora audit trail + * @param boolean $quiet + * if quiet = TRUE we don't print error messages. * - * @return type + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function modify_datastream_by_reference($external_url, $dsid, $label, $mime_type, $force = FALSE, $logMessage = 'Modified by Islandora API', $quiet=FALSE) { global $base_url; @@ -1376,17 +1548,28 @@ RDF; } /** - * Modify datastream by value + * Modify datastream by value. This operation is only valid for Inline XML + * Datastreams (i.e. controlGroup "X") * - * @param type $content - * @param type $dsid - * @param type $label - * @param type $mime_type - * @param type $force - * @param type $logMessage - * @param type $quiet + * @param string $content + * the datastreams content + * @param string $dsid + * the datastreams id + * @param string $label + * the datastreams label + * @param string $mime_type + * the contents mime type + * @param boolean $force + * DEPRECATED in the Fedora api-m soap api, the default is FALSE and should + * be left at FALSE in most cases. + * Force the update even if it would break the data contract + * @param string $logMessage + * a log message, this will get written to the fedora objects audit trail + * @param boolean $quiet + * if $quiet = TRUE don't do drupal_set_message * - * @return type + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. */ function modify_datastream_by_value($content, $dsid, $label, $mime_type, $force = FALSE, $logMessage = 'Modified by Islandora API', $quiet=FALSE) { $params = array( @@ -1406,11 +1589,18 @@ RDF; } /** + * set the state of a fedora objects datastream + * @param string $dsid + * the datastream id + * @param string $state + * the datastream state one of 'A', 'D' or 'I' (Active, Deleted, Inactive) + * @param string $log_message + * a log message will get written to the Fedora objects audit trail + * @param string $quiet + * if $quite = TRUE do not call drupal_set_message + * @return string + * The timestamp of the operation according to the server, in ISO8601 format. * - * @param unknown_type $dsid - * @param unknown_type $state - * @param unknown_type $log_message - * @param unknown_type $quiet */ function set_datastream_state($dsid, $state, $log_message = 'Modified by Islandora API', $quiet = FALSE) { $valid_states = array('A', 'D', 'I'); @@ -1476,8 +1666,10 @@ RDF; * Creates the minimal FOXML for a new Fedora object, which is then passed to * ingest_from_FOXML to be added to the repository. * - * @param string $pid if none given, getnextpid will be called. - * @param string $state The initial state, A - Active, I - Inactive, D - Deleted + * @param string $pid + * if none given, getnextpid will be called. + * @param string $state + * The initial state, A - Active, I - Inactive, D - Deleted * @param type $label * @param string $owner * Used to set an object's ownerId attribute. Defaults to current user's @@ -1535,12 +1727,17 @@ RDF; /** * ingest new item * - * @param type $pid - * @param type $state - * @param type $label - * @param type $owner + * @param string $pid + * Fedora identifier to use in the Foxml + * @param string $state + * Objects state one of 'A', 'D' or 'I' (Active, Deleted, Inactive) + * @param string $label + * the objects label + * @param string $owner + * the objects owner * - * @return type + * @return Fedora_Item + * the new Fedora_Item object */ static function ingest_new_item($pid = '', $state = 'A', $label = '', $owner = '') { return self::ingest_from_FOXML(self::create_object_FOXML($pid, $state, $label, $owner)); @@ -1549,9 +1746,11 @@ RDF; /** * fedora item exists * - * @param type $pid + * @param string $pid + * The Fedora objects identifier (pid) * - * @return type + * @return boolean + * returns TRUE if the item exists */ static function fedora_item_exists($pid) { $item = new Fedora_Item($pid); @@ -1564,6 +1763,9 @@ RDF; * * @param string $PID * The Fedora PID to retrieve the + * + * @return string + * The ownerId property of the Fedora object */ static function getOwnerId($PID) { $params = array(