NAME
Catmandu::FedoraCommons - Low level Catmandu interface to the Fedora
Commons REST API
SYNOPSIS
# Use the command line tools
$ fedora_admin.pl
# Or the low-level API-s
use Catmandu::FedoraCommons;
my $fedora = Catmandu::FedoraCommons->new('http://localhost:8080/fedora','fedoraAdmin','fedoraAdmin');
my $result = $fedora->findObjects(terms=>'*');
die $result->error unless $result->is_ok;
my $hits = $result->parse_content();
for my $hit (@{ $hits->{results} }) {
printf "%s\n" , $hit->{pid};
}
# Or using the higher level Catmandu::Store codes you can do things like
use Catmandu::Store::FedoraCommons;
my $store = Catmandu::Store::FedoraCommons->new(
baseurl => 'http://localhost:8080/fedora',
username => 'fedoraAdmin',
password => 'fedoraAdmin',
model => 'Catmandu::Store::FedoraCommons::DC' # default
);
$store->bag->each(sub {
my $model = shift;
printf "title: %s\n" , join("" , @{ $model->{title} });
printf "creator: %s\n" , join("" , @{ $model->{creator} });
my $pid = $model->{_id};
my $ds = $store->fedora->listDatastreams(pid => $pid)->parse_content;
});
my $obj = $store->bag->add({
title => ['The Master and Margarita'] ,
creator => ['Bulgakov, Mikhail'] }
);
$store->fedora->addDatastream(pid => $obj->{_id} , url => "http://myurl/rabbit.jpg");
# Add your own perl version of a descriptive metadata model by implementing your own
# model that can do a serialize and deserialize.
DESCRIPTION
Catmandu::FedoraCommons is an Perl API to the Fedora Commons REST API
(http://www.fedora.info/). Supported versions are Fedora Commons 3.6 or
better.
ACCESS METHODS
new($base_url,$username,$password)
Create a new Catmandu::FedoraCommons connecting to the baseurl of the
Fedora Commons installation.
findObjects(query => $query, maxResults => $maxResults)
findObjects(terms => $terms , maxResults => $maxResults)
Execute a search query on the Fedora Commons server. One of 'query' or
'terms' is required. Query contains a phrase optionally including '*'
and '?' wildcards. Terms contain one or more conditions separated by
space. A condition is a field followed by an operator, followed by a
value. The = operator will match if the field's entire value matches
the value given. The ~ operator will match on phrases within fields,
and accepts the ? and * wildcards. The <, >, <=, and >= operators can
be used with numeric values, such as dates.
Examples:
query => "*o*"
query => "?edora"
terms => "pid~demo:* description~fedora"
terms => "cDate>=1976-03-04 creator~*n*"
terms => "mDate>2002-10-2 mDate<2002-10-2T12:00:00"
Optionally a maxResults parameter may be specified limiting the number
of search results (default is 20). This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::findObjects model.
resumeFindObjects(sessionToken => $token)
This method returns the next batch of search results. This method
returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::findObjects model.
Example:
my $result = $fedora->findObjects(terms=>'*');
die $result->error unless $result->is_ok;
my $hits = $result->parse_content();
for my $hit (@{ $hits->{results} }) {
printf "%s\n" , $hit->{pid};
}
my $result = $fedora->resumeFindObjects(sessionToken => $hits->{token});
my $hits = $result->parse_content();
...
getDatastreamDissemination(pid => $pid, dsID=> $dsID, asOfDateTime =>
$date, callback => \&callback)
This method returns a datastream from the Fedora Commons repository.
Required parameters are the identifier of the object $pid and the
identifier of the datastream $dsID. Optionally a datestamp
$asOfDateTime can be provided. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::getDatastreamDissemination model.
To stream the contents of the datastream a callback function can be
provided.
Example:
$fedora->getDatastreamDissemination(pid => 'demo:5', dsID => 'VERYHIGHRES', callback => \&process);
sub process {
my ($data, $response, $protocol) = @_;
print $data;
}
getDissemination(pid => $pid , sdefPid => $sdefPid , method => $method ,
%method_parameters , callback => \&callback)
This method execute a dissemination method on the Fedora Commons
server. Required parametes are the object $pid, the service definition
$sdefPid and the name of the method $method. Optionally further method
parameters can be provided and a callback function to stream the
results (see getDatastreamDissemination). This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::getDatastreamDissemination model.
Example:
$fedora->getDissemination(pid => 'demo:29', sdefPid => 'demo:27' , method => 'resizeImage' , width => 100, callback => \&process);
getObjectHistory(pid => $pid)
This method returns the version history of an object. Required is the
object $pid. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::getObjectHistory model.
Example:
my $obj = $fedora->getObjectHistory(pid => 'demo:29')->parse_content;
for @{$obj->{objectChangeDate}} {}
print "$_\n;
}
getObjectProfile(pid => $pid, asOfDateTime => $date)
This method returns a detailed description of an object. Required is
the object $pid. Optionally a version date asOfDateTime can be
provided. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::getObjectProfile model.
Example:
my $obj = $fedora->getObjectProfile(pid => 'demo:29')->parse_content;
printf "Label: %s\n" , $obj->{objLabel};
listDatastreams(pid => $pid, asOfDateTime => $date)
This method returns a list of datastreams provided in the object.
Required is the object $pid. Optionally a version date asOfDateTime can
be provided. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::listDatastreams model.
Example:
my $obj = $fedora->listDatastreams(pid => 'demo:29')->parse_content;
for (@{ $obj->{datastream}} ) {
printf "Label: %s\n" , $_->{label};
}
listMethods(pid => $pid , sdefPid => $sdefPid , asOfDateTime => $date)
This method return a list of methods that can be executed on an object.
Required is the object $pid and the object $sdefPid. Optionally a
version date asOfDateTime can be provided. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::listMethods model.
Example:
my $obj = $fedora->listMethods(pid => 'demo:29')->parse_content;
for ( @{ $obj->{sDef} }) {
printf "[%s]\n" , $_->{$pid};
for my $m ( @{ $_->{method} } ) {
printf "\t%s\n" , $m->{name};
}
}
describeRepository
This method returns information about the fedora repository. No
arguments required. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::describeRepository model.
Example:
my $desc = $fedora->describeRepository()->parse_content();
MODIFY METHODS
addDatastream(pid => $pid , dsID => $dsID, url => $remote_location, %args)
addDatastream(pid => $pid , dsID => $dsID, file => $filename , %args)
addDatastream(pid => $pid , dsID => $dsID, xml => $xml , %args)
This method adds a data stream to the object. Required parameters are
the object $pid, a new datastream $dsID and a remote $url, a local
$file or an $xml string which contains the content. Optionally any of
these datastream modifiers may be provided: controlGroup, altIDs,
dsLabel, versionable, dsState, formatURI, checksumType, checksum,
mimeType, logMessage. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
Example:
my $obj = $fedora->addDatastream(pid => 'demo:29', dsID => 'TEST' , file => 'README', mimeType => 'text/plain')->parse_content;
print "Uploaded at: %s\n" , $obj->{dateTime};
addRelationship(pid => $pid, relation => [ $subject, $predicate, $object]
[, dataType => $dataType])
This methods adds a triple to the 'RELS-EXT' data stream of the object.
Requires parameters are the object $pid and a relation as a triple
ARRAY reference. Optionally the $datatype of the literal may be
provided. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::addRelationship model.
Example:
$fedora->addRelationship(pid => 'demo:29' , relation => [ 'info:fedora/demo:29' , 'http://my.org/name' , 'Peter']);
export(pid => $pid [, format => $format , context => $context , encoding
=> $encoding])
This method exports the data model of the object in FOXML,METS or ATOM.
Required is $pid of the object. Optionally a $context may be provided
and the $format of the export. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::export model.
Example:
my $res = $fedora->export(pid => 'demo:29');
print $res->raw;
print "%s\n" , $res->parse_content->{objectProperties}->{label};
getDatastream(pid => $pid, dsID => $dsID , %args)
This method return metadata about a data stream. Required is the object
$pid and the $dsID of the data stream. Optionally a version
'asOfDateTime' can be provided and a 'validateChecksum' check. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
Example:
my $obj = $fedora->getDatastream(pid => 'demo:29', dsID => 'DC')->parse_content;
printf "Label: %s\n" , $obj->{profile}->{dsLabel};
getDatastreamHistory(pid => $pid , dsID => $dsID , %args)
This method returns the version history of a data stream. Required
paramter is the $pid of the object and the $dsID of the data stream.
This method returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::datastreamHistory model.
Example:
my $obj = $fedora->getDatastreamHistory(pid => 'demo:29', dsID => 'DC')->parse_content;
for (@{ $obj->{profile} }) {
printf "Version: %s\n" , $_->{dsCreateDate};
}
getNextPID(namespace => $namespace, numPIDs => $numPIDs)
This method generates a new pid. Optionally a 'namespace' can be
provided and the required 'numPIDs' you need. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::pidList model.
Example:
my $pid = $fedora->getNextPID()->parse_content->[0];
getObjectXML(pid => $pid)
This method exports the data model of the object in FOXML format.
Required is $pid of the object. This method returns a
Catmandu::FedoraCommons::Response object .
Example:
my $res = $fedora->getObjectXML(pid => 'demo:29');
print $res->raw;
getRelationships(pid => $pid [, relation => [$subject, $predicate, undef]
, format => $format ])
This method returns all RELS-EXT triples for an object. Required
parameter is the $pid of the object. Optionally the triples may be
filetered using the 'relation' parameter. Format defines the returned
format. See: https://wiki.duraspace.org/display/FEDORA36/REST+API for
more information. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::getRelationships model.
Example:
my $obj = $fedora->getRelationships(pid => 'demo:29')->parse_content;
my $iter = $obj->get_statements();
print "Names of things:\n";
while (my $st = $iter->next) {
my $s = $st->subject;
my $name = $st->object;
print "The name of $s is $name\n";
}
ingest(pid => $pid , file => $filename , xml => $xml , format => $format ,
%args)
ingest(pid => 'new' , file => $filename , xml => $xml , format => $format
, %args)
This method ingest an object into Fedora Commons. Required is the $pid
of the new object (which can be the string 'new' when Fedora has to
generate a new pid), and the $filename or $xml to upload writen as
$format. Optionally the following parameters can be provided: label,
encoding, namespace, ownerId, logMessage. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::ingest model.
Example:
my $obj = $fedora->ingest(pid => 'new', file => 't/obj_demo_40.zip', format => 'info:fedora/fedora-system:ATOMZip-1.1')->parse_content;
printf "created: %s\n" , $obj->{pid};
modifyDatastream(pid => $pid , dsID => $dsID, url => $remote_location,
%args)
modifyDatastream(pid => $pid , dsID => $dsID, file => $filename , %args)
modifyDatastream(pid => $pid , dsID => $dsID, xml => $xml , %args)
This method updated a data stream in the object. Required parameters
are the object $pid, a new datastream $dsID and a remote $url, a local
$file or an $xml string which contains the content. Optionally any of
these datastream modifiers may be provided: controlGroup, altIDs,
dsLabel, versionable, dsState, formatURI, checksumType, checksum,
mimeType, logMessage. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::datastreamProfile model.
Example:
my $obj = $fedora->modifyDatastream(pid => 'demo:29', dsID => 'TEST' , file => 'README', mimeType => 'text/plain')->parse_content;
print "Uploaded at: %s\n" , $obj->{dateTime};
modifyObject(pid => $pid, label => $label , ownerId => ownerId , state =>
$state , logMessage => $logMessage , lastModifiedDate =>
$lastModifiedDate)
This method updated the metadata of an object. Required parameter is
the $pid of the object. Optionally one or more of label, ownerId,
state, logMessage and lastModifiedDate can be provided. This method
returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::modifyObject model.
Example:
$fedora->modifyObject(pid => 'demo:29' , state => 'I');
purgeDatastream(pid => $pid , dsID => $dsID , startDT => $startDT , endDT
=> $endDT , logMessage => $logMessage)
This method purges a data stream from an object. Required parameters is
the $pid of the object and the $dsID of the data stream. Optionally a
range $startDT to $endDT versions can be provided to be deleted. See:
https://wiki.duraspace.org/display/FEDORA36/REST+API for more
information. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::purgeDatastream model.
Example:
$fedora->purgeDatastream(pid => 'demo:29', dsID => 'TEST')->parse_content;
purgeObject(pid => $pid, logMessage => $logMessage)
This method purges an object from Fedora Commons. Required parameter is
the $pid of the object. Optionally a $logMessage can be provided. This
method returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::purgeObject model.
Example:
$fedora->purgeObject(pid => 'demo:29');
purgeRelationship(pid => $pid, relation => [ $subject, $predicate,
$object] [, dataType => $dataType])
This method removes a triple from the RELS-EXT data stream of an
object. Required parameters are the $pid of the object and the relation
to be deleted. Optionally the $dataType of the literal can be provided.
This method returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::purgeRelationship model.
Example:
$fedora->purgeRelationship(pid => 'demo:29' , relation => [ 'info:fedora/demo:29' , 'http://my.org/name' , 'Peter'])
setDatastreamState(pid => $pid, dsID => $dsID, dsState => $dsState)
This method can be used to put a data stream on/offline. Required
parameters are the $pid of the object , the $dsID of the data stream
and the required new $dsState ((A)ctive, (I)nactive, (D)eleted). This
method returns a Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::datastreamProfile model.
Example:
$fedora->setDatastreamState(pid => 'demo:29' , dsID => 'url' , dsState => 'I');
setDatastreamVersionable(pid => $pid, dsID => $dsID, versionable =>
$versionable)
This method updates the versionable state of a data stream. Required
parameters are the $pid of the object, the $dsID of the data stream and
the new $versionable (true|false) state. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::datastreamProfile model.
Example:
$fedora->setDatastreamVersionable(pid => 'demo:29' , dsID => 'url' , versionable => 'false');
validate(pid => $pid)
This method can be used to validate the content of an object. Required
parameter is the $pid of the object. This method returns a
Catmandu::FedoraCommons::Response object with a
Catmandu::FedoraCommons::Model::validate model.
Example:
my $obj = $fedora->validate(pid => 'demo:29')->parse_content;
print "Is valid: %s\n" , $obj->{valid};
upload(file => $file)
This method uploads a file to the Fedora Server. Required parameter is
the $file name. This method returns a Catmandu::FedoraCommons::Response
object with a Catmandu::FedoraCommons::Model::upload- model.
Example:
my $obj = $fedora->upload(file => 't/marc.xml')->parse_content;
print "Upload id: %s\n" , $obj->{id};
SEE ALSO
Catmandu::FedoraCommons::Response, Catmandu::Model::findObjects,
Catmandu::Model::getObjectHistory, Catmandu::Model::getObjectProfile,
Catmandu::Model::listDatastreams, Catmandu::Model::listMethods
AUTHOR
* Patrick Hochstenbach, <patrick.hochstenbach at ugent.be>
LICENSE AND COPYRIGHT
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.