com.sleepycat.persist

Class SubIndex<PK,E>

java.lang.Object

com.sleepycat.persist.SubIndex<PK,E>

All Implemented Interfaces:

EntityIndex<PK,E>

class SubIndex<PK,E>
extends java.lang.Object
implements EntityIndex<PK,E>

The EntityIndex returned by SecondaryIndex.subIndex. A SubIndex, in JE internal terms, is a duplicates btree for a single key in the main btree. From the user's viewpoint, the keys are primary keys. This class implements that viewpoint. In general, getSearchBoth and getSearchBothRange are used where in a normal index getSearchKey and getSearchRange would be used. The main tree key is always implied, not passed as a parameter.

Author:

Mark Hayes

Constructor Summary

Constructors

Constructor and Description
SubIndex(SecondaryIndex<SK,PK,E> secIndex, EntityBinding entityBinding, SK key)

Method Summary

Modifier and Type	Method and Description
boolean	contains(PK key) Checks for existence of a key in this index.
boolean	contains(Transaction txn, PK key, LockMode lockMode) Checks for existence of a key in this index.
long	count() Returns a non-transactional count of the entities in this index.
boolean	delete(PK key) Deletes all entities with a given index key.
boolean	delete(Transaction txn, PK key) Deletes all entities with a given index key.
EntityCursor<E>	entities() Opens a cursor for traversing all entities in this index.
EntityCursor<E>	entities(PK fromKey, boolean fromInclusive, PK toKey, boolean toInclusive) Opens a cursor for traversing entities in a key range.
EntityCursor<E>	entities(Transaction txn, CursorConfig config) Opens a cursor for traversing all entities in this index.
EntityCursor<E>	entities(Transaction txn, PK fromKey, boolean fromInclusive, PK toKey, boolean toInclusive, CursorConfig config) Opens a cursor for traversing entities in a key range.
E	get(PK key) Gets an entity via a key of this index.
E	get(Transaction txn, PK key, LockMode lockMode) Gets an entity via a key of this index.
EntityCursor<PK>	keys() Opens a cursor for traversing all keys in this index.
EntityCursor<PK>	keys(PK fromKey, boolean fromInclusive, PK toKey, boolean toInclusive) Opens a cursor for traversing keys in a key range.
EntityCursor<PK>	keys(Transaction txn, CursorConfig config) Opens a cursor for traversing all keys in this index.
EntityCursor<PK>	keys(Transaction txn, PK fromKey, boolean fromInclusive, PK toKey, boolean toInclusive, CursorConfig config) Opens a cursor for traversing keys in a key range.
java.util.Map<PK,E>	map() Returns a standard Java map based on this entity index.
java.util.SortedMap<PK,E>	sortedMap() Returns a standard Java sorted map based on this entity index.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SubIndex

SubIndex(SecondaryIndex<SK,PK,E> secIndex,
         EntityBinding entityBinding,
         SK key)
  throws DatabaseException

Throws:

DatabaseException

Method Detail

contains

public boolean contains(PK key)
                 throws DatabaseException

Description copied from interface: EntityIndex

Checks for existence of a key in this index.

The operation will not be transaction protected, and LockMode.DEFAULT is used implicitly.

READ_UNCOMMITTED can be used with this method to reduce I/O, since the record data item will not be read. This is the same benefit as described in Key Cursor Optimization with READ_UNCOMMITTED

Specified by:

contains in interface EntityIndex<PK,E>

Parameters:

key - the key to search for.

Returns:

whether the key exists in the index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

contains

public boolean contains(Transaction txn,
                        PK key,
                        LockMode lockMode)
                 throws DatabaseException

Description copied from interface: EntityIndex

Checks for existence of a key in this index.

READ_UNCOMMITTED can be used with this method to reduce I/O, since the record data item will not be read. This is the same benefit as described in Key Cursor Optimization with READ_UNCOMMITTED

Specified by:

contains in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect this operation, or null if the operation should not be transaction protected.

key - the key to search for.

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

whether the key exists in the index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

get

public E get(PK key)
      throws DatabaseException

Description copied from interface: EntityIndex

Gets an entity via a key of this index.

The operation will not be transaction protected, and LockMode.DEFAULT is used implicitly.

Specified by:

get in interface EntityIndex<PK,E>

Parameters:

key - the key to search for.

Returns:

the value mapped to the given key, or null if the key is not present in the index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

get

public E get(Transaction txn,
             PK key,
             LockMode lockMode)
      throws DatabaseException

