Berkeley DB Java Edition version 3.2.76

## com.sleepycat.persist
Class EntityStore

    java.lang.Object
      com.sleepycat.persist.EntityStore

    public class EntityStore

extends Object

A store for managing persistent entity objects.

`EntityStore` objects are thread-safe. Multiple threads may safely call the methods of a shared `EntityStore` object.

See the package summary example for an example of using an `EntityStore`.

Before creating an `EntityStore` you must create an `Environment` object using the Berkeley DB engine API. The environment may contain any number of entity stores and their associated databases, as well as other databases not associated with an entity store.

An entity store is based on an `EntityModel`: a data model which defines persistent classes (entity classes), primary keys, secondary keys, and relationships between entities. A primary index is created for each entity class. An associated secondary index is created for each secondary key. The `Entity`, `PrimaryKey` and `SecondaryKey` annotations may be used to define entities and keys.

To use an `EntityStore`, first obtain `PrimaryIndex` and `SecondaryIndex` objects by calling `getPrimaryIndex` and `getSecondaryIndex`. Then use these indices to store and access entity records by key.

Although not normally needed, you can also use the entity store along with the `Base API`. Methods in the `PrimaryIndex` and `SecondaryIndex` classes may be used to obtain databases and bindings. The databases may be used directly for accessing entity records. The bindings should be called explicitly to translate between `DatabaseEntry` objects and entity model objects.

Each primary and secondary index is associated internally with a `Database`. With any of the above mentioned use cases, methods are provided that may be used for database performance tuning. The `setPrimaryConfig` and `setSecondaryConfig` methods may be called anytime before a database is opened via `getPrimaryIndex` or `getSecondaryIndex`. The `setSequenceConfig` method may be called anytime before `getSequence` is called or `getPrimaryIndex` is called for a primary index associated with that sequence.

### Database Names

The database names of primary and secondary indices are designed to be unique within the environment and identifiable for debugging and use with tools such as `DbDump` and `DbLoad`.

The syntax of a primary index database name is:

       persist#STORE_NAME#ENTITY_CLASS

Where STORE_NAME is the name parameter passed to `EntityStore` and ENTITY_CLASS is name of the class passed to `getPrimaryIndex`.

The syntax of a secondary index database name is:

       persist#STORE_NAME#ENTITY_CLASS#KEY_NAME

Where KEY_NAME is the secondary key name passed to `getSecondaryIndex`.

Although you should never have to construct these names manually, understanding their syntax is useful for several reasons:

- Exception messages sometimes contain the database name, from which you can identify the entity class and secondary key.
- If you create other databases in the same environment that are not part of an `EntityStore`, to avoid naming conflicts the other database names should not begin with `"persist#"`.
- If you are using `DbDump` or `DbLoad` to perform a backup or copy databases between environments, knowing the database names can be useful. Normally you will dump or load all database names starting with `"persist#STORE_NAME#"`.

If you are copying all databases in a store as mentioned in the last point above, there is one further consideration. There are two internal databases that must be kept with the other databases in the store in order for the store to be used. These contain the data formats and sequences for the store:

       persist#STORE_NAME#com.sleepycat.persist.formats

       persist#STORE_NAME#com.sleepycat.persist.sequences

These databases should normally be included with copies of other databases in the store. They should not be modified by the application.

Author:
  Mark Hayes

Constructor Summary
`EntityStore(Environment env, String storeName, StoreConfig config)` Opens an entity store in a given environment.

Method Summary
`void` `close()` Closes all databases and sequences that were opened via this store.
`void` `closeClass(Class entityClass)` Closes the primary and secondary databases for the given entity class that were opened via this store.
`EvolveStats` `evolve(EvolveConfig config)` Performs conversion of unevolved objects in order to reduce lazy conversion overhead.
`StoreConfig` `getConfig()` Returns a copy of the entity store configuration.
`Environment` `getEnvironment()` Returns the environment associated with this store.
`EntityModel` `getModel()` Returns the current entity model for this store.
`Mutations` `getMutations()` Returns the set of mutations that were configured when the store was opened, or if none were configured, the set of mutations that were configured and stored previously.
`DatabaseConfig` `getPrimaryConfig(Class entityClass)` Returns the default primary database Berkeley DB engine API configuration for an entity class.

