|
|||||||||
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.
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:
EntityStore
, to avoid naming conflicts the other
database names should not begin with "persist#"
.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.
Constructor Summary | |
---|---|
EntityStore(Environment env,
java.lang.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(java.lang.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 complete set of active mutations for this store, including mutations configured when this store was opened and those configured and stored previously. |
|
DatabaseConfig |
getPrimaryConfig(java.lang.Class entityClass)
Returns the default primary database Berkeley DB engine API configuration for an entity class. |
|
|
getPrimaryIndex(java.lang.Class<PK> primaryKeyClass,
java.lang.Class<E> entityClass)
Returns the primary index for a given entity class, opening it if necessary. |
|
SecondaryConfig |
getSecondaryConfig(java.lang.Class entityClass,
java.lang.String keyName)
Returns the default secondary database Berkeley DB engine API configuration for an entity class and key name. |
|
|
getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex,
java.lang.Class<SK> keyClass,
java.lang.String keyName)
Returns a secondary index for a given primary index and secondary key, opening it if necessary. |
|
Sequence |
getSequence(java.lang.String name)
Returns a named sequence for using Berkeley DB engine API directly, opening it if necessary. |
|
SequenceConfig |
getSequenceConfig(java.lang.String name)
Returns the default Berkeley DB engine API configuration for a named key sequence. |
|
java.lang.String |
getStoreName()
Returns the name of this store. |
|
static java.util.Set<java.lang.String> |
getStoreNames(Environment env)
Returns the names of all entity stores in the given environment. |
|
void |
setPrimaryConfig(java.lang.Class entityClass,
DatabaseConfig config)
Configures the primary database for an entity class using the Berkeley DB engine API. |
|
void |
setSecondaryConfig(java.lang.Class entityClass,
java.lang.String keyName,
SecondaryConfig config)
Configures a secondary database for an entity class and key name using the Berkeley DB engine API. |
|
void |
setSequenceConfig(java.lang.String name,
SequenceConfig config)
Configures a named key sequence using the Berkeley DB engine API. |
|
void |
truncateClass(java.lang.Class entityClass)
Deletes all instances of this entity class and its (non-entity) subclasses. |
|
void |
truncateClass(Transaction txn,
java.lang.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, java.lang.String storeName, StoreConfig config) throws 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
Mutations
for more information.
DatabaseException
Method Detail |
---|
public Environment getEnvironment()
public StoreConfig getConfig()
public java.lang.String getStoreName()
public static java.util.Set<java.lang.String> getStoreNames(Environment env) throws DatabaseException
DatabaseException
public EntityModel getModel()
public Mutations getMutations()
public <PK,E> PrimaryIndex<PK,E> getPrimaryIndex(java.lang.Class<PK> primaryKeyClass, java.lang.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.
java.lang.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
public <SK,PK,E> SecondaryIndex<SK,PK,E> getSecondaryIndex(PrimaryIndex<PK,E> primaryIndex, java.lang.Class<SK> keyClass, java.lang.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
casade to open other primary indices.
primaryIndex
- the primary index associated with the returned
secondary index. The primary index must be for an entity class
containing 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.
java.lang.IllegalArgumentException
- if the given key class or key name is
does not match a secondary key of the entity class of the given primary
index, or if metadata for the secondary key is invalid.
DatabaseException
public EvolveStats evolve(EvolveConfig config) throws DatabaseException
Mutations
for more information
on class evolution.
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, the appropriate
Mutations
are deleted. Therefore, if this method is called
twice successfully, the second call will do nothing.
DatabaseException
public void truncateClass(java.lang.Class entityClass) throws DatabaseException
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.
entityClass
- the entity class whose instances are to be deleted.
DatabaseException
public void truncateClass(Transaction txn, java.lang.Class entityClass) throws DatabaseException
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.
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
public void closeClass(java.lang.Class entityClass) throws DatabaseException
entityClass
- the entity class whose databases are to be closed.
DatabaseException
public void close() throws DatabaseException
DatabaseException
public Sequence getSequence(java.lang.String name) throws DatabaseException
name
- the sequence name, which is normally defined using the
PrimaryKey.sequence()
annotation property.
DatabaseException
public SequenceConfig getSequenceConfig(java.lang.String name)
InitialValue
is one.Range
minimum is one.CacheSize
is 100.AutoCommitNoSync
is
true.AllowCreate
is set to true
if the store is not ReadOnly
.
name
- the sequence name, which is normally defined using the
PrimaryKey.sequence()
annotation property.
public void setSequenceConfig(java.lang.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.
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.
java.lang.IllegalArgumentException
- if the configuration is incompatible
with the entity model or the Direct Persistence Layer.
java.lang.IllegalStateException
- if the sequence has already been opened.public DatabaseConfig getPrimaryConfig(java.lang.Class entityClass)
Transactional
is set to
match StoreConfig
.AllowCreate
is set to true
if the store is not ReadOnly
.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(java.lang.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:
entityClass
- the entity class identifying the primary database.config
- the configuration to use for the given entity class.
java.lang.IllegalArgumentException
- if the configuration is incompatible
with the entity model or the Direct Persistence Layer.
java.lang.IllegalStateException
- if the database has already been opened.public SecondaryConfig getSecondaryConfig(java.lang.Class entityClass, java.lang.String keyName)
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.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(java.lang.Class entityClass, java.lang.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:
SortedDuplicates
BtreeComparator
DuplicateComparator
AllowPopulate
KeyCreator
MultiKeyCreator
ForeignKeyNullifier
ForeignMultiKeyNullifier
ForeignKeyDeleteAction
ForeignKeyDatabase
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.
java.lang.IllegalArgumentException
- if the configuration is incompatible
with the entity model or the Direct Persistence Layer.
java.lang.IllegalStateException
- if the database has already been opened.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |