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);

  $status = $apia->listDatastreams(
              pid=>$pid, 
              datastream_ref =>\$datastreams,
              list => \@dsList);

  Return Status for above methods:

   0 = success
   1 = Error
   2 = Error on remote server

   $bool   = $apia->datastreamExists(
               pid => $pid,
               dsID => $dsID);

   datastreamExists returns 1 (True) or 0 (False).

DESCRIPTION

FedoraCommons::APIA provides an interface to the SOAP-based access API (API-A) of the Fedora repository architecture (http://www.fedora.info/).

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 http://www.fedora-commons.org/confluence/display/FCR30/API-A.

Constructor

new()

Constructor. Called as

my $apia = new FedoraCommons::APIA (
  protocol => "https",        # Optional: enables SSL
  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 and associated values in a hash. 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
);

Used as: [available fields: ID, label, MIMEType]

  if ($apia->listDatastreams(pid=>$pid, 
			     datastream_ref =>\$datastreams) == 0) {
    foreach my $ds ($datastreams->valueof('//datastreamDef')) {
      print "dsID: $ds->{ID} LABEL: $ds->{label} MIME: $ds->{MIMEType}\n";
    }
  }

New list feature added to simplify the common tasks of creating a list of datastream names. Add a reference to a @list as argument list and the method will populate this with the list of the names.

my $datastreams;
my @dsList = ();
$apia->listDatastreams(
  pid => $pid,                       # Required. Scalar holding
                                     #   PID of object 
  datastream_ref => \$datastreams,   # Required. Reference to scalar 
                                     #   into which resulting 
                                     #   datastreams data is returned.
  list => \@dsList,                  # Optional: return list of 
);                                   #   datastreams.

datastreamExists()

Returns 1 (True) if datastream id exists in specified object. Otherwise returns false which indicates either datastream doesn't exist or there was an error. Check $apia->error() to determine if an error occurred.

This method is not part of the APIA specification.

$apia->datastreamExists(
  pid => $pid,                       # Required. Scalar holding
                                     #   PID of object
  dsID => $dsID                      # Required. Datastream name 
                                     # (Examples: DC, RELS-EXT) 
);

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: http://fedora-commons.org/confluence/display/FCR30/Fedora+Repository+3.2.1+Documentation.

Fedora API-A documentation: http://www.fedora-commons.org/confluence/display/FCR30/API-A.

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, <ct at dtv dot dk> 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] http://dpubs.org. Maryam Kutchemeshgi <mxk128 at psu dot edu> is no longer involved with maintaining this module.

David L. Fielding (<dlf2 at cornell dot edu<gt>) 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, http://www.cornell.edu/ Copyright (C) 2007 by PSU, http://www.psu.edu/ Copyright (C) 2006 by DTV, http://www.dtv.dk/

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

cpanm FedoraCommons::APIA

perl -MCPAN -e shell
install FedoraCommons::APIA