`

`<PK,E> PrimaryIndex<PK,E>`

`

`getPrimaryIndex(Class<PK> primaryKeyClass, Class<E> entityClass)`
Returns the primary index for a given entity class, opening it if necessary.

`SecondaryConfig` `getSecondaryConfig(Class entityClass, String keyName)` Returns the default secondary database Berkeley DB engine API configuration for an entity class and key name.

`

`<SK,PK,E> SecondaryIndex<SK,PK,E>`

`

`getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex, Class<SK> keyClass, String keyName)`
Returns a secondary index for a given primary index and secondary key, opening it if necessary.

`Sequence` `getSequence(String name)` Returns a named sequence for using Berkeley DB engine API directly, opening it if necessary.
`SequenceConfig` `getSequenceConfig(String name)` Returns the default Berkeley DB engine API configuration for a named key sequence.
`String` `getStoreName()` Returns the name of this store.
`static Set<String>` `getStoreNames(Environment env)` Returns the names of all entity stores in the given environment.

`

`<SK,PK,E1,E2 extends E1> SecondaryIndex<SK,PK,E2>`

`

`getSubclassIndex(PrimaryIndex<PK,E1> primaryIndex, Class<E2> entitySubclass, Class<SK> keyClass, String keyName)`
Returns a secondary index for a secondary key in an entity subclass, opening it if necessary.

`void` `setPrimaryConfig(Class entityClass, DatabaseConfig config)` Configures the primary database for an entity class using the Berkeley DB engine API.
`void` `setSecondaryConfig(Class entityClass, String keyName, SecondaryConfig config)` Configures a secondary database for an entity class and key name using the Berkeley DB engine API.
`void` `setSequenceConfig(String name, SequenceConfig config)` Configures a named key sequence using the Berkeley DB engine API.
`void` `sync()` Flushes each modified index to disk that was opened in deferred-write mode.
`void` `truncateClass(Class entityClass)` Deletes all instances of this entity class and its (non-entity) subclasses.
`void` `truncateClass(Transaction txn, Class entityClass)` Deletes all instances of this entity class and its (non-entity) subclasses.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### EntityStore

    public EntityStore(Environment env,
                       String storeName,
                       StoreConfig config)
                throws DatabaseException,
                       IncompatibleClassException

  Opens an entity store in a given environment.

  Parameters:
    `env` - an open Berkeley DB Environment.
    `storeName` - the name of the entity store within the given environment. An empty string is allowed. Named stores may be used to distinguish multiple sets of persistent entities for the same entity classes in a single environment. Underlying database names are prefixed with the store name.
    `config` - the entity store configuration, or null to use default configuration properties.
  Throws:
    `IncompatibleClassException` - if an incompatible class change has been made and mutations are not configured for handling the change. See `Class Evolution` for more information.
    `DatabaseException`

Method Detail

### getEnvironment

    public Environment getEnvironment()

  Returns the environment associated with this store.

  Returns:
    the environment.

### getConfig

    public StoreConfig getConfig()

  Returns a copy of the entity store configuration.

  Returns:
    the config.

### getStoreName

    public String getStoreName()

  Returns the name of this store.

  Returns:
    the name.

### getStoreNames

    public static Set<String> getStoreNames(Environment env)
                                     throws DatabaseException

  Returns the names of all entity stores in the given environment.

  Returns:
    the store names. An empty set is returned if no stores are present.
  Throws:
    `DatabaseException`

### getModel

    public EntityModel getModel()

  Returns the current entity model for this store. The current model is derived from the configured entity model and the live entity class definitions.

  Returns:
    the model.

### getMutations

    public Mutations getMutations()

  Returns the set of mutations that were configured when the store was opened, or if none were configured, the set of mutations that were configured and stored previously.

  Returns:
    the mutations.

### getPrimaryIndex

    public <PK,E> PrimaryIndex<PK,E> getPrimaryIndex(Class<PK> primaryKeyClass,
                                                     Class<E> entityClass)
                                       throws DatabaseException

  Returns the primary index for a given entity class, opening it if necessary.

  If they are not already open, the primary and secondary databases for the entity class are created/opened together in a single internal transaction. When the secondary indices are opened, that can cascade to open other related primary indices.

  Parameters:
    `primaryKeyClass` - the class of the entity's primary key field, or the corresponding primitive wrapper class if the primary key field type is a primitive.
    `entityClass` - the entity class for which to open the primary index.
  Returns:
    the primary index.
  Throws:
    `IllegalArgumentException` - if the entity class or classes referenced by it are not persistent, or the primary key class does not match the entity's primary key field, or if metadata for the entity or primary key is invalid.
    `DatabaseException`

### getSecondaryIndex

    public <SK,PK,E> SecondaryIndex<SK,PK,E> getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex,
                                                               Class<SK> keyClass,
                                                               String keyName)
                                              throws DatabaseException

  Returns a secondary index for a given primary index and secondary key, opening it if necessary.

  NOTE: If the secondary key field is declared in a subclass of the entity class, use `getSubclassIndex(com.sleepycat.persist.PrimaryIndex<PK, E1>, java.lang.Class<E2>, java.lang.Class<SK>, java.lang.String)` instead.

  If a `SecondaryKey.relatedEntity()` is used and the primary index for the related entity is not already open, it will be opened by this method. That will, in turn, open its secondary indices, which can casade to open other primary indices.

  Parameters:
    `primaryIndex` - the primary index associated with the returned secondary index. The entity class of the primary index, or one of its superclasses, must contain a secondary key with the given secondary key class and key name.
    `keyClass` - the class of the secondary key field, or the corresponding primitive wrapper class if the secondary key field type is a primitive.
    `keyName` - the name of the secondary key field, or the `SecondaryKey.name()` if this name annotation property was specified.
  Returns:
    the secondary index.
  Throws:
    `IllegalArgumentException` - if the entity class or one of its superclasses does not contain a key field of the given key class and key name, or if the metadata for the secondary key is invalid.
    `DatabaseException`

### getSubclassIndex

    public <SK,PK,E1,E2 extends E1> SecondaryIndex<SK,PK,E2> getSubclassIndex(PrimaryIndex<PK,E1> primaryIndex,
                                                                              Class<E2> entitySubclass,
                                                                              Class<SK> keyClass,
                                                                              String keyName)
                                                         throws DatabaseException

  Returns a secondary index for a secondary key in an entity subclass, opening it if necessary.

  If a `SecondaryKey.relatedEntity()` is used and the primary index for the related entity is not already open, it will be opened by this method. That will, in turn, open its secondary indices, which can casade to open other primary indices.

  Parameters:
    `primaryIndex` - the primary index associated with the returned secondary index. The entity class of the primary index, or one of its superclasses, must contain a secondary key with the given secondary key class and key name.
    `entitySubclass` - a subclass of the entity class for the primary index. The entity subclass must contain a secondary key with the given secondary key class and key name.
    `keyClass` - the class of the secondary key field, or the corresponding primitive wrapper class if the secondary key field type is a primitive.
    `keyName` - the name of the secondary key field, or the `SecondaryKey.name()` if this name annotation property was specified.
  Returns:
    the secondary index.
  Throws:
    `IllegalArgumentException` - if the given entity subclass does not contain a key field of the given key class and key name, or if the metadata for the secondary key is invalid.
    `DatabaseException`

### evolve

    public EvolveStats evolve(EvolveConfig config)
                       throws DatabaseException

  Performs conversion of unevolved objects in order to reduce lazy conversion overhead. Evolution may be performed concurrently with normal access to the store.

  Conversion is performed one entity class at a time. An entity class is converted only if it has `Mutations` associated with it via `StoreConfig.setMutations`.

  Conversion of an entity class is performed by reading each entity, converting it if necessary, and updating it if conversion was performed. When all instances of an entity class are converted, references to the appropriate `Mutations` are deleted. Therefore, if this method is called twice successfully without changing class definitions, the second call will do nothing.

  Throws:
    `DatabaseException`
  See Also:
    `Class Evolution`

