Berkeley DbXML
version 1.2.1

com.sleepycat.dbxml
Class XmlContainer

java.lang.Object
  extended bycom.sleepycat.dbxml.XmlContainer

public class XmlContainer
extends Object

The XmlContainer class encapsulates a document container and its related indices and statistics. XmlContainer exposes methods for managing the storage and retrieval of XmlDocument objects.


Field Summary
static int CATEGORY_ALL
           
static int CATEGORY_CONTAINER
           
static int CATEGORY_DICTIONARY
           
static int CATEGORY_INDEXER
           
static int CATEGORY_NONE
           
static int CATEGORY_OPTIMIZER
           
static int CATEGORY_QUERY
           
static int LEVEL_ALL
           
static int LEVEL_DEBUG
           
static int LEVEL_ERROR
           
static int LEVEL_INFO
           
static int LEVEL_NONE
           
static int LEVEL_WARNING
           
static String metaDataName_content
           
static String metaDataName_default
           
static String metaDataName_id
           
static String metaDataName_name
           
static String metaDataNamespace_prefix
           
static String metaDataNamespace_prefix_debug
           
static String metaDataNamespace_uri
           
 
Constructor Summary
XmlContainer(DbEnv dbenv, String name, int flags)
          The XmlContainer constructor creates a new XmlContainer handle within the given environment (if any), and sets the container's name.
 
Method Summary
 void addIndex(DbTxn txn, String uri, String name, String index)
          The XmlContainer.addindex method adds an index of the specified type for the named document node.
 void close(int flags)
          The XmlContainer.close method closes the container.
 void delete()
           
 void deleteDocument(DbTxn txn, int id, XmlUpdateContext context, int flags)
          The XmlContainer.deleteDocument method removes the specified XmlDocument from the XmlContainer.
 void deleteDocument(DbTxn txn, XmlDocument document, XmlUpdateContext context, int flags)
          The XmlContainer.deleteDocument method removes the specified XmlDocument from the XmlContainer.
 void deleteIndex(DbTxn txn, String uri, String name, String index)
          The XmlContainer.deleteindex method deletes an index of the specified type for the named document node.
 void dump(String filename, int flags)
          The XmlContainer.dump method dumps the container contents to the specified output stream.
 boolean exists(DbTxn txn)
          The XmlContainer.exists method tests if a container exists.
static int get_version_major()
           
static int get_version_minor()
           
static int get_version_patch()
           
static String get_version_string()
           
 XmlDocument getDocument(DbTxn txn, int id, int flags)
          The XmlContainer.getDocument method returns the XmlDocument corresponding to the specified document ID.
 XmlIndexSpecification getIndexSpecification(DbTxn txn)
          The XmlContainer.getIndexSpecification method retrieves the current indexing specification for the container.
 String getName()
          The XmlContainer.getName method returns the name of the XmlContainer.
 boolean isOpen()
          The XmlContainer.isOpen method tests if a container is open.
 void load(String filename, int flags)
          The XmlContainer.load methods loads data from the specified stream into the container.
 void modifyDocument(DbTxn txn, XmlModify modify, XmlUpdateContext context, int flags)
          The XmlContainer.modifyDocument method performs in-place modification of all XmlDocuments in the XmlContainer according to the state of the XmlModify object, which contains an XPath expression to target document nodes, as well as specification of the modifications to perform.
 void open(DbTxn txn, int flags, int mode)
          The XmlContainer.open method opens the XmlContainer for reading and writing.
 XmlQueryExpression parseXPathExpression(DbTxn txn, String query, XmlQueryContext context)
          The XmlContainer.parseXPathExpression returns a pre-parsed XPath expression, which can be used with the XmlContainer.queryWithXPath method.
 int putDocument(DbTxn txn, XmlDocument document, XmlUpdateContext context, int flags)
          The XmlContainer.putDocument method inserts a XmlDocument into the container, and returns the system-assigned document ID, as a 32-bit unsigned integral value.
 XmlResults queryWithXPath(DbTxn txn, String query, XmlQueryContext context, int flags)
          The XmlContainer.queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.
 XmlResults queryWithXPath(DbTxn txn, XmlQueryExpression query, int flags)
          The XmlContainer.queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.
 void remove(DbTxn txn, int flags)
          The XmlContainer.remove method removes the underlying file for the container from the file system.
 void rename(DbTxn txn, String newName, int flags)
          The XmlContainer.rename method renames the container's underlying file.
 void replaceIndex(DbTxn txn, String uri, String name, String index)
          The XmlContainer.replaceindex method replaces an index of the specified type for the named document node.
 void setIndexSpecification(DbTxn txn, XmlIndexSpecification index)
          The XmlContainer.setIndexSpecification method defines the type of indexing to be maintained for a container of documents.
