NAME
XML::DB::Database::Exist - XML:DB driver for the eXist database
SYNOPSIS
use XML::DB::Database::Exist;DESCRIPTION
This is the eXist XML-RPC driver. It is intended to be used through the XML:DB API, so that it is never called directly from user code. It implements the internal API defined in XML::DB::Database
The methods required to implement the Database interface are documented in Database.pm; only methods unique to eXist, and not required by the XML:DB API are documented here.
BUGS
AUTHOR
Graham Seaman
CPAN ID: AUTHOR
graham@opencollector.org
http://opencollector.org/modulesCOPYRIGHT
Copyright (c) 2002 Graham Seaman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
perl(1).
PUBLIC METHODS
new
Usage : $driver = new XML::DB::Database('eXist');
Purpose : Constructor
Argument : URL for XML-RPC service
Returns : Exist driver, an extension of XML::DB::Database
Comments : Normally only called indirectly, via the DatabaseManager
setURI
Usage : $driver->setURI
Purpose : sets the URI
Argument : URI to use
Returns : 1
Comments : This should probably be done in the constructor but is separate till DatabaseManager is properly sorted out.
ADDITIONAL METHODS
The following methods are not used directly by this XML:DB implementation. Some are called indirectly by the interface methods, others implement features specific to eXist.
getExistDocument
$name - the documents name.
$encoding - optional (UTF8 by default)
$prettyPrint - pretty print XML if >0 (optional, 0 by default)
$xsl (optional)
Usage : $doc = getExistDocument($name, $encoding, $prettyPrint, $xsl )
Purpose : retrieve document by name. XML content is indented if prettyPrint is set to >=0. Use supplied encoding for output. This method is provided to retrieve a document with encodings other than UTF-8. Since the data is handled as binary data, character encodings are preserved. byte-array values are automatically BASE64-encoded by the XMLRPC library.
Arguments :
<Returns> : xml string
Throws : Exception
hasDocument
Usage : if (hasDocument($name)){....
Purpose : Does a document called $name exist in the repository?
Argument : $name - string identifying document
Returns : True/false
Throws : Exception
getDocumentListing
Usage : $docList = getDocumentListing($collection)
Purpose : get a list of all documents contained in the repository, or in the collection if $collection is defined
Argument : $collection - collection to list (may be undef)
Returns : Lists of documents as a struct consisting of: array of all document names in collection; array of all subcolection names; name of collection.
Throws : Exception
Comment : Actual behaviour doesnt match spec (above) - returns simple arrayref (maybe containing a flattened version of above structure?).
retrieve
$id - internal id of node
$noResults - number of results to return
$prettyPrint - pretty print XML if >0 (default 0)
$encoding - default UTF8
Usage : $xml = retrieve($doc, $id, $prettyPrint, $encoding)
Purpose : retrieve a single node from a document.
Arguments :
Returns : Base-64 encoded xml
Throws : Exception
executeQuery
Usage : $reference = executeQuery($xpath)
Purpose : Execute XPath query and return a reference to the result set.
Argument : $xpath - the query
Returns : The returned reference may be used later to get a summary of results or retrieve the actual hits.
Throws : Exception
parse
$xmlData - the documents XML content.
$docName - identifying name for the document
$overwrite - replace an existing document with the same name? (1=yes, 0=no)
Usage : if (parse($xml, $docName, $overwrite)){...
Purpose : parse an XML document and store it into the database.
Arguments :
Returns : 1 on success
Throws : Exception
remove
Usage : if (remove($docName)){ ...
Purpose : remove a document from the repository.
Argument : $docName - document to remove
Returns : 1 on success
Throws : Exception
querySummary
Usage : $struct = querySummary($xpath)
Purpose : execute XPath query and return a summary of hits per document and hits per doctype.
Argument : $xpath - query string
Returns : This method returns a struct consisting of $queryTime -int; $hits - int; $documents - array of array: Object[][3]; doctypes - array of array: Object[][2], where documents and doctypes represent tables where each row describes one document or doctype for which hits were found. Each document entry has the following structure: docId (int), docName (string), hits (int). The doctype entry has this structure: doctypeName (string), hits (int)
Throws : Exception
getHits
Usage : $hitcount = getHits($resultId) Purpose : Get the number of hits in the result set identified by it\'s result-set-id. Argument : $resultId Returns : Number of hits Throws : Exception
existQuery
$xpath - the XPath query to execute. This is in the format document(*|list_of_paths) or collection(collectionName, true|false). See eXist documentation on xpath extensions.
$howmany - maximum number of results to return (default 999).
$start - item in the result set to start with.
$encoding - the character encoding to use (default UTF8).
$prettyPrint - pretty print XML if >0 (default 0)
Usage : $xml = existQuery($xpath, $howmany, $start, $encoding, $prettyPrint)
Purpose : execute XPath query and return $howmany nodes from the result set, starting at position $start.
Arguments :
Returns : string of nodes selected
Throws : Exception
getCollectionDesc
Usage : $desc = getCollectionDesc($collection)
Purpose : describe a collection
Argument : $collection - name of collection
Returns : This method will return a hashref with the following fields: documents - array of all document names contained in this collection; collections - an array containing the names of all subcollections in this collection; name - the collections name
Throws : Exception