Class ContainerConfig

Container configuration settings.

Inheritance

System.Object

ContainerConfig

Implements

System.IDisposable

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: Figaro

Assembly: Figaro.dll

Syntax

public class ContainerConfig : IDisposable

Remarks

The ContainerConfig class encapsulates all the properties with which a container can be created or opened. It is passed as an argument to CreateContainer(String) and OpenContainer(String) as well as other methods that previously accepted flag parameters.

ContainerConfig conforms to the properties found in the ContainerElement found in the Figaro.Configuration namespace. This allows for fast, factory-style Container creation while minimizing the amount of parameters needed for Container creation and open operations.

implementnotes

If a ContainerConfig object is passed to an XmlManager object where a parameter in the method signature is also found in the ContainerConfig properties, the parameter will be used and the ContainerConfig property will be ignored.

Constructors

View Source

ContainerConfig()

Initializes a new instance of the ContainerConfig class.

Declaration

public ContainerConfig()

Properties

View Source

AllowCreate

Gets or sets a value indicating whether a container can be created during a call to OpenContainer(String) if it does not already exist. The default value is false.

Declaration

public bool AllowCreate { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to false an exception will be thrown when OpenContainer(String) is called for a container that does not exist.

View Source

AllowValidation

Gets or sets a value indicating whether to validate XML if it refers to a DTD or XML Schema.

Declaration

public bool AllowValidation { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If enabled validation is only performed on document insertion or update and not when modified via XQuery Update expressions. The default value is false and is used by container open.

Set to true to do validation.

View Source

Checksum

Gets or sets a value indicating whether to do checksum verification of pages read into the cache from the backing file store.

Declaration

public bool Checksum { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

Figaro uses the SHA1 Secure Hash Algorithm if encryption is configured and a general hash algorithm if it is not. The default value is false. ///

View Source

CompressionEnabled

Gets or sets a value indicating whether or not to enable container compression.

Declaration

public bool CompressionEnabled { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

Compression is only used by whole document storage containers. Compression can only be set at creation time; afterward, the container must always be open with the same setting.

View Source

ConfigurationName

Gets or sets the container configuration instance name.

Declaration

public string ConfigurationName { get; set; }

Property Value

Type	Description
System.String

Remarks

This property is set and used by the Figaro.Configuration and Figaro.Web.Configuration library objects at creation, and used for reference purposes only. This property is not required and can safely be set to null if ContainerConfig is created programmatically.

View Source

ContainerType

Gets or sets whether the container was built to handle documents or nodes.

Declaration

public XmlContainerType ContainerType { get; set; }

Property Value

Type	Description
XmlContainerType

Remarks

Sets the type of container to be created. The default value is NodeContainer. This value is ignored if the container already exists.

View Source

Encrypted

Gets or sets a value indicating whether to encrypt the database using the cryptographic password specified to SetEncryption(String, Boolean).

Declaration

public bool Encrypted { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

The default setting is false.

View Source

ExclusiveCreate

Gets or sets a value indicating whether to throw an exception if the container is already created.

Declaration

public bool ExclusiveCreate { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true OpenContainer(String) and CreateContainer(String) will throw exceptions if the container already exists and AllowCreate has been set to true.

The default value is false.

View Source

IndexNodes

Gets or sets configuration state for setting up node or document indexing.

Declaration

public ConfigurationState IndexNodes { get; set; }

Property Value

Type	Description
ConfigurationState

Remarks

Sets whether the index targets reference nodes or documents. The default setting is UseDefault. This value is ignored unless the container is being created or re-indexed.

If set to On it 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 NodeContainer.

If set to Off it 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 WholeDocContainer.

If set to Off, then the container type will decide whether nodes or documents are referenced.

View Source

MultiVersion

Gets or sets a value indicating whether to open the container with multi-version currency control (MVCC).

Declaration

public bool MultiVersion { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true then the database will be opened with support for multi-version concurrency control. This will cause updates to the container to follow a copy-on-write protocol which is required to support snapshot isolation.

The MultiVersion flag requires that the container be transactionally protected during its open.

The default value is false.

View Source

NoMMap

Gets or sets a value indicating whether the container will be mapped into process memory.

Declaration

public bool NoMMap { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true then the container will not be mapped into process memory (see the MaxFileMapSize property for further information).

View Source

PageSize

Gets or sets the size, in bytes, of the database pages used to store node and document data.

Declaration

public ushort PageSize { get; set; }

Property Value

Type	Description
System.UInt16

Remarks

The PageSize property gets/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. If no page size is specified the system will create containers with page size 8192 for NodeContainer storage containers and 16384 for WholeDocContainer storage containers.

Page size affects the amount of I/O performed as well as granularity of locking as Figaro performs page-level locking. These needs are often at odds with one another.

The page size cannot be changed once a container has been created. This value is ignored unless the container is being created.

View Source

Path

Gets or sets the container path and file name.

Declaration

public string Path { get; set; }

Property Value

Type	Description
System.String

Remarks

This property can be set using the Figaro.Configuration namespace, or when manually creating a new ContainerConfig instance.

implementnotes

View Source

ReadOnly

Gets or sets a value indicating whether to open the container with read-only access.

Declaration

public bool ReadOnly { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true, the container is opened for reading only.

Any attempt to modify items in the container will fail regardless of the permissions of the underlying files. If set to false then the container can be modified. The default value is false and can only be set to true for existing containers.

View Source

ReadUncommitted

Gets or sets a value indicating whether or not to enable 'dirty' reads.

Declaration

public bool ReadUncommitted { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true then the container will support degree 1 isolation; that is, read operations may return information that has been modified by another transaction but has not yet been committed. This setting should be used rarely if at all. The default value is false.

View Source

SequenceIncrement

Gets or sets the integer increment to be used when pre-allocating document ids for new documents created by PutDocument(String, UpdateContext).

Declaration

public uint SequenceIncrement { get; set; }

Property Value

Type	Description
System.UInt32

Remarks

Every document added to a 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 may eventually cause the container to run out of IDs. Once out of IDs, the container will never again be able to accept new documents. However, document IDs are 64-bit quantities so this is extremely unlikely.

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.

View Source

Statistics

Gets or sets the container structural statistics.

Declaration

public ConfigurationState Statistics { get; set; }

Property Value

Type	Description
ConfigurationState

Remarks

Gets or sets whether the structural statistics are stored in the container. These statistics are used in query optimization. The default setting is UseDefault and the default is to use statistics. This value is ignored unless the container is being created or re-indexed.

Structural statistics information is very useful for cost based query optimization. Containers created with these statistics will take slightly longer to load and update, since the statistics must also be updated. In addition the statistics affect the concurrent behavior in the face of updates.

If the state is set to Off then the container is created without structural statistics. If the state is set to On or UseDefault the container is created with structural statistics.

View Source

Threaded

Gets or sets a value indicating whether the container handle is marked as free-threaded.

Declaration

public bool Threaded { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true, this property causes the container handle to be free-threaded; that is, concurrently usable by multiple threads in the address space. If multiple threads access a container that does not have this property set the results are unpredictable. The default value is false.

View Source

Transactional

Gets or sets a value indicating whether or not to enable container transactions.

Declaration

public bool Transactional { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true it causes the container to use transactions. Even if the environment has been configured for transactions, this property must be used in order to create or open a transactional container. In other words, a transactional environment can support both transactional and non-transactional containers. If the environment has not also been configured for transactions then use of this property when opening a container will result in an exception.

If this property is set an XmlTransaction object can and should be passed to any method that supports it. If a container is transactional and an explicit XmlTransaction object is not passed to a modifying method (e.g. PutDocument(String, UpdateContext)), an exception will occur indicating an XmlTransaction object is required.

The default value for this property is false and it affects containers being created and containers that already exist.

View Source

TransactionNotDurable

Gets or sets a value indicating whether transactions are durable for the specified container.

Declaration

public bool TransactionNotDurable { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If set to true, Figaro 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. The default value is false.

Methods

View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

View Source

Dispose(Boolean)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

protected void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	If disposing equals `true`, the method has been called directly or indirectly by a user's code. Managed and unmanaged resources can be disposed. If disposing equals `false`, the method has been called by the runtime from inside the finalizer and you should not reference other objects. Only unmanaged resources can be disposed.

Implements

System.IDisposable