Berkeley DB Java Edition
version 3.3.87

com.sleepycat.je
Class DatabaseConfig

java.lang.Object
  extended by com.sleepycat.je.DatabaseConfig
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
SecondaryConfig

public class DatabaseConfig
extends Object
implements Cloneable

Specifies the attributes of a database.


Field Summary
static DatabaseConfig DEFAULT
          An instance created using the default constructor is initialized with the system's default settings.
 
Constructor Summary
DatabaseConfig()
          An instance created using the default constructor is initialized with the system's default settings.
 
Method Summary
 DatabaseConfig cloneConfig()
          Returns a copy of this configuration object.
 boolean getAllowCreate()
          Returns true if the Environment.openDatabase method is configured to create the database if it does not already exist.
 Comparator<byte[]> getBtreeComparator()
          Returns the Comparator used for key comparison on this database.
 boolean getBtreeComparatorByClassName()
          Returns true if the btree comparator is set by class name, not by serializable Comparator object
 boolean getDeferredWrite()
          Returns the deferred-write option.
 Comparator<byte[]> getDuplicateComparator()
          Returns the Comparator used for duplicate record comparison on this database.
 boolean getDuplicateComparatorByClassName()
          Returns true if the duplicate comparator is set by class name, not by serializable Comparator object.
 boolean getExclusiveCreate()
          Returns true if the Environment.openDatabase method is configured to fail if the database already exists.
 boolean getKeyPrefixing()
          Returns the key prefixing configuration.
 int getNodeMaxDupTreeEntries()
          Returns the maximum number of children a B+Tree duplicate tree node can have.
 int getNodeMaxEntries()
          Returns the maximum number of children a B+Tree node can have.
 boolean getOverrideBtreeComparator()
          Returns the override setting for the btree comparator.
 boolean getOverrideDuplicateComparator()
          Returns the override setting for the duplicate comparator.
 boolean getReadOnly()
          Returns true if the database is configured in read-only mode.
 boolean getSortedDuplicates()
          Returns true if the database is configured to support sorted duplicate data items.
 boolean getTemporary()
          Returns the temporary database option.
 boolean getTransactional()
          Returns true if the database open is enclosed within a transaction.
 void setAllowCreate(boolean allowCreate)
          Configures the Environment.openDatabase method to create the database if it does not already exist.
 void setBtreeComparator(Class<? extends Comparator<byte[]>> btreeComparatorClass)
          By default, a byte by byte lexicographic comparison is used for btree keys.
 void setBtreeComparator(Comparator<byte[]> btreeComparator)
          By default, a byte by byte lexicographic comparison is used for btree keys.
 void setDeferredWrite(boolean deferredWrite)
          Sets the deferred-write option.
 void setDuplicateComparator(Class<? extends Comparator<byte[]>> duplicateComparatorClass)
          By default, a byte by byte lexicographic comparison is used for duplicate data items in a duplicate set.
 void setDuplicateComparator(Comparator<byte[]> duplicateComparator)
          By default, a byte by byte lexicographic comparison is used for duplicate data items in a duplicate set.
 void setExclusiveCreate(boolean exclusiveCreate)
          Configure the Environment.openDatabase method to fail if the database already exists.
 void setKeyPrefixing(boolean keyPrefixingEnabled)
          Configure the database to support key prefixing.
 void setNodeMaxDupTreeEntries(int nodeMaxDupTreeEntries)
          Configures the Environment.openDatabase method to have a B+Tree duplicate tree fanout of nodeMaxDupTreeEntries.
 void setNodeMaxEntries(int nodeMaxEntries)
          Configures the Environment.openDatabase method to have a B+Tree fanout of nodeMaxEntries.
 void setOverrideBtreeComparator(boolean override)
          Sets to true if the database exists and the btree comparator specified in this configuration object should override the current comparator.
 void setOverrideDuplicateComparator(boolean override)
          Sets to true if the database exists and the duplicate comparator specified in this configuration object should override the current comparator.
 void setReadOnly(boolean readOnly)
          Configures the database in read-only mode.
 void setSortedDuplicates(boolean duplicatesAllowed)
          Configure the database to support sorted, duplicate data items.
 void setTemporary(boolean temporary)
          Sets the temporary database option.
 void setTransactional(boolean transactional)
          Encloses the database open within a transaction.
 String toString()
          Returns the values for each configuration attribute.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT

public static final DatabaseConfig DEFAULT
An instance created using the default constructor is initialized with the system's default settings.

Constructor Detail

DatabaseConfig

public DatabaseConfig()
An instance created using the default constructor is initialized with the system's default settings.

Method Detail

setAllowCreate

public void setAllowCreate(boolean allowCreate)
Configures the Environment.openDatabase method to create the database if it does not already exist.

Parameters:
allowCreate - If true, configure the Environment.openDatabase method to create the database if it does not already exist.

getAllowCreate

public boolean getAllowCreate()
Returns true if the Environment.openDatabase method is configured to create the database if it does not already exist.

This method may be called at any time during the life of the application.

Returns:
True if the Environment.openDatabase method is configured to create the database if it does not already exist.

setExclusiveCreate

public void setExclusiveCreate(boolean exclusiveCreate)
Configure the Environment.openDatabase method to fail if the database already exists.

The exclusiveCreate mode is only meaningful if specified with the allowCreate mode.

Parameters:
exclusiveCreate - If true, configure the Environment.openDatabase method to fail if the database already exists.

getExclusiveCreate

public boolean getExclusiveCreate()
Returns true if the Environment.openDatabase method is configured to fail if the database already exists.

This method may be called at any time during the life of the application.

Returns:
True if the Environment.openDatabase method is configured to fail if the database already exists.

setSortedDuplicates

public void setSortedDuplicates(boolean duplicatesAllowed)
Configure the database to support sorted, duplicate data items.

Insertion when the key of the key/data pair being inserted already exists in the database will be successful. The ordering of duplicates in the database is determined by the duplicate comparison function.

If the application does not specify a duplicate data item comparison function, a default lexical comparison will be used.

If a primary database is to be associated with one or more secondary databases, it may not be configured for duplicates.

Calling this method affects the database, including all threads of control accessing the database.

If the database already exists when the database is opened, any database configuration specified by this method must be the same as the existing database or an error will be returned.

Parameters:
duplicatesAllowed - If true, configure the database to support duplicate data items. A value of false is illegal to this method, that is, once set, the configuration cannot be cleared.

getSortedDuplicates

public boolean getSortedDuplicates()
Returns true if the database is configured to support sorted duplicate data items.

This method may be called at any time during the life of the application.

Returns:
True if the database is configured to support sorted duplicate data items.

getKeyPrefixing

public boolean getKeyPrefixing()
Returns the key prefixing configuration.

Returns:
true if key prefixing has been enabled in this database.

setKeyPrefixing

public void setKeyPrefixing(boolean keyPrefixingEnabled)
Configure the database to support key prefixing. Key prefixing causes the representation of keys in the b-tree internal nodes to be split between the common prefix of all keys and the suffixes. Using this may result in a more space-efficient representation in both the in-memory and on-disk formats, but at some possible performance cost.

Parameters:
keyPrefixingEnabled - If true, enables keyPrefixing for the database.

setTransactional

public void setTransactional(boolean transactional)
Encloses the database open within a transaction.

If the call succeeds, the open operation will be recoverable. If the call fails, no database will have been created.

All future operations on this database, which are not explicitly enclosed in a transaction by the application, will be enclosed in in a transaction within the library.

Parameters:
transactional - If true, enclose the database open within a transaction.

getTransactional

public boolean getTransactional()
Returns true if the database open is enclosed within a transaction.

This method may be called at any time during the life of the application.

Returns:
True if the database open is enclosed within a transaction.

setReadOnly

public void setReadOnly(boolean readOnly)
Configures the database in read-only mode.

Any attempt to modify items in the database will fail, regardless of the actual permissions of any underlying files.

Parameters:
readOnly - If true, configure the database in read-only mode.

getReadOnly

public boolean getReadOnly()
Returns true if the database is configured in read-only mode.

This method may be called at any time during the life of the application.

Returns:
True if the database is configured in read-only mode.

setNodeMaxEntries

public void setNodeMaxEntries(int nodeMaxEntries)
Configures the Environment.openDatabase method to have a B+Tree fanout of nodeMaxEntries.

The nodeMaxEntries parameter is only meaningful if specified with the allowCreate mode.

Parameters:
nodeMaxEntries - The maximum children per B+Tree node.

setNodeMaxDupTreeEntries

public void setNodeMaxDupTreeEntries(int nodeMaxDupTreeEntries)
Configures the Environment.openDatabase method to have a B+Tree duplicate tree fanout of nodeMaxDupTreeEntries.

The nodeMaxDupTreeEntries parameter is only meaningful if specified with the allowCreate mode.

Parameters:
nodeMaxDupTreeEntries - The maximum children per duplicate B+Tree node.

getNodeMaxEntries

public int getNodeMaxEntries()
Returns the maximum number of children a B+Tree node can have.

This method may be called at any time during the life of the application.

Returns:
The maximum number of children a B+Tree node can have.

getNodeMaxDupTreeEntries

public int getNodeMaxDupTreeEntries()
Returns the maximum number of children a B+Tree duplicate tree node can have.

This method may be called at any time during the life of the application.

Returns:
The maximum number of children a B+Tree duplicate tree node can have.

setBtreeComparator

public void setBtreeComparator(Comparator<byte[]> btreeComparator)
By default, a byte by byte lexicographic comparison is used for btree keys. To customize the comparison, supply a different Comparator.

Note that there are two ways to set the comparator: by specifying the class or by specifying a serializable object. This method is used to specify a serializable object. The comparator class must implement java.util.Comparator and must be serializable. JE will serialize the Comparator and deserialize it when subsequently opening the database.

The Comparator.compare() method is passed the byte arrays that are stored in the database. If you know how your data is organized in the byte array, then you can write a comparison routine that directly examines the contents of the arrays. Otherwise, you have to reconstruct your original objects, and then perform the comparison. See the Getting Started Guide for examples.

WARNING: There are several special considerations that must be taken into account when implementing a comparator.

A special type of comparator is a partial comparator, which compares a proper subset (not all bytes) of the key. A partial comparator allows uniquely identifying a record by a partial key value. For example, the key could contain multiple fields but could uniquely identify the record with a single field. The partial comparator could then compare only the single identifying field. A query (Cursor.getSearchKey, for example) could then be performed by passing a partial key that contains only the identifying field.

A partial comparator has limited value when used as a Btree comparator. Instead of using a partial comparator, the non-identifying fields of the key could be placed in the data portion of the key/data pair. This makes the key smaller, which normally provides better performance. A partial comparator is much more useful when used as a duplicate comparator (see setDuplicateComparator).

However, if you do use a partial comparator as a Btree comparator, be aware that you may not configure the database for duplicates (true may not be passed to setSortedDuplicates). In a duplicate set, each key must have the same (identical bytes) key. The internal structure of JE's Btree cannot support duplicates with non-identical keys, and cannot support specifying non-identical keys for addressing the records in a duplicate set.

The comparator for an existing database will not be overridden unless setOverrideBtreeComparator() is set to true.


setBtreeComparator

public void setBtreeComparator(Class<? extends Comparator<byte[]>> btreeComparatorClass)
By default, a byte by byte lexicographic comparison is used for btree keys. To customize the comparison, supply a different Comparator.

Note that there are two ways to set the comparator: by specifying the class or by specifying a serializable object. This method is used to specify a Comparator class. The comparator class must implement java.util.Comparator and must have a public zero-parameter constructor. JE will store the class name and instantiate the Comparator by class name (using Class.forName and newInstance) when subsequently opening the database. Because the Comparator is instantiated using its default constructor, it should not be dependent on other constructor parameters.

The Comparator.compare() method is passed the byte arrays that are stored in the database. If you know how your data is organized in the byte array, then you can write a comparison routine that directly examines the contents of the arrays. Otherwise, you have to reconstruct your original objects, and then perform the comparison. See the Getting Started Guide for examples.

WARNING: There are several special considerations that must be taken into account when implementing a comparator.

A special type of comparator is a partial comparator, which compares a proper subset (not all bytes) of the key. A partial comparator allows uniquely identifying a record by a partial key value. For example, the key could contain multiple fields but could uniquely identify the record with a single field. The partial comparator could then compare only the single identifying field. A query (Cursor.getSearchKey, for example) could then be performed by passing a partial key that contains only the identifying field.

A partial comparator has limited value when used as a Btree comparator. Instead of using a partial comparator, the non-identifying fields of the key could be placed in the data portion of the key/data pair. This makes the key smaller, which normally provides better performance. A partial comparator is much more useful when used as a duplicate comparator (see setDuplicateComparator).

However, if you do use a partial comparator as a Btree comparator, please be aware that you may not configure the database for duplicates (true may not be passed to setSortedDuplicates). In a duplicate set, each key must have the same (identical bytes) key. The internal structure of JE's Btree cannot support duplicates with non-identical keys, and cannot support specifying non-identical keys for addressing the records in a duplicate set.

The comparator for an existing database will not be overridden unless setOverrideBtreeComparator() is set to true.


getBtreeComparator

public Comparator<byte[]> getBtreeComparator()
Returns the Comparator used for key comparison on this database.


getBtreeComparatorByClassName

public boolean getBtreeComparatorByClassName()
Returns true if the btree comparator is set by class name, not by serializable Comparator object

Returns:
true if the comparator is set by class name, not by serializable Comparator object.

setOverrideBtreeComparator

public void setOverrideBtreeComparator(boolean override)
Sets to true if the database exists and the btree comparator specified in this configuration object should override the current comparator.

Parameters:
override - Set to true to override the existing comparator.

getOverrideBtreeComparator

public boolean getOverrideBtreeComparator()
Returns the override setting for the btree comparator.


setDuplicateComparator

public void setDuplicateComparator(Comparator<byte[]> duplicateComparator)
By default, a byte by byte lexicographic comparison is used for duplicate data items in a duplicate set. To customize the comparison, supply a different Comparator.

Note that there are two ways to set the comparator: by specifying the class or by specifying a serializable object. This method is used to specify a serializable object. The comparator class must implement java.util.Comparator and must be serializable. JE will serialize the Comparator and deserialize it when subsequently opening the database.

The Comparator.compare() method is passed the byte arrays that are stored in the database. If you know how your data is organized in the byte array, then you can write a comparison routine that directly examines the contents of the arrays. Otherwise, you have to reconstruct your original objects, and then perform the comparison. See the Getting Started Guide for examples.

WARNING: There are several special considerations that must be taken into account when implementing a comparator.

A special type of comparator is a partial comparator, which is a comparator that compares a proper subset (not all bytes) of the data. A partial comparator allows uniquely identifying a record within a duplicate set by a partial data value. For example, the data could contain multiple fields but could uniquely identify the record with a single field. The partial comparator could then compare only the single identifying field. A query (Cursor.getSearchBoth, for example) could then be performed by passing a partial data value that contains only the identifying field.

When using a partial comparator, it is possible to update the data for a duplicate record, as long as only the non-identifying fields in the data are changed. See Cursor.putCurrent for more information.

The comparator for an existing database will not be overridden unless setOverrideDuplicateComparator() is set to true.


setDuplicateComparator

public void setDuplicateComparator(Class<? extends Comparator<byte[]>> duplicateComparatorClass)
By default, a byte by byte lexicographic comparison is used for duplicate data items in a duplicate set. To customize the comparison, supply a different Comparator.

Note that there are two ways to set the comparator: by specifying the class or by specifying a serializable object. This method is used to specify a Comparator class. The comparator class must implement java.util.Comparator and must have a public zero-parameter constructor. JE will store the class name and instantiate the Comparator by class name (using Class.forName and newInstance) when subsequently opening the database. Because the Comparator is instantiated using its default constructor, it should not be dependent on other constructor parameters.