Description copied from interface: EntityIndex

Gets an entity via a key of this index.

Specified by:

get in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect this operation, or null if the operation should not be transaction protected.

key - the key to search for.

lockMode - the lock mode to use for this operation, or null to use LockMode.DEFAULT.

Returns:

the value mapped to the given key, or null if the key is not present in the index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

count

public long count()
           throws DatabaseException

Description copied from interface: EntityIndex

Returns a non-transactional count of the entities in this index.

This operation is faster than obtaining a count by scanning the index manually, and will not perturb the current contents of the cache. However, the count is not guaranteed to be accurate if there are concurrent updates. Note that this method does scan a significant portion of the index and should be considered a fairly expensive operation.

Specified by:

count in interface EntityIndex<PK,E>

Returns:

the number of entities in this index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

delete

public boolean delete(PK key)
               throws DatabaseException

Description copied from interface: EntityIndex

Deletes all entities with a given index key.

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

Specified by:

delete in interface EntityIndex<PK,E>

Parameters:

key - the key to search for.

Returns:

whether any entities were deleted.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

delete

public boolean delete(Transaction txn,
                      PK key)
               throws DatabaseException

Description copied from interface: EntityIndex

Deletes all entities with a given index key.

Specified by:

delete in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect this operation, null to use auto-commit, or null if the store is non-transactional.

key - the key to search for.

Returns:

whether any entities were deleted.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException - the base class for all BDB exceptions.

keys

public EntityCursor<PK> keys()
                      throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing all keys in this index.

The operations performed with the cursor will not be transaction protected, and CursorConfig.DEFAULT is used implicitly. If the store is transactional, the cursor may not be used to update or delete entities.

Note that READ_UNCOMMITTED can be used with a key cursor to reduce I/O, potentially providing significant performance benefits. See Key Cursor Optimization with READ_UNCOMMITTED

Specified by:

keys in interface EntityIndex<PK,E>

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

keys

public EntityCursor<PK> keys(Transaction txn,
                             CursorConfig config)
                      throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing all keys in this index.

Note that READ_UNCOMMITTED can be used with a key cursor to reduce I/O, potentially providing significant performance benefits. See Key Cursor Optimization with READ_UNCOMMITTED

Specified by:

keys in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect all operations performed with the cursor, or null if the operations should not be transaction protected. If the store is non-transactional, null must be specified. For a transactional store the transaction is optional for read-only access and required for read-write access.

config - the cursor configuration that determines the default lock mode used for all cursor operations, or null to implicitly use CursorConfig.DEFAULT.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

entities

public EntityCursor<E> entities()
                         throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing all entities in this index.

The operations performed with the cursor will not be transaction protected, and CursorConfig.DEFAULT is used implicitly. If the store is transactional, the cursor may not be used to update or delete entities.

Specified by:

entities in interface EntityIndex<PK,E>

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

entities

public EntityCursor<E> entities(Transaction txn,
                                CursorConfig config)
                         throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing all entities in this index.

Specified by:

entities in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect all operations performed with the cursor, or null if the operations should not be transaction protected. If the store is non-transactional, null must be specified. For a transactional store the transaction is optional for read-only access and required for read-write access.

config - the cursor configuration that determines the default lock mode used for all cursor operations, or null to implicitly use CursorConfig.DEFAULT.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

keys

public EntityCursor<PK> keys(PK fromKey,
                             boolean fromInclusive,
                             PK toKey,
                             boolean toInclusive)
                      throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing keys in a key range.

The operations performed with the cursor will not be transaction protected, and CursorConfig.DEFAULT is used implicitly. If the store is transactional, the cursor may not be used to update or delete entities.

Note that READ_UNCOMMITTED can be used with a key cursor to reduce I/O, potentially providing significant performance benefits. See Key Cursor Optimization with READ_UNCOMMITTED

Specified by:

keys in interface EntityIndex<PK,E>

Parameters:

fromKey - is the lower bound of the key range, or null if the range has no lower bound.

fromInclusive - is true if keys greater than or equal to fromKey should be included in the key range, or false if only keys greater than fromKey should be included.

toKey - is the upper bound of the key range, or null if the range has no upper bound.

toInclusive - is true if keys less than or equal to toKey should be included in the key range, or false if only keys less than toKey should be included.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

keys

