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

    Fedora API-A documentation:
    <http://www.fedora.info/definitions/1/0/api/Fedora-API-A.html>.

    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@dtv.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@psu.edu> is no longer involved with maintaining this module.

    David L. Fielding (<dlf2@cornell.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