The Comparator.compare() method is passed the byte arrays that are stored in the database. If you know how your data is organized in the byte array, then you can write a comparison routine that directly examines the contents of the arrays. Otherwise, you have to reconstruct your original objects, and then perform the comparison. See the Getting Started Guide for examples.

WARNING: There are several special considerations that must be taken into account when implementing a comparator.

A special type of comparator is a partial comparator, which is a comparator that compares a proper subset (not all bytes) of the data. A partial comparator allows uniquely identifying a record within a duplicate set by a partial data value. For example, the data could contain multiple fields but could uniquely identify the record with a single field. The partial comparator could then compare only the single identifying field. A query (Cursor.getSearchBoth, for example) could then be performed by passing a partial data value that contains only the identifying field.

When using a partial comparator, it is possible to update the data for a duplicate record, as long as only the non-identifying fields in the data are changed. See Cursor.putCurrent for more information.

The comparator for an existing database will not be overridden unless setOverrideDuplicateComparator() is set to true.


getDuplicateComparator

public Comparator<byte[]> getDuplicateComparator()
Returns the Comparator used for duplicate record comparison on this database.


getDuplicateComparatorByClassName

public boolean getDuplicateComparatorByClassName()
Returns true if the duplicate comparator is set by class name, not by serializable Comparator object.

Returns:
true if the duplicate comparator is set by class name, not by serializable Comparator object.

setOverrideDuplicateComparator

public void setOverrideDuplicateComparator(boolean override)
Sets to true if the database exists and the duplicate comparator specified in this configuration object should override the current comparator.

Parameters:
override - Set to true to override the existing comparator.

getOverrideDuplicateComparator

public boolean getOverrideDuplicateComparator()
Returns the override setting for the duplicate comparator.


setTemporary

public void setTemporary(boolean temporary)
Sets the temporary database option.

Temporary databases operate internally in deferred-write mode to provide reduced disk I/O and increased concurrency. But unlike an ordinary deferred-write database, the information in a temporary database is not durable or persistent.

A temporary database is not flushed to disk when the database is closed or when a checkpoint is performed, and the Database.sync method may not be called. When all handles for a temporary database are closed, the database is automatically removed. If a crash occurs before closing a temporary database, the database will be automatically removed when the environment is re-opened.

Note that although temporary databases can page to disk if the cache is not large enough to hold the databases, they are much more efficient if the database remains in memory. See the JE FAQ on the Oracle Technology Network site for information on how to estimate the cache size needed by a given database.

See the Getting Started Guide, Database chapter for a full description of temporary databases.

Parameters:
temporary - if true, the database will be opened as a temporary database.

getTemporary

public boolean getTemporary()
Returns the temporary database option.

Returns:
boolean if true, the database is temporary.

setDeferredWrite

public void setDeferredWrite(boolean deferredWrite)
Sets the deferred-write option.

Deferred-write databases have reduced disk I/O and improved concurrency. Disk I/O is reduced when data records are frequently modified or deleted. The information in a deferred-write database is not guaranteed to be durable or persistent until Database.close() or Database.sync() is called, or a checkpoint is performed.

After a deferred-write database is closed it may be re-opened as an ordinary transactional or non-transactional database. For example, this can be used to initially load a large data set in deferred-write mode and then switch to transactional mode for subsequent operations.

Note that although deferred-write databases can page to disk if the cache is not large enough to hold the databases, they are much more efficient if the database remains in memory. See the JE FAQ on the Oracle Technology Network site for information on how to estimate the cache size needed by a given database.

See the Getting Started Guide, Database chapter for a full description of deferred-write databases.

Parameters:
deferredWrite - if true, the database will be opened as a deferred-write database.

getDeferredWrite

public boolean getDeferredWrite()
Returns the deferred-write option.

Returns:
boolean if true, deferred-write is enabled.

cloneConfig

public DatabaseConfig cloneConfig()
Returns a copy of this configuration object.


toString

public String toString()
Returns the values for each configuration attribute.

Overrides:
toString in class Object
Returns:
the values for each configuration attribute.

Berkeley DB Java Edition
version 3.3.87

Copyright (c) 2004,2008 Oracle. All rights reserved.