islandora/islandora.module

<?php

/**
 * @file
 * Defines all the hooks this module implements.
 *
 * islandora.module: defines paths (drupal menu items) as entry points and acts
 *  as a hub for dispatching tasks to other modules.
 *
 * This file is part of Islandora.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with the program.  If not, see <http ://www.gnu.org/licenses/>.
 */

// Common datastreams.
define('DS_COMP_STREAM', 'DS-COMPOSITE-MODEL');

// Permissions.
define('FEDORA_VIEW_OBJECTS', 'view fedora repository objects');
define('FEDORA_METADATA_EDIT', 'edit fedora metadata');
define('FEDORA_ADD_DS', 'add fedora datastreams');
define('FEDORA_INGEST', 'ingest fedora objects');
define('FEDORA_PURGE', 'delete fedora objects and datastreams');
define('FEDORA_MANAGE_PROPERTIES', 'manage object properties');

// Hooks.
define('ISLANDORA_VIEW_HOOK', 'islandora_view_object');
define('ISLANDORA_EDIT_HOOK', 'islandora_edit_object');
define('ISLANDORA_OVERVIEW_HOOK', 'islandora_overview_object');
define('ISLANDORA_PRE_INGEST_HOOK', 'islandora_ingest_pre_ingest');
define('ISLANDORA_POST_INGEST_HOOK', 'islandora_ingest_post_ingest');
define('ISLANDORA_PRE_PURGE_OBJECT_HOOK', 'islandora_pre_purge_object');
define('ISLANDORA_POST_PURGE_OBJECT_HOOK', 'islandora_post_purge_object');

// @todo Add Documentation.
define('ISLANDORA_OBJECT_INGESTED_HOOK', 'islandora_object_ingested');
define('ISLANDORA_OBJECT_MODIFIED_HOOK', 'islandora_object_modified');
define('ISLANDORA_OBJECT_PURGED_HOOK', 'islandora_object_purged');
define('ISLANDORA_DATASTREAM_INGESTED_HOOK', 'islandora_datastream_ingested');
define('ISLANDORA_DATASTREAM_MODIFIED_HOOK', 'islandora_datastream_modified');
define('ISLANDORA_DATASTREAM_PURGED_HOOK', 'islandora_datastream_purged');
define('ISLANDORA_INGEST_STEP_HOOK', 'islandora_ingest_steps');

/**
 * Implements hook_menu().
 *
 * We need some standard entry points so we can have consistent urls for
 * different Object actions
 */
