com.sleepycat.dbxml
Class XmlManager

java.lang.Object
  com.sleepycat.dbxml.XmlManager

public class XmlManager

extends Object

Provides a high-level object used to manage various aspects of Berkeley DB XML usage. An XmlManager object is used to perform activities such as container management (including creation and open), preparing XQuery queries, executing one-off queries, creating transaction objects, creating update and query context objects, and creating input streams.

A copy constructor is provided for this class. The class is implemented using a handle-body idiom. When a handle is copied both handles maintain a reference to the same body.

This object is free threaded, and can be safely shared among threads in an application.

Field Summary

static int	CATEGORY_ALL All messages.
static int	CATEGORY_CONTAINER Container messages.
static int	CATEGORY_DICTIONARY Dictionary messages.
static int	CATEGORY_INDEXER Indexer messages.
static int	CATEGORY_MANAGER Manager messages.
static int	CATEGORY_NODESTORE Node storage messages.
static int	CATEGORY_NONE No message category.
static int	CATEGORY_OPTIMIZER Optimizer messages.
static int	CATEGORY_QUERY Query processor messages.
static int	LEVEL_ALL Enable all debug levels.
static int	LEVEL_DEBUG Enable program execution tracing messages.
static int	LEVEL_ERROR Enable fatal error messages.
static int	LEVEL_INFO Enable informational messages.
static int	LEVEL_NONE Disable logging.
static int	LEVEL_WARNING Enable warning messages.
static String	metaDataName_name The "name" of the XmlDocument name metadata item
static String	metaDataName_root The "name" of the root metadata item
static String	metaDataNamespace_prefix The prefix for the built-in BDB XML metadata namespace.
static String	metaDataNamespace_uri The URI for the built-in BDB XML metadata namespace.

Constructor Summary

XmlManager()
Constructor that uses a private internal database environment.

XmlManager(Environment dbenv, XmlManagerConfig config)
Constructor that uses the provided Environment for the underlying environment.

XmlManager(XmlManagerConfig config)
Constructor that uses a private internal database environment.

Method Summary

