NAME
perfSONAR_PS::DB::XMLDB - A module that provides methods for dealing with the Sleepycat [Oracle] XML database.
DESCRIPTION
This module wraps methods and techniques from the Sleepycat::DbXml API for interacting with the Sleepycat [Oracle] XML database. The module is to be treated as an object, where each instance of the object represents a direct connection to a single database and collection. Each method may then be invoked on the object for the specific database.
new($package, { env, cont, ns })
Create a new XMLDB object. All arguments are optional:
* env - path to the xmldb data directory
* cont - name of the 'container' inside of the xmldb
* ns - hash reference of namespace values to registerThe arguments can be set (and re-set) via the appropriate function calls.
setEnvironment($self, { env })
(Re-)Sets the "environment" (the directory where the xmldb was created, such as '/usr/local/LS/xmldb'; this should not be confused with the actual installation directory).
setContainer($self, { cont })
(Re-)Sets the "container" (a specific file that lives in the environment, such as 'snmpstore.dbxml'; many containers can live in a single environment).
setNamespaces($self, { ns })
(Re-)Sets the hash reference containing a prefix to namespace mapping. All namespaces that may appear in the container should be mapped (there is no harm is sending mappings that will not be used).
prep($self, { txn, error })
Prepares the database for use, this is called only once usually when the service starts up. The purpose of this function is to create the database (if brand new) or perform recovery operations (if the database exists already). A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
openDB($self, { txn, error })
Opens the database environment and containers. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
indexDB($self, { txn, error })
Creates a simple index for the database if one does not exist. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
deIndexDB($self, { txn, error })
Removes a simple index from the database if one does exist. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
getTransaction($self, { error })
Creates a new transaction object. The error argument is optional.
commitTransaction($self, { dbTr, error })
Given a transaction object, commit it. The error argument is optional.
abortTransaction($self, { dbTr, error })
Given a transaction object, abort it. The error argument is optional.
query($self, { query, txn, error })
The string $query must be an XPath expression to be sent to the database. Examples are:
//nmwg:metadata
or
//nmwg:parameter[@name="SNMPVersion" and @value="1"]Results are returned as an array of strings or error status. This function should be used for XPath statements. The error parameter is optional and is a reference to a scalar. The function will use it to return the error message if one occurred, it returns the empty string otherwise.
A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
queryForName($self, { query, txn, error })
Given a query, return the 'name' of the container. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
queryByName($self, { query, txn, error })
Given a query, see if it exists in the container and return the document name. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
queryByName($self, { name, txn, error })
Given a name, see if it exists in the container. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
getDocumentByName($self, { name, txn, error })
Return a document given a it's name. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
updateByName($self, { content, name, txn, error })
Update container content by name. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
count($self, { query, txn, error })
The string $query must also be an XPath expression that is sent to the database. The result of this expression is simple the number of elements that match the query. Returns -1 on error. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
insertIntoContainer($self, { content, name, txn, error })
Insert the content into the container with the name. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
insertElement($self, { query, content, txn, error })
Perform a query, and insert the content into this result. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
remove($self, { name, txn, error })
Remove the container w/ the given name. A transaction element may be passed in from the caller, or this argument can be left blank for an atomic operation. The error argument is optional.
closeDB($self, { error })
Frees local elements for object destruction.
wrapStore( { content, type } )
Adds 'store' tags around some content. This is to mimic the way eXist deals with storing XML data. The 'type' argument is used to type the store file.
SYNOPSIS
use perfSONAR_PS::DB::XMLDB;
my %ns = (
nmwg => "http://ggf.org/ns/nmwg/base/2.0/",
netutil => "http://ggf.org/ns/nmwg/characteristic/utilization/2.0/",
nmwgt => "http://ggf.org/ns/nmwg/topology/2.0/",
snmp => "http://ggf.org/ns/nmwg/tools/snmp/2.0/"
);
my $db = new perfSONAR_PS::DB::XMLDB(
"/home/jason/Netradar/MP/SNMP/xmldb",
"snmpstore.dbxml",
\%ns
);
# or also:
#
# my $db = new perfSONAR_PS::DB::XMLDB;
# $db->setEnvironment("/home/jason/Netradar/MP/SNMP/xmldb");
# $db->setContainer("snmpstore.dbxml");
# $db->setNamespaces(\%ns);
if ($db->openDB == -1) {
print "Error opening database\n";
}
print "There are " , $db->count("//nmwg:metadata") , " elements in the XMLDB.\n\n";
my @resultsString = $db->query("//nmwg:metadata");
if($#resultsString != -1) {
for(my $x = 0; $x <= $#resultsString; $x++) {
print $x , ": " , $resultsString[$x], "\n";
}
}
else {
print "Nothing Found.\n";
}
my $xml = "<nmwg:metadata xmlns:nmwg=\"http://ggf.org/ns/nmwg/base/2.0/\" id=\"test\" />";
if ($db->insertIntoContainer($xml, "test") == -1) {
print "Couldn't insert node into container\n";
}
my $xml2 = "<nmwg:subject xmlns:nmwg='http://ggf.org/ns/nmwg/base/2.0/'/>";
if ($db->insertElement("/nmwg:metadata[\@id='test']", $xml2) == -1) {
print "Couldn't insert element\n";
}
print "There are " , $db->count("//nmwg:metadata") , " elements in the XMLDB.\n\n";
my @resultsString = $db->query("//nmwg:metadata");
if($#resultsString != -1) {
for(my $x = 0; $x <= $#resultsString; $x++) {
print $x , ": " , $resultsString[$x], "\n";
}
}
else {
print "Nothing Found.\n";
}
if ($db->remove("test") == -1) {
print "Error removing test\n";
}SEE ALSO
Sleepycat::DbXml, Log::Log4perl, XML::LibXML, English, Params::Validate, perfSONAR_PS::Common
To join the 'perfSONAR-PS' mailing list, please visit:
https://mail.internet2.edu/wws/info/i2-perfsonarThe perfSONAR-PS subversion repository is located at:
https://svn.internet2.edu/svn/perfSONAR-PS Questions and comments can be directed to the author, or the mailing list. Bugs, feature requests, and improvements can be directed here:
https://bugs.internet2.edu/jira/browse/PSPSVERSION
$Id$
AUTHOR
Jason Zurawski, zurawski@internet2.edu
LICENSE
You should have received a copy of the Internet2 Intellectual Property Framework along with this software. If not, see <http://www.internet2.edu/membership/ip.html>
COPYRIGHT
Copyright (c) 2004-2008, Internet2 and the University of Delaware
All rights reserved.