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
    (<http://www.fedora.info/>).

    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
    <http://www.fedora.info/definitions/1/0/api/Fedora-API-M.html>.

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

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

AUTHOR
    The Fedora::APIM 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::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] <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-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,
    <http://www.cornell.edu/> Copyright (C) 2006 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 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