static void setLogCategory(int category, boolean enabled)
          Berkeley DB XML can be configured to generate a stream of messages to help application debugging.
static void setLogLevel(int level, boolean enabled)
          Berkeley DB XML can be configured to generate a stream of messages to help application debugging.
 void setName(String name)
          The XmlContainer.setName method sets the name of the XmlContainer.
 void setPageSize(int pagesize)
          The XmlContainer.setPageSize method sets the size of the pages used to store documents in the database.
 void updateDocument(DbTxn txn, XmlDocument document, XmlUpdateContext context)
          The XmlContainer.updateDocument method updates a XmlDocument in the container.
 void upgrade(int flags)
          The XmlContainer.upgrade method upgrades the container from a previous version of Berkeley DB XML, or Berkeley DB, to the current version.
 void verify(String filename, int flags)
          The XmlContainer.verify method checks that the container data files are not corrupt, and optionally writes the salvaged container data to the specified output stream.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LEVEL_NONE

public static final int LEVEL_NONE

LEVEL_DEBUG

public static final int LEVEL_DEBUG

LEVEL_INFO

public static final int LEVEL_INFO

LEVEL_WARNING

public static final int LEVEL_WARNING

LEVEL_ERROR

public static final int LEVEL_ERROR

LEVEL_ALL

public static final int LEVEL_ALL

CATEGORY_NONE

public static final int CATEGORY_NONE

CATEGORY_INDEXER

public static final int CATEGORY_INDEXER

CATEGORY_QUERY

public static final int CATEGORY_QUERY

CATEGORY_OPTIMIZER

public static final int CATEGORY_OPTIMIZER

CATEGORY_DICTIONARY

public static final int CATEGORY_DICTIONARY

CATEGORY_CONTAINER

public static final int CATEGORY_CONTAINER

CATEGORY_ALL

public static final int CATEGORY_ALL

metaDataNamespace_uri

public static final String metaDataNamespace_uri

metaDataNamespace_prefix

public static final String metaDataNamespace_prefix

metaDataName_id

public static final String metaDataName_id

metaDataName_name

public static final String metaDataName_name

metaDataName_content

public static final String metaDataName_content

metaDataName_default

public static final String metaDataName_default

metaDataNamespace_prefix_debug

public static final String metaDataNamespace_prefix_debug
Constructor Detail

XmlContainer

public XmlContainer(DbEnv dbenv,
                    String name,
                    int flags)
             throws XmlException
The XmlContainer constructor creates a new XmlContainer handle within the given environment (if any), and sets the container's name.

If the XmlContainer is opened, the application must close it when finished with it, otherwise the XmlContainer resources will not be released, and the container may be corrupted.

Create a database to be accessed by applications running under an X/Open conformant Transaction Manager. The database will be opened in the environment specified by the OPENINFO parameter of the GROUPS section of the ubbconfig file. See the XA Resource Manager chapter in the Reference Guide for more information.

