Berkeley DB
version 5.3.28

com.sleepycat.persist
Class EntityStore

java.lang.Object
  extended by 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.


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.
<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 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 StoreExistsException,
                   StoreNotFoundException,
                   IncompatibleClassException,
                   DatabaseException
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 - the base class for all BDB exceptions.
StoreExistsException
StoreNotFoundException
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.

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 - the base class for all BDB exceptions.

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, java.lang.Class, java.lang.Class, 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 cascade 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 - the base class for all BDB exceptions.

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 cascade 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 - the base class for all BDB exceptions.

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 - the base class for all BDB exceptions.
See Also:
Class Evolution

truncateClass

public void truncateClass(Class entityClass)
                   throws DatabaseException
Deletes all instances of this entity class and its (non-entity) subclasses.

The primary database for the given entity class will be truncated and all secondary databases will be removed. The primary and secondary databases associated with the entity class must not be open except by this store, since database truncation/removal is only possible when the database is not open.

The primary and secondary databases for the entity class will be closed by this operation and the existing PrimaryIndex and SecondaryIndex objects will be invalidated. To access the indexes, the user must call getPrimaryIndex(java.lang.Class, java.lang.Class) and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex, java.lang.Class, java.lang.String) after this operation is complete.

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

Parameters:
entityClass - the entity class whose instances are to be deleted.
Throws:
DatabaseException - the base class for all BDB exceptions.

truncateClass

public void truncateClass(Transaction txn,
                          Class entityClass)
                   throws DatabaseException
Deletes all instances of this entity class and its (non-entity) subclasses.

The primary database for the given entity class will be truncated and all secondary databases will be removed. The primary and secondary databases associated with the entity class must not be open except by this store, since database truncation/removal is only possible when the database is not open.

The primary and secondary databases for the entity class will be closed by this operation and the existing PrimaryIndex and SecondaryIndex objects will be invalidated. To access the indexes, the user must call getPrimaryIndex(java.lang.Class, java.lang.Class) and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex, java.lang.Class, java.lang.String) after this operation is complete.

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 - the base class for all BDB exceptions.

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 for the entity class are no longer in use.

The primary and secondary databases for the entity class will be closed by this operation and the existing PrimaryIndex and SecondaryIndex objects will be invalidated. To access the indexes, the user must call getPrimaryIndex(java.lang.Class, java.lang.Class) and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex, java.lang.Class, java.lang.String) after this operation is complete.

Parameters:
entityClass - the entity class whose databases are to be closed.
Throws:
DatabaseException - the base class for all BDB exceptions.

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.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Throws:
DatabaseException - the base class for all BDB exceptions.

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 - the base class for all BDB exceptions.

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.

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. The following configuration properties may not be changed:

In addition, AllowCreate must be the inverse of ReadOnly

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.

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:

In addition, AllowCreate must be the inverse of ReadOnly

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.

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:

In addition, AllowCreate must be the inverse of ReadOnly

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
version 5.3.28

Copyright (c) 1996, 2013 Oracle and/or its affiliates. All rights reserved.