Build, Access, Modify and Delete Fedora objects with the Tuque interface

William Panting edited this page May 1, 2014 · 17 revisions
Clone this wiki locally

This document has been deprecated in favor of Working With Fedora Objects Programmatically Via Tuque

Using the Tuque API to build and manipulate Fedora Repository objects.

It is inadvisable to rely on functionality available in lower level API objects due to the possibility of these interfaces not being present on all repository implementations in the future.

Connecting to a Fedora Repository

To connect directly to a Fedora Repository using the tuque library:

$connection = new RepositoryConnection($fedoraUrl, $username, $password);
$connection->reuseConnection = TRUE;
$repository = new FedoraRepository(
       new FedoraApi($connection),
       new SimpleCache());

The IslandoraTuque class provides a simple constructor for Islandora users.

D6 module_load_include('inc', 'fedora_repository', 'api/tuque');

No module_load_include is required for Drupal 7 installations.
The IslandoraTuque class is found in includes/tuque.inc and is automatically loaded by the islandora.info file

$my_islandora_tuque = new IslandoraTuque();
$repository = $my_islandora_tuque->repository;

or

$my_islandora_tuque = islandora_get_tuque_connection()
$repository = $my_islandora_tuque->repository;

All interaction with Fedora can now take place through the $repository object. D7 There is a wrapper object that handles some errors and fires some hooks in includes/tuque.inc. More error handling is available if one uses the wrapper functions in islandora.module.

To build a new object:

Create array of ContentModels for the object. This will normally be a single element array:

$content_models = array(array('pid' => 'islandora:collectionCModel'));

Identify the namespace for the new pid, and identify the collection the object is to be a member of. Tuque will retrieve the next available PID in that namespace.

$namespace = 'test';
$collection_pid = 'islandora:root';

Create the object directly with tuque:

$fedora_object = $repository->constructObject($namespace); // allow fedora to generate a PID

or with a specified PID:

$fedora_object = $repository->constructObject($pid); // create an object with the given PID

Set the content model

$fedora_object->models = array('islandora:collectionCModel');

Label the object

$fedora_object->label = “my new object”;

Set the owner

$fedora_object->owner = $username;

Build datastream

$datastream_id = “TN”;
$new_datastream = $fedora_object->constructDatastream($datastream_id);

or

$datastream_id = "MODS";
$controlGroup = "X";
$new_datastream = $fedora_object->constructDatastream($datastream_id, $controlGroup);

Set label, mimetype, and content as a minimum. Content may come from url, string, or file

$new_datastream->label = 'MYDSID';
$new_datastream->mimetype = 'something/something';
$new_datastream->setContentFromUrl(URL_TO_CONTENT);

or

$new_datastream->setContentFromFile(PATH_TO_CONTENT);

or

$new_datastream->setContentFromString(“content”);

For datastreams of the Redirect control group:

$new_datastream->url = 'some redirect URL';

Add datastream to object

$fedora_object->ingestDatastream($new_datastream);

Manipulate object's RELS-EXT

$fedora_object->relationships->remove(FEDORA_MODEL_URI, 'hasModel', 'islandora:collectionCModel');
$fedora_object->relationships->add(FEDORA_MODEL_URI, 'hasModel', 'islandora:imageCModel');

Manipulate object's RELS-INT

$fedora_object['your dsid']->relationships->remove(ISLANDORA_SCHOLAR_EMBARGO_RELS_URI, 'embargo-until');
$fedora_object['your dsid']->relationships->add(ISLANDORA_SCHOLAR_EMBARGO_RELS_URI, 'embargo-until', 'some date', RELS_TYPE_DATETIME);

Ingest object into fedora repository

$new_fedora_object = islandora_add_object($fedora_object);

or ingest with existing repository object

$repository->ingestObject($fedora_object);

Working with existing objects.

Create object to access and manipulate existing Fedora object.

$pid = “test:1”;
$fedora_object = islandora_object_load($pid);

or

$fedora_object = $repository->getObject($pid);

Object evaluates to FALSE if the Object doesn't exist.

if (!$fedora_object) {
  drupal_set_message("Fedora Object isn't in the repo!");
}

Print the existing models

print_r($fedora_object['models']);

Remove model

unset($fedora_object['models']['islandora:collectionCModel']);

Check if an object has a model

in_array('islandora:collectionCModel', $fedora_object->models);

Purge Object from repository

$fedora_object->repository->purgeObject($pid);

or

$repository->purgeObject($pid);

Delete Object from repository (set object's state as 'D')

$fedora_object->delete()

Get PID of object.

$pid = $fedoraObject->id;

Accessing RELS_EXT

Returns an array of associative arrays representing all relationships.

$rels = $fedora_object->relationships->get()

Each array has two keys, each pointing to its own associative array of values.

[0] = Array
  (
   [predicate] => Array
       (
           [value] => hasModel
           [alias] => fedora-model
           [namespace] => info:fedora/fedora-system:def/model#
       )

   [object] => Array
       (
           [literal] => 
           [value] => islandora:collectionCModel
       )
  )
[1] => Array......

Returns array of relationships filtered by namespace and predicate

$rels = $fedora_object->relationships->get('info:fedora/fedora-system:def/model#', 'hasModel' );

Datastreams

Get individual datastream by DSID

$datastream = $fedora_object['dsid'];

Get properties of Datastream.

$dsid = $datastream->id;

All datastream properties. Not case sensitive.

label
controlGroup
versionable
state
mimetype
format
size
checksum
checksumType
createdDate
content
url
location
logMessage

Iterate through datastreams in an object.

foreach($fedora_object as $datastream){
 // access individual datastreams.
}

Properties can be accessed or mutated.

$old_mime = $datastream->mimeType;
$datastream->mimeType = “new/mimetype”;
$datastream->content = file_get_contents('http://myexample.com/sample.jpg'));

Creating or updating a datastream that may or may not exist.

// Create DS or grab it.
if (!isset($fedora_object["JP2"])) {
  $jp2_ds = $fedora_object->constructDatastream('JP2', 'M');
}
else {
  $jp2_ds = $fedora_object["JP2"];
}
$jp2_ds->label = 'Derived display JP2.';
$jp2_ds->mimeType = 'image/jp2';
// Don't copy the file.
$jp2_ds->setContentFromFile($jp2_file, FALSE);
// May not need to be called if the DS already existed
$fedora_object->ingestDatastream($jp2_ds);

Exporting an object's FOXML

See wiki.duraspace.org/display/FEDORA35/REST+API#RESTAPI-export for possible values of the 'format', context', and 'encoding' parameters in the call to the Tuque API's 'export' method.

// $foxml is a string containing the requested XML.
$foxml = $repository->api->m->export($pid,
array('format' => 'info:fedora/fedora-system:FOXML-1.1',
  'context' => 'migrate',
  'encoding' => 'UTF-8')
);

Access Resource Index

$objects = $fedora_object->repository->ri->itqlQuery($query, 'unlimited'); // for itql
$objects = $fedora_object->repository->ri->sparqlQuery($query); // for SparQL queries