#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)
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.
To create and open a new container, either use XmlManager::createContainer, or set
XmlContainerConfig::setAllowCreate to true for the
flags or config
parameter on this method.
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.
There are two basic forms of this method: one that accepts an XmlContainerConfig object, and a simpler form that opens a default container.
#include <DbXml.hpp>
XmlContainer XmlManager::openContainer(const std::string &name)
XmlContainer XmlManager::openContainer(
XmlTransaction &txn, const std::string &name)
Opens the container, using only default values for all
configuration options. 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 are:
The XmlTransaction object to use for this container open.
The container's name. The container is located relative to the underlying environment's home directory (see the XmlManager class description for more information) unless an absolute path is used for the name; in that case the container is exists in the location identified by the path.
#include <DbXml.hpp>
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)
Opens a container using the supplied XmlContainerConfig object. If you are creating the container with this method, you can provide a container type and a mode value.
Unless XmlContainerConfig::setAllowCreate was set to
true and assigned using either the
flags parameter or the
XmlManager::setDefaultContainerConfig method, the container
must have previously been created or an exception is thrown.
Parameters are:
The XmlTransaction object to use for this container open.
The container's name. The container is located relative to the underlying environment's home directory (see the XmlManager class description for more information) unless an absolute path is used for the name; in that case the container is exists in the location identified by the path.
The type of container to create. This parameter is relevant
only if you have set XmlContainerConfig::setAllowCreate to
true.
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.
This 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. This 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. This flag requires that the container be transactionally protected during its open.
DB_NOMMAP
Do not map this container into process memory (see the
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
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.
On Windows systems, mode is always ignored.
Otherwise, this parameter is relevant
only if you have set XmlContainerConfig::setAllowCreate to
true.
On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX)
environments, files 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, DB XML will use a
default mode of readable and writable by both owner and
group.
The XmlManager::openContainer method
may fail and throw
XmlException
, encapsulating one of the
following non-zero errors:
The container name that you provided does not exist, and
you did not allow the container to be automatically created
by setting XmlContainerConfig::setAllowCreate to
true.