=encoding utf8

=head1 NAME

XML::eXistDB::RPC - access eXist databases via RPC

=head1 DESCRIPTION

This module is a full implementation of the fXML-RPC interface to the
eXist Database. This is not just an one-on-one implementation: some
methods are smarter and many methods are renamed to correct historical
mistakes. Hopefully, the result is more readible.

B<warning:> some methods are tested lightly, but a lot is B<not tested>
in real-life. I have a long list of bugs for eXist 1.4, and hope that
they will get fixed in a next release. Please do not be disappointed:
contribute tests and fixes!

B<warning:> be careful when upgrading to release until C<0.90>, because
they may change method behavior and naming, See ChangeLog!

=head2 Perl interface

The methods in this module provide access to all facilities the XML-RPC
protocol interface offers. However, some of these calls are on a lower
level than practical in a programmers interface. A few larger wrapper
methods were created, most importantly L<uploadDocument()|XML::eXistDB::RPC/"Upload documents"> and
L<downloadDocument()|XML::eXistDB::RPC/"Download documents">.

Some defaults can be set at initiation (L<new()|XML::eXistDB::RPC/"Constructors">), such that repetition
can be avoided.

=head2 Definitions

The whole database (I<Repository>) contains sub-databases (I<Collections>),
which can have sub-collections themselves. Any collection contains
I<Documents> (indexable XML) and I<Binaries> (raw data). When both documents
and binaries are accepted, we speak about a I<Resource>.

=head2 Naming convensions

The XML-RPC method names are a mess: an typical example of many years
of growth. To repair that, consistent naming convensions are introduced.

Any method C<describeXXX()> collects a HASH with details about C<XXX>.
And any C<listXXX()> collects a list of C<XXX> names.  The typical Java
C<get> prefixes on some methods were removed in favor of better named
alternatives: sometimes C<list>, sometimes C<describe>, often something
completely different. Class attribute getters and setters naming should
not be used in interfaces (and are very not-Perl).

Most methods already had the form "<action><class>" (like "removeCollection"),
but on some random spots, the "class" was not present in the name.  This
has been repaired, which lowers the need to read the explanation of the
methods to understand what they are doing.

=head2 Return codes

RPC is a network protocol. Just like operating system calls: you shall
always check the return status of each call! Of course, this module could
simply ignore the existence of fault conditions, to provide a much simpler
programmers interface. But keep in mind: handling error conditions is
very important on the long run. A burdon for the first small programs,
but a desperate need for maintainability.

All methods return a LIST, where the first scalar is a return code (RC).
When that code is C<0>, all went well.  Otherwise, the code represent the
transport error or the exception (refusal) as reported by the server
logic.  In either case, the second scalar in the returned list contains
the error message.  For instance,

  my $user = guest;
  my ($rc, $details) = $db->describeUser($user);
  $rc==0
      or die "cannot get user info for `$user': $details ($rc)\n";

=head1 METHODS

=head2 Constructors

=over 4

=item XML::eXistDB::RPC-E<gt>B<new>(%options)

You must either specify your own L<XML::Compile::RPC::Client> object
with the C<rpc> option, or a C<destination> which will be used to create
such object.

 -Option            --Default
  chunk_size          32
  compress_upload     128
  destination         <undef>
  format              []
  password            'guest'
  prettyprint_upload  <false>
  repository          '/db'
  rpc                 <undef>
  schemas             <created>
  user                'guest'

=over 2

=item chunk_size => KILOBYTES

Send or download data in chunks (fragments) of this size when the size
exceeds this quantity.  If C<0>, then chunking is disabled.

=item compress_upload => KILOBYTES

Compress the upload of resources when their size is over this number of
KILOBYTES in size. This will cost performance mainly on the client.

=item destination => URI

Where the RPC server is (the ExistDB access point).  For instance
C<http://localhost:8080/exist/xmlrpc>

=item format => ARRAY|HASH