public EntityCursor<PK> keys(Transaction txn,
                             PK fromKey,
                             boolean fromInclusive,
                             PK toKey,
                             boolean toInclusive,
                             CursorConfig config)
                      throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing keys in a key range.

Key Cursor Optimization with READ_UNCOMMITTED

Using a key cursor potentially has a large performance benefit when the READ_UNCOMMITTED isolation mode is used. In this case, if the record data is not in the JE cache, it will not be read from disk. The performance benefit is potentially large because random access disk reads may be reduced. Examples are:

• Scanning all records in key order, when the entity is not needed and READ_UNCOMMITTED isolation is acceptable.
• Skipping over records quickly to perform approximate pagination with READ_UNCOMMITTED isolation.

For other isolation modes (READ_COMMITTED, REPEATABLE_READ and SERIALIZABLE), the performance benefit of a key cursor is not as significant. In this case, the data item must be read into the JE cache if it is not already present, in order to lock the record. The only performance benefit is that the data will not be copied from the JE cache to the application's entry parameter, and will not be unmarshalled into an entity object.

For information on specifying isolation modes, see LockMode, CursorConfig and TransactionConfig.

Specified by:

keys in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect all operations performed with the cursor, or null if the operations should not be transaction protected. If the store is non-transactional, null must be specified. For a transactional store the transaction is optional for read-only access and required for read-write access.

fromKey - is the lower bound of the key range, or null if the range has no lower bound.

fromInclusive - is true if keys greater than or equal to fromKey should be included in the key range, or false if only keys greater than fromKey should be included.

toKey - is the upper bound of the key range, or null if the range has no upper bound.

toInclusive - is true if keys less than or equal to toKey should be included in the key range, or false if only keys less than toKey should be included.

config - the cursor configuration that determines the default lock mode used for all cursor operations, or null to implicitly use CursorConfig.DEFAULT.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

entities

public EntityCursor<E> entities(PK fromKey,
                                boolean fromInclusive,
                                PK toKey,
                                boolean toInclusive)
                         throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing entities in a key range.

The operations performed with the cursor will not be transaction protected, and CursorConfig.DEFAULT is used implicitly. If the store is transactional, the cursor may not be used to update or delete entities.

Specified by:

entities in interface EntityIndex<PK,E>

Parameters:

fromKey - is the lower bound of the key range, or null if the range has no lower bound.

fromInclusive - is true if keys greater than or equal to fromKey should be included in the key range, or false if only keys greater than fromKey should be included.

toKey - is the upper bound of the key range, or null if the range has no upper bound.

toInclusive - is true if keys less than or equal to toKey should be included in the key range, or false if only keys less than toKey should be included.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

entities

public EntityCursor<E> entities(Transaction txn,
                                PK fromKey,
                                boolean fromInclusive,
                                PK toKey,
                                boolean toInclusive,
                                CursorConfig config)
                         throws DatabaseException

Description copied from interface: EntityIndex

Opens a cursor for traversing entities in a key range.

Specified by:

entities in interface EntityIndex<PK,E>

Parameters:

txn - the transaction used to protect all operations performed with the cursor, or null if the operations should not be transaction protected. If the store is non-transactional, null must be specified. For a transactional store the transaction is optional for read-only access and required for read-write access.

fromKey - is the lower bound of the key range, or null if the range has no lower bound.

fromInclusive - is true if keys greater than or equal to fromKey should be included in the key range, or false if only keys greater than fromKey should be included.

toKey - is the upper bound of the key range, or null if the range has no upper bound.

toInclusive - is true if keys less than or equal to toKey should be included in the key range, or false if only keys less than toKey should be included.

config - the cursor configuration that determines the default lock mode used for all cursor operations, or null to implicitly use CursorConfig.DEFAULT.

Returns:

the cursor.

Throws:

DatabaseException - the base class for all BDB exceptions.

map

public java.util.Map<PK,E> map()

Description copied from interface: EntityIndex

Returns a standard Java map based on this entity index. The StoredMap returned is defined by the Collections API. Stored collections conform to the standard Java collections framework interface.

Specified by:

map in interface EntityIndex<PK,E>

Returns:

the map.

sortedMap

public java.util.SortedMap<PK,E> sortedMap()

Description copied from interface: EntityIndex

Returns a standard Java sorted map based on this entity index. The StoredSortedMap returned is defined by the Collections API. Stored collections conform to the standard Java collections framework interface.

Specified by:

sortedMap in interface EntityIndex<PK,E>

Returns:

the map.