NAME FedoraCommons::APIA - Interface for interaction with Fedora's Access API VERSION SYNOPSIS use FedoraCommons::APIA; my $apia=new Fedora::APIA( host => "my.fedora.host", port => "8080", usr => "fedoraAdmin", pwd => "foobarbaz", timeout => 100); $status = $apia->findObjects( resultFields => @resFlds, maxResults => $maxRes, fldsrchValue => $fldsrchVal, fldsrchProperty => $fldsrchProp, fldsrchOperator => $fldsrchOp, searchRes_ref => \$searchRes); $status = $apia->resumeFindObjects( sessionToken => $sessionToken, searchRes_ref => \$searchRes); $status = $apia->getDatastreamDissemination( pid => $pid, dsID => $dsID, stream_ref => \$stream); $status = $apia->listDatastreams( pid=>$pid, datastream_ref =>\$datastreams); Return Status: 0 = success 1 = Error 2 = Error on remote server DESCRIPTION FedoraCommons::APIA provides an interface to the SOAP-based access API (API-A) of the Fedora repository architecture (). It exposes a subset of the API-A operations and handles errors and elapsed-time profiling. OPTIONS FedoraCommons::APIA may be invoked with an option version FedoraCommons::APIA supports multiple versions of the Fedora API-A. Specifying the version of the Fedora API-A is done at invocation time by use Fedora::APIA version=>3.2; Supported versions of the Fedora API-A: 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-A operation described at . Constructor new() Constructor. Called as my $apia = new FedoraCommons::APIA ( 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-A 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. findObjects() Gets requested object fields @resFlds for all objects in the repository matching the given criteria $apia->findObjects ( resultFields => @resFlds, # Required. Fields returned maxResults=> $maxres, # Required. Max number of # results returned. fldsrchProperty => $fldsrchProp, # Required. Field being searched fldsrchOperator => $fldsrchOp, # Required. Operator for # comparing a property to # a value fldsrchValue => $fldsrchval, # Required. Value of the property # being searched. searchres_ref => \$searchres # Required. Reference to scalar # into which search results # is put ); resumeFindObjects() Gets the next list of results from a truncated findObjects response $apia->resumeFindObjects ( sessionToken => $sessionToken, # Required. token of the session # in which the next few # results can be found searchres_ref => \$searchres # Required. Reference to scalar # into which search results # is put ); getDatastreamDissemination() Gets a datastream in the digital Fedora object and returns the datastream. Called as my $mystream; $apia->getDatastreamDissemination( pid => $pid, # Required. Scalar holding # PID of object dsID => $dsID, # Required. asOfDateTime => $asOfDateTime, # Optional. stream_ref => \$stream # Required. Reference to scalar # into which resulting stream # is put ); Note: Empty (or null'ed) dsID are currently not supported. listDatastreams() Lists all of the datastreams in the digital Fedora object and returns the list of datastreams. Called as my $datastreams; $apia->listDatastreams( pid => $pid, # Required. Scalar holding # PID of object datastream_ref => \$datastreams # Required. Reference to scalar # into which resulting # datastreams is put ); Methods Currently Not Implemented The following API-A methods are currently not supported in this module. The decision to implement methods was based on the specific needs of our project. describeRepository() Provides information that describes the repository. getObjectHistory() Gets a list of timestamps that correspond to modification dates of components. This currently includes changes to Datastreams and disseminators. getObjectProfile() Profile of an object, which includes key metadata fields and URLs for the object Dissemination Index and the object Item Index. Can be thought of as a default view of the object. getDissemination() Disseminates the content produced by executing the method specified in the service definition associated the specified digital object. listMethods() Lists all the methods that the object supports. Other methods error() Return error of most recent API-A method. get_time() Return the elapsed time of the most recent SOAP::Lite call to the fedora API-A. 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-A. start_stat() Start over the collection of elapsed times and number of calls statistics. DEPENDENCIES SOAP::Lite, Time::HiRes, Carp KNOWN BUGS, LIMITATIONS AND ISSUES In its current implementation, Fedora::APIA 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-A documentation: . APIA Method summary descriptions are taken directly from the APIA documentation. AUTHOR The Fedora::APIA 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::APIA. 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-A 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. perl Makefile.PL make make test make install COPYRIGHT AND LICENSE Copyright (C) 2008, 2009 by Cornell University, Copyright (C) 2007 by PSU, Copyright (C) 2006 by DTV, This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available. 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