function islandora_menu() {
  $items = array();
  $items['admin/islandora'] = array(
    'title' => 'Islandora',
    'description' => "Configure settings associated with Islandora.",
    'access arguments' => array('administer site configuration'),
    'type' => MENU_NORMAL_ITEM,
  );
  $items['admin/islandora/configure'] = array(
    'title' => 'Configuration',
    'description' => 'Configure settings for Islandora.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('islandora_repository_admin'),
    'file' => 'includes/admin.form.inc',
    'access arguments' => array('administer site configuration'),
    'type' => MENU_NORMAL_ITEM,
    'weight' => -1,
  );
  $items['admin/islandora/solution_packs'] = array(
    'title' => 'Solution packs',
    'description' => 'Install content models and collections required by installed solution packs.',
    'page callback' => 'islandora_solution_packs_admin',
    'access arguments' => array(FEDORA_ADD_DS),
    'file' => 'includes/solution_packs.inc',
    'type' => MENU_NORMAL_ITEM,
  );
  $items['islandora'] = array(
    'title' => 'Islandora Repository',
    'page callback' => 'islandora_view_default_object',
    'type' => MENU_NORMAL_ITEM,
    'access arguments' => array(FEDORA_VIEW_OBJECTS),
  );
  $items['islandora/object/%islandora_object'] = array(
    'title' => 'Repository',
    'page callback' => 'islandora_view_object',
    'page arguments' => array(2),
    'type' => MENU_NORMAL_ITEM,
    'access callback' => 'islandora_object_access_callback',
    'access arguments' => array(FEDORA_VIEW_OBJECTS, 2),
  );
  $items['islandora/object/%islandora_object/view'] = array(
    'title' => 'View',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -1,
  );
  $items['islandora/object/%islandora_object/view/default'] = array(
    'title' => 'View',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -1,
  );
  $items['islandora/object/%islandora_object/manage'] = array(
    'title' => 'Manage',
    'page callback' => 'islandora_manage_overview_object',
    'page arguments' => array(2),
    'type' => MENU_LOCAL_TASK,
    'access callback' => 'islandora_object_manage_access_callback',
    'access arguments' => array(
      array(
        FEDORA_MANAGE_PROPERTIES,
        FEDORA_METADATA_EDIT,
        FEDORA_ADD_DS,
        FEDORA_PURGE,
      ), 2),
  );

  $items['islandora/object/%islandora_object/manage/overview'] = array(
    'title' => 'Overview',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -20,
  );

  $items['islandora/object/%islandora_object/manage/datastreams'] = array(
    'title' => 'Datastreams',
    'type' => MENU_LOCAL_TASK,
    'page callback' => 'islandora_edit_object',
    'page arguments' => array(2),
    'access callback' => 'islandora_object_manage_access_callback',
    'access arguments' => array(
      array(
        FEDORA_METADATA_EDIT,
        FEDORA_ADD_DS,
        FEDORA_PURGE,
      ), 2),
    'weight' => -10,
  );

  $items['islandora/object/%islandora_object/manage/properties'] = array(
    'title' => 'Properties',
    'page callback' => 'drupal_get_form',
    'file' => 'includes/object_properties.form.inc',
    'page arguments' => array('islandora_object_properties_form', 2),
    'type' => MENU_LOCAL_TASK,
    'access callback' => 'islandora_object_access_callback',
    'access arguments' => array(FEDORA_MANAGE_PROPERTIES, 2),
    'weight' => -5,
  );
  $items['islandora/object/%islandora_object/delete'] = array(
    'title' => 'Delete object',
    'file' => 'includes/delete_object.form.inc',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('islandora_delete_object_form', 2),
    'type' => MENU_CALLBACK,
    'access callback' => 'islandora_object_access_callback',
    'access arguments' => array(FEDORA_PURGE, 2),
  );
  $items['islandora/object/%islandora_object/manage/datastreams/add'] = array(
    'title' => 'Add a datastream',
    'file' => 'includes/add_datastream.form.inc',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('islandora_add_datastream_form', 2),
    'type' => MENU_LOCAL_ACTION,
    'access callback' => 'islandora_object_access_callback',
    'access arguments' => array(FEDORA_ADD_DS, 2),
  );
  $items['islandora/object/%islandora_object/manage/datastreams/add/autocomplete'] = array(
    'file' => 'includes/add_datastream.form.inc',
    'page callback' => 'islandora_add_datastream_form_autocomplete_callback',
    'page arguments' => array(2),
    'type' => MENU_CALLBACK,
    'access callback' => 'islandora_object_access_callback',
    'access arguments' => array(FEDORA_ADD_DS, 2),
  );
  $items['islandora/object/%islandora_object/datastream/%islandora_datastream'] = array(
    'title' => 'View datastream',
    'page callback' => 'islandora_view_datastream',
    'page arguments' => array(4, FALSE),
    'type' => MENU_CALLBACK,
    'file' => 'includes/datastream.inc',
    'access callback' => 'islandora_object_datastream_access_callback',
    'access arguments' => array(FEDORA_VIEW_OBJECTS, 2, 4),
    'load arguments' => array(2),
  );
  // This menu item uses token authentication in islandora_tokened_object.
  $items['islandora/object/%islandora_tokened_object/datastream/%islandora_tokened_datastream/view'] = array(
    'title' => 'View datastream',
    'load arguments' => array('%map'),
    'access callback' => 'islandora_object_datastream_tokened_access_callback',
    'access arguments' => array(FEDORA_VIEW_OBJECTS, 2, 4),
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['islandora/object/%islandora_object/datastream/%islandora_datastream/download'] = array(
    'title' => 'Download datastream',
    'page callback' => 'islandora_download_datastream',
    'page arguments' => array(4),
    'type' => MENU_CALLBACK,
    'file' => 'includes/datastream.inc',
    'access callback' => 'islandora_object_datastream_access_callback',
    'access arguments' => array(FEDORA_VIEW_OBJECTS, 2, 4),
    'load arguments' => array(2),
  );
  $items['islandora/object/%islandora_object/datastream/%islandora_datastream/edit'] = array(
    'title' => 'Edit datastream',
    'page callback' => 'islandora_edit_datastream',
    'page arguments' => array(4),
    'type' => MENU_CALLBACK,
    'file' => 'includes/datastream.inc',
    'access callback' => 'islandora_object_datastream_access_callback',
    'access arguments' => array(FEDORA_METADATA_EDIT, 2, 4),
    'load arguments' => array(2),
  );
  $items['islandora/object/%islandora_object/datastream/%islandora_datastream/delete'] = array(
    'title' => 'Delete data stream',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('islandora_delete_datastream_form', 4),
    'file' => 'includes/delete_datastream.form.inc',
    'type' => MENU_CALLBACK,
    'access callback' => 'islandora_object_datastream_access_callback',
    'access arguments' => array(FEDORA_PURGE, 2, 4),
    'load arguments' => array(2),
  );
  $items['islandora/ingest'] = array(
    'title' => 'Add an Object',
    'page callback' => 'islandora_ingest_callback',
    'file' => 'includes/ingest.menu.inc',
    'type' => MENU_SUGGESTED_ITEM,
    'access arguments' => array(FEDORA_INGEST),
  );
  return $items;
}

/**
 * Implements hook_admin_paths().
 */
function islandora_admin_paths() {
  $paths = array();
  $paths['islandora/object/*/manage*'] = TRUE;
  $paths['islandora/object/*/delete'] = TRUE;
  $paths['islandora/object/*/datastream/*/edit'] = TRUE;
  return $paths;
}

/**
 * Implements hook_theme().
 */
function islandora_theme() {
  return array(
    // Default object template.
    'islandora_default' => array(
      'file' => 'theme/theme.inc',
      'template' => 'theme/islandora-object',
      'variables' => array('islandora_object' => NULL),
    ),
    // Default edit page.
    'islandora_default_edit' => array(
      'file' => 'theme/theme.inc',
      'template' => 'theme/islandora-object-edit',
      'variables' => array('islandora_object' => NULL),
    ),
    // Admin table for solution pack viewer selection.
    'islandora_viewers_table' => array(
      'file' => 'includes/solution_packs.inc',
      'render element' => 'form',
    ),
  );
}

/**
 * Implements hook_permission().
 */
function islandora_permission() {
  return array(
    FEDORA_VIEW_OBJECTS => array(
      'title' => t('View repository objects'),
      'description' => t('View objects in the repository. Note: Fedora XACML security policies may override this permission.'),
    ),
    FEDORA_ADD_DS => array(
      'title' => t('Add datastreams to repository objects'),
      'description' => t('Add datastreams to objects in the repository. Note: Fedora XACML security policies may override this position.'),
    ),
    FEDORA_METADATA_EDIT => array(
      'title' => t('Edit metadata'),
      'description' => t('Edit metadata for objects in the repository.'),
    ),
    FEDORA_INGEST => array(
      'title' => t('Create new repository objects'),
      'description' => t('Create new objects in the repository.'),
    ),
    FEDORA_PURGE => array(
      'title' => t('Permanently remove objects from the repository'),
      'description' => t('Permanently remove objects from the repository.'),
    ),
    FEDORA_MANAGE_PROPERTIES => array(
      'title' => t('Manage object properties'),
      'description' => t('Modify object labels, owner IDs, and states.'),
    ),
  );
}

/**
 * Implements hook_forms().
 */
function islandora_forms($form_id) {
  $forms = array();
  if (strpos($form_id, 'islandora_solution_pack_form_') !== FALSE) {
    $forms[$form_id] = array(
      'callback' => 'islandora_solution_pack_form',
    );
  }
  return $forms;
}

/**
 * Checks whether the user can access the given object.
 *
 * Checks for object existance, accessiblitly, namespace permissions,
 * and user permissions
 *
 * @param string $perm
 *   User permission to test for.
 * @param FedoraObject $object
 *   The object to test, if NULL given the object doesn't exist or is
 *   inaccessible.
 *
 * @return bool
 *   TRUE if the user is allowed to access this object, FALSE otherwise.
 */
function islandora_object_access_callback($perm, $object = NULL) {
  module_load_include('inc', 'islandora', 'includes/utilities');

  if (!$object && !islandora_describe_repository()) {
    islandora_display_repository_inaccessible_message();
    return FALSE;
  }

  return user_access($perm) && is_object($object) && islandora_namespace_accessible($object->id);
}

/**
 * Checks whether the user can access the given object and datastream.
 *
 * Checks for object existance, accessiblitly, namespace permissions,
 * and user permissions
 *
 * @param string $perm
 *   The user permission to test for.
 * @param FedoraObject $object
 *   The object to test, if NULL given the object doesn't exist or is
 *   inaccessible.
 * @param FedoraDatastream $datastream
 *   The datastream to test, if NULL given the datastream doesn't exist
 *   or is inaccessible.
 * @param StdObject $account
 *   The account to test permissions as or NULL for current user.
 *
 * @return bool
 *   TRUE if the user is allowed to access this object, FALSE otherwise.
 */
function islandora_object_datastream_access_callback($perm, $object = NULL, $datastream = NULL, $account = NULL) {
  module_load_include('inc', 'islandora', 'includes/utilities');
  return user_access($perm, $account) && is_object($object) && islandora_namespace_accessible($object->id) && is_object($datastream);
}

/**
 * Checks whether the user can access the given object and datastream.
 *
 * This function will validate and use a token if present in the GET parameters.
 *
 * Checks for object existance, accessiblitly, namespace permissions,
 * and user permissions
 *
 * @see islandora_object_datastream_tokened_access_callback()
 */
function islandora_object_datastream_tokened_access_callback($perm, $object = NULL, $datastream = NULL) {
  module_load_include('inc', 'islandora', 'includes/utilities');

  $token_account = NULL;
  $token = filter_input(INPUT_GET, 'token', FILTER_SANITIZE_STRING);

  if ($token) {
    $user = islandora_validate_object_token($object->id, $datastream->id, $token);
    if ($user) {
      $token_account = user_load($user->uid);
    }
  }

  return islandora_object_datastream_access_callback($perm, $object, $datastream, $token_account);
}

/**
 * Checks whether the user can access the given object's manage tab.
 *
 * Checks for object existance, accessiblitly, namespace permissions,
 * and user permissions
 *
 * @param array $perms
 *   Array of user permission to test for.
 * @param FedoraObject $object
 *   The object to test, if NULL given the object doesn't exist or is
 *   inaccessible.
 *
 * @return bool
 *   TRUE if the user is allowed to access this object, FALSE otherwise.
 */
function islandora_object_manage_access_callback($perms, $object = NULL) {
  module_load_include('inc', 'islandora', 'includes/utilities');

  if (!$object && !islandora_describe_repository()) {
    islandora_display_repository_inaccessible_message();
    return FALSE;
  }

  $has_access = FALSE;
  for ($i = 0; $i < count($perms) && !$has_access; $i++) {
    $has_access = $has_access || user_access($perms[$i]);
  }

  return $has_access && is_object($object) && islandora_namespace_accessible($object->id);
}

/**
 * Renders the given objects manage overview page.
 *
 * @param FedoraObject $object
 *   The object to manage.
 *
 * @return string
 *   The HTML repersentation of the manage object page.
 */
function islandora_manage_overview_object(FedoraObject $object) {
  module_load_include('inc', 'islandora', 'includes/utilities');
  $output = array();
  foreach (islandora_build_hook_list(ISLANDORA_OVERVIEW_HOOK, $object->models) as $hook) {
    $temp = module_invoke_all($hook, $object);
    if (!empty($temp)) {
      $output = array_merge_recursive($output, $temp);
    }
  }
  if (empty($output)) {
    // Add in the default, if we did not get any results.
    $output = islandora_default_islandora_manage_overview_object($object);
  }
  arsort($output);
  drupal_alter(ISLANDORA_OVERVIEW_HOOK, $object, $output);
  return implode('', $output);
}

/**
 * Renders the default manage object page for the given object.
 *
 * @param FedoraObject $object
 *   The object used to render the manage object page.
 *
 * @return array
 *   The default rendering of the object manage page, indexed at
 *   'Default Edit output'.
 */
function islandora_default_islandora_manage_overview_object(FedoraObject $object) {
  $output = theme('islandora_default_overview', array('islandora_object' => $object));
  return array('Default overview output' => $output);
}

/**
 * Renders the given objects manage page.
 *
 * Its possible to modify the output of this function if 'ISLANDORA_EDIT_HOOK'
 * is implemented in other modules.
 *
 * If no modules implement 'ISLANDORA_EDIT_HOOK' then this function returns the
 *  default manage view.
 *
 * @param FedoraObject $object
 *   The object to manage.
 *
 * @return string
 *   The HTML repersentation of the manage object page.
 */
function islandora_edit_object(FedoraObject $object) {
  module_load_include('inc', 'islandora', 'includes/breadcrumb');
  module_load_include('inc', 'islandora', 'includes/utilities');
  drupal_set_title($object->label);
  drupal_set_breadcrumb(islandora_get_breadcrumbs($object));
  $output = array();
  foreach (islandora_build_hook_list(ISLANDORA_EDIT_HOOK, $object->models) as $hook) {
    $temp = module_invoke_all($hook, $object);
    if (!empty($temp)) {
      $output = array_merge_recursive($output, $temp);
    }
  }
  if (empty($output)) {
    // Add in the default, if we did not get any results.
    $output = islandora_default_islandora_edit_object($object);
  }
  arsort($output);
  drupal_alter(ISLANDORA_EDIT_HOOK, $object, $output);
  return implode('', $output);
}

/**
 * Renders the default manage object page for the given object.
 *
 * @param FedoraObject $object
 *   The object used to render the manage object page.
 *
 * @return array
 *   The default rendering of the object manage page, indexed at
 *   'Default Edit output'.
 */
function islandora_default_islandora_edit_object(FedoraObject $object) {
  $output = theme('islandora_default_edit', array('islandora_object' => $object));
  return array('Default Edit output' => $output);
}

/**
 * Page callback for the path "islandora".
 *
 * Redirects to the view of the object indicated by the Drupal variable
 * 'islandora_repository_pid'.
 */
function islandora_view_default_object() {
  $pid = variable_get('islandora_repository_pid', 'islandora:root');
  drupal_goto("islandora/object/$pid");
}

/**
 * Renders the default view object page for the given object.
 *
 * Modules should implement ISLANDORA_VIEW_HOOK for the Fedora Content
 * models that their modules want to provide a view for.
 *
 * If no modules implement the hook then the default view object page
 *  will be rendered.
 *
 * @param FedoraObject $object
 *   The object to view.
 *
 * @return string
 *   The html repersentation of this object.
 */
function islandora_view_object(FedoraObject $object) {
  module_load_include('inc', 'islandora', 'includes/breadcrumb');
  module_load_include('inc', 'islandora', 'includes/utilities');
  drupal_set_title($object->label);
  drupal_set_breadcrumb(islandora_get_breadcrumbs($object));
  // Optional pager parameters.
  $page_number = (empty($_GET['page'])) ? '1' : $_GET['page'];
  $page_size = (empty($_GET['pagesize'])) ? '10' : $_GET['pagesize'];
  $output = array();
  foreach (islandora_build_hook_list(ISLANDORA_VIEW_HOOK, $object->models) as $hook) {
    // @todo Remove page number and size from this hook, implementers of the
    // hook should use drupal page handling directly.
    $temp = module_invoke_all($hook, $object, $page_number, $page_size);
    if (!empty($temp)) {
      $output = array_merge_recursive($output, $temp);
    }
  }
  if (empty($output)) {
    // No results, use the default view.
    $output = islandora_default_islandora_view_object($object);
  }
  arsort($output);
  drupal_alter(ISLANDORA_VIEW_HOOK, $object, $output);
  return implode('', $output);
}

/**
 * Renders the default view object page for the given object.
 *
 * @param FedoraObject $object
 *   The object used to render the view object page.
 *
 * @return array
 *   The default rendering of the object view page, indexed at 'Default output'.
 */
function islandora_default_islandora_view_object($object) {
  $output = theme('islandora_default', array('islandora_object' => $object));
  return array('Default output' => $output);
}

/**
 * Just a wrapper around fetchings the IslandoraTuque object.
 *
 * Includes some very basic error logging.
 *
 * @param object $user
 *   The user to connect as.
 * @param string $url
 *   The URL to connect to.
 *
 * @return IslandoraTuque
 *   A IslandoraTuque instance
 */
function islandora_get_tuque_connection($user = NULL, $url = NULL) {
  $tuque = &drupal_static(__FUNCTION__);
  if (!$tuque) {
    if (IslandoraTuque::exists()) {
      try {
        $tuque = new IslandoraTuque($user, $url);
      }
      catch (Exception $e) {
        drupal_set_message(t('Unable to connect to the repository %e', array('%e' => $e)), 'error');
      }
    }
    else {
      return NULL;
    }
  }
  return $tuque;
}

/**
 * Loads the object from the given ID if possible.
 *
 * Often used to get a connection and return an object for the one specified in
 * the menu path as '%islandora_object'.
 *
 * @param string $object_id
 *   The pid of an object in the menu path identified by '%islandora_object'.
 *
 * @return FedoraObject
 *   If the given object id exists in the repository then this returns a
 *   FedoraObject.
 *   If no object was found it returns FALSE which triggers
 *   drupal_page_not_found().
 *   If the object was inaccessible then NULL is returned, and the
 *   access callback is expected to catch that case, triggering
 *   drupal_access_denied().
 */
function islandora_object_load($object_id) {
  $tuque = islandora_get_tuque_connection();
  if ($tuque) {
    try {
      return $tuque->repository->getObject(urldecode($object_id));
    }
    catch (Exception $e) {
      if ($e->getCode() == '404') {
        return FALSE;
      }
      else {
        return NULL;
      }
    }
  }
  else {
    IslandoraTuque::getError();
  }
  // Assuming access denied in all other cases for now.
  return NULL;
}

/**
 * Load the the object using a token if passed as a GET parameter.
 *
 * A helper function to get a connection and return an object using a token
 * for authentication.
 *
 * @param string $object_id
 *   The PID of an object in the menu path identified by
 *   '%islandora_tokened_object'.
 * @param array $map
 *   Used to extract the Fedora object's DSID at $map[4].
 *
 * @return FedoraObject
 *   A token authenticated object. @see islandora_object_load
 */
function islandora_tokened_object_load($object_id, $map) {
  if (array_key_exists('token', $_GET)) {
    $token = filter_input(INPUT_GET, 'token', FILTER_SANITIZE_STRING);
    if ($token) {
      module_load_include('inc', 'islandora', 'includes/authtokens');
      $token_user = islandora_validate_object_token($object_id, $map[4], $token);
      $token_user = $token_user ? user_load($token_user->uid) : NULL;
      islandora_get_tuque_connection($token_user);
    }
  }
  return islandora_object_load($object_id);
}

/**
 * Fetches a datastream object.
 *
 * This datastream load must take in arguments in a different
 * order than the usual islandora_datastream_load.  This is because
 * the function islandora_tokened_object_load needs DSID. It uses
 * the path %map to avoid duplicate parameters. The menu system
 * passes 'load arguments' to both islandora_tokened_object_load
 * and this function and the first parameter is positional with the token.
 * An alternative:
 * islandora_tokened_object_load(PID, DSID, PID)
 * islandora_tokened_datastream_load(DSID, DSID, PID)
 *
 * @param mixed $datastream_id
 *   %islandora_tokened_datastream @see islandora_datastream_load
 * @param array $map
 *   Used to extract the Fedora object's PID at $map[2].
 *
 * @return FedoraDatastream
 *   A datastream from Fedora.
 *
 * @see islandora_datastream_load
 */
function islandora_tokened_datastream_load($datastream_id, $map) {
  return islandora_datastream_load($datastream_id, $map[2]);
}

/**
 * Fetches a datastream object.
 *
 * A helper function to get an datastream specified as '%islandora_datastream'
 * for the object specified in the menu path as '%islandora_object'.
 *
 * Its up to the access callbacks and menu callbacks to trigger
 * drupal_access_denied() when appropriate.
 *
 * @param string $datastream_id
 *   The DSID of the datastream specified as '%islandora_datastream' to fetch
 *   from the given object in the menu path identified by '%islandora_object'.
 *
 * @param mixed $object_id
 *   The object to load the datastream from.  This can be a Fedora PID or
 *   an instantiated IslandoraFedoraObject as it implements __toString()
 *   returning the PID.
 *
 * @return FedoraDatastream
 *   If the given datastream ID exists then this returns a FedoraDatastream
 *   object, otherwise it returns NULL which triggers drupal_page_not_found().
 */
function islandora_datastream_load($datastream_id, $object_id) {
  $object = is_object($object_id) ? $object_id : islandora_object_load($object_id);
  if (!$object) {
    return NULL;
  }
  return $object[$datastream_id];
}

/**
 * Fetches the given datastream version from its datastream.
 *
 * Content model, collection view and collection policy datastreams may now
 * optionally define a version number in their top-level XML element as an
 * attribute, as in:
 *   <content_model name="Collection" version="2" ...
 *
 * @param FedoraObject $object
 *   The Object the datastream belongs to.
 * @param string $dsid
 *   The ID of the datastream.
 * @param string $datastream_file
 *   The datastream's content.
 *
 * @return int
 *   The datastreams version if found, NULL otherwise.
 */
function islandora_get_islandora_datastream_version($object = NULL, $dsid = NULL, $datastream_file = NULL) {
  $return = NULL;
  // @TODO, need better check for $object
  if ($object && $object[$dsid]) {
    $doc = simplexml_load_string($object[$dsid]->content);
  }
  elseif (!empty($datastream_file)) {
    $doc = simplexml_load_file($datastream_file);
  }

  if (!empty($doc) && $version = (int) $doc->attributes()->version) {
    $return = $version;
  }

  return $return;
}

/**
 * Implements hook_islandora_required_objects().
 */
function islandora_islandora_required_objects(IslandoraTuque $connection) {
  $module_path = drupal_get_path('module', 'islandora');
  // Root Collection.
  $root_collection = $connection->repository->constructObject('islandora:root');
  $root_collection->owner = 'fedoraAdmin';
  $root_collection->label = 'Top-level Collection';
  $root_collection->models = 'islandora:collectionCModel';
  // Collection Policy Datastream.
  $datastream = $root_collection->constructDatastream('COLLECTION_POLICY', 'X');
  $datastream->label = 'Collection policy';
  $datastream->mimetype = 'text/xml';
  $datastream->setContentFromFile("$module_path/xml/islandora_collection_policy.xml", FALSE);
  $root_collection->ingestDatastream($datastream);
  // TN Datastream.
  $datastream = $root_collection->constructDatastream('TN', 'M');
  $datastream->label = 'Thumbnail';
  $datastream->mimetype = 'image/png';
  $datastream->setContentFromFile("$module_path/images/folder.png", FALSE);
  $root_collection->ingestDatastream($datastream);
  return array(
    'islandora' => array(
      'title' => 'Islandora',
      'objects' => array(
        $root_collection,
      ),
    ),
  );
}

/**
 * Implements islandora_undeleteable_datastreams().
 */
function islandora_islandora_undeletable_datastreams(array $models) {
  return array('DC');
}

/**
 * Ingest the given object.
 *
 * @param NewFedoraObject $object
 *   An ingestable FedoraObject.
 *
 * @return FedoraObject
 *   The ingested FedoraObject.
 */
function islandora_add_object(NewFedoraObject &$object) {
  return $object->repository->ingestObject($object);
}

/**
 * Delete's or purges the given object.
 *
 * @param FedoraObject $object
 *   An object to delete.
 *
 * @return bool
 *   The ingested FedoraObject, after running the pre/post ingest hooks.
 */
function islandora_delete_object(FedoraObject &$object) {
  return $object->repository->purgeObject($object->id);
}

/**
 * Delete's or purges the given datastream.
 *
 * @throws Exception
 *  Which types are undefined, but more than likely because of the hooks
 *  there will be several kinds.
 *
 * @param FedoraDatastream $datastream
 *   The datastream to delete.
 *
 * @return bool
 *   TRUE if successful, FALSE otherwise.
 */
function islandora_delete_datastream(FedoraDatastream &$datastream) {
  $object = $datastream->parent;
  return $object->purgeDatastream($datastream->id);
}

/**
 * Implements hook_cron().
 */
function islandora_cron() {
  module_load_include('inc', 'islandora', 'includes/authtokens');
  islandora_remove_expired_tokens();
}

/**
 * Implements hook_entity_info().
 *
 * Some boiler-plate for Tokens (the module, not our authentication work-
 * around).
 */
function islandora_entity_info() {
  $entities = array();

  $entities['islandora_object'] = array(
    'label' => t('Islandora Object'),
    'controller class' => 'IslandoraObjectEntityController',
    'fieldable' => FALSE,
    'entity keys' => array(
      'id' => 'id',
      'label' => 'label',
    ),
  );

  return $entities;
}

/**
 * Implements hook_entity_property_info().
 *
 * Details the tokens which will be available on the given object.
 */
function islandora_entity_property_info() {
  $info = array();

  $p = &$info['islandora_object']['properties'];

  $p['id'] = array(
    'type' => 'text',
    'label' => t('ID'),
    'description' => t('The identifier of the object.'),
  );
  $p['label'] = array(
    'type' => 'text',
    'label' => t('Object Label'),
    'description' => t('The label of the object.'),
  );
  $p['owner'] = array(
    'type' => 'text',
    'label' => t('Object Owner'),
    'description' => t('The name of the owner of the object.'),
  );
  $p['state'] = array(
    'type' => 'text',
    'label' => t('Object State'),
    'description' => t('An initial representing the state of the object.'),
  );
  $p['models'] = array(
    'type' => 'list<text>',
    'label' => t('Content Models'),
    'description' => t('The list of content models which the object has.'),
  );

  return $info;
}