Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.dbxml
Class XmlContainer

    java.lang.Object
      com.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.
  - none-none-none-none
  - node-element-presence-none
  - node-attribute-presence-none
  - node-element-equality-string
  - node-element-equality-number
  - node-element-substring-string
  - node-attribute-equality-string
  - node-attribute-equality-number
  - node-attribute-substring-string
  - edge-element-presence-none
  - edge-attribute-presence-none
  - edge-element-equality-string
  - edge-element-equality-number
  - edge-element-substring-string
  - edge-attribute-equality-string
  - edge-attribute-equality-number
  - edge-attribute-substring-string

  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.
  - none-none-none-none
  - node-element-presence-none
  - node-attribute-presence-none
  - node-element-equality-string
  - node-element-equality-number
  - node-element-substring-string
  - node-attribute-equality-string
  - node-attribute-equality-number
  - node-attribute-substring-string
  - edge-element-presence-none
  - edge-attribute-presence-none
  - edge-element-equality-string
  - edge-element-equality-number
  - edge-element-substring-string
  - edge-attribute-equality-string
  - edge-attribute-equality-number
  - edge-attribute-substring-string

  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.
  - none-none-none-none
  - node-element-presence-none
  - node-attribute-presence-none
  - node-element-equality-string
  - node-element-equality-number
  - node-element-substring-string
  - node-attribute-equality-string
  - node-attribute-equality-number
  - node-attribute-substring-string
  - edge-element-presence-none
  - edge-attribute-presence-none
  - edge-element-equality-string
  - edge-element-equality-number
  - edge-element-substring-string
  - edge-attribute-equality-string
  - edge-attribute-equality-number
  - edge-attribute-substring-string

  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 `XmlDocument`s 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 `XmlDocument`s 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 `XmlDocument`s 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`

Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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