|
Berkeley DB version 5.3.21 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sleepycat.persist.EntityStore
public class EntityStore
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. |
|
|
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. |
|
|
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. |
|
|
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 |
---|
public EntityStore(Environment env, String storeName, StoreConfig config) throws StoreExistsException, StoreNotFoundException, IncompatibleClassException, DatabaseException
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.
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 |
---|
public Environment getEnvironment()
public StoreConfig getConfig()
public String getStoreName()
public EntityModel getModel()
public Mutations getMutations()
public <PK,E> PrimaryIndex<PK,E> getPrimaryIndex(Class<PK> primaryKeyClass, Class<E> entityClass) throws DatabaseException
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.
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.
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.public <SK,PK,E> SecondaryIndex<SK,PK,E> getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex, Class<SK> keyClass, String keyName) throws DatabaseException
NOTE: If the secondary key field is declared in a subclass
of the entity class, use getSubclassIndex(com.sleepycat.persist.PrimaryIndex
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.
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.
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.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
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.
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.
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.public EvolveStats evolve(EvolveConfig config) throws DatabaseException
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.
DatabaseException
- the base class for all BDB exceptions.Class Evolution
public void truncateClass(Class entityClass) throws DatabaseException
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
and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex
after this operation is complete.
Auto-commit is used implicitly if the store is transactional.
entityClass
- the entity class whose instances are to be deleted.
DatabaseException
- the base class for all BDB exceptions.public void truncateClass(Transaction txn, Class entityClass) throws DatabaseException
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
and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex
after this operation is complete.
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.
DatabaseException
- the base class for all BDB exceptions.public void closeClass(Class entityClass) throws DatabaseException
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
and getSecondaryIndex(com.sleepycat.persist.PrimaryIndex
after this operation is complete.
entityClass
- the entity class whose databases are to be closed.
DatabaseException
- the base class for all BDB exceptions.public void close() throws DatabaseException
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.
DatabaseException
- the base class for all BDB exceptions.public Sequence getSequence(String name) throws DatabaseException
name
- the sequence name, which is normally defined using the
PrimaryKey.sequence()
annotation property.
DatabaseException
- the base class for all BDB exceptions.public SequenceConfig getSequenceConfig(String name)
InitialValue
is one.Range
minimum is one.CacheSize
is 100.AutoCommitNoSync
is
true.AllowCreate
is set to the
inverse of the store ReadOnly
.
setting.
name
- the sequence name, which is normally defined using the
PrimaryKey.sequence()
annotation property.
public void setSequenceConfig(String name, SequenceConfig config)
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.
name
- the sequence name, which is normally defined using the
PrimaryKey.sequence()
annotation property.config
- the configuration to use for the given sequence name.
IllegalArgumentException
- if the configuration is incompatible
with the entity model or the Direct Persistence Layer.
IllegalStateException
- if the sequence has already been opened.public DatabaseConfig getPrimaryConfig(Class entityClass)
Transactional
is set to
match StoreConfig
.AllowCreate
is set to the
inverse of the store ReadOnly
.
setting.ReadOnly
is set to match
StoreConfig
.BtreeComparator
is set to
an internal class if a key comparator is used.
entityClass
- the entity class identifying the primary database.
public void setPrimaryConfig(Class entityClass, DatabaseConfig config)
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
entityClass
- the entity class identifying the primary database.config
- the configuration to use for the given entity class.
IllegalArgumentException
- if the configuration is incompatible
with the entity model or the Direct Persistence Layer.
IllegalStateException
- if the database has already been opened.public SecondaryConfig getSecondaryConfig(Class entityClass, String keyName)
Transactional
is set to
match the primary database.AllowCreate
is set to the
inverse of the primary database ReadOnly
setting.ReadOnly
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
.
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.
public void setSecondaryConfig(Class entityClass, String keyName, SecondaryConfig config)
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:
ExclusiveCreate
SortedDuplicates
BtreeComparator
DuplicateComparator
AllowPopulate
KeyCreator
MultiKeyCreator
ForeignKeyNullifier
ForeignMultiKeyNullifier
ForeignKeyDeleteAction
ForeignKeyDatabase
In addition, AllowCreate
must be
the inverse of ReadOnly
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.
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.21 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |