NAME FedoraCommons::APIM - Interface for interaction with Fedoras Management API VERSION This documentation describes version 0.1. SYNOPSIS use Fedora::APIM; my $apim=new Fedora::APIM( host => "my.fedora.host", port => "8080", usr => "fedoraAdmin", pwd => "foobarbaz", timeout => 100); if ($apim->ingest(XML_ref=>\$foxml, logMessage=>"Ingesting", \$pid)) { print "Ingested FOXML Record:\n".$foxml."\n\nFedora PID: $pid"; } else { print "Error ingesting: ".$apim->error(); } DESCRIPTION Fedora::APIM provides an interface to the SOAP::Lite based management API (API-M) of the Fedora repository architecture (). It exposes a subset of the API-M operations and handles errors and elapsed-time profiling. OPTIONS Fedora::APIM may be invoked with an option version Fedora::APIM supports multiple versions of the Fedora API-M. Specifying the version of the Fedora API-M is done at invocation time by use FedoraCommons::APIM version=>3.2; Supported versions of the Fedora API-M: 3.2. METHODS Parameters for each method is passed as an anonymous hash. Below is a description of required and optional hash keys for each method. Methods will croak if mandatory keys are missing. Most keys corresponds to paramter names to the equivalent API-M operation described at . Constructor new() Constructor. Called as my $apim = new Fedora::APIM( host => "hostname", # Required. Host name of # fedora installation port => "8080", # Required. Port number of # fedora installation usr => "fedoraAdmin", # Required. Fedora admin user pwd => "fedoraAdmin", # Required. Fedora admin password timeout => 100 # Optional. Timeout for # SOAP connection ); Methods representing API-M operations Each method returns 0 upon success and 1 upon failure. Method error() may be used to get back a textual description of the error of the most recent method call. ingest() Ingest a FOXML record into Fedora and return the PID. Called as my $pid; $apim->ingest( XML_ref => \$foxml_record, # Required. Reference to scalar # holding FOXML record logMessage => $msg, # Optional. Log message pid_ref => \$pid # Required. Reference to scalar # to hold pid returned from # fedora ); The createObject() method encapsulates the ingest and addDatastream methods into a single call. See createObject(). purgeObject() Purge a Fedora object and return the timestamp of that operation. Called as my $ts; $apim->purgeObject( pid => $pid, # Required. Scalar holding # PID of object to be purged logMessage => $msg, # Optional. Log message timestamp_ref => \$ts # Required. Reference to scalar # to hold timestamp returned # from fedora ); uploadFile() Uploading a file via multipart HTTP POST to /fedora/management/upload. This allows adding a datastream from a local file (url not required). This is a method from the API-M Lite api. Allows you to upload a local file and avoid having to specify a URL when adding a datastream. This method is used by uploadNewDatastream() which combines uploadFile() and addDatastream() into one method. $apim->uploadFile(filename => $filename, file_ref => \$file_ref) then supply $file_ref to addDatastream() call: my $url = $file_ref; # Remove trailing spaces $url =~ s/\s+$//; $apim->addDatastream( pid => $pid, dsID => $dsID, altIDs => $altids, dsLabel => $label, versionable => $v, MIMEType => $mime, formatURI => $uri, dsLocation => $url, # file_ref controlGroup => $cg, dsState => $state, logMessage => $msg, dsid_ref => \$dsid ) addDatastream() Add a datastream to a Fedora object and return the datastream id. Called as my $dsid; $apim->addDatastream( pid => $pid, # Required. PID of object dsID => $dsID, # Required. ID of the datastream altIDs => $altids, # Optional. Alternative id's dsLabel => $label, # Required. Datastream label versionable => $v, # Required. "false" or "true" MIMEType =>, $mime, # Required. Mime type of datastream formatURI => $uri, # Required. dsLocation => $url, # Required. URL from where # fedora can fetch datastream controlGroup => $cg, # Required. Must have value # "X", "M", "R" or "E" dsState => $state, # Required. Must have value # "A", "I" or "D" checksumType => $checksumType, # Optional. Checksum algorithm checksum => $checksum # Optional. Checksum value logMessage => $msg, # Optional. Log message dsid_ref => \$dsid # Required. Reference to scalar # to hold datastream ID returned # from fedora ); compareDatastreamChecksum() Verifies that the Datastream content has not changed since the checksum was initially computed. $apim->compareDatastreamChecksum ( pid => $pid, # Required. PID of object dsID => $dsID, # Required. datastream ID versionDate => $versionDate, # Optional. 0 or 1 checksum_result =>\$checksum_result,# Required. Returns checksum # or error message. ); getDatastream() Get a datastream from a Fedora object and returns the datastream. Called as my $ds_ref; $apim->getDatastream( pid => $pid, # Required. Scalar holding # PID of object to be purged dsID => $dsID, # Required. ds_ref => \$ds_ref # Required. Reference to scalar # to hold datastream returned # from fedora ); modifyDatastreamByReference() Modifies an existing datastream in an object, by reference and returns the timestamp. Called as my $ts; $apim->modifyDatastreamByReference( pid => $pid, # Required. PID of object dsID => $dsID, # Required. ID of the datastream altIDs => $altids, # Optional. Alternative id's dsLabel => $label, # Required. Datastream label MIMEType =>, $mime, # Required. Mime type of datastream formatURI => $uri, # Required. dsLocation => $url, # Required. URL from where # fedora can fetch datastream checksumType => $checksumType, # Optional.Checksum algorithm checksum => $checksum # Optional. Checksum value logMessage => $msg, # Optional. Log message force => $force, # Required. "false" or "true" timestamp_ref => \$ts # Required. Reference to scalar # to hold timestamp returned # from fedora ); setDatastreamVersionable() Selectively turn versioning on or off for selected datastream. When versioning is disabled, subsequent modifications to the datastream replace the current datastream contents and no versioning history is preserved. To put it another way: No new datastream versions will be made, but all the existing versions will be retained. All changes to the datastream will be to the current version. $apim->setDatastreamVersionable ( pid => $pid, # Required. PID of object dsID => $dsID, # Required. ID of the datastream versionable => $versionable,# Required. versionable setting 0 or 1 timestamp_ref => \$ts, # Required. Reference to scalar # to hold timestamp returned # from fedora ); purgeDatastream() Purge a datastream from a Fedora object and return the timestamp of that operation. Called as my $ts; $apim->purgeDatastream( pid => $pid, # Required. PID of object to be purged dsID => $dsID, # Required. ID of the datastream startDT => $startDT, # Optional. endDT => $endDT, # Optional. logMessage => $msg, # Optional. Log message force => $force, # Required. "false" or "true" timestamp_ref => \$ts # Required. Reference to scalar # to hold timestamp returned # from fedora ); addRelationship() Creates a new relationship in the object. $apim->addRelationship( pid => $pid, # Required. PID of object relationship => $relation, # Required. Relation to add. object => $object, # Required. Target object. isLiteral => 'false', # Optional. Is object a literal? # Default: 'false' datatype => "", # Optional. Datatype of literal. # Default: '' ); purgeRelationship() Delete the specified relationship. $apim->purgeRelationship( pid => $pid, # Required. PID of object relationship => $relation, # Required. Relation to delete. # Note: null matches any relationship object => "$object", # Required. Target object. # Note: null matches any object. isLiteral => 'false', # Optional. Is object a literal? datatype => "", # Optional. Datatype of literal. result => \$result, # Required. Result of purge. ); getNextPID() Get next PID(s) from Fedora in a given PID namespace. Called as my @pids; $apim->getNextPID ( numPids => $n, # Required. Number of pids. pidNamespace => $ns, # Required. Namespace for pids. pidlist_ref => \@pids # Required. Reference to list # into which resulting pids # are put ); Methods Currently Not Implemented getDatastreamHistory() Gets all versions of a datastream, sorted from most to least recent. getDatastreams() Gets all datastreams in the object. modifyDatastreamByValue() Modifies an existing Datastream in an object, by value. setDatastreamState() Sets the state of a Datastream to the specified state value. getRelationships() Get the relationships asserted in the object's RELS-EXT Datastream that match the given criteria. modifyObject() Modify an object. export() Exports the entire digital object in the specified XML format, and encoded appropriately for the specified export context. getObjectXML() Gets the serialization of the digital object to XML appropriate for persistent storage in the repository, ensuring that any URLs that are relative to the local repository are stored with the Fedora local URL syntax. Additional NON-APIM Methods These methods often consolidate several APIM methods into a single method. The idea is to encapsulate functionality where several APIM methods are normally used together in client code into a single method. createObject() This method takes care of creating the FOXML and the new object [normally two APIA steps]. Creating an object requires FOXML for the object you are creating. You must install the default ingest template (available) in the default file path location [/ingesttemplate.xml] or you must provide a path to the method as an argument. The params are values in the FOXML template that will be substitutes before being ingested. You may create your own FOXML template and supply the appropriate values to be substituted. The current default template accepts the values: pid_in, title_in, and collection_in. Typical createObject() method call: $apim->createObject ( XML_file=> "./ingesttemplate.xml", params => { pid_in => $idno, title_in => "$title", collection_in => "DXLS:Math"}, pid_ref =>\$pid ); To use default ingest template: $apim->createObject ( params => { pid_in => $idno, title_in => "$title", collection_in => "DXLS:Math"}, pid_ref =>\$pid To specify FOXML template that's already stored in memory: $apim->createObject ( XML_ref => "$foxml", params => { pid_in => $idno, title_in => "$title", collection_in => "DXLS:Math"}, pid_ref =>\$pid uploadNewDatastream() This method combines the upload operation and the add datastream operation into a single call and sets reasonable defaults (which the caller may override) for several parameters. Full method call looks like: $apim->uploadNewDatastream( pid => $pid, # Required. PID of object dsID => $dsID, # Required. ID of the datastream altIDs => $altids, # Optional. Alternative id's dsLabel => $dsLabel, # Optional. Datastream label. # Default: null string versionable => $versionable, # Optional. Is datastream versionable? # Default: true filename => $filename, # Required. Datastream file to upload. MIMEType => $mime, # Required. Mime type of datastream controlGroup => $cgroup, # Optional. Control group. # Default: 'M', for managed content. dsState => $dsState, # Optional. Datastream state. # Default: 'A', for active. checksumType => $checksumType,# Optional. Checksum type. # Default: SHA-1 checksum => $checksum, # Optional. Actual checksum. # Default: null, calculated # automatically by repository logMessage => $logMessage, # Optional. Log message. # Default: "Add datastream." dsid_ref => \$dsid, # Required. Reference to scalar # to hold datastream ID returned # from fedora timestamp_ref => \$ts, # Required. Reference to scalar # to hold timestamp returned # from fedora ); Typical call looks like: $apim->uploadNewDatastream( pid => $pid, dsID => $dsID, filename => $filename, MIMEType => $mime, dsid_ref => \$dsid, timestamp_ref => \$ts, ); Other methods error() Return error of most recent API-M method. get_time() Return the elapsed time of the most recent SOAP::Lite call to the fedora API-M. get_stat() Return reference to hash describing total elapsed time and number of calls - since instantiation or since most recent call to start_stat() - of all SOAP::Lite calls to the fedora API-M. start_stat() Start over the collection of elapsed times and number of calls statistics. get_default_foxml() The APIM module stores a default FOXML internally. This is used when the client does not provide the createObject with raw FOXML or a file path to custom FOXML. The get_default_foxml() method will return the internal FOXML template so that you may customize it for your purposes. If you save the FOXML template in the location './ingesttemplate.xml' it will be detected automatically when you call createObject() without specifying a FOXML argument. DEPENDENCIES MIME::Base64, SOAP::Lite, Time::HiRes, Carp KNOWN BUGS, LIMITATIONS AND ISSUES In its current implementation, Fedora::APIM represents a wrapping of the SOAP based interface in which most of the parameters for the SOAP operations are required parameters to the corresponding wrapping method, even though parameters may be optional in the SOAP interface. In future versions, parameters should become optional in the methods if they are optional in the corresponding SOAP operation; or suitable defaults may be used with SOAP for some of the parameters, should they be missing as parameters to the wrapping method. SEE ALSO Fedora documentation: . Fedora API-M documentation: . AUTHOR The Fedora::APIM module is based on a module written by Christian Tønsberg, , in 2006. Christian no longer supports or distributes the module he developed. Maryam Kutchemeshgi (Penn State University) put together the initial version of Fedora::APIM. This module was originally developed (circa 2007) in a collaboration between Cornell University and Penn State University as part of a project to develop an interface to support the use of the Fedora Repository as the underlying repository for DPubS [Digital Publishing System] . Maryam Kutchemeshgi is no longer involved with maintaining this module. David L. Fielding () is responsible for recent enhancements along with packaging up the module and placing it on CPAN. To avoid confusion between Fedora (the Linux operating system) and Fedora (the repository) I changed the name of the module package from Fedora to FedoraCommons (the qualified name of the Fedora repository). I have modified the modules to work with the Fedora Commons 3.2 APIs. This module implements a subset of the requests supported by the API-M specification. Additional requests may be implemented upon request. Please direct comments, suggestions, and bug reports (with fixes) to me. The amount of additional development will depend directly on how many individuals are using the module. Please refer to module comments for information on who implemented various methods. INSTALLATION This module uses the standard method for installing Perl modules. This module functions as an API for a Fedora server and therefore requires a functioning Fedora server to run the tests ('make test'). Settings for the Fedora server are read from the following environment variables: FEDORA_HOST, FEDORA_PORT, FEDORA_USER, FEDORA_PWD. The tests will not run if these environment variable are not set properly. Note: The APIM module supports methods that modify the repository. The 'make test' operation below will create objects in the repository in order to test methods. The last step will be to remove the test objects. Be ware that this test will attempt to modify the target repository. perl Makefile.PL make make test make install COPYRIGHT AND LICENSE Copyright (C) 2008, 2009 by Cornell University, Copyright (C) 2006 by PSU, Copyright (C) 2006 by DTV, This library 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 2 of the License, or (at your option) any later version. This library 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 this library; if not, visit http://www.gnu.org/licenses/gpl.txt or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA