=head1 NAME

XmlContainer - A Perl interface to the DbXml XmlContainer Class

=head1 SYNOPSIS

    use Sleepycat::DbXml;

    my $c = new XmlContainer([$dbenv,] $name [, $flags]);

    $c->upgrade([$flags]);
    $c->setPageSize($size);
    $c->open([$txnid,] $flags, $mode);
    my $bool = $c->isOpen();
    my $bool = $c->exists([$txnid]);
    $c->close([$flags]);

    $c->declareIndex([$tdnid,] $uri, $name, $index [, $flags]); #deprecated
    setIndexSpecification([$txnid,] $index);
    $index = $c->getIndexSpecification([$txnid]);

    my $doc = new XmlDocument ;
    my $id = $c->putDocument([$txnid,] $doc [, $context [, $flags]]);

    my $doc = $c->getDocument([$txnid,] $id [, $flags]);

    $c->deleteDocument([$txnid,] $id [, $context [, $flags]]);
    $c->deleteDocument([$txnid,] $doc [, $context [, $flags]]);
    $c->updateDocument([$txnid,] $doc [, $context]);

    my $string = $c->getName;

    my $exp = $c->parseXPathExpression([$txnid,] $xpath [, $context]);

    my $results = $c->queryWithXPath([$txnid,] $exp [, $flags]);
    my $results = $c->queryWithXPath([$txnid,] $string [, $context] [, $flags]);

    $c->modifyDocument([$txnid,] xmlModify, [, $context] [, $flags]);

    $c->remove([$txnid] [, $flags]);
    $c->rename([$txnid], $newName);
    $c->setName($newName);
    $c->dump($filename [, $flags]);
    $c->load($filename, $lineno [, $flags]);
    $c->verify($filename [, $flags]);



=head1 DESCRIPTION


This module 

=head1 CONFORMANCE to C++ API

The Perl interface to XMlContainer is identical to the C++ API, apart
from the following

=over 5

=item 1.

The use of the TxnId parameter is optional.

=back


=head1 Constructor

The constructor for this class can take any of the following forms

    my $c = new XmlContainer($name);
    my $c = new XmlContainer($name, $flags);
    my $c = new XmlContainer($dbenv, $name);
    my $c = new XmlContainer($dbenv,$name, $flags);

=head1 Methods

=head2 $c->upgrade([$flags])

=head2 $c->exists([$txnid])

Returns true if the container exists on disk, otherwise it returns false.

=head2 $c->setPageSize($size)

Sets the underlying page size that will be used by DbXml in the database
files it uses to store documents. The value, $size, shold be between
512 bytes and 64K.

=head2 $c->declareIndex([$tdnid,] $uri, $name, $index [, $flags]);

Creates an index for this container. This method is deprecated. Use
setIndexSpecification instead.

=head2 setIndexSpecification([$txnid,] $index);

Sets the indexing to be used for this container. The $index parameter
must be an XmlIndexSpecification object.

=head2 $index = $c->getIndexSpecification([$txnid]);

Retrieves an XmlIndexSpecification object from the container, $c.

=head2 $c->open([$txnid,] $flags, $mode);

Opens the container, $c, for reading and writing.

=head2 $c->isOpen();

Returns true if the container is open, and false if it is closed.

=head2 $c->close([$flags]);

Closes the container, $c.

=head2 my $id = $c->putDocument([$txnid,] $doc [, $context [, $flags]]);

Writes the XmlDocument, $doc, into the container, $c, and returns a
document ID.

The document parameter, $doc, must be a valid XmlDocument object.

If present, the $context parameter must be an XmlUpdateContext object.

The $flags parameter is currently unused.


=head2 my $doc = $c->getDocument([$txnid,] $id [, $flags]);

Returns an XmlDocument object from the container that matches the Document
ID, $id.

Valid values for the flags parameter are:

=over 5

=item Db::DB_DIRTY_READ

=item Db::DB_RMW

=back

=head2 $c->deleteDocument([$txnid,] $id [, $context [, $flags]]);

Removes the document with ID, $id from the container, $c.

If present, the $context parameter must be an XmlUpdateContext object.

The $flags parameter is currently unused.

=head2 $c->deleteDocument([$txnid,] $doc [, $context [, $flags]]);

Removes the document that matches the one in the XmlDocument object,
$doc, from the container, $c.

If present, the $context parameter must be an XmlUpdateContext object.

The $flags parameter is currently unused.

=head2 $c->updateDocument([$txnid,] $doc [, $context]);

Updates document $doc in container $c.

If present, the $context parameter must be an XmlUpdateContext object.

=head2 my $string = $c->getName;

Returns the name of the XmlContainer, $c.


=head2 my $exp = $c->parseXPathExpression([$txnid,] $xpath [, $context]);

Parses the XPath expression contained in the $xpath parameter and returns
an XPathExpresion object that can be used in subsequent calls to the
queryWithXPath method.

If the $context parameter is present, it must be a valid XmlQueryContext
object.


=head2 my $results = $c->queryWithXPath([$txnid,] $exp [, $flags]);

This method applies the XmlQueryExpression object, $exp, against the
documents in the container, $c. The result of the query is returned as
an XmlResults object.

Valid values for the flags parameter are:

=over 5

=item Db::DB_DIRTY_READ

=item Db::DB_RMW

=back

=head2 my $results = $c->queryWithXPath([$txnid,] $string [, $context] [, $flags]);

This method applies the XPath expression in the parameter $string, against
the documents in the container, $c. The result of the query is returned as
an XmlResults object.

Valid values for the flags parameter are:

=over 5

=item Db::DB_DIRTY_READ

=item Db::DB_RMW

=back

=head2 $c->modifyDocument([$txnid,] xmlModify, [, $context] [, $flags]);

=head2 $c->remove([$txnid][ , $flags]);

Deletes the database files used to store the container, $c. The comtainer
must be closed before this method is called.

=head2 $c->rename([$txnid], $newName);

Rename the database files used to store the container, $c. 

The comtainer must be closed before this method is called.

=head2 $c->setName($newName);

Sets the name of the container, $c, to $newName.

=head2 $c->dump($filename [, $flags]);

Dumps the contents of the container, $c, to the file, $filename.

The comtainer must be closed before this method is called.

The $flags parameter is currently unused.

=head2 $c->load($filename, $lineno [, $flags]);

Loads the contents of the container, $c, with the contents of the file, $filename. The file must have been created by a previous callto the load method.

The $flags parameter is currently unused.

=head2 $c->verify($filename [, $flags]);

Verifies the container, $c, and dumps the contents of the container to
the file, $filename.

The comtainer must be closed before this method is called.

If present valid values for the flags parameter are:

=over 5

=item Db::DB_SALVAGE

=item Db::SALVAGE | Db::DB_AGGRESSIVE

=back

=head1 NOTES



=head1 EXAMPLES

=head1 SEE ALSO


=head1 AUTHOR

Paul Marquess
