XmlManager::openContainer
|
![Ref](../../images/ref.gif) |
#include <DbXml.hpp>
XmlContainer XmlManager::openContainer(const std::string &name)
XmlContainer XmlManager::openContainer(
XmlTransaction &txn, const std::string &name)
XmlContainer XmlManager::openContainer(
const std::string &name, const XmlContainerConfig &config)
XmlContainer XmlManager::openContainer(
XmlTransaction &txn, const std::string &name,
const XmlContainerConfig &config)
XmlContainer XmlManager::openContainer(
const std::string &name, const XmlContainerConfig &flags,
XmlContainer::ContainerType type, int mode)
XmlContainer XmlManager::openContainer(
XmlTransaction &txn, const std::string &name,
const XmlContainerConfig &flags, XmlContainer::ContainerType type,
int mode)
Description: XmlManager::openContainer
Opens a container, returning a handle to an XmlContainer object.
Unless the config or flags parameter is set to true using XmlContainerConfig::setAllowCreate, the container must already exist at the
time that this method is called or an exception is thrown.
Use XmlManager::createContainer, or set XmlContainerConfig::setAllowCreate to true for the flags or config parameter on this method, to create and open a new container.
Containers always remain open until the last handle referencing the
container is destroyed.
The name provided here must be unique for the environment or an
exception is thrown.
Description: XmlManager::openContainer(XmlTransaction &txn, const std::string &name)
Opens the identified container.
Unless XmlContainerConfig::setAllowCreate was set to true and assigned using
XmlManager::setDefaultContainerConfig, the container must have previously been created or an exception is thrown.
Parameters
txn
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.
Errors
The XmlManager::openContainer method
may fail and throw
XmlException,
encapsulating one of the following non-zero errors:
CONTAINER_NOT_FOUND- Error: Db::open: File exists
Description: XmlManager::openContainer(XmlTransaction &txn, const
std::string &name, const XmlContainerConfig &flags)
Opens a container. Unless XmlContainerConfig::setAllowCreate was set to true for flags, the container must
have previously been created or an exception is thrown.
Parameters
txn
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.
flags
The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one
or more of the following values:
DB_CREATE- If the container does not currently exist, create it.
DB_READ_UNCOMMITTED- This operation will support degree 1 isolation; that is, read operations
may return data that has been modified by other transactions but which
has not yet been committed.
Silently ignored if the DB_READ_UNCOMMITTED flag
was not specified when the underlying container was opened.
DB_EXCL- Return an error if the container already exists. The DB_EXCL
flag is only meaningful when specified with the DB_CREATE
flag.
DB_MULTIVERSION- Open the database with support for multiversion concurrency control. This will cause updates to the
container to follow a copy-on-write protocol, which is required to
support snapshot isolation. The DB_MULTIVERSION flag requires
that the container be transactionally protected during its open.
DB_NOMMAP- Do not map this container into process memory (see the
UNREF==dbenv_set_mp_mmapsize method for further information).
DB_RDONLY- Open the container for reading only. Any attempt to modify items in the
container will fail, regardless of the actual permissions of any
underlying files.
DB_THREAD- Cause the container handle to be free-threaded;
that is, concurrently usable by multiple
threads in the address space.
DBXML_CHKSUM- 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.
DBXML_ENCRYPT- Encrypt the database using the cryptographic password specified to
UNREF==dbenv_set_encrypt.
DB_TXN_NOT_DURABLE- If set, Berkeley DB XML will not write log records for this database. This means
that updates of this database exhibit the ACI (atomicity, consistency,
and isolation) properties, but not D (durability); that is, database
integrity will be maintained, but if the application or system fails,
integrity will not persist. The database file must be verified and/or
restored from backup after a failure.
DBXML_INDEX_NODES- Causes the indexer to create index targets that reference nodes
rather than documents. This allows index lookups during query processing
to more efficiently find target nodes and avoid walking the document tree.
It can apply to both container types, and is the default for containers
of type XmlContainer::NodeContainer.
DBXML_NO_INDEX_NODES- Causes the indexer to create index targets that reference documents rather than
nodes. This can be more desirable for simple queries that only need to
return documents and do relatively little navigation during querying.
It can apply to both container types, and is the default for containers
of type XmlContainer::WholedocContainer.
DBXML_STATISTICS- Causes the container to be created to include structural statistics
information, which is very useful for cost based query optimisation. Containers
created with these statistics will take longer to load and update, since the
statistics must also be updated. This is the default.
DBXML_NO_STATISTICS- Causes the container to be created without structural statistics
information - by default structural statistics are created.
DBXML_TRANSACTIONAL- Cause the container to support transactions. If this flag is set, an
XmlTransaction object may be used with any method that supports
transactional protection. Also, if this flag is used, and if an
XmlTransaction object is not provided to a method that modifies an
XmlContainer or XmlDocument object, then auto commit is
automatically used for the operation.
DBXML_ALLOW_VALIDATION- When loading documents into the container, validate the XML if it refers
to a DTD or XML Schema.
config
Errors
The XmlManager::openContainer method
may fail and throw
XmlException,
encapsulating one of the following non-zero errors:
CONTAINER_CONTAINER_NOT_FOUND- Error: Db::open: File exists
INVALID_VALUE- Invalid flags to method XmlManager::openContainer
Description: XmlManager::openContainer(XmlTransaction &txn, const
std::string &name, XmlContainer::ContainerType type,
const XmlContainerConfig &flags, int mode)
Opens a container. Unless XmlContainerConfig::setAllowCreate was set to true for flags, the container must
have previously been created or an exception is thrown.
Parameters
txn
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.
type- If the container is to be created, the type of the container.
The container type must be one of the following values:
XmlContainer::NodeContainer- Documents are broken down into their component nodes, and these nodes
are stored individually in the container. This is the preferred
container storage type.
XmlContainer::WholedocContainer- Documents are stored intact; all white space and formatting is preserved.
The default is XmlContainer::NodeContainer
flags- The XmlContainerConfig object used to set the flags to use for this container open.
The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one
or more of the following values:
DB_CREATE- If the container does not currently exist, create it.
DB_READ_UNCOMMITTED- This operation will support degree 1 isolation; that is, read operations
may return data that has been modified by other transactions but which
has not yet been committed.
Silently ignored if the DB_READ_UNCOMMITTED flag
was not specified when the underlying container was opened.
DB_EXCL- Return an error if the container already exists. The DB_EXCL
flag is only meaningful when specified with the DB_CREATE
flag.
DB_MULTIVERSION- Open the database with support for multiversion concurrency control. This will cause updates to the
container to follow a copy-on-write protocol, which is required to
support snapshot isolation. The DB_MULTIVERSION flag requires
that the container be transactionally protected during its open.
DB_NOMMAP- Do not map this container into process memory (see the
UNREF==dbenv_set_mp_mmapsize method for further information).
DB_RDONLY- Open the container for reading only. Any attempt to modify items in the
container will fail, regardless of the actual permissions of any
underlying files.
DB_THREAD- Cause the container handle to be free-threaded;
that is, concurrently usable by multiple
threads in the address space.
DBXML_CHKSUM- 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.
DBXML_ENCRYPT- Encrypt the database using the cryptographic password specified to
UNREF==dbenv_set_encrypt.
DB_TXN_NOT_DURABLE- If set, Berkeley DB XML will not write log records for this database. This means
that updates of this database exhibit the ACI (atomicity, consistency,
and isolation) properties, but not D (durability); that is, database
integrity will be maintained, but if the application or system fails,
integrity will not persist. The database file must be verified and/or
restored from backup after a failure.
DBXML_INDEX_NODES- Causes the indexer to create index targets that reference nodes
rather than documents. This allows index lookups during query processing
to more efficiently find target nodes and avoid walking the document tree.
It can apply to both container types, and is the default for containers
of type XmlContainer::NodeContainer.
DBXML_NO_INDEX_NODES- Causes the indexer to create index targets that reference documents rather than
nodes. This can be more desirable for simple queries that only need to
return documents and do relatively little navigation during querying.
It can apply to both container types, and is the default for containers
of type XmlContainer::WholedocContainer.
DBXML_STATISTICS- Causes the container to be created to include structural statistics
information, which is very useful for cost based query optimisation. Containers
created with these statistics will take longer to load and update, since the
statistics must also be updated. This is the default.
DBXML_NO_STATISTICS- Causes the container to be created without structural statistics
information - by default structural statistics are created.
DBXML_TRANSACTIONAL- Cause the container to support transactions. If this flag is set, an
XmlTransaction object may be used with any method that supports
transactional protection. Also, if this flag is used, and if an
XmlTransaction object is not provided to a method that modifies an
XmlContainer or XmlDocument object, then auto commit is
automatically used for the operation.
DBXML_ALLOW_VALIDATION- When loading documents into the container, validate the XML if it refers
to a DTD or XML Schema.
mode- On Windows systems, the mode parameter is ignored.
On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by
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)). Created files are owned by the process owner; the
group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB. System shared memory
segments created by are created with mode mode, unmodified
by the process' umask value. If mode is 0, will use a
default mode of readable and writable by both owner and group.
Errors
The XmlManager::openContainer method
may fail and throw
XmlException,
encapsulating one of the following non-zero errors:
CONTAINER_CONTAINER_NOT_FOUND- Error: Db::open: File exists
INVALID_VALUE- Invalid flags to method XmlManager::openContainer
Copyright (c) 1996-2009 Oracle. All rights reserved.