Constructors

XmlManager()

Declaration

XmlManager(FigaroEnv)

Initializes a new instance of the XmlManager class that uses the
provided FigaroEnv instance for the underlying environment. The
subsystems initiated in this environment (for example,
transactions, logging, the memory pool), are the subsystems that are
available to Figaro when operations are performed using
this manager object.

Remarks

See Also

XmlManager(FigaroEnv, ManagerInitOptions)

Initializes a new instance of the XmlManager class. This constructor uses the provided FigaroEnv for the underlying environment. The
Figaro subsystems initiated by this environment (for example, transactions, logging, the
memory pool), are the subsystems that are available to Figaro when operations are performed
using this manager object.

Declaration

Parameters

Remarks

The underlying FigaroEnv is opened with the
Private,
Create, and
InitMemoryBufferPool flags. These flags
allow the underlying environment to be created if it does not already exist. In addition, the memory
pool (in-memory cache) is initialized and available. Finally, the environment is private, which means
that 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 FigaroEnv home is located in either the current
working directory, or in the directory identified by the DB_HOME environment variable.

Remarks

See Also

Properties

ConfigurationName

Gets or sets the manager instance name.

Declaration

public string ConfigurationName { get; set; }

Property Value

Type

Description

System.String

Remarks

This property is currently used by configuration
objects for reference purposes. When an XmlManager instance is created from configuration,
its configuration instance name will be assigned to this property, which in turn can be used to create
ContainerConfig configuration instances.

See Also

DefaultPageSize

Gets or sets the size, in bytes, of the pages used to store documents in the database.

Declaration

public int DefaultPageSize { get; set; }

Property Value

Type

Description

System.Int32

The size, in bytes, of pages used to store documents in the database.

Remarks

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 DefaultPageSize property will only affect containers created after it is set. It
has no effect on existing containers.

See Also

DefaultSequenceIncrement

Declaration

public int DefaultSequenceIncrement { get; set; }

Property Value

Type

Description

System.Int32

Gets or sets the number of pre-allocated document IDs for new documents.

Remarks

Every document added to an Container is assigned an internal unique ID, and BDB XML performs an
internal database operation to obtain these IDs. In order to increase database concurrency and
improve performance of ID allocation, BDB XML pre-allocates a sequence of these numbers. The size
of this sequence is determined by the value specified here. The default ID sequence size is 5.

Be aware that when a container is closed, any unused IDs in the current sequence are lost. Under
some extreme cases, this can result in a container to which documents can no longer be added. For
example, setting this value to a very large number (such as, say, 1 million) and then repeatedly
opening and closing the container while adding a few documents will eventually cause the container
to run out of IDs. Once out of IDs, the container will never again be able to accept new documents. The
maximum number of IDs that a container has available to it is currently 4 billion.

warning

You should almost always leave this value alone. However, if you are loading a large number of
documents to a container all at once, you may find a small performance benefit to setting the sequence
number to a larger value. If you do this, be aware that this value is persistent across container
opens, so you should take care to reset the value to its default once you are done loading
the documents.

See Also

Environment

Declaration

Property Value

Remarks

If a FigaroEnv object is not specified at construction, an internal environment object is created with default
settings. This property gives developers access to either the instantiated or default FigaroEnv object associated with
this particular XmlManager instance.

This property is only available to Concurrent Data Store (CDS) and Transactional Data Store (TDS) editions of the Figaro XML Database.

Declaration

Parameters

Remarks

Every XmlManager instance has an FigaroEnv instance associated with it, even
if developers do not explicitly associate one to it. This method allows developers to specify one or more
data directories for an XmlManager's environment so that developers can reference the
container names in XQuery expressions without the need to explicitly provide the absolute path to the
container(s) being queried.

Returns

CreateContainer(XmlTransaction, String)

Creates and opens a container, returning a handle to a Container object using the specified transaction
handle. If the container already exists at the time this method is called, an exception is thrown.

Parameters

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.

Returns

CreateContainer(String)

Creates and opens a container, returning a handle to a Container object. If the container already
exists at the time this method is called, an exception is thrown.

Declaration

public Container CreateContainer(string name)

Parameters

Type

Name

Description

System.String

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.

Parameters

Returns

Remarks

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 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.

Returns

Remarks

Note that there is no attempt to ensure that the memory 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

Returns

Remarks

If the XmlTransaction object is destroyed or goes out of scope before
Commit() or Abort() are called, the state of the
underlying transaction is left unchanged. This allows a transaction to be controlled
external to its XmlTransaction object.

Remarks

See Also

GetDataDirectories()

Declaration

public ReadOnlyCollection<string> GetDataDirectories()

Returns

Type

Description

System.Collections.ObjectModel.ReadOnlyCollection<System.String>

A list of data directories.

Remarks

Every XmlManager instance has an FigaroEnv instance associated with it, even
if developers do not explicitly associate one to it. This method allows developers to list thedata directories for an XmlManager's environment so that developers know what directories the
XmlManager instance has access to.

Declaration

Parameters

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 opened in the location identified by the path.

Declaration

Parameters

Remarks

This object is used by the internal XML document parser to locate data based on URIs,
or public and system ids. Custom System.Xml.XmlResolver objects can be created
by applications to provide a mechanism to name and retrieve collections, documents,
and XML entities external to the database engine.

Remarks

The container should be backed up prior to using this method, as it destroys existing indices
before re-indexing. If the operation fails, and your container is not backed up, you may lose information.

Use this call to change the type of indexing used for a container between document-level indices
and node-level indices. This method can take a very long time to execute, depending on the size of
the container, and should not be used casually.

Remarks

The container should be backed up prior to using this method, as it destroys existing indices
before re-indexing. If the operation fails, and your container is not backed up, you may lose information.

Use this call to change the type of indexing used for a container between document-level indices
and node-level indices. This method can take a very long time to execute, depending on the size of
the container, and should not be used casually.

Declaration

Parameters

Remarks

If you created a Container object, you must ensure that you runClose() before attempting
to run this method. You must also ensure no other applications are accessing the container
when attempting this operation. If either condition exists, an exception will occur.
The container must be closed for this operation, or an exception will occur.

Parameters

Remarks

A Berkeley DB upgrade is first performed, and then the Berkeley DB
container is upgraded. If no upgrade is needed, then no changes are made.

warning

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.