Added doc tags to the api

14 years ago · 64fac18623
7 changed files with 405 additions and 135 deletions
--- a/api/dublin_core.inc
+++ b/api/dublin_core.inc
@ -1,13 +1,19 @@
 <?php
+
 // $Id$

-/* 
+/**
+ * @file
 * Implements a simple class for working with Dublin Core data and exporting it
 * back to XML. Inspiration and design shamelessly stolen from the pyfedora
 * project at http://pypi.python.org/pypi/pyfedora/0.1.0
 */

+/**
+ * Dublin Core Class
+ */
 class Dublin_Core {
+
  public $dc = array(
    'dc:title' => array(),
    'dc:creator' => array(),
@ -41,7 +47,7 @@ class Dublin_Core {
  }

  /**
-   *
+   * Add Elements
   * @param <type> $element_name
   * @param <type> $value
   */
@ -67,6 +73,8 @@ class Dublin_Core {

  /**
   * Serialize this object to XML and return it.
+   * @param type $with_preamble
+   * @return type 
   */
  function as_xml($with_preamble = FALSE) {
    $dc_xml = new DomDocument();
@ -88,10 +96,17 @@ class Dublin_Core {
    return $dc_xml->saveXML();
  }

+  /**
+   * Create dc from dict ( does nothing )
+   */
  static function create_dc_from_dict() {
    
  }

+  /**
+   * Save ??
+   * @param type $alt_owner 
+   */
  function save($alt_owner = NULL) {
    $item_to_update = (!empty($alt_owner) ? $alt_owner : $this->owner);
    // My Java roots showing, trying to do polymorphism in PHP.
--- a/api/fedora_collection.inc
+++ b/api/fedora_collection.inc
@ -1,10 +1,11 @@
 <?php
+
 // $Id$

-/* 
+/**
+ * @file
 * Operations that affect a Fedora repository at a collection level.
 */
-
 module_load_include('inc', 'fedora_repository', 'CollectionClass');
 module_load_include('inc', 'fedora_repository', 'api/fedora_item');
 module_load_include('inc', 'fedora_repository', 'api/fedora_utils');
@ -13,7 +14,10 @@ module_load_include('module', 'fedora_repository');
 /**
 * Exports a fedora collection object and all of its children in a format
 * that will let you import them into another repository.
- * @param <type> $format
+ * @param type $collection_pid
+ * @param type $relationship
+ * @param type $format
+ * @return type 
 */
 function export_collection($collection_pid, $relationship = 'isMemberOfCollection', $format = 'info:fedora/fedora-system:FOXML-1.1') {
  $collection_item = new Fedora_Item($collection_pid);
@ -117,6 +121,17 @@ function get_related_items_as_xml($collection_pid, $relationship = array('isMemb
  return $content;
 }

+/**
+ * Get Related Items as Arrays
+ * @param type $collection_pid
+ * @param type $relationship
+ * @param type $limit
+ * @param type $offset
+ * @param type $active_objects_only
+ * @param type $cmodel
+ * @param type $orderby
+ * @return type 
+ */
 function get_related_items_as_array($collection_pid, $relationship = 'isMemberOfCollection', $limit = 10000, $offset = 0, $active_objects_only = TRUE, $cmodel = NULL, $orderby = '$title') {
  $content = get_related_items_as_xml($collection_pid, $relationship, $limit, $offset, $active_objects_only, $cmodel, $orderby);
  if (empty($content)) {
--- a/api/fedora_export.inc
+++ b/api/fedora_export.inc
@ -2,6 +2,10 @@

 // $Id$

+/**
+ * @file
+ * Fedora Export
+ */
 define('FOXML_10', 'info:fedora/fedora-system:FOXML-1.0');
 define('FOXML_11', 'info:fedora/fedora-system:FOXML-1.1');
 define('METS_10', 'info:fedora/fedora-system:METSFedoraExt-1.0');
@ -11,6 +15,11 @@ define('ATOMZip_11', 'info:fedora/fedora-system:ATOMZip-1.1');

 /**
 * Function to to export all objects assocoiated with a given pid to the export area
+ * @param type $pid
+ * @param type $foxml_dir
+ * @param type $ob_dir
+ * @param type $log
+ * @return type 
 */
 function export_to_export_area($pid, $foxml_dir, $ob_dir, &$log = array()) {
  if (!$paths = export_objects_for_pid($pid, $ob_dir, $log)) {
@ -24,6 +33,13 @@ function export_to_export_area($pid, $foxml_dir, $ob_dir, &$log = array()) {
  return TRUE;
 }

+/**
+ * Export objects for pids ??
+ * @param type $pid
+ * @param type $dir
+ * @param type $log
+ * @return string 
+ */
 function export_objects_for_pid($pid, $dir, &$log) {
  module_load_include('inc', 'fedora_repository', 'api/fedora_item');
  $item = new Fedora_Item($pid);
@ -58,6 +74,16 @@ function export_objects_for_pid($pid, $dir, &$log) {
  return $paths;
 }

+/**
+ * Export foxml for pid
+ * @param type $pid
+ * @param type $dir
+ * @param type $paths
+ * @param type $log
+ * @param type $format
+ * @param type $remove_islandora
+ * @return type 
+ */
 function export_foxml_for_pid($pid, $dir, $paths, &$log, $format = FOXML_11, $remove_islandora = FALSE) {
  module_load_include('inc', 'fedora_repository', 'ObjectHelper');
  $ob_helper = new ObjectHelper();
@ -170,10 +196,22 @@ function export_foxml_for_pid($pid, $dir, $paths, &$log, $format = FOXML_11, $re
  return TRUE;
 }

+/**
+ * Get file extension
+ * @param type $mimeType
+ * @return type 
+ */
 function get_file_extension($mimeType) {
  return substr(strstr($mimeType, '/'), 1);
 }

+/**
+ * Log line
+ * @param type $msg
+ * @param type $severity
+ * @param type $sep
+ * @return type 
+ */
 function log_line($msg, $severity = 'info', $sep = "\t") {
  return date("Y-m-d H:i:s") . $sep . ucfirst($severity) . $sep . $msg;
 }
--- a/api/fedora_item.inc
+++ b/api/fedora_item.inc
@ -2,9 +2,16 @@

 // $Id$

+/**
+ * @file
+ * Fedora Item
+ */
 define('RELS_EXT_URI', 'info:fedora/fedora-system:def/relations-external#');
 define("FEDORA_MODEL_URI", 'info:fedora/fedora-system:def/model#');

+/**
+ * Fedora Item Class
+ */
 class Fedora_Item {

  public $pid = NULL; // The $pid of the fedora object represented by an instance of this class.
@ -51,10 +58,24 @@ class Fedora_Item {
    }
  }

+  /**
+   * Exists 
+   * @return type 
+   */
  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
+   * @return type 
+   */
  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');
    if (empty($datastream_mimetype)) {
@ -76,6 +97,16 @@ class Fedora_Item {
    return $return_value;
  }

+  /**
+   * 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 
+   */
  function add_datastream_from_url($datastream_url, $datastream_id, $datastream_label = NULL, $datastream_mimetype = '', $controlGroup = 'M', $logMessage = null) {
    if (empty($datastream_label)) {
      $datastream_label = $datastream_id;
@ -99,9 +130,18 @@ class Fedora_Item {


    return $this->soap_call('addDataStream', $params);
-
  }

+  /**
+   * 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 
+   */
  function add_datastream_from_string($str, $datastream_id, $datastream_label = NULL, $datastream_mimetype = 'text/xml', $controlGroup = 'M', $logMessage = null) {
    $dir = sys_get_temp_dir();
    $tmpfilename = tempnam($dir, 'fedoratmp');
@ -116,8 +156,9 @@ class Fedora_Item {
  /**
   * Add a relationship string to this object's RELS-EXT.
   * does not support rels-int yet.
-   * @param string $relationship
-   * @param <type> $object
+   * @param type $relationship
+   * @param type $object
+   * @param type $namespaceURI 
   */
  function add_relationship($relationship, $object, $namespaceURI = RELS_EXT_URI) {
    $ds_list = $this->get_datastreams_list_as_array();
@ -214,6 +255,10 @@ class Fedora_Item {
    //print ($description->dump_node());
  }

+  /**
+   * Export as foxml
+   * @return type 
+   */
  function export_as_foxml() {
    $params = array(
      'pid' => $this->pid,
@ -290,6 +335,12 @@ class Fedora_Item {
    return $results;
  }

+  /**
+   * Get datastream dissemination
+   * @param type $dsid
+   * @param type $as_of_date_time
+   * @return string 
+   */
  function get_datastream_dissemination($dsid, $as_of_date_time = "") {
    $params = array(
      'pid' => $this->pid,
@ -307,6 +358,12 @@ class Fedora_Item {
    return $content;
  }

+  /**
+   * Get datastream
+   * @param type $dsid
+   * @param type $as_of_date_time
+   * @return type 
+   */
  function get_datastream($dsid, $as_of_date_time = "") {
    $params = array(
      'pid' => $this->pid,
@ -318,6 +375,11 @@ class Fedora_Item {
    return $object->datastream;
  }

+  /**
+   * Get datastream history
+   * @param type $dsid
+   * @return type 
+   */
  function get_datastream_history($dsid) {
    $params = array(
      'pid' => $this->pid,
@ -332,6 +394,14 @@ class Fedora_Item {
    return $ret;
  }

+  /**
+   * Get dissemination
+   * @param type $service_definition_pid
+   * @param type $method_name
+   * @param type $parameters
+   * @param type $as_of_date_time
+   * @return string 
+   */
  function get_dissemination($service_definition_pid, $method_name, $parameters = array(), $as_of_date_time = null) {
    $params = array(
      'pid' => $this->pid,
@ -530,6 +600,9 @@ class Fedora_Item {

  /**
   * Removes this object form the repository.
+   * @param type $log_message
+   * @param type $force
+   * @return type 
   */
  function purge($log_message = 'Purged using Islandora API.', $force = FALSE) {
    $params = array(
@ -541,6 +614,15 @@ class Fedora_Item {
    return $this->soap_call('purgeObject', $params);
  }

+  /**
+   * Purge datastream
+   * @param type $dsID
+   * @param type $start_date
+   * @param type $end_date
+   * @param type $log_message
+   * @param type $force
+   * @return type 
+   */
  function purge_datastream($dsID, $start_date = NULL, $end_date = NULL, $log_message = 'Purged datastream using Islandora API', $force = FALSE) {
    $params = array(
      'pid' => $this->pid,
@ -553,11 +635,21 @@ class Fedora_Item {
    return $this->soap_call('purgeDatastream', $params);
  }

+  /**
+   * URL
+   * @global type $base_url
+   * @return type 
+   */
  function url() {
    global $base_url;
    return $base_url . '/fedora/repository/' . $this->pid . (!empty($this->objectProfile) ? '/-/' . drupal_urlencode($this->objectProfile->objLabel) : '');
  }

+  /**
+   * Get Next PID in Namespace
+   * @param type $pid_namespace
+   * @return type 
+   */
  static function get_next_PID_in_namespace($pid_namespace = '') {

    if (empty($pid_namespace)) {
@ -581,18 +673,32 @@ class Fedora_Item {
    return $result->pid;
  }

+  /**
+   * ingest from FOXML
+   * @param type $foxml
+   * @return Fedora_Item 
+   */
  static function ingest_from_FOXML($foxml) {
    $params = array('objectXML' => $foxml->saveXML(), 'format' => "info:fedora/fedora-system:FOXML-1.1", 'logMessage' => "Fedora Object Ingested");
    $object = self::soap_call('ingest', $params);
    return new Fedora_Item($object->objectPID);
  }

+  /**
+   * ingest from FOXML file
+   * @param type $foxml_file
+   * @return type 
+   */
  static function ingest_from_FOXML_file($foxml_file) {
    $foxml = new DOMDocument();
    $foxml->load($foxml_file);
    return self::ingest_from_FOXML($foxml);
  }

+  /**
+   * ingest from FOXML files in directory
+   * @param type $path 
+   */
  static function ingest_from_FOXML_files_in_directory($path) {
    // Open the directory
    $dir_handle = @opendir($path);
@ -612,6 +718,15 @@ class Fedora_Item {
    closedir($dir_handle);
  }

+  /**
+   * Modify Object
+   * @param type $label
+   * @param type $state
+   * @param type $ownerId
+   * @param type $logMessage
+   * @param type $quiet
+   * @return type 
+   */
  function modify_object($label = '', $state = null, $ownerId = null, $logMessage = 'Modified by Islandora API', $quiet=TRUE) {

    $params = array(
@ -625,6 +740,17 @@ class Fedora_Item {
    return self::soap_call('modifyObject', $params, $quiet);
  }

+  /**
+   * 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
+   * @return type 
+   */
  function modify_datastream_by_reference($external_url, $dsid, $label, $mime_type, $force = FALSE, $logMessage = 'Modified by Islandora API', $quiet=FALSE) {
    $params = array(
      'pid' => $this->pid,
@ -642,6 +768,17 @@ class Fedora_Item {
    return self::soap_call('modifyDatastreamByReference', $params, $quiet);
  }

+  /**
+   * Modify datastream by value
+   * @param type $content
+   * @param type $dsid
+   * @param type $label
+   * @param type $mime_type
+   * @param type $force
+   * @param type $logMessage
+   * @param type $quiet
+   * @return type 
+   */
  function modify_datastream_by_value($content, $dsid, $label, $mime_type, $force = FALSE, $logMessage = 'Modified by Islandora API', $quiet=FALSE) {
    $params = array(
      'pid' => $this->pid,
@ -659,6 +796,13 @@ class Fedora_Item {
    return self::soap_call('modifyDatastreamByValue', $params, $quiet);
  }

+  /**
+   * Soap call
+   * @param type $function_name
+   * @param type $params_array
+   * @param type $quiet
+   * @return type 
+   */
  static function soap_call($function_name, $params_array, $quiet = FALSE) {
    if (!self::$connection_helper) {
      module_load_include('inc', 'fedora_repository', 'ConnectionHelper');
@ -730,6 +874,9 @@ class Fedora_Item {
   *
   * @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 type $owner
+   * @return DOMDocument 
   */
  static function create_object_FOXML($pid = '', $state = 'A', $label = 'Untitled', $owner = '') {
    $foxml = new DOMDocument("1.0", "UTF-8");
@ -778,10 +925,23 @@ class Fedora_Item {
    return $foxml;
  }

+  /**
+   * ingest new item
+   * @param type $pid
+   * @param type $state
+   * @param type $label
+   * @param type $owner
+   * @return type 
+   */
  static function ingest_new_item($pid = '', $state = 'A', $label = '', $owner = '') {
    return self::ingest_from_FOXML(self::create_object_FOXML($pid, $state, $label, $owner));
  }

+  /**
+   * fedora item exists 
+   * @param type $pid
+   * @return type 
+   */
  static function fedora_item_exists($pid) {
    $item = new Fedora_Item($pid);
    return $item->exists();
--- a/api/fedora_utils.inc
+++ b/api/fedora_utils.inc
@ -1,13 +1,16 @@
 <?php
-// $Id$

-// @file fedora_utils.inc
-// Base utilities used by the Islansora fedora module.
+// $Id$

+/**
+ * @file
+ * Base utilities used by the Islandora fedora module.
+ */
 /*
 * Functions that emulate php5.3 functionality for backwards compatiablity
 */
 if (!function_exists('str_getcsv')) {
+
  function str_getcsv($input, $delimiter=',', $enclosure='"', $escape=null, $eol=null) {
    $temp = fopen("php://memory", "rw");
    fwrite($temp, $input);
@ -16,7 +19,9 @@ if (!function_exists('str_getcsv')) {
    fclose($temp);
    return $r;
  }
+
 }
+
 /*
 * Functions that emulate php5.3 functionality for backwards compatiablity
 */
@ -25,7 +30,15 @@ if (!function_exists('str_getcsv')) {
 * Static functions used by the Fedora PHP API.
 */

-
+/**
+ * do curl
+ * @global type $user
+ * @param type $url
+ * @param type $return_to_variable
+ * @param type $number_of_post_vars
+ * @param type $post
+ * @return type 
+ */
 function do_curl($url, $return_to_variable = 1, $number_of_post_vars = 0, $post = NULL) {
  global $user;
  // Check if we are inside Drupal and there is a valid user.
@ -65,14 +78,16 @@ function do_curl($url, $return_to_variable = 1, $number_of_post_vars = 0, $post
  }
 }

+/**
+ * Fedora available
+ * @return type 
+ */
 function fedora_available() {

  $response = do_curl(variable_get('fedora_base_url', 'http://localhost:8080/fedora') . '/describe');
  return strstr($response, 'Repository Information HTML Presentation') !== FALSE;
-
 }

-
 /**
 * Returns a UTF-8-encoded transcripiton of the string given in $in_str.
 * @param string $in_str
@ -88,6 +103,11 @@ function fix_encoding($in_str) {
  }
 }

+/**
+ * valid pid ??
+ * @param type $pid
+ * @return boolean 
+ */
 function validPid($pid) {
  $valid = FALSE;
  if (strlen(trim($pid)) <= 64 && preg_match('/^([A-Za-z0-9]|-|\.)+:(([A-Za-z0-9])|-|\.|~|_|(%[0-9A-F]{2}))+$/', trim($pid))) {
@ -97,6 +117,11 @@ function validPid($pid) {
  return $valid;
 }

+/**
+ * Valid Dsid ??
+ * @param type $dsid
+ * @return boolean 
+ */
 function validDsid($dsid) {
  $valid = FALSE;
  if (strlen(trim($dsid)) <= 64 && preg_match('/^[a-zA-Z0-9\_\-\.]+$/', trim($dsid))) {
@ -106,6 +131,11 @@ function validDsid($dsid) {
  return $valid;
 }

+/**
+ * fixDsid ??
+ * @param type $dsid
+ * @return string 
+ */
 function fixDsid($dsid) {
  $new_dsid = trim($dsid);

@ -123,6 +153,5 @@ function fixDsid($dsid) {
    $new_dsid = 'item' . rand(1, 100);

  return $new_dsid;
-
 }

--- a/api/rels-ext.inc
+++ b/api/rels-ext.inc
@ -1,32 +1,35 @@
 <?php
+
 // $Id$

-/* 
- * To change this template, choose Tools | Templates
- * and open the template in the editor.
+/**
+ * @file
+ * RelsExt class
 */

 /**
- * Description of relsext
- *
- * @author aoneill
+ * RelsExt class
 */
 class RelsExt {
+
  // Instance variables
  public $relsExtArray = array();
  private $originalRelsExtArray = array(); // Used to determine the result of modified() funciton.
-    // Member functions

  /**
   * Constructor that builds itself by retrieving the RELS-EXT stream from
   * the repository for the given Fedora_Item.
   * @param Fedora_Item $item
   */
+
  function RelsExt($item) {
    $relsextxml = $item->get_datastream_dissemination('RELS-EXT');
-
  }

+  /**
+   * modified 
+   * @return type 
+   */
  function modified() {
    return!(empty(array_diff($this->relsExtArray, $this->originalRelsExtArray)) &&
    empty(array_diff($this->originalRelsExtArray, $this->relsExtArray)));
@ -39,5 +42,6 @@ class RelsExt {
  function save() {
    
  }
+
 }

--- a/api/tagging.inc
+++ b/api/tagging.inc
@ -1,20 +1,25 @@
 <?php
+
 // $Id$

-/*
- * @file tagging.inc
+/**
+ * @file
+ * TagSet Class
 */

 /**
- * Description of tagging
- *
- * @author aoneill
+ * TagSet Class
 */
 class TagSet {
+
  public $tags = array();
  public $item = NULL;
  public $tagsDSID = 'TAGS';

+  /**
+   * Constructor
+   * @param type $item 
+   */
  function TagSet($item = NULL) {
    if (!empty($item) && get_class($item) == 'Fedora_Item') {
      $this->item = $item;
@ -22,6 +27,10 @@ class TagSet {
    }
  }

+  /**
+   * Load ??
+   * @return type 
+   */
  function load() {
    $tagsxml = isset($this->item->datastreams[$this->tagsDSID]) ? $this->item->get_datastream_dissemination($this->tagsDSID) : NULL;
    if (empty($tagsxml)) {
@ -59,11 +68,11 @@ class TagSet {
      else {
        $this->item->modify_datastream_by_value($tagdoc->saveXML(), $this->tagsDSID, 'Tags', 'text/xml', 'X');
      }
-    } 
-    catch (exception $e) {
+    } catch (exception $e) {
      drupal_set_message('There was an error saving the tags datastream: !e', array('!e' => $e), 'error');
      return FALSE;
    }
    return TRUE;
  }
+
 }