Parameters:
dbenv - If a dbenv value is specified, the container is created within the specified Berkeley DB environment and all operations are performed within the context of that environment. The user is expected to suitably configure the environment for their particular application. If a dbenv value is not specified (it is left null), the container is not created in a Berkeley DB environment.
name - The name argument is used as the name of an underlying file that will be used to store container content. We suggest using the file extension '.dbxml' for ease of identification, for example 'mydata.dbxml'. The container file is created in the directory specified within the Berkeley DB environment. The current working directory will be used if a Berkeley DB environment is not provided. A memory only container can be created by passing an empty string for the container name.
flags - The flags value must be set to zero or the following value:
Throws:
XmlException
Method Detail

delete

public void delete()

setPageSize

public void setPageSize(int pagesize)
                 throws XmlException
The XmlContainer.setPageSize method sets the size of the pages used to store documents in the database. The size is specified in bytes in the range 512 bytes to 64K bytes. The system selects a page size based on the underlying file system I/O block size if one is not explicitly set by the application. The default page size has a lower limit of 512 bytes and an upper limit of 16K bytes. Documents that are larger than a single page are stored on multiple pages.

The XmlContainer.setPageSize method may only be used before the container is opened for the first time.

Parameters:
pagesize - The page size in bytes.
Throws:
XmlException - The XmlContainer.setPageSize method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The page size may only be set for new containers.

  • open

    public void open(DbTxn txn,
                     int flags,
                     int mode)
              throws XmlException
    The XmlContainer.open method opens the XmlContainer for reading and writing. The XmlContainer.open method may only be called on a closed container. A container is in the closed state after construction, and after the XmlContainer.close, XmlContainer.rename, or XmlContainer.remove methods have been called. A container can be reopened after it has been closed. The XmlContainer.isOpen method can be used to determine if a given container is currently open or closed.

    A container is created using the XmlContainer.open method with the Db.DB_CREATE flag. The container is created without any indices specified. The XmlContainer.getIndexSpecification method can be used to retrieve the container indexing specification, the XmlIndexSpecification.addIndex method can be used to add indexing strategies, and the XmlContainer.setIndexSpecification method can be used to set the indexing specification for the container.

    Automatically transact all update operations, unless the application provides a transaction handle.

    Create the XmlContainer if it does not already exist.

    Support reading of modified, but not yet committed data.

    Return an error if the container already exists. The Db.DB_EXCL flag is only meaningful when specified with the Db.DB_CREATE flag.

    Do not map this container into process memory (see DbEnv.setMemoryPoolMapSize for further information).

    Open the XmlContainer for reading only. Subsequent attempts to modify the XmlContainer will fail.

    Cause the XmlContainer handle returned by XmlContainer.open to be free-threaded; that is, usable by multiple threads within a single address space.

    Threading is always assumed in the Java API, so no special flags are required, and Berkeley DB functions will always behave as if the Db.DB_THREAD flag was specified.

    Do checksum verification of pages read into the cache from the backing filestore. Berkeley DB XML uses the SHA1 Secure Hash Algorithm if encryption is configured and a general hash algorithm if it is not.

    Encrypt the database using the cryptographic password specified to the DbEnv.setEncrypted.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    flags - Specifies which modes the container will be opened in. The flags value must be set to zero, or a value created by bitwise inclusively OR'ing one or more of the following values:
    mode - On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by XmlContainer.open are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)). If mode is 0, XmlContainer.open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode parameter is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.
    Throws:
    XmlException - The XmlContainer.open method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The DB_CREATE flag was specified, but the container already exists.
  • The container is already open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The container version and dbxml library version differ; use the XmlContainer.upgrade method to update the container version.

  • exists

    public boolean exists(DbTxn txn)
                   throws XmlException
    The XmlContainer.exists method tests if a container exists.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    Returns:
    It returns true if the container has already been created, and false if not.

    Throws:
    XmlException

    isOpen

    public boolean isOpen()
                   throws XmlException
    The XmlContainer.isOpen method tests if a container is open. It returns true if the container is open, and false if the container is closed. A container can be opened with the XmlContainer.open, and closed with the XmlContainer.close.

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

    Throws:
    XmlException

    close

    public void close(int flags)
               throws XmlException
    The XmlContainer.close method closes the container. The XmlContainer must be open for the call to succeed. The XmlContainer.isOpen method can be used to determine if a given container is currently open or closed. An XmlContainer may be reopened after it has been closed. If multiple threads are using the XmlContainer concurrently, only a single thread may call the XmlContainer.close method.

    Parameters:
    flags - Specifies how the XmlContainer is to be closed. Flags may be set to zero or Db.DB_NOSYNC. The Db.DB_NOSYNC flag causes the XmlContainer to be closed without flushing cached information to disk.
    Throws:
    XmlException - The XmlContainer.close method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is already closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • setIndexSpecification

    public void setIndexSpecification(DbTxn txn,
                                      XmlIndexSpecification index)
                               throws XmlException
    The XmlContainer.setIndexSpecification method defines the type of indexing to be maintained for a container of documents. The currently defined indexing specification can be retrieved with the XmlContainer.getIndexSpecification method.

    If the container is not empty then the contained documents are incrementally indexed. Index keys for disabled index strategies are removed and index keys for enabled index strategies are added. Note that the length of time taken to perform this re-indexing operation is proportional to the size of the container.

    The application must open the container before attempting to modify its indexing specification.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    index - The indexing specification for the container.
    Throws:
    XmlException - The XmlContainer.setIndexSpecification method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • Indices may only be declared on open containers.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • addIndex

    public void addIndex(DbTxn txn,
                         String uri,
                         String name,
                         String index)
                  throws XmlException
    The XmlContainer.addindex method adds an index of the specified type for the named document node. This method is for convenience - see XmlIndexSpecification.addIndex for more information.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.
    name - The name of the element or attribute node to be indexed.
    index - A space-separated list of the following indexing strategy names:
    Throws:
    XmlException - The XmlContainer.addindex method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • deleteIndex

    public void deleteIndex(DbTxn txn,
                            String uri,
                            String name,
                            String index)
                     throws XmlException
    The XmlContainer.deleteindex method deletes an index of the specified type for the named document node. This method is for convenience - see XmlIndexSpecification.addIndex for more information.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.
    name - The name of the element or attribute node to be indexed.
    index - A space-separated list of the following indexing strategy names:
    Throws:
    XmlException - The XmlContainer.deleteindex method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • replaceIndex

    public void replaceIndex(DbTxn txn,
                             String uri,
                             String name,
                             String index)
                      throws XmlException
    The XmlContainer.replaceindex method replaces an index of the specified type for the named document node. This method is for convenience - see XmlIndexSpecification.addIndex for more information.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    uri - The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.
    name - The name of the element or attribute node to be indexed.
    index - A space-separated list of the following indexing strategy names:
    Throws:
    XmlException - The XmlContainer.replaceindex method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • upgrade

    public void upgrade(int flags)
                 throws XmlException
    The XmlContainer.upgrade method upgrades the container from a previous version of Berkeley DB XML, or Berkeley DB, to the current version. A Berkeley DB upgrade is first performed using the Db.upgrade method, and then the Berkeley DB XML container is upgraded. If no upgrade is needed, then no changes are made.

    Container upgrades are done in place and are destructive. For example, if pages need to be allocated and no disk space is available, the container may be left corrupted. Backups should be made before containers are upgraded. See Upgrading databases for more information.

    The container must be closed; the system throws an exception if the container is open.

    Parameters:
    flags - Flags must be set to zero.
    Throws:
    XmlException - The XmlContainer.upgrade method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • getIndexSpecification

    public XmlIndexSpecification getIndexSpecification(DbTxn txn)
                                                throws XmlException
    The XmlContainer.getIndexSpecification method retrieves the current indexing specification for the container. The indexing specification can be modified with the XmlContainer.setIndexSpecification method.

    The application must open the container before attempting to retrieve its indexing specification.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    Returns:
    Returns the current indexing specification for the container.

    Throws:
    XmlException - The XmlContainer.getIndexSpecification method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • getName

    public String getName()
                   throws XmlException
    The XmlContainer.getName method returns the name of the XmlContainer.

    Returns:
    Returns the name of the XmlContainer.

    Throws:
    XmlException

    setName

    public void setName(String name)
                 throws XmlException
    The XmlContainer.setName method sets the name of the XmlContainer. The underlying file for the container is not renamed - for that, see XmlContainer.rename.

    This method can only be called while the container is closed.

    Parameters:
    name - The new name for the container.
    Throws:
    XmlException

    putDocument

    public int putDocument(DbTxn txn,
                           XmlDocument document,
                           XmlUpdateContext context,
                           int flags)
    The XmlContainer.putDocument method inserts a XmlDocument into the container, and returns the system-assigned document ID, as a 32-bit unsigned integral value. The document content is indexed according to the container indexing specification. The indexer supports the Xerces content encodings and expects the content to be well-formed, but it need not be valid.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    document - The XmlDocument to be inserted into the XmlContainer.
    context - (Optional) The update context within which the document is to be added. The context provides a performance improvement by caching objects that can be reused for multiple operations.
    flags - Not currently used.
    Returns:
    The id of the document.

    Throws:
    XmlException - The XmlContainer.putDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The XML Indexer could not parse the document.

  • updateDocument

    public void updateDocument(DbTxn txn,
                               XmlDocument document,
                               XmlUpdateContext context)
                        throws XmlException
    The XmlContainer.updateDocument method updates a XmlDocument in the container. The document must have been retrieved from the container using the XmlContainer.getDocument or XmlContainer.queryWithXPath methods, and must still exist within the container. The document content is indexed according to the container indexing specification, with index keys being removed for the previous document content, and added for the updated document content.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    document - The XmlDocument to be inserted into the XmlContainer.
    context - The optional XmlUpdateContext object provides a performance improvement by caching internal objects over multiple calls to the container update methods.
    Throws:
    XmlException - The XmlContainer.updateDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The specified document is not in the XmlContainer.
  • The XML Indexer could not parse the document.

  • remove

    public void remove(DbTxn txn,
                       int flags)
                throws XmlException
    The XmlContainer.remove method removes the underlying file for the container from the file system.

    The container must be closed; the system throws an exception if the container is open.

    The container must have been opened at least once; the system throws an exception if the underlying file has not yet been created.

    Automatically wrap the operation in a transaction.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    flags - must be set to zero, or a value created by bitwise inclusively OR'ing one or more of the following values:
    Throws:
    XmlException - The XmlContainer.remove method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • rename

    public void rename(DbTxn txn,
                       String newName,
                       int flags)
                throws XmlException
    The XmlContainer.rename method renames the container's underlying file. Note that the name of the container object in memory is not changed - for that, use XmlContainer.setName.

    The container must be closed; the system throws an exception if the container is open.

    The container must have been opened at least once; the system throws an exception if the underlying file has not yet been created.

    Automatically wrap the operation in a transaction.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    newName - The new container name.
    flags - must be set to zero, or a value created by bitwise inclusively OR'ing one or more of the following values:
    Throws:
    XmlException - The XmlContainer.rename method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • deleteDocument

    public void deleteDocument(DbTxn txn,
                               int id,
                               XmlUpdateContext context,
                               int flags)
                        throws XmlException
    The XmlContainer.deleteDocument method removes the specified XmlDocument from the XmlContainer.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    id - The ID of the XmlDocument to be deleted from the container.
    context - (Optional) The update context within which the document is to be deleted. The context provides a performance improvement by caching objects that can be reused for multiple operations.
    flags - Not currently used.
    Throws:
    XmlException - The XmlContainer.deleteDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The specified document is not in the XmlContainer.

  • deleteDocument

    public void deleteDocument(DbTxn txn,
                               XmlDocument document,
                               XmlUpdateContext context,
                               int flags)
                        throws XmlException
    The XmlContainer.deleteDocument method removes the specified XmlDocument from the XmlContainer.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    document - The XmlDocument to be deleted from the container.
    context - (Optional) The update context within which the document is to be deleted. The context provides a performance improvement by caching objects that can be reused for multiple operations.
    flags - Not currently used.
    Throws:
    XmlException - The XmlContainer.deleteDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The specified document is not in the XmlContainer.

  • modifyDocument

    public void modifyDocument(DbTxn txn,
                               XmlModify modify,
                               XmlUpdateContext context,
                               int flags)
                        throws XmlException
    The XmlContainer.modifyDocument method performs in-place modification of all XmlDocuments in the XmlContainer according to the state of the XmlModify object, which contains an XPath expression to target document nodes, as well as specification of the modifications to perform. All affected XmlDocument objects and indexes are updated. In order to determine how many modification operations were performed, the XmlModify.getNumModifications method should be used.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    modify - The XmlModify object describing how to change the target documents. It encapsulates the XPath query, which specifies the target nodes in the document, as well as the modification operation to perform, with associated arguments.
    context - The optional XmlUpdateContext used for the update operations on the XmlContainer. There are potential performance benefits when this object is reused across operations that modify an XmlContainer.
    flags - The flags parameter must be set to zero or one of the following values:
    Throws:
    XmlException - The XmlContainer.modifyDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The XPath expression referred to an undefined variable.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.
  • The operation requested could not be performed on the target node(s), as specified by the XmlModify object.

  • getDocument

    public XmlDocument getDocument(DbTxn txn,
                                   int id,
                                   int flags)
                            throws XmlException
    The XmlContainer.getDocument method returns the XmlDocument corresponding to the specified document ID.

    Read modified but not yet committed data. Silently ignored if the Db.DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    id - The ID of the XmlDocument to be retrieved from the container.
    flags - The flags parameter must be set to zero or one of the following values:
    Returns:
    Returns the XmlDocument corresponding to the specified document ID.
    Throws:
    XmlException - The XmlContainer.getDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The specified document is not in the XmlContainer.

  • parseXPathExpression

    public XmlQueryExpression parseXPathExpression(DbTxn txn,
                                                   String query,
                                                   XmlQueryContext context)
                                            throws XmlException
    The XmlContainer.parseXPathExpression returns a pre-parsed XPath expression, which can be used with the XmlContainer.queryWithXPath method.

    The query may optionally be parsed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    query - The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.
    context - The context within which the query is to be performed. The context contains the variable bindings, the namespace prefix to URI mapping, and the query processing flags.
    Returns:
    Returns a pre-parsed XPath expression.

    Throws:
    XmlException - The XmlContainer.close method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • The XPath parser could not parse the XPath expression.

  • queryWithXPath

    public XmlResults queryWithXPath(DbTxn txn,
                                     String query,
                                     XmlQueryContext context,
                                     int flags)
                              throws XmlException
    The XmlContainer.queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

    In this case the expression is provided as a string.

    The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

    Read modified but not yet committed data. Silently ignored if the Db.DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    query - The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.
    context - The context within which the query is to be performed. The context contains the variable bindings, the namespace prefix to URI mapping, and the query processing flags.
    flags - The flags parameter must be set to zero or one of the following values:
    Returns:
    Returns the result of the XPath query.
    Throws:
    XmlException - The XmlContainer.queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The DOM parser was unable to parse an XML document.
  • The XPath expression referred to an undefined variable.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.

  • queryWithXPath

    public XmlResults queryWithXPath(DbTxn txn,
                                     XmlQueryExpression query,
                                     int flags)
                              throws XmlException
    The XmlContainer.queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

    In this case the expression is provided in the form of an XmlQueryExpression object. This is a pre-parsed XPath expression created by a call to the XmlContainer.parseXPathExpression method.

    The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

    Read modified but not yet committed data. Silently ignored if the Db.DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

    Parameters:
    txn - If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv.txnBegin, otherwise, NULL.
    query - The query to be performed, expressed as an XmlQueryExpression object.
    flags - The flags parameter must be set to zero or one of the following values:
    Returns:
    Returns the result of the XPath query.
    Throws:
    XmlException - The XmlContainer.queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The DOM parser was unable to parse an XML document.
  • The XPath expression referred to an undefined variable.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.

  • dump

    public void dump(String filename,
                     int flags)
              throws XmlException
    The XmlContainer.dump method dumps the container contents to the specified output stream. The container can be reconstructed by a call to XmlContainer.load.

    The container must be closed; the system throws an exception if the container is open.

    The container must be have been opened at least once; the system throws an exception if the underlying files have not yet been created.

    Parameters:
    filename - The name of a file to which the container will be dumped.
    flags - Not currently used.
    Throws:
    XmlException - The XmlContainer.dump method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • load

    public void load(String filename,
                     int flags)
              throws XmlException
    The XmlContainer.load methods loads data from the specified stream into the container. The container's existing contents are discarded and replaced with the documents from the stream.

    The container must be closed; the system throws an exception if the container is open.

    The container must be have been opened at least once; the system throws an exception if the underlying files have not yet been created.

    Parameters:
    filename - The name of a file from which the container is to be loaded.
    flags - Not currently used.
    Throws:
    XmlException - The XmlContainer.load method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • verify

    public void verify(String filename,
                       int flags)
                throws XmlException
    The XmlContainer.verify method checks that the container data files are not corrupt, and optionally writes the salvaged container data to the specified output stream.

    The container must be closed; the system throws an exception if the container is open.

    The container must have been opened at least once; the system throws an exception if the underlying files have not yet been created.

    Parameters:
    filename - The name of a file that the salvaged container data is to be dumped to.
    flags - Flags must be set to zero, Db.DB_SALVAGE, or Db.DB_SALVAGE and Db.DB_AGGRESSIVE method. Please refer to the Berkeley DB reference manual for a full discussion of these values.
    Throws:
    XmlException - The XmlContainer.verify method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The container is open.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.

  • setLogLevel

    public static void setLogLevel(int level,
                                   boolean enabled)
                            throws XmlException
    Berkeley DB XML can be configured to generate a stream of messages to help application debugging. The messages are categorized by subsystem, and by importance. The messages are sent to the output stream that is configured in the Berkeley DB environment associated with the XmlContainer generating the message. The output is sent to System.err if no environment is associated with the XmlContainer.

    Parameters:
    level - The log level to enable or disable.
    enabled - A Boolean flag that specifies whether to enable or disable the level or category.
    Throws:
    XmlException

    setLogCategory

    public static void setLogCategory(int category,
                                      boolean enabled)
                               throws XmlException
    Berkeley DB XML can be configured to generate a stream of messages to help application debugging. The messages are categorized by subsystem, and by importance. The messages are sent to the output stream that is configured in the Berkeley DB environment associated with the XmlContainer generating the message. The output is sent to System.err if no environment is associated with the XmlContainer.

    Parameters:
    category - The log category to enable or disable.
    enabled - A Boolean flag that specifies whether to enable or disable the level or category.
    Throws:
    XmlException

    get_version_major

    public static int get_version_major()
                                 throws XmlException
    Throws:
    XmlException

    get_version_minor

    public static int get_version_minor()
                                 throws XmlException
    Throws:
    XmlException

    get_version_patch

    public static int get_version_patch()
                                 throws XmlException
    Throws:
    XmlException

    get_version_string

    public static String get_version_string()
                                     throws XmlException
    Throws:
    XmlException

    Berkeley DbXML
    version 1.2.1

    Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.