### truncateClass

    public void truncateClass(Class entityClass)
                       throws DatabaseException

  Deletes all instances of this entity class and its (non-entity) subclasses.

  This is the equivalent of `Environment.truncateDatabase`. The primary and secondary databases associated with the entity class must not be open except by this store, since database truncation is only possible when the database is not open. The databases to be truncated will be closed before performing this operation, if they were previously opened by this store.

  Auto-commit is used implicitly if the store is transactional.

  Parameters:
    `entityClass` - the entity class whose instances are to be deleted.
  Throws:
    `DatabaseException`

### truncateClass

    public void truncateClass(Transaction txn,
                              Class entityClass)
                       throws DatabaseException

  Deletes all instances of this entity class and its (non-entity) subclasses.

  This is the equivalent of `Environment.truncateDatabase`. The primary and secondary databases associated with the entity class must not be open except by this store, since database truncation is only possible when the database is not open. The databases to be truncated will be closed before performing this operation, if they were previously opened by this store.

  Parameters:
    `txn` - the transaction used to protect this operation, null to use auto-commit, or null if the store is non-transactional.
    `entityClass` - the entity class whose instances are to be deleted.
  Throws:
    `DatabaseException`

### sync

    public void sync()
              throws DatabaseException

  Flushes each modified index to disk that was opened in deferred-write mode.

  All indexes are opened in deferred-write mode if true was passed to `StoreConfig.setDeferredWrite(boolean)` for the store.

  Alternatively, individual databases may be configured for deferred write using `DatabaseConfig.setDeferredWrite(boolean)` along with `getPrimaryConfig(java.lang.Class)` and `setPrimaryConfig(java.lang.Class, com.sleepycat.je.DatabaseConfig)`. Caution should be used when configuring only some databases for deferred-write, since durability will be different for these databases than for other databases in the same store.

  This method is functionally equivalent to calling `Database.sync()` for each deferred-write index Database that is open for this store. However, while `Database.sync()` flushes the log to disk each time it is called, this method flushes the log only once after syncing all databases; this method therefore causes less I/O than calling `Database.sync()` multiple times.

  Instead of calling this method, `Environment.sync()` may be used. The difference is that this method will only flush the databases for this store, while `Environment.sync()` will sync all deferred-write databases currently open for the environment and will also perform a full checkpoint. This method is therefore less expensive than a full sync of the environment.

  Throws:
    `DatabaseException`

### closeClass

    public void closeClass(Class entityClass)
                    throws DatabaseException

  Closes the primary and secondary databases for the given entity class that were opened via this store. The caller must ensure that the primary and secondary indices obtained from this store are no longer in use.

  Parameters:
    `entityClass` - the entity class whose databases are to be closed.
  Throws:
    `DatabaseException`

### close

    public void close()
               throws DatabaseException

  Closes all databases and sequences that were opened via this store. The caller must ensure that no databases opened via this store are in use.

  Throws:
    `DatabaseException`

### getSequence

    public Sequence getSequence(String name)
                         throws DatabaseException

  Returns a named sequence for using Berkeley DB engine API directly, opening it if necessary.

  Parameters:
    `name` - the sequence name, which is normally defined using the `PrimaryKey.sequence()` annotation property.
  Returns:
    the open sequence for the given sequence name.
  Throws:
    `DatabaseException`

### getSequenceConfig

    public SequenceConfig getSequenceConfig(String name)

  Returns the default Berkeley DB engine API configuration for a named key sequence. The returned configuration is as follows. All other properties have default values.
  - The `InitialValue` is one.
  - The `Range` minimum is one.
  - The `CacheSize` is 100.
  - `AutoCommitNoSync` is true.
  - `AllowCreate` is set to true if the store is not `ReadOnly`.

  Parameters:
    `name` - the sequence name, which is normally defined using the `PrimaryKey.sequence()` annotation property.
  Returns:
    the default configuration for the given sequence name.

### setSequenceConfig

    public void setSequenceConfig(String name,
                                  SequenceConfig config)

  Configures a named key sequence using the Berkeley DB engine API.

  To be compatible with the entity model and the Direct Persistence Layer, the configuration should be retrieved using `getSequenceConfig`, modified, and then passed to this method.

  If the range is changed to include the value zero, see `PrimaryKey` for restrictions.

  Parameters:
    `name` - the sequence name, which is normally defined using the `PrimaryKey.sequence()` annotation property.
    `config` - the configuration to use for the given sequence name.
  Throws:
    `IllegalArgumentException` - if the configuration is incompatible with the entity model or the Direct Persistence Layer.
    `IllegalStateException` - if the sequence has already been opened.

### getPrimaryConfig

    public DatabaseConfig getPrimaryConfig(Class entityClass)

  Returns the default primary database Berkeley DB engine API configuration for an entity class. The returned configuration is as follows. All other properties have default values.
  - `Transactional` is set to match `StoreConfig`.
  - `AllowCreate` is set to true if the store is not `ReadOnly`.
  - `ReadOnly` is set to match `StoreConfig`.
  - `DeferredWrite` is set to match `StoreConfig`.
  - `BtreeComparator` is set to an internal class if a key comparator is used.

  Parameters:
    `entityClass` - the entity class identifying the primary database.
  Returns:
    the default configuration for the given entity class.

### setPrimaryConfig

    public void setPrimaryConfig(Class entityClass,
                                 DatabaseConfig config)

  Configures the primary database for an entity class using the Berkeley DB engine API.

  To be compatible with the entity model and the Direct Persistence Layer, the configuration should be retrieved using `getPrimaryConfig`, modified, and then passed to this method. The following configuration properties may not be changed:

  - `SortedDuplicates`
  - `BtreeComparator`

  Parameters:
    `entityClass` - the entity class identifying the primary database.
    `config` - the configuration to use for the given entity class.
  Throws:
    `IllegalArgumentException` - if the configuration is incompatible with the entity model or the Direct Persistence Layer.
    `IllegalStateException` - if the database has already been opened.

### getSecondaryConfig

    public SecondaryConfig getSecondaryConfig(Class entityClass,
                                              String keyName)

  Returns the default secondary database Berkeley DB engine API configuration for an entity class and key name. The returned configuration is as follows. All other properties have default values.
  - `Transactional` is set to match the primary database.
  - `AllowCreate` is set to true if the primary database is not `ReadOnly`.
  - `ReadOnly` is set to match the primary database.
  - `DeferredWrite` is set to match the primary database.
  - `BtreeComparator` is set to an internal class if a key comparator is used.
  - `SortedDuplicates` is set according to `SecondaryKey.relate()`.
  - `AllowPopulate` is set to true when a secondary key is added to an existing primary index.
  - `KeyCreator` or `MultiKeyCreator` is set to an internal instance.
  - `ForeignMultiKeyNullifier` is set to an internal instance if `SecondaryKey.onRelatedEntityDelete()` is `DeleteAction.NULLIFY`.

  Parameters:
    `entityClass` - the entity class containing the given secondary key name.
    `keyName` - the name of the secondary key field, or the `SecondaryKey.name()` if this name annotation property was specified.
  Returns:
    the default configuration for the given secondary key.

### setSecondaryConfig

    public void setSecondaryConfig(Class entityClass,
                                   String keyName,
                                   SecondaryConfig config)

  Configures a secondary database for an entity class and key name using the Berkeley DB engine API.

  To be compatible with the entity model and the Direct Persistence Layer, the configuration should be retrieved using `getSecondaryConfig`, modified, and then passed to this method. The following configuration properties may not be changed:

  - `SortedDuplicates`
  - `BtreeComparator`
  - `DuplicateComparator`
  - `AllowPopulate`
  - `KeyCreator`
  - `MultiKeyCreator`
  - `ForeignKeyNullifier`
  - `ForeignMultiKeyNullifier`
  - `ForeignKeyDeleteAction`
  - `ForeignKeyDatabase`

  Parameters:
    `entityClass` - the entity class containing the given secondary key name.
    `keyName` - the name of the secondary key field, or the `SecondaryKey.name()` if this name annotation property was specified.
    `config` - the configuration to use for the given secondary key.
  Throws:
    `IllegalArgumentException` - if the configuration is incompatible with the entity model or the Direct Persistence Layer.
    `IllegalStateException` - if the database has already been opened.

Berkeley DB Java Edition version 3.2.76

Copyright 1996,2008 Oracle. All rights reserved.