void	close() Close the XmlManager instance.
XmlContainer	createContainer(String name) Creates and opens a container, returning a handle to an XmlContainer object.
XmlContainer	createContainer(String name, XmlContainerConfig config) Creates a container, returning a handle to an XmlContainer object.
XmlContainer	createContainer(XmlTransaction txn, String name) Creates and opens a container in the context of a transaction, returning a handle to an XmlContainer object.
XmlContainer	createContainer(XmlTransaction txn, String name, XmlContainerConfig config) Creates a container in the scope of a transaction, returning a handle to an XmlContainer object.
XmlDocument	createDocument() Instantiate a XmlDocument object.
XmlIndexLookup	createIndexLookup(XmlContainer container, String uri, String name, String index, XmlValue value, int op) Returns a XmlIndexLookup object that can be executed to perform and index lookup on a container.
XmlInputStream	createInputStream(InputStream is) Returns a XmlInputStream that wraps a InputStream.
XmlInputStream	createLocalFileInputStream(String filename) Returns a XmlInputStream to the file filename.
XmlInputStream	createMemBufInputStream(String buffer, int bufLen, boolean copyBuf) Returns a XmlInputStream for the buffer buffer.
XmlModify	createModify() Instantiate an XmlModify object.
XmlQueryContext	createQueryContext() Creates a new XmlQueryContext.
XmlQueryContext	createQueryContext(int rt) Creates a new XmlQueryContext.
XmlQueryContext	createQueryContext(int rt, int et) Creates a new XmlQueryContext.
XmlResults	createResults() Instantiates an new, empty XmlResults object.
XmlInputStream	createStdInInputStream() Returns an XmlInputStream to the console.
XmlTransaction	createTransaction() Creates a new XmlTransaction object by calling Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig).
XmlTransaction	createTransaction(Transaction toUse) Creates a new XmlTransaction object by adopting the provided transaction handle.
XmlTransaction	createTransaction(Transaction parent, TransactionConfig config) Creates a new XmlTransaction object by calling Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig) with the supplied parent transaction.
XmlUpdateContext	createUpdateContext() Instantiates a new, default, XmlUpdateContext object.
XmlInputStream	createURLInputStream(String baseId, String systemId) Creates an input stream to the identified URL.
XmlInputStream	createURLInputStream(String baseId, String systemId, String publicId) Creates an input stream to the identified URL.
void	delete() Free the native resources associated with this object.
void	dumpContainer(String name, String filename) Dumps the contents of the specified container to the specified output file.
int	existsContainer(String name) See if a container exists.
static int	get_version_major() Returns the DB XML release's major version number.
static int	get_version_minor() Returns the DB XML release's minor version number.
static int	get_version_patch() Returns the DB XML release's patch version number.
static String	get_version_string() Returns the DB XML release's version as a string.
XmlContainerConfig	getDefaultContainerConfig() Gets the default configuration object used for containers opened and created by this XmlManager object.
int	getDefaultContainerType() Returns the default type used for containers opened and created by this XmlManager object.
int	getDefaultPageSize() Gets the size of the pages used to store documents in the database.
int	getDefaultSequenceIncrement() Returns the integer increment to be used when pre-allocating document ids for new documents created by XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext).
Environment	getEnvironment() Returns a handle to the underlying database environment.
String	getHome() Returns the home directory for the underlying database environment.
XmlManagerConfig	getManagerConfig() Gets the configuration object for this XmlManager instance.
void	loadContainer(String name, String filename, XmlUpdateContext uc) Loads data from the specified file into the container.
XmlContainer	openContainer(String name) Opens a container, returning a handle to an XmlContainer object.
XmlContainer	openContainer(String name, XmlContainerConfig config) Opens a container, returning a handle to an XmlContainer object.
XmlContainer	openContainer(XmlTransaction txn, String name) Opens a container in the context of a transaction, returning a handle to an XmlContainer object.
XmlContainer	openContainer(XmlTransaction txn, String name, XmlContainerConfig config) Opens a container, returning a handle to an XmlContainer object.
XmlQueryExpression	prepare(String query, XmlQueryContext context) Compile an XQuery expression into an XmlQueryExpression object.
XmlQueryExpression	prepare(XmlTransaction txn, String query, XmlQueryContext context) Compile an XQuery expression into an XmlQueryExpression object.
XmlResults	query(String query, XmlQueryContext context) Executes a query in the context of the XmlManager object.
XmlResults	query(String query, XmlQueryContext context, XmlDocumentConfig config) Executes a query in the context of the XmlManager object.
XmlResults	query(XmlTransaction txn, String query, XmlQueryContext context) Executes a query in the context of the XmlManager object.
XmlResults	query(XmlTransaction txn, String query, XmlQueryContext context, XmlDocumentConfig config) Executes a query in the context of the XmlManager object.
void	registerResolver(XmlResolver resolver) Identifies an XmlResolver object to be used for file resolution.
void	reindexContainer(String name, XmlUpdateContext context, XmlContainerConfig config) Reindex a container.
void	reindexContainer(XmlTransaction txn, String name, XmlUpdateContext context, XmlContainerConfig config) Reindex a container.
void	removeContainer(String name) Removes the underlying file for the container from the file system.
void	removeContainer(XmlTransaction txn, String name) Removes the underlying file for the container from the file system in the context of a transaction.
void	renameContainer(String oldName, String newName) Renames the container's underlying file.
void	renameContainer(XmlTransaction txn, String oldName, String newName) Renames the container's underlying file in the context of a transaction.
void	setDefaultContainerConfig(XmlContainerConfig config) Sets the default configuration object used for containers opened and created by this XmlManager object.
void	setDefaultContainerType(int type) Sets the default type used for containers opened and created by this XmlManager object.
void	setDefaultPageSize(int pageSize) Sets the size of the pages used to store documents in the database.
void	setDefaultSequenceIncrement(int incr) Sets the integer increment to be used when pre-allocating document ids for new documents created by XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext).
static void	setLogCategory(int category, boolean enabled) Enable or disable a category of log messages.
static void	setLogLevel(int level, boolean enabled) Enable or disable log messages of a given level of importance.
void	upgradeContainer(String name, XmlUpdateContext context) Upgrades the container from a previous version of Berkeley DB XML, or Berkeley DB, to the current version.
void	verifyContainer(String name, String filename) Checks that the container data files are not corrupt, and optionally writes the salvaged container data to the specified output stream.
void	verifyContainer(String name, String filename, VerifyConfig config) 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

Disable logging.

See Also:

Constant Field Values

LEVEL_DEBUG

public static final int LEVEL_DEBUG

Enable program execution tracing messages.

See Also:

Constant Field Values

LEVEL_INFO

public static final int LEVEL_INFO

Enable informational messages.

See Also:

Constant Field Values

LEVEL_WARNING

