| The interface for accessing keys and entities via a primary or secondary
index.
EntityIndex objects are thread-safe. Multiple threads may safely
call the methods of a shared
EntityIndex object.
An index is conceptually a map. {key:value} mappings are
stored in the index and accessed by key. In fact, for interoperability with
other libraries that use the standard Java
Map or
SortedMap interfaces, an
EntityIndex may be accessed via these standard
interfaces by calling the
EntityIndex.map or
EntityIndex.sortedMap methods.
EntityIndex is an interface that is implemented by several
classes in this package for different purposes. Depending on the context,
the key type (K) and value type (V) of the index take on different meanings.
The different classes that implement
EntityIndex are:
In all cases, the index key type (K) is a primary or secondary key class.
The index value type (V) is an entity class in all cases except for a
SecondaryIndex.keysIndex , when it is a primary key class.
In the following example, a
Employee entity with a
MANY_TO_ONE secondary key is defined.
class Employee {
long id;
String department;
String name;
private Employee() {}
}
Consider that we have stored the entities below:
| Entities |
|---|
| ID | Department | Name |
|---|
| 1 | Engineering | Jane Smith |
| 2 | Sales | Joan Smith |
| 3 | Engineering | John Smith |
| 4 | Sales | Jim Smith |
PrimaryIndex maps primary keys to entities:
PrimaryIndex primaryIndex =
store.getPrimaryIndex(Long.class, Employee.class);
| primaryIndex |
|---|
| Primary Key | Entity |
|---|
| 1 | 1 | Engineering | Jane Smith |
| 2 | 2 | Sales | Joan Smith |
| 3 | 3 | Engineering | John Smith |
| 4 | 4 | Sales | Jim Smith |
SecondaryIndex maps secondary keys to entities:
SecondaryIndex secondaryIndex =
store.getSecondaryIndex(primaryIndex, String.class, "department");
| secondaryIndex |
|---|
| Secondary Key | Entity |
|---|
| Engineering | 1 | Engineering | Jane Smith |
| Engineering | 3 | Engineering | John Smith |
| Sales | 2 | Sales | Joan Smith |
| Sales | 4 | Sales | Jim Smith |
SecondaryIndex.keysIndex maps secondary keys to primary
keys:
EntityIndex keysIndex = secondaryIndex.keysIndex();
| keysIndex |
|---|
| Secondary Key | Primary Key |
|---|
| Engineering | 1 |
| Engineering | 3 |
| Sales | 2 |
| Sales | 4 |
SecondaryIndex.subIndex maps primary keys to entities, for the
subset of entities having a specified secondary key:
EntityIndex subIndex = secondaryIndex.subIndex("Engineering");
| subIndex |
|---|
| Primary Key | Entity |
|---|
| 1 | 1 | Engineering | Jane Smith |
| 3 | 3 | Engineering | John Smith |
Accessing the Index
An
EntityIndex provides a variety of methods for retrieving
entities from an index. It also provides methods for deleting entities.
However, it does not provide methods for inserting and updating. To insert
and update entities, use the
PrimaryIndex.put family of methods in
the
PrimaryIndex class.
An
EntityIndex supports two mechanisms for retrieving
entities:
- The
EntityIndex.get mehod returns a single value for a given key. If there
are multiple values with the same secondary key (duplicates), it returns the
first entity in the duplicate set.
- An
EntityCursor can be obtained using the
EntityIndex.keys and
EntityIndex.entities family of methods. A cursor can be used to return all
values in the index, including duplicates. A cursor can also be used to
return values within a specified range of keys.
Using the example entities above, calling
EntityIndex.get on the primary
index will always return the employee with the given ID, or null if no such
ID exists. But calling
EntityIndex.get on the secondary index will retrieve
the first employee in the given department, which may not be very
useful:
Employee emp = primaryIndex.get(1); // Returns by unique ID
emp = secondaryIndex.get("Engineering"); // Returns first in department
Using a cursor, you can iterate through all duplicates in the secondary
index:
EntityCursor cursor = secondaryIndex.entities();
try {
for (Employee entity : cursor) {
if (entity.department.equals("Engineering")) {
// Do something with the entity...
}
}
} finally {
cursor.close();
}
But for a large database it is much more efficient to iterate over only
those entities with the secondary key you're searching for. This could be
done by restricting a cursor to a range of keys:
EntityCursor cursor =
secondaryIndex.entities("Engineering", true, "Engineering", true);
try {
for (Employee entity : cursor) {
// Do something with the entity...
}
} finally {
cursor.close();
}
However, when you are interested only in the entities with a particular
secondary key value, it is more convenient to use a sub-index:
EntityIndex subIndex = secondaryIndex.subIndex("Engineering");
EntityCursor cursor = subIndex.entities();
try {
for (Employee entity : cursor) {
// Do something with the entity...
}
} finally {
cursor.close();
}
In addition to being more convenient than a cursor range, a sub-index
allows retrieving by primary key:
Employee emp = subIndex.get(1);
When using a sub-index, all operations performed on the sub-index are
restricted to the single key that was specified when the sub-index was
created. For example, the following returns null because employee 2 is not
in the Engineering department and therefore is not part of the
sub-index:
Employee emp = subIndex.get(2);
For more information on using cursors and cursor ranges, see
EntityCursor .
Note that when using an index, keys and values are stored and retrieved
by value not by reference. In other words, if an entity object is stored
and then retrieved, or retrieved twice, each object will be a separate
instance. For example, in the code below the assertion will always
fail.
MyKey key = ...;
MyEntity entity1 = index.get(key);
MyEntity entity2 = index.get(key);
assert entity1 == entity2; // always fails!
Deleting from the Index
Any type of index may be used to delete entities with a specified key by
calling
EntityIndex.delete . The important thing to keep in mind is that
all entities with the specified key are deleted. In a primay index,
at most a single entity is deleted:
primaryIndex.delete(1); // Deletes a single employee by unique ID
But in a secondary index, multiple entities may be deleted:
secondaryIndex.delete("Engineering"); // Deletes all Engineering employees
This begs this question: How can a single entity be deleted without
knowing its primary key? The answer is to use cursors. After locating an
entity using a cursor, the entity can be deleted by calling
EntityCursor.delete .
Transactions
Transactions can be used to provide standard ACID (Atomicity,
Consistency, Integrity and Durability) guarantees when retrieving, storing
and deleting entities. This section provides a brief overview of how to use
transactions with the Direct Persistence Layer. For more information on
using transactions, see Writing
Transactional Applications.
Transactions may be used only with a transactional
EntityStore ,
which is one for which
StoreConfig.setTransactionalStoreConfig.setTransactional(true) has been called. Likewise, a
transactional store may only be used with a transactional
Environment , which is one for which
EnvironmentConfig.setTransactional EnvironmentConfig.setTransactional(true) has been called. For example:
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setTransactional(true);
envConfig.setAllowCreate(true);
Environment env = new Environment(new File("/my/data"), envConfig);
StoreConfig storeConfig = new StoreConfig();
storeConfig.setTransactional(true);
storeConfig.setAllowCreate(true);
EntityStore store = new EntityStore(env, "myStore", storeConfig);
Transactions are represented by
Transaction objects, which are
part of the
com.sleepycat.je Base API . Transactions are created
using the
Environment.beginTransaction Environment.beginTransaction method.
A transaction will include all operations for which the transaction
object is passed as a method argument. All retrieval, storage and deletion
methods have an optional
Transaction parameter for this purpose.
When a transaction is passed to a method that opens a cursor, all retrieval,
storage and deletion operations performed using that cursor will be included
in the transaction.
A transaction may be committed by calling
Transaction.commit or
aborted by calling
Transaction.abort . For example, two employees
may be deleted atomically with a transaction; other words, either both are
deleted or neither is deleted:
Transaction txn = env.beginTransaction(null, null);
try {
primaryIndex.delete(txn, 1);
primaryIndex.delete(txn, 2);
txn.commit();
txn = null;
} finally {
if (txn != null) {
txn.abort();
}
}
WARNING: Transactions must always be committed or aborted to
prevent resource leaks which could lead to the index becoming unusable or
cause an OutOfMemoryError. To ensure that a transaction is
aborted in the face of exceptions, call
Transaction.abort in a
finally block.
For a transactional store, storage and deletion operations are always
transaction protected, whether or not a transaction is explicitly used. A
null transaction argument means to perform the operation using auto-commit,
or the implied thread transaction if an XAEnvironment is being used. A
transaction is automatically started as part of the operation and is
automatically committed if the operation completes successfully. The
transaction is automatically aborted if an exception occurs during the
operation, and the exception is re-thrown to the caller. For example, each
employee is deleted using a an auto-commit transaction below, but it is
possible that employee 1 will be deleted and employee 2 will not be deleted,
if an error or crash occurs while deleting employee 2:
primaryIndex.delete(null, 1);
primaryIndex.delete(null, 2);
When retrieving entities, a null transaction argument means to perform
the operation non-transactionally. The operation is performed outside the
scope of any transaction, without providing transactional ACID guarantees.
If an implied thread transaction is present (i.e. if an XAEnvironment is
being used), that transaction is used. When a non-transactional store is
used, transactional ACID guarantees are also not provided.
For non-transactional and auto-commit usage, overloaded signatures for
retrieval, storage and deletion methods are provided to avoid having to pass
a null transaction argument. For example,
EntityIndex.delete may be called
instead of
EntityIndex.delete(Transaction,Object) . For example, the following
code is equivalent to the code above where null was passed for the
transaction:
primaryIndex.delete(1);
primaryIndex.delete(2);
For retrieval methods the overloaded signatures also include an optional
LockMode parameter, and overloaded signatures for opening cursors
include an optional
CursorConfig parameter. These parameters are
described further below in the Locking and Lock Modes section.
Transactions and Cursors
There are two special consideration when using cursors with transactions.
First, for a transactional store, a non-null transaction must be passed to
methods that open a cursor if that cursor will be used to delete or update
entities. Cursors do not perform auto-commit when a null transaction is
explicitly passed or implied by the method signature. For example, the
following code will throw
DatabaseException when the
EntityCursor.delete method is called:
// Does not work with a transactional store!
EntityCursor cursor = primaryIndex.entities();
try {
for (Employee entity : cursor) {
cursor.delete(); // Will throw DatabaseException.
}
} finally {
cursor.close();
}
Instead, the
EntityIndex.entities(Transaction,CursorConfig) signature must
be used and a non-null transaction must be passed:
EntityCursor cursor = primaryIndex.entities(txn, null);
try {
for (Employee entity : cursor) {
cursor.delete();
}
} finally {
cursor.close();
}
The second consideration is that error handling is more complex when
using both transactions and cursors, for the following reasons:
- When an exception occurs, the transaction should be aborted.
- Cursors must be closed whether or not an exception occurs.
- Cursors must be closed before committing or aborting the
transaction.
For example:
Transaction txn = env.beginTransaction(null, null);
EntityCursor cursor = null;
try {
cursor = primaryIndex.entities(txn, null);
for (Employee entity : cursor) {
cursor.delete();
}
cursor.close();
cursor = null;
txn.commit();
txn = null;
} finally {
if (cursor != null) {
cursor.close();
}
if (txn != null) {
txn.abort();
}
}
Locking and Lock Modes
This section provides a brief overview of locking and describes how lock
modes are used with the Direct Persistence Layer. For more information on
locking, see Writing
Transactional Applications.
When using transactions, locks are normally acquired on each entity that
is retrieved or stored. The locks are used to isolate one transaction from
another. Locks are normally released only when the transaction is committed
or aborted.
When not using transactions, locks are also normally acquired on each
entity that is retrieved or stored. However, these locks are released when
the operation is complete. When using cursors, in order to provide
cursor stability locks are held until the cursor is moved to a
different entity or closed.
This default locking behavior provides full transactional ACID guarantees
and cursor stability. However, application performance can sometimes be
improved by compromising these guarantees. As described in Writing
Transactional Applications, the
LockMode and
CursorConfig parameters are two of the mechanisms that can be used to make
compromises.
For example, imagine that you need an approximate count of all entities
matching certain criterion, and it is acceptable for entities to be changed
by other threads or other transactions while performing this query.
LockMode.READ_UNCOMMITTED can be used to perform the retrievals without
acquiring any locks. This reduces memory consumption, does less processing,
and can improve concurrency.
EntityCursor cursor = primaryIndex.entities(txn, null);
try {
Employee entity;
while ((entity = cursor.next(LockMode.READ_UNCOMMITTED)) != null) {
// Examine the entity and accumulate totals...
}
} finally {
cursor.close();
}
The
LockMode parameter specifies locking behavior on a
per-operation basis. If null or
LockMode.DEFAULT is specified, the
default lock mode is used.
It is also possible to specify the default locking behavior for a cursor
using
CursorConfig . The example below is equivalent to the example
above:
CursorConfig config = new CursorConfig();
config.setReadUncommitted(true);
EntityCursor cursor = primaryIndex.entities(txn, config);
try {
Employee entity;
while ((entity = cursor.next()) != null) {
// Examine the entity and accumulate totals...
}
} finally {
cursor.close();
}
The use of other lock modes, cursor configuration, and transaction
configuration are discussed in Writing
Transactional Applications.
Deadlock handling is another important topic discussed in Writing
Transactional Applications. To go along with that material, here we
show a deadlock handling loop in the context of the Direct Persistence
Layer. The example below shows deleting all entities in a primary index in
a single transaction. If a deadlock occurs, the transaction is aborted and
the operation is retried.
int retryCount = 0;
boolean retry = true;
while (retry) {
Transaction txn = env.beginTransaction(null, null);
EntityCursor cursor = null;
try {
cursor = primaryIndex.entities(txn, null);
for (Employee entity : cursor) {
cursor.delete();
}
cursor.close();
cursor = null;
txn.commit();
txn = null;
retry = false;
} catch (DeadlockException e) {
retryCount += 1;
if (retryCount >= MAX_DEADLOCK_RETRIES) {
throw e;
}
} finally {
if (cursor != null) {
cursor.close();
}
if (txn != null) {
txn.abort();
}
}
}
Low Level Access
Each Direct Persistence Layer index is associated with an underlying
Database or
SecondaryDatabase defined in the
com.sleepycat.je Base API . At this level, an index is a Btree managed by
the Berkeley DB Java Edition transactional storage engine. Although you may
never need to work at the
Base API level, keep in mind that some
types of performance tuning can be done by configuring the underlying
databases. See the
EntityStore class for more information on
database and sequence configuration.
If you wish to access an index using the
Base API , you may call
the
PrimaryIndex.getDatabase or
SecondaryIndex.getDatabase method to get the underying database. To translate between entity or key
objects and
DatabaseEntry objects at this level, use the bindings
returned by
PrimaryIndex.getEntityBinding ,
PrimaryIndex.getKeyBinding , and
SecondaryIndex.getKeyBinding .
author:
Mark Hayes |