The default for "options" which can be passed with many methods.

=item password => STRING

=item prettyprint_upload => BOOLEAN

=item repository => STRING

The repository; the top-level collection.

=item rpc => OBJECT

=item schemas => OBJECT

When you need to do complex things with the eXist schema's, you
may prepare an L<XML::eXistDB|XML::eXistDB> object beforehand. However, that
shouldn't be needed under normal cicumstances. By default, such
object is created for you.

=item user => USERNAME

Used as default when a username is required. For now, that is only used
by L<lockResource()|XML::eXistDB::RPC/"Resources">.

=back

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<schemas>()

Returns the L<XML::eXistDB|XML::eXistDB> object which contains all eXistDB specific
schema information. At first call, the object will get created for you.
Once created, you'll always get the same.

=item $obj-E<gt>B<trace>()

Returns the trace information from the last command executed over RPC. Nearly
all methods in this class only perform one RPC call. You can find the timings,
http request, and http response in the returned HASH.

=back

=head3 Format

A number of methods support formatting options, to control the output.
With the method call, these parameters can be passed as list with pairs.

 indent:  returns indented pretty-print XML.         yes|no
 encoding: character encoding used for the output.   <string>
 omit-xml-declaration: XML declaration to the head.  yes|no
 expand-xincludes: expand XInclude elements.         yes|no
 process-xsl-pi: apply stylesheet to the output.     yes|no
 highlight-matches: show result from fulltext search.elements|attributes|both
 stylesheet: to apply. rel-path from database        <path>
 stylesheet-params: stylesheet params                <HASH>

The use of the "stylesheet-params" is simplified compared to the official
XML-RPC description, with a nested HASH.

=head3 Sending XML

Some method accept a DOCUMENT which can be a XML::LibXML::Document
node, a string containing XML, a SCALAR (ref-string) with the same, or
a filename.

=head2 Repository

=over 4

=item $obj-E<gt>B<backup>($user, $password, $tocoll, $fromcoll)

Returns success. Create a backup of the $fromcoll into the $tocoll, using
$user and $password to write it.  There is also an Xquery function to
produce backups.

example: 

  my ($rc, $ok) = $db->backup('sys', 'xxx', '/db/orders', '/db/backup');
  $rc==0 or die "$rc $ok";

=item $obj-E<gt>B<hasCollection>($collection)

Does the $collection identified by name exist in the repository?

example: 

  my ($rc, $exists) = $db->hasCollection($name);
  $rc and die "$exists (RC=$rc)";
  if($exists) ...

=item $obj-E<gt>B<hasDocument>($docname)

Returns whether a document with NAME exists in the repository.

example: 

  my ($rc, $exists) = $db->hasDocument($name);
  if($rc==0 && $exists) ....

=item $obj-E<gt>B<isXACMLEnabled>()

Returns whether the eXtensible Access Control Markup Language (XACML)
by OASIS is enabled on the database.

example: 

  my ($rc, $enabled) = $db->isACMLEnabled;
  if(!$rc && $enable) { ... }

=item $obj-E<gt>B<shutdown>( [$delay] )

Shutdown the database.  The $delay is in milliseconds.

example: 

  my ($rc, $success) = $db->shutdown(3000);  # 3 secs
  $rc==0 or die "$rc $success";

=item $obj-E<gt>B<sync>()

Force the synchronization of all db page cache buffers.

example: 

  my ($rc, $success) = $db->sync;

=back

=head2 Collections

=over 4

=item $obj-E<gt>B<collectionCreationDate>( [$collection] )

[non-API] Returns the date of the creation of the $collection, by default
from the root.

example: 

  my ($rc, $date) = $db->collectionCreationDate($coll);
  $rc and die "$rc $date";
  print $date;  # f.i. "2009-10-21T12:13:13Z"

=item $obj-E<gt>B<configureCollection>($collection, $configuration, %options)