public static final int LEVEL_WARNING

Enable warning messages.

See Also:

Constant Field Values

LEVEL_ERROR

public static final int LEVEL_ERROR

Enable fatal error messages.

See Also:

Constant Field Values

LEVEL_ALL

public static final int LEVEL_ALL

Enable all debug levels.

See Also:

Constant Field Values

CATEGORY_NONE

public static final int CATEGORY_NONE

No message category.

See Also:

Constant Field Values

CATEGORY_INDEXER

public static final int CATEGORY_INDEXER

Indexer messages.

See Also:

Constant Field Values

CATEGORY_QUERY

public static final int CATEGORY_QUERY

Query processor messages.

See Also:

Constant Field Values

CATEGORY_OPTIMIZER

public static final int CATEGORY_OPTIMIZER

Optimizer messages.

See Also:

Constant Field Values

CATEGORY_DICTIONARY

public static final int CATEGORY_DICTIONARY

Dictionary messages.

See Also:

Constant Field Values

CATEGORY_CONTAINER

public static final int CATEGORY_CONTAINER

Container messages.

See Also:

Constant Field Values

CATEGORY_NODESTORE

public static final int CATEGORY_NODESTORE

Node storage messages.

See Also:

Constant Field Values

CATEGORY_MANAGER

public static final int CATEGORY_MANAGER

Manager messages.

See Also:

Constant Field Values

CATEGORY_ALL

public static final int CATEGORY_ALL

All messages.

See Also:

Constant Field Values

metaDataNamespace_uri

public static final String metaDataNamespace_uri

The URI for the built-in BDB XML metadata namespace.

See Also:

Constant Field Values

metaDataNamespace_prefix

public static final String metaDataNamespace_prefix

The prefix for the built-in BDB XML metadata namespace.

See Also:

Constant Field Values

metaDataName_name

public static final String metaDataName_name

The "name" of the XmlDocument name metadata item

See Also:

Constant Field Values

metaDataName_root

public static final String metaDataName_root

The "name" of the root metadata item

See Also:

Constant Field Values

Constructor Detail

XmlManager

public XmlManager()
           throws XmlException

Constructor that uses a private internal database environment. No external processes can join the environment, but the XmlManager object can be shared between threads within the opening process.

Note that for this form of the constructor, the environment home is located in either the current working directory, or in the directory identified by the DB_HOME environment variable.

XmlManager

public XmlManager(XmlManagerConfig config)
           throws XmlException

Constructor that uses a private internal database environment. No external processes can join the environment, but the XmlManager object can be shared between threads within the opening process.

Note that for this form of the constructor, the environment home is located in either the current working directory, or in the directory identified by the DB_HOME environment variable.

Parameters:

config - The configuration settings for this XmlManager instance.

XmlManager

public XmlManager(Environment dbenv,
                  XmlManagerConfig config)
           throws XmlException

Constructor that uses the provided Environment for the underlying environment. The Berkeley DB subsystems initiated by this environment (for example, transactions, logging, the memory pool), are the subsystems that are available to Berkeley DB XML when operations are performed using this manager object.

Parameters:

dbenv - The environment handle to use for the underlying database environment. The handle provided here must be opened.

config - The configuration settings for this XmlManager instance.

Method Detail

delete

public void delete()

Free the native resources associated with this object.

close

public void close()
           throws XmlException

Close the XmlManager instance. If an Environment was adopted, that is closed, as well. This method also calls delete() to free the native resources.

Throws:

XmlException

createContainer

public XmlContainer createContainer(String name)
                             throws XmlException

Creates and opens a container, returning a handle to an XmlContainer object. If the container already exists at the time this method is called, an exception is thrown. The container is set up to use node-level storage unless setDefaultContainerType(int) has been called.

Use openContainer(java.lang.String) to open a container that has already been created.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

name - The container's name. The container is created relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is created in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

Throws:

XmlException

createContainer

public XmlContainer createContainer(XmlTransaction txn,
                                    String name)
                             throws XmlException

Creates and opens a container in the context of a transaction, returning a handle to an XmlContainer object. If the container already exists at the time this method is called, an exception is thrown. The container is set up to use node-level storage unless setDefaultContainerType(int) has been called.

Use openContainer(java.lang.String) to open a container that has already been created.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

txn - The transaction handle to use for this container creation.

name - The container's name. The container is created relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is created in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

Throws:

XmlException

createContainer

public XmlContainer createContainer(String name,
                                    XmlContainerConfig config)
                             throws XmlException

Creates a container, returning a handle to an XmlContainer object.

Parameters:

name - The container's name. The container is created relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is created in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

config - The configuration settings for the container

Throws:

XmlException

createContainer

public XmlContainer createContainer(XmlTransaction txn,
                                    String name,
                                    XmlContainerConfig config)
                             throws XmlException

Creates a container in the scope of a transaction, returning a handle to an XmlContainer object.

Parameters:

txn - The transaction handle to use for this container creation.

name - The container's name. The container is created relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is created in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

config - The configuration settings for the container

Throws:

XmlException

createDocument

public XmlDocument createDocument()
                           throws XmlException

Instantiate a XmlDocument object.

Throws:

XmlException

createIndexLookup

public XmlIndexLookup createIndexLookup(XmlContainer container,
                                        String uri,
                                        String name,
                                        String index,
                                        XmlValue value,
                                        int op)
                                 throws XmlException

Returns a XmlIndexLookup object that can be executed to perform and index lookup on a container.

The constructed object can be further configured, and used with the XmlIndexLookup.execute(com.sleepycat.dbxml.XmlQueryContext) method to perform the lookup operation.

Parameters:

container - The target container for the lookup operation

uri - The namespace of the node to be used. The default namespace is selected by passing a null string.

name - The name of the element or attribute node to be used.

index - Identifies the index to be used for the lookup operation. The value supplied here must be a valid index. See XmlIndexSpecification.addIndex(java.lang.String,java.lang.String,java.lang.String) for a description of valid index specifications, with the exceptions that only one index can be specified, and substring indexes are not supported.

value - The value to be used as the single value for an equality or inequality lookup, or as the lower bound of a range lookup. An empty value is specified using a null object.

op - The comparison operation to be performed. See XmlIndexLookup for valid operations.

Throws:

XmlException

createLocalFileInputStream

public XmlInputStream createLocalFileInputStream(String filename)
                                          throws XmlException

Returns a XmlInputStream to the file filename. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

The input stream must be passed to one of these methods, or the underlying memory will leak. It cannot be deleted from Java code. Note that there is no attempt to ensure that the file referenced contains well-formed or valid XML. Exceptions may be thrown at the time that this input stream is actually read if the stream does not contain well-formed, or valid XML.

Parameters:

filename - The file to which you want an input stream formed.

Throws:

XmlException

createMemBufInputStream

public XmlInputStream createMemBufInputStream(String buffer,
                                              int bufLen,
                                              boolean copyBuf)
                                       throws XmlException

Returns a XmlInputStream for the buffer buffer. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

The

The input stream must be passed to one of these methods, or the underlying memory will leak. It cannot be deleted from Java code. Note that there is no attempt to ensure that the file referenced contains well-formed or valid XML. Exceptions may be thrown at the time that this input stream is actually read if the stream does not contain well-formed, or valid XML.

Parameters:

buffer - The buffer from which you want an input stream formed.

bufLen - The number of bytes in buffer. Do not include any trailing null.

copyBuf - Must be true to indicate that the buffer should be copied.

Throws:

XmlException

createInputStream

public XmlInputStream createInputStream(InputStream is)
                                 throws XmlException

Returns a XmlInputStream that wraps a InputStream. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

The input stream must be passed to one of these methods, or the underlying memory may leak. It cannot be deleted from Java code. Note that there is no attempt to ensure that the file referenced contains well-formed or valid XML. Exceptions may be thrown at the time that this input stream is actually read if the stream does not contain well-formed, or valid XML.

Parameters:

is - a java.io.InputStream from which the XmlInputStream should be created.

Throws:

XmlException

createModify

public XmlModify createModify()
                       throws XmlException

Instantiate an XmlModify object.

Throws:

XmlException

createQueryContext

public XmlQueryContext createQueryContext(int rt,
                                          int et)
                                   throws XmlException

Creates a new XmlQueryContext.

Parameters:

rt - Specifies whether to return live or dead values: XmlQueryContext.LiveValues or XmlQueryContext.DeadValues

et - The evaluation type must be specified as either: XmlQueryContext.Eager or XmlQueryContext.Lazy.

Throws:

XmlException

createQueryContext

public XmlQueryContext createQueryContext()
                                   throws XmlException

Creates a new XmlQueryContext.

Throws:

XmlException

createQueryContext

public XmlQueryContext createQueryContext(int rt)
                                   throws XmlException

Creates a new XmlQueryContext.

Parameters:

rt - Specifies whether to return live or dead values: XmlQueryContext.LiveValues or XmlQueryContext.DeadValues

Throws:

XmlException

createResults

public XmlResults createResults()
                         throws XmlException

Instantiates an new, empty XmlResults object. You can then use XmlResults.add(com.sleepycat.dbxml.XmlValue) to add XmlValue objects to this result set.

Throws:

XmlException

createStdInInputStream

public XmlInputStream createStdInInputStream()
                                      throws XmlException

Returns an XmlInputStream to the console. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

If the input stream is passed to either of these methods, it will be adopted, and deleted. If it is not passed, it is the responsibility of the user to delete the object.

Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

Throws:

XmlException

createTransaction

public XmlTransaction createTransaction()
                                 throws XmlException

Creates a new XmlTransaction object by calling Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig).

If transactions were not initialized when this XmlManager object was opened then this method throws an exception.

Throws:

XmlException

createTransaction

public XmlTransaction createTransaction(Transaction toUse)
                                 throws XmlException

Creates a new XmlTransaction object by adopting the provided transaction handle.

If transactions were not initialized when this XmlManager object was opened then this method throws an exception.

Parameters:

toUse - A transaction handle to adopt. If the returned XmlTransaction is not committed or aborted, the state of the underlying transaction is left unchanged. This allows a transaction to be controlled external to its XmlTransaction object.

Throws:

XmlException

createTransaction

public XmlTransaction createTransaction(Transaction parent,
                                        TransactionConfig config)
                                 throws XmlException

Creates a new XmlTransaction object by calling Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig) with the supplied parent transaction.

If transactions were not initialized when this XmlManager object was opened then this method throws an exception.

Parameters:

parent - The parent transaction passed to Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig).

config - The transaction configuration passed to Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig).

Throws:

XmlException

createUpdateContext

public XmlUpdateContext createUpdateContext()
                                     throws XmlException

Instantiates a new, default, XmlUpdateContext object. This object is used for XmlContainer and XmlModify operations that add, delete, and modify documents, and documents in containers.

Throws:

XmlException

createURLInputStream

public XmlInputStream createURLInputStream(String baseId,
                                           String systemId,
                                           String publicId)
                                    throws XmlException

Creates an input stream to the identified URL. File URLs are always supported by this method. URLs that require network access (for example, http://...) are supported only if Xerces was compiled with socket support. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

If the input stream is passed to either of these methods, it will be adopted, and deleted. If it is not passed, it is the responsibility of the user to delete the object. Note that there is no attempt to ensure that the URI referenced contains well-formed or valid XML. Exceptions may be thrown at the time that this input stream is actually read if the stream does not contain well-formed, or valid XML.

Parameters:

baseId - The base ID to use for this URL.

systemId - The system ID to use for this URL.

publicId - The public ID to use for this URL.

Throws:

XmlException

createURLInputStream

public XmlInputStream createURLInputStream(String baseId,
                                           String systemId)
                                    throws XmlException

Creates an input stream to the identified URL. File URLs are always supported by this method. URLs that require network access (for example, http://...) are supported only if Xerces was compiled with socket support. Use this input stream with XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext) or XmlDocument.setContentAsXmlInputStream(com.sleepycat.dbxml.XmlInputStream).

If the input stream is passed to either of these methods, it will be adopted, and deleted. If it is not passed, it is the responsibility of the user to delete the object. Note that there is no attempt to ensure that the URI referenced contains well-formed or valid XML. Exceptions may be thrown at the time that this input stream is actually read if the stream does not contain well-formed, or valid XML.

Parameters:

baseId - The base ID to use for this URL.

systemId - The system ID to use for this URL.

Throws:

XmlException

setDefaultContainerConfig

public void setDefaultContainerConfig(XmlContainerConfig config)
                               throws XmlException

Sets the default configuration object used for containers opened and created by this XmlManager object. If a form of createContainer(java.lang.String) or openContainer(java.lang.String) is used that takes an XmlContainerConfig argument, the settings provided using this method are ignored.

Parameters:

config - The configuration object to use for container creation.

Throws:

XmlException

getDefaultContainerConfig

public XmlContainerConfig getDefaultContainerConfig()
                                             throws XmlException

Gets the default configuration object used for containers opened and created by this XmlManager object.

Throws:

XmlException

setDefaultPageSize

public void setDefaultPageSize(int pageSize)
                        throws XmlException

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.

This method will only affect containers created after it is set. It has no effect on existing containers.

Parameters:

pageSize - The page size in bytes.

Throws:

XmlException

getDefaultPageSize

public int getDefaultPageSize()
                       throws XmlException

Gets the size of the pages used to store documents in the database.

Throws:

XmlException

setDefaultContainerType

public void setDefaultContainerType(int type)
                             throws XmlException

Sets the default type used for containers opened and created by this XmlManager object. If a form of createContainer(java.lang.String) or openContainer(java.lang.String) is used that is provided with a type via XmlContainerConfig.setNodeContainer(boolean), the settings provided using this method are ignored.

Parameters:

type - The type of container to create. One of: XmlContainer.NodeContainer or XmlContainer.WholedocContainer.

Throws:

XmlException

getDefaultContainerType

public int getDefaultContainerType()
                            throws XmlException

Returns the default type used for containers opened and created by this XmlManager object. One of: XmlContainer.NodeContainer or XmlContainer.WholedocContainer.

Throws:

XmlException

setDefaultSequenceIncrement

public void setDefaultSequenceIncrement(int incr)
                                 throws XmlException

Sets the integer increment to be used when pre-allocating document ids for new documents created by XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext).

Parameters:

incr - The page size in bytes.

Throws:

XmlException

getDefaultSequenceIncrement

public int getDefaultSequenceIncrement()
                                throws XmlException

Returns the integer increment to be used when pre-allocating document ids for new documents created by XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument, com.sleepycat.dbxml.XmlUpdateContext).

Throws:

XmlException

getEnvironment

public Environment getEnvironment()
                           throws XmlException

Returns a handle to the underlying database environment.

Throws:

XmlException

getHome

public String getHome()
               throws XmlException

Returns the home directory for the underlying database environment. XmlContainer files are placed relative to this directory unless an absolute path is used for the container name.

Throws:

XmlException

getManagerConfig

public XmlManagerConfig getManagerConfig()
                                  throws XmlException

Gets the configuration object for this XmlManager instance.

Throws:

XmlException

dumpContainer

public void dumpContainer(String name,
                          String filename)
                   throws XmlException

Dumps the contents of the specified container to the specified output file. The container can be reconstructed by a call to loadContainer(java.lang.String, java.lang.String, com.sleepycat.dbxml.XmlUpdateContext).

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:

name - The name of the container to dump.

filename - The filename to which the container is to be dumped.

Throws:

XmlException

existsContainer

public int existsContainer(String name)
                    throws XmlException

See if a container exists.

Returns 0 if the file named either does not exist or is not a container. Returns the format version if it is a valid container.

Parameters:

name - The name of the container.

Throws:

XmlException

loadContainer

public void loadContainer(String name,
                          String filename,
                          XmlUpdateContext uc)
                   throws XmlException

Loads data from the specified file into the container. The container's existing contents are discarded and replaced with the documents from the stream.

The specified input stream should contain data as created by dumpContainer(java.lang.String, java.lang.String).

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:

name - The name of the container to load.

filename - The filename from which the container is to be loaded.

Throws:

XmlException

openContainer

public XmlContainer openContainer(String name)
                           throws XmlException

Opens a container, returning a handle to an XmlContainer object.

Use createContainer(java.lang.String) to create and open a new container.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

name - The container's name. The container is opened relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is opened in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

Throws:

XmlException

openContainer

public XmlContainer openContainer(XmlTransaction txn,
                                  String name)
                           throws XmlException

Opens a container in the context of a transaction, returning a handle to an XmlContainer object.

Use createContainer(java.lang.String) to create and open a new container.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

txn - The transaction handle to use for this container creation.

name - The container's name. The container is opened relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is opened in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

Throws:

XmlException

openContainer

public XmlContainer openContainer(String name,
                                  XmlContainerConfig config)
                           throws XmlException

Opens a container, returning a handle to an XmlContainer object.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

name - The container's name. The container is opened relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is opened in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

config - The configuration settings for the container

Throws:

XmlException

openContainer

public XmlContainer openContainer(XmlTransaction txn,
                                  String name,
                                  XmlContainerConfig config)
                           throws XmlException

Opens a container, returning a handle to an XmlContainer object.

Containers always remain open until the last handle referencing the container is destroyed.

Parameters:

txn - The transaction handle to use for this container creation.

name - The container's name. The container is opened relative to the underlying environment's home directory (see XmlManager for more information) unless an absolute path is used for the name; in that case the container is opened in the location identified by the path.

The name provided here must be unique for the environment or an exception is thrown.

config - The configuration settings for the container

Throws:

XmlException

prepare

public XmlQueryExpression prepare(String query,
                                  XmlQueryContext context)
                           throws XmlException

Compile an XQuery expression into an XmlQueryExpression object. You can then run the XQuery expression repeatedly using XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Use this method to compile and evaluate XQuery expressions against your XmlContainer and XmlDocument objects any time you want to evaluate the expression more than once.

Note that the scope of the query provided here can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Parameters:

query - The XQuery query string to compile.

context - The XmlQueryContext to use for this query.

Throws:

XmlException

prepare

public XmlQueryExpression prepare(XmlTransaction txn,
                                  String query,
                                  XmlQueryContext context)
                           throws XmlException

Compile an XQuery expression into an XmlQueryExpression object. You can then run the XQuery expression repeatedly using XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Use this method to compile and evaluate XQuery expressions against your XmlContainer and XmlDocument objects any time you want to evaluate the expression more than once.

Note that the scope of the query provided here can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from createTransaction().

query - The XQuery query string to compile.

context - The XmlQueryContext to use for this query.

Throws:

XmlException

query

public XmlResults query(String query,
                        XmlQueryContext context,
                        XmlDocumentConfig config)
                 throws XmlException

Executes a query in the context of the XmlManager object. This method is the equivalent of calling prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) and then XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) on the prepared query.

The scope of the query can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Note that this method is suitable for performing one-off queries. If you want to execute a query more than once, you should use prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) to compile the expression, and then use XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) to run it.

This method returns an XmlResults object. You then iterate over the results set contained in that object using XmlResults.next() and XmlResults.previous().

For more information on querying containers and documents, see the Berkeley DB XML Getting Started Guide.

Parameters:

query - The XQuery query string.

context - The XmlQueryContext to use for this query.

config - Configuration settings for this operation

Throws:

XmlException

query

public XmlResults query(XmlTransaction txn,
                        String query,
                        XmlQueryContext context,
                        XmlDocumentConfig config)
                 throws XmlException

Executes a query in the context of the XmlManager object. This method is the equivalent of calling prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) and then XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) on the prepared query.

The scope of the query can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Note that this method is suitable for performing one-off queries. If you want to execute a query more than once, you should use prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) to compile the expression, and then use XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) to run it.

This method returns an XmlResults object. You then iterate over the results set contained in that object using XmlResults.next() and XmlResults.previous().

For more information on querying containers and documents, see the Berkeley DB XML Getting Started Guide.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from createTransaction().

query - The XQuery query string.

context - The XmlQueryContext to use for this query.

config - Configuration settings for this operation

Throws:

XmlException

query

public XmlResults query(String query,
                        XmlQueryContext context)
                 throws XmlException

Executes a query in the context of the XmlManager object. This method is the equivalent of calling prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) and then XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) on the prepared query.

The scope of the query can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Note that this method is suitable for performing one-off queries. If you want to execute a query more than once, you should use prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) to compile the expression, and then use XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) to run it.

This method returns an XmlResults object. You then iterate over the results set contained in that object using XmlResults.next() and XmlResults.previous().

For more information on querying containers and documents, see the Berkeley DB XML Getting Started Guide.

Parameters:

query - The XQuery query string.

context - The XmlQueryContext to use for this query.

Throws:

XmlException

query

public XmlResults query(XmlTransaction txn,
                        String query,
                        XmlQueryContext context)
                 throws XmlException

Executes a query in the context of the XmlManager object. This method is the equivalent of calling prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) and then XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) on the prepared query.

The scope of the query can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext).

Note that this method is suitable for performing one-off queries. If you want to execute a query more than once, you should use prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext) to compile the expression, and then use XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext) to run it.

This method returns an XmlResults object. You then iterate over the results set contained in that object using XmlResults.next() and XmlResults.previous().

For more information on querying containers and documents, see the Berkeley DB XML Getting Started Guide.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from createTransaction().

query - The XQuery query string.

context - The XmlQueryContext to use for this query.

Throws:

XmlException

registerResolver

public void registerResolver(XmlResolver resolver)
                      throws XmlException

Identifies an XmlResolver object to be used for file resolution. This object is used by the underlying XercesC DOM or SAX parsers to locate data based on URIs, or public and system ids. Custom XmlResolver objects can be created by applications to provide a mechanism to name and retrieve collections, documents, and XML entities external to Berkeley DB XML.