The $configuration is a whole C<.xconfig>, describing the collection.
This can be a XML::LibXML::Document node, a stringified XML
document, or a HASH.

When the $configuration is a HASH, the data will get formatted
by L<XML::eXistDB::createCollectionConfig()|XML::eXistDB/"Collection configuration (.xconf)">.

The configuration will be placed in C</db/system/config/$collection>,
inside the database.

 -Option  --Default
  beautify  <new(prettyprint_upload)>

=over 2

=item beautify => BOOLEAN

Produce a readible configuration file.

=back

example: 

  my %index1   = (path => ..., qname => .., type => ...);
  my @indexes  = (\%index1, \%index2, \%index3);
  my %fulltext = (default => 'none', attributes => 0, alphanum => 0);
  my %trigger1 = (parameter => [ {name => 'p1', value => '42'} ];
  my @triggers = (\%trigger1, \%trigger2);

  my %config   =
    ( index      => {fulltext => \%fulltext, create => \@indexes}
    , triggers   => {trigger  => \@triggers};
    , validation => {mode     => 'yes'}
    );

  my ($rc, $success) = $db->configureCollection($name, \%config);

=item $obj-E<gt>B<copyCollection>( $from, $to | <$tocoll, $subcoll> )

Copy the $from collection to a new $to. With three arguments, $subcoll
is a collection within $tocoll.

example: 

  my ($rc, $succ) = $db->copyCollection('/db/from', '/db/some/to');
  my ($rc, $succ) = $db->copyCollection('/db/from', '/db/some', 'to');

=item $obj-E<gt>B<createCollection>( $collection, [$date] )

Is a success if the collection already exists or can be created.

example: createCollection

  my $subcoll = "$supercoll/$myname";
  my ($rc, $success) = $db->createCollection($subcoll);
  $rc==0 or die "$rc $success";

=item $obj-E<gt>B<describeCollection>( [$collection], %options )

Returns the RC and a HASH with details.  The details are the same as
returned with L<getCollectionDesc()|XML::eXistDB::RPC/"Please avoid: collections">, excluding details about
documents.

 -Option   --Default
  documents  <false>

=over 2

=item documents => BOOLEAN

=back

example: 

  my ($rc, $descr) = $db->describeCollection($coll, documents => 1);
  $rc and die $rc;
  print Dumper $descr;  # Data::Dumper::Dumper

=item $obj-E<gt>B<listResources>( [$collection] )

[non-API] Returns ... with all documents in the $collection. Without
$collection, it will list all documents in the whole repository.

example: 

  my ($rc, @elems) = $db->listResources;
  $rc==0 or die "error: $elems[0] ($rc)";

=item $obj-E<gt>B<moveCollection>( $from, $to | <$tocoll, $subcoll> )

Copy the $from collection to a new $to. With three arguments, $subcoll
is a collection within $tocoll.

example: 

  my ($rc, $succ) = $db->moveCollection('/db/from', '/db/some/to');
  my ($rc, $succ) = $db->moveCollection('/db/from', '/db/some', 'to');

=item $obj-E<gt>B<reindexCollection>($collection)

Reindex all documents in a certain collection.

example: 

   my ($rc, $success) = $db->reindexCollection($name);
   die "error: $success ($rc)" if $rc;
   die "failed" unless $success;

=item $obj-E<gt>B<removeCollection>($collection)

Remove an entire collection from the database.

example: 

   my ($rc, $success) = $db->removeCollection($name);
   die "error: $rc $success" if $rc;
   die "failed" unless $success;

=item $obj-E<gt>B<subCollections>( [$collection] )

[non-API] Returns a list of sub-collections for this collection, based
on the results of L<describeCollection()|XML::eXistDB::RPC/"Collections">. The returned names are made
absolute.

example: 

  my ($rc, @subs) = $db->subCollections($coll);
  $rc and die "$rc $subs[0]";
  print "@subs\n";

=back

=head2 Permissions

=over 4

=item $obj-E<gt>B<describeCollectionPermissions>( [$collection] )

Returns the RC and a HASH which shows the permissions on the $collection.
The output of the API is regorously rewritten to simplify implementation.

The HASH contains absolute collection names as keys, and then as values
a HASH with C<user>, C<group> and C<mode>.

=item $obj-E<gt>B<describeResourcePermissions>($resource)

[non-API] returns HASH with permission details about a $resource>

=item $obj-E<gt>B<describeUser>($username)

[non-API] returns a HASH with user information.

example: 

  my ($rc, $info) = $db->describeUser($username);
  $rc==0 or die "error: $info ($rc)";
  my @groups = @{$info->{groups}};

=item $obj-E<gt>B<listDocumentPermissions>( [$collection] )

List the permissions for all resources in the $collection

=item $obj-E<gt>B<listGroups>()

[non-API] list all defined groups.
Returns a vector.

example: 

  my ($rc, @groups) = $db->listGroups;
  $rc==0 or die "$groups[0] ($rc)";

=item $obj-E<gt>B<listUsers>()

[non-API] Returns a LIST with all defined usernames.

example: 

  my ($rc, @users) = $db->listUsers;
  $rc==0 or die "error $users[0] ($rc)";

=item $obj-E<gt>B<login>( $username, [$password] )

[non-API] Change the $username (as known by ExistDB). When you specify
a non-existing $username or a wrong $password, you will not get more data
from this connection.  The next request will tell.

=item $obj-E<gt>B<removeUser>($username)

Returns true on success.

=item $obj-E<gt>B<setPermissions>( $target, $permissions, [$user, $group] )

The $target which is addressed is either a resource or a collection.

The $permissions are specified either as an integer value or using a
modification string. The bit encoding of the integer value corresponds
to Unix conventions (with 'x' is replaced by 'update'). The modification
string has as syntax:
  [user|group|other]=[+|-][read|write|update][, ...]

=item $obj-E<gt>B<setUser>( $user, $password, $groups, [$home] )

Modifies or creates a repository user.
The $password is plain-text password. $groups are specified as single
scalar or and ARRAY. The first group is the user's primary group.

=back

=head2 Resources

=over 4

=item $obj-E<gt>B<copyResource>($from, $tocoll, $toname)

example: 

  my ($rc, $success) = $db->copyResource(...);

=item $obj-E<gt>B<countResources>( [$collection] )

[non-API] Returns the number of resources in the $collection.

example: 

  my ($rc, $count) = $db->countResources($collection);

=item $obj-E<gt>B<describeResource>($resource)

Returns details about a $resource (which is a document or a binary).

example: 

  my ($rc, $details) = $db->describeResource($resource);

=item $obj-E<gt>B<getDocType>($document)

Returns details about the $document, the docname, public-id and system-id
as list of three.

example: 

  my ($docname, $public, $system) = $db->getDocType($doc);

=item $obj-E<gt>B<lockResource>( $resource, [$username] )

=item $obj-E<gt>B<moveResource>($from, $tocoll, $toname)

example: 

  my ($rc, $success) = $db->moveResource(...);

=item $obj-E<gt>B<removeResource>($docname)

[non-API] remove a DOCument from the repository by NAME.  This method's name
is more consistent than the official API name C<remove()>.

=item $obj-E<gt>B<setDocType>($document, $typename, $public_id, $system_id)

Add DOCTYPE information to a $document.

example: 

  $rpc->setDocType($doc, "HTML"
     , "-//W3C//DTD HTML 4.01 Transitional//EN"
     , "http://www.w3.org/TR/html4/loose.dtd");

Will add to the document

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   "http://www.w3.org/TR/html4/loose.dtd">

=item $obj-E<gt>B<uniqueResourceName>( [$collection] )

Produces a random (and hopefully unique) resource-id (string) within
the $collection.  The returned id looks something like C<fe7c6ea4.xml>.

example: 

  my ($rc, $id) = $db->uniqueResourceName($coll);

=item $obj-E<gt>B<unlockResource>($resource)

Returns its success.

=item $obj-E<gt>B<whoLockedResource>($resource)

[non-API] Returns a username.

=back

=head3 Download documents

=over 4

=item $obj-E<gt>B<downloadDocument>($resource, $format)

Returns a document as byte array.

=item $obj-E<gt>B<listResourceTimestamps>($resource)

[non-API] Returns the creation and modification dates.

example: 

   my ($rc, $created, $modified) = $db->listResourceTimestamps($resource);
   $rc==0 or die "error: $created ($rc)";

=back

=head3 Upload documents

=over 4

=item $obj-E<gt>B<downloadBinary>($resource)

[non-API] Get the bytes of a binary file from the server.

example: 

  my ($rc, $bytes) = $db->downloadBinary($resource);

=item $obj-E<gt>B<uploadBinary>( $resource, $bytes, $mime, $replace, [$created, $modified] )

[non-API] The $bytes can be passed as string or better as string reference.

example: 

  my ($rc, $ok) = $db->storeBinaryResource($name, $bytes, 'text/html', 1);

=item $obj-E<gt>B<uploadDocument>($resource, $document, %options)

[non-API] Hide all the different kinds of uploads via L<parse()|XML::eXistDB::RPC/"Please avoid: uploading documents"> or
L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents"> behind one interface.

It depends on the size of the document and the type of DATA provided,
whether L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents">, L<uploadCompressed()|XML::eXistDB::RPC/"Please avoid: uploading documents">, or L<parse()|XML::eXistDB::RPC/"Please avoid: uploading documents"> is used to
transmit the data to the server.

 -Option       --Default
  beautify       <false>
  chunk_size     <new(chunk_size)>
  compress       <new(compress_upload)>
  creation_date  <undef>
  is_xml         <false>
  mime_type      'text/xml'
  modify_date    <undef>
  replace        <false>

=over 2

=item beautify => BOOLEAN

=item chunk_size => KILOBYTES

=item compress => KILOBYTES

=item creation_date => DATE

=item is_xml => BOOLEAN  # treatAsXML

=item mime_type => STRING

=item modify_date => DATE

=item replace => BOOLEAN

=back

=back

=head2 Queries

=head3 Compiled queries

=over 4

=item $obj-E<gt>B<compile>($query, $format)

Returns a HASH.

=item $obj-E<gt>B<describeCompile>($query, $format)

[non-API] Returns a string which contains the diagnostics of compiling
the query.

=item $obj-E<gt>B<execute>($queryhandle, $format)

Returns a HASH.

=back

=head3 Query returns result as set

=over 4

=item $obj-E<gt>B<describeResultSet>($resultset)

[non-API] Retrieve a summary of the result set identified by it's
result-set-id. This method returns a HASH with simple values
C<queryTime> (milli-seconds) and C<hits> (number of results).
Besides, it contains complex structures C<documents> and C<doctypes>.

=item $obj-E<gt>B<executeQuery>( $query, [$encoding], [$format] )

Run the $query given in the specified $encoding.  Returned is
only an identifier to the result.

example: 

   my ($rc1, $set)   = $db->executeQuery($query);
   my ($rc2, $count) = $db->numberOfResults($set);
   my ($rc3, @data)  = $db->retrieveResults($set);
   $db->releaseResults($set);

=item $obj-E<gt>B<numberOfResults>($resultset)

[non-API] Returns the number of answers in the RESULT set of a query.
Replaces C<getHits()>.

=item $obj-E<gt>B<releaseResultSet>( $resultset, [$params] )

[non-API] Give-up on the $resultset on the server.

=item $obj-E<gt>B<retrieveResult>( $resultset, $pos, [$format] )

[non-API] retrieve a single result from the RESULT-SET.
Replaces L<retrieve()|XML::eXistDB::RPC/"Please avoid: collect query results"> and L<retrieveFirstChunk()|XML::eXistDB::RPC/"Please avoid: simple node queries">.

=item $obj-E<gt>B<retrieveResults>( $resultset, [$format] )

Replaces L<retrieveAll()|XML::eXistDB::RPC/"Please avoid: collect query results"> and L<retrieveAllFirstChunk()|XML::eXistDB::RPC/"Please avoid: collect query results">.

=back

=head3 Query returns result

=over 4

=item $obj-E<gt>B<query>( $query, $limit, [$first], [$format] )

Returns a document of the collected results.

This method is deprecated according to the java description, in favor of
L<executeQuery()|XML::eXistDB::RPC/"Query returns result as set">, however often used for its simplicity.

=item $obj-E<gt>B<queryXPath>($xpath, $docname, $node_id, %options)

When DOCUMENT is defined, then the search is limited to that document,
optionally further restricted to the NODE with the indicated ID.

example: 

  my ($rc, $h) = $db->queryXPath($xpath, undef, undef);

=back

=head3 Simple node queries

=over 4

=item $obj-E<gt>B<retrieveDocumentNode>( $document, $nodeid, [$format] )

[non-API] Collect one node from a certain document. Doesn't matter
how large: this method will always work (by always using chunks).

=back

=head3 Modify document content

=over 4

=item $obj-E<gt>B<updateCollection>($collection, $xupdate)

[non-API]

example: 

  my ($rc, $some_int) = $db->updateCollection($coll, $xupdate);

=item $obj-E<gt>B<updateResource>( $resource, $xupdate, [$encoding] )

example: 

  my ($rc, $some_int) = $db->updateResource($resource, $xupdate);

=back

=head2 Indexing

=over 4

=item $obj-E<gt>B<getIndexedElements>($collection, $recursive)

=item $obj-E<gt>B<scanIndexTerms>($collection, $begin, $end, $recursive)

or C<< $db->scanIndexTerms(XPATH, $begin, $end) >>.

example: 

  my ($rc, $details) = $db->scanIndexTerms($xpath, $begin, $end);
  my ($rc, $details) = $db->scanIndexTerms($coll, $begin, $end, $recurse);

=back

=head2 Helpers

=head2 Please avoid

Some standard API methods have gotten more powerful alternatives.  Please
avoid using the methods described in this section (although they do work)

=head3 Please avoid: collections

=over 4

=item $obj-E<gt>B<getCollectionDesc>( [$collection] )

Please use L<describeCollection()|XML::eXistDB::RPC/"Collections"> with option C<< documents => 0 >>.

=back

=head3 Please avoid: download documents

=over 4

=item $obj-E<gt>B<getDocument>( $resource, $format|<$encoding, $pretty, $style> )

Please use L<downloadDocument()|XML::eXistDB::RPC/"Download documents">.  Either specify $format parameters
(a list of pairs), or three arguments.  In the latter case, the
$style must be present but may be C<undef>.  $style refers to a
stylesheet document.

=item $obj-E<gt>B<getDocumentAsString>( $resource, $format|<$encoding, $pretty, $style> )

Please use L<downloadDocument()|XML::eXistDB::RPC/"Download documents">. See L<getDocument()|XML::eXistDB::RPC/"Please avoid: download documents">.

=item $obj-E<gt>B<getDocumentData>($resource, $format)

Please use L<downloadDocument()|XML::eXistDB::RPC/"Download documents">.
Retrieve the specified document, but limit the number of bytes
transmitted to avoid memory shortage on the server. The size of the
chunks is controled by the server.  Returned is a HASH.

When the returned HASH contains C<supports-long-offset>, then get the
next Chunk with L<getNextExtendedChunk()|XML::eXistDB::RPC/"Please avoid: download documents"> otherwise use L<getNextChunk()|XML::eXistDB::RPC/"Please avoid: download documents">.

example: 

   my ($rc, $chunk) = $db->getDocumentData($resource);
   my $doc = $chunk->{data};
   while($rc==0 && $chunk->{offset}!=0)
   {   ($rc, $chunk) = $chunk->{'supports-long-offset'}
       ? $db->getNextExtendedChunk($chunk->{handle}, $chunk->{offset})
       : $db->getNextChunk($chunk->{handle}, $chunk->{offset});
       $rc==0 and $doc .= $chunk->{data};
   }
   $rc==0 or die "error: $chunk ($rc)";

=item $obj-E<gt>B<getNextChunk>($tmpname, $offset)

Collect the next chunk, initiated with a L<getDocumentData()|XML::eXistDB::RPC/"Please avoid: download documents">. The file
is limited to 2GB.

=item $obj-E<gt>B<getNextExtendedChunk>($tmpname, $offset)

Collect the next chunk, initiated with a L<getDocumentData()|XML::eXistDB::RPC/"Please avoid: download documents">. This method
can only be used with servers which run an eXist which supports long files.

=back

=head3 Please avoid: uploading documents

=over 4

=item $obj-E<gt>B<parse>( $document, $resource, [$replace, [$created, $modified]] )

Please use L<uploadDocument()|XML::eXistDB::RPC/"Upload documents">.
Store the $document of a document under the $resource name into the
repository. When $replace is true, it will overwrite an existing document
when it exists.

The DATA can be a string containing XML or XML::LibXML::Document.

=item $obj-E<gt>B<parseLocal>( $tempname, $resource, $replace, $mime, [$created, $modified] )

Please use L<uploadDocument()|XML::eXistDB::RPC/"Upload documents">.
Put the content of document which was just oploaded to the server under some
$tempname (received from L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents">), as $resource in the database.

NB: B<Local> means "server local", which is remote for us as clients.

=item $obj-E<gt>B<parseLocalExt>( $tempname, $resource, $replace, $mime, $isxml, [$created, $modified] )

Please use L<uploadDocument()|XML::eXistDB::RPC/"Upload documents">.
Put the content of document which was just oploaded with L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents"> to
the server under some $tempname (received from L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents">) as $resource
in the database. Like L<parseLocal()|XML::eXistDB::RPC/"Please avoid: uploading documents">, but with extra C<$isxml> boolean,
to indicate that the object is XML, where the server does not know that
from the mime-type.

NB: B<Local> means "server local", which is remote for us as clients.

=item $obj-E<gt>B<storeBinary>( $bytes, $resource, $mime, $replace, [$created, $modified] )

Please use L<uploadBinary()|XML::eXistDB::RPC/"Upload documents">.

=item $obj-E<gt>B<upload>( [$tempname], $chunk )

Please use L<uploadDocument()|XML::eXistDB::RPC/"Upload documents">.
Upload a document in parts to the server. The first upload will give
you the TEMPoraryNAME for the object. You may leave that name out or
explicitly state C<undef> at that first call.  When all data is uploaded,
call L<parseLocal()|XML::eXistDB::RPC/"Please avoid: uploading documents"> or L<parseLocalExt()|XML::eXistDB::RPC/"Please avoid: uploading documents">.

example: 

   # start uploading
   my ($rc1, $tmp)  = $db->upload(undef, substr($data, 0, 999));
   my ($rc1, $tmp)  = $db->upload(substr($data, 0, 999));  # same

   # send more chunks
   my ($rc2, undef) = $db->upload($tmp,  substr($data, 1000));

   # insert the document in the database
   my ($rc3, $ok)   = $db->parseLocal($tmp, '/db/file.xml', 0, 'text/xml')
      if $rc1==0 && $rc2==0;

=item $obj-E<gt>B<uploadCompressed>( [$tempname], $chunk )

Please use L<uploadDocument()|XML::eXistDB::RPC/"Upload documents">.
Like L<upload()|XML::eXistDB::RPC/"Please avoid: uploading documents">, although the chunks are part of a compressed file.

=back

=head3 Please avoid: simple node queries

=over 4

=item $obj-E<gt>B<retrieveFirstChunk>( <($doc, $nodeid) | ($resultset, $pos)>, [$format] )

Please use L<retrieveDocumentNode()|XML::eXistDB::RPC/"Simple node queries"> or L<retrieveResult()|XML::eXistDB::RPC/"Query returns result as set">.
Two very different uses for this method: either retrieve the first part
of a single node from a document, or retrieve the first part of an
answer in a result set.  See L<getNextChunk()|XML::eXistDB::RPC/"Please avoid: download documents"> for the next chunks.

=back

=head3 Please avoid: collect query results

=over 4

=item $obj-E<gt>B<getDocumentChunked>($docname, %options)

Please use L<downloadDocument()|XML::eXistDB::RPC/"Download documents">

example: 

   my ($rc, $handle, $total_length) = $db->getDocumentChuncked($doc);
   my $xml = $db->getDocumentNextChunk($handle, 0, $total_length-1);

=item $obj-E<gt>B<getDocumentNextChunk>($handle, $start, $length)

=item $obj-E<gt>B<initiateBackup>($directory)

Trigger the backup task to write to the $directory. Returns true, always,
but that does not mean success: the initiation will succeed.

=item $obj-E<gt>B<isValidDocument>($document)

Returns true when the $document (inside the database) is validated as
correct.

=item $obj-E<gt>B<retrieve>( <($doc, $nodeid) | ($resultset, $pos)>, [$format] )

Please use L<retrieveResult()|XML::eXistDB::RPC/"Query returns result as set"> or L<retrieveDocumentNode()|XML::eXistDB::RPC/"Simple node queries">.

=item $obj-E<gt>B<retrieveAll>( $resultset, [$format] )

Please use L<retrieveResults()|XML::eXistDB::RPC/"Query returns result as set">.

=item $obj-E<gt>B<retrieveAllFirstChunk>( $resultset, [$format] )

Please use L<retrieveResults()|XML::eXistDB::RPC/"Query returns result as set">.

=item $obj-E<gt>B<retrieveAsString>($document, $nodeid, %options)

=back

=head2 Renamed methods

Quite a number of API methods have been renamed to be more consistent
with other names.  Using the new names should improve readibility. The
original names are still available:

  -- xml-rpc name           -- replacement name
  createResourceId          => uniqueResourceName
  dataBackup                => initiateBackup
  getBinaryResource         => downloadBinary
  getCreationDate           => collectionCreationDate
  getDocumentListing        => listResources
  getGroups                 => listGroups
  getHits                   => numberOfResults
  getPermissions            => describeResourcePermissions
  getResourceCount          => countResources
  getTimestamps             => listResourceTimestamps
  getUser                   => describeUser
  getUsers                  => listUsers
  hasUserLock               => whoLockedResource
  isValid                   => isValidDocument
  listCollectionPermissions => describeCollectionPermissions
  printDiagnostics          => describeCompile
  queryP                    => queryXPath
  querySummary              => describeResultSet
  releaseQueryResult        => releaseResultSet
  remove                    => removeResource
  xupdate                   => xupdateCollection
  xupdateResource           => xupdateResource

=head1 SYNOPSYS

  my $db = XML::eXistDB::RPC->new(destination => $uri);
  my ($rc1, $h) = $db->describeUser('guest');
  $rc1==0 or die "Error: $h\n";

  my ($rc2, $set) = $db->executeQuery($query);
  my ($rc3, @answers) = $db->retrieveResults($set);

=head1 SEE ALSO

This module is part of XML-ExistDB distribution version 0.14,
built on July 25, 2015. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::WSDL11>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2010-2015 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