Parameters:

resolver - The XmlResolver instance to be used for file resolution.

Throws:

XmlException

reindexContainer

public void reindexContainer(String name,
                             XmlUpdateContext context,
                             XmlContainerConfig config)
                      throws XmlException

Reindex a container.

Remove indexes and reindex the container, to change the indexing mode between node-level and document-level indexes.

The container should be backed up before using this method. This method may take a very long time, depending on the size of the container, and should not be used casually.

Parameters:

name - The name of the container to reindex

context - The update context for the opeartion

config - XmlContainerConfig. For document indexes, pass null, for node indexes, use new XmlContainerConfig().setIndexNodes(true). See XmlContainerConfig.

Throws:

XmlException

reindexContainer

public void reindexContainer(XmlTransaction txn,
                             String name,
                             XmlUpdateContext context,
                             XmlContainerConfig config)
                      throws XmlException

Reindex a container.

Remove indexes and reindex the container, to change the indexing mode between node-level and document-level indexes.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from createTransaction().

name - The name of the container to reindex

context - The update context for the opeartion

config - XmlContainerConfig. For document indexes, pass null, for node indexes, use new XmlContainerConfig().setIndexNodes(true). See XmlContainerConfig.

Throws:

XmlException

removeContainer

public void removeContainer(String name)
                     throws XmlException

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.

Parameters:

name - The name of the container to be removed.

Throws:

XmlException

removeContainer

public void removeContainer(XmlTransaction txn,
                            String name)
                     throws XmlException

Removes the underlying file for the container from the file system in the context of a transaction.

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.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from createTransaction().

name - The name of the container to be removed.

Throws:

XmlException

renameContainer

public void renameContainer(String oldName,
                            String newName)
                     throws XmlException

Renames the container's underlying file.

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.

Parameters:

oldName - The name of the container whose name you want to change.

newName - The new container name.

Throws:

XmlException

renameContainer

public void renameContainer(XmlTransaction txn,
                            String oldName,
                            String newName)
                     throws XmlException

Renames the container's underlying file in the context of a transaction.

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.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from

oldName - The name of the container whose name you want to change.

newName - The new container name.

Throws:

XmlException

upgradeContainer

public void upgradeContainer(String name,
                             XmlUpdateContext context)
                      throws XmlException

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 Database.upgrade(java.lang.String, com.sleepycat.db.DatabaseConfig) 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:

name - The name of the container to be upgraded.

context - The XmlUpdateContext object to be used for this operation.

Throws:

XmlException

verifyContainer

public void verifyContainer(String name,
                            String filename)
                     throws XmlException

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:

name - The name of the container to be verified.

filename - The name of the file into which salvaged container data is to be dumped.

Throws:

XmlException

verifyContainer

public void verifyContainer(String name,
                            String filename,
                            VerifyConfig config)
                     throws XmlException

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:

name - The name of the container to be verified.

filename - The name of the file into which salvaged container data is to be dumped.

config - The configuration settings for this operation.

Throws:

XmlException

setLogLevel

public static void setLogLevel(int level,
                               boolean enabled)
                        throws XmlException

Enable or disable log messages of a given level of importance.

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 XmlManager generating the message. The output is sent to System.err if no environment is associated with the XmlManager.

Parameters:

level - The log level to enable or disable. One of: LEVEL_DEBUG, LEVEL_INFO, LEVEL_WARNING, LEVEL_ERROR, or LEVEL_ALL.

enabled - Whether to enable or disable the importance level.

Throws:

XmlException

setLogCategory

public static void setLogCategory(int category,
                                  boolean enabled)
                           throws XmlException

Enable or disable a category of log messages.

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 XmlManager generating the message. The output is sent to System.err if no environment is associated with the XmlManager.

Parameters:

category - The log category to enable or disable. One of: CATEGORY_INDEXER, CATEGORY_QUERY, CATEGORY_OPTIMIZER, CATEGORY_DICTIONARY, CATEGORY_CONTAINER, CATEGORY_NODESTORE, CATEGORY_MANAGER, or CATEGORY_ALL

enabled - Whether to enable or disable the category.

Throws:

XmlException

get_version_major

public static int get_version_major()

Returns the DB XML release's major version number.

get_version_minor

public static int get_version_minor()

Returns the DB XML release's minor version number.

get_version_patch

public static int get_version_patch()

Returns the DB XML release's patch version number.

get_version_string

public static String get_version_string()

Returns the DB XML release's version as a string.