-PrimaryIndex (Oracle - Berkeley DB Java API) -

java.lang.Object
+
- com.sleepycat.persist.PrimaryIndex<PK,E>
+

All Implemented Interfaces:: EntityIndex<PK,E>

+
+

public class PrimaryIndex<PK,E>
+extends java.lang.Object

The primary index for an entity class and its primary key.

PrimaryIndex objects are thread-safe. Multiple threads may safely call the methods of a shared PrimaryIndex object.

PrimaryIndex implements EntityIndex to map the primary +

PrimaryIndex implements EntityIndex to map the primary key type (PK) to the entity type (E).

The Entity annotation may be used to define an entity class and - the PrimaryKey annotation may be used to define a primary key as +

The Entity annotation may be used to define an entity class and + the PrimaryKey annotation may be used to define a primary key as shown in the following example.

@@ -133,7 +132,7 @@ The primary index for an entity class and its primary key.
      private Employee() {} // For bindings
  }

To obtain the PrimaryIndex for a given entity class, call EntityStore.getPrimaryIndex, passing the +

To obtain the PrimaryIndex for a given entity class, call EntityStore.getPrimaryIndex, passing the primary key class and the entity class. For example:

@@ -147,12 +146,12 @@ The primary index for an entity class and its primary key.
  primary key field has the primitive type long.  When a primitive
  primary key field is used, the corresponding primitive wrapper class is used
  to access the primary index.  For more information on key field types, see
- PrimaryKey.
+ PrimaryKey.
 
  The PrimaryIndex provides the primary storage and access methods
  for the instances of a particular entity class.  Entities are inserted and
  updated in the PrimaryIndex by calling a method in the family of
- put(E) methods.  The put(E) method will insert the entity if no
+ put(E) methods.  The put(E) method will insert the entity if no
  entity with the same primary key already exists.  If an entity with the same
  primary key does exist, it will update the entity and return the existing
  (old) entity.  For example:
@@ -166,9 +165,9 @@ The primary index for an entity class and its primary key.
  oldEntity = primaryIndex.put(new Employee(2, "Joan M. Smith")); // Updates an entity
  assert oldEntity != null;

The putNoReturn(E) method can be used to avoid the overhead of +

The putNoReturn(E) method can be used to avoid the overhead of returning the existing entity, when the existing entity is not important to - the application. The return type of putNoReturn(E) is void. For + the application. The return type of putNoReturn(E) is void. For example:

@@ -176,8 +175,8 @@ The primary index for an entity class and its primary key.
  primaryIndex.putNoReturn(new Employee(2, "Joan Smith"));    // Inserts an entity
  primaryIndex.putNoReturn(new Employee(2, "Joan M. Smith")); // Updates an entity

The putNoOverwrite(E) method can be used to ensure that an existing - entity is not overwritten. putNoOverwrite(E) returns true if the +

The putNoOverwrite(E) method can be used to ensure that an existing + entity is not overwritten. putNoOverwrite(E) returns true if the entity was inserted, or false if an existing entity exists and no action was taken. For example:

@@ -194,7 +193,7 @@ The primary index for an entity class and its primary key. given entity class must have a distinct primary key value. Rather than assigning the unique primary key values yourself, a sequence can be used to assign sequential integer values automatically, starting with the - value 1 (one). A sequence is defined using the PrimaryKey.sequence() + value 1 (one). A sequence is defined using the PrimaryKey.sequence() annotation property. For example:

@@ -216,10 +215,10 @@ The primary index for an entity class and its primary key.
  The name of the sequence used above is "ID".  Any name can be used.  If
  the same sequence name is used in more than one entity class, the sequence
  will be shared by those classes, in other words, a single sequence of
- integers will be used for all instances of those classes.  See PrimaryKey.sequence() for more information.
+ integers will be used for all instances of those classes.  See PrimaryKey.sequence() for more information.
 
- Any method in the family of put(E) methods may be used to insert
- entities where the primary key is assigned from a sequence.  When the put(E) method returns, the primary key field of the entity object will be set
+ 
Any method in the family of put(E) methods may be used to insert
+ entities where the primary key is assigned from a sequence.  When the put(E) method returns, the primary key field of the entity object will be set
  to the assigned key value.  For example:
 
  @@ -232,10 +231,10 @@ The primary index for an entity class and its primary key.
  assert employee.id == 2;
 
  This begs the question:  How do you update an existing entity, without
- assigning a new primary key?  The answer is that the put(E) methods
+ assigning a new primary key?  The answer is that the put(E) methods
  will only assign a new key from the sequence if the primary key field is
  zero or null (for reference types).  If an entity with a non-zero and
- non-null key field is passed to a put(E) method, any existing entity
+ non-null key field is passed to a put(E) method, any existing entity
  with that primary key value will be updated.  For example:
 
  @@ -250,9 +249,9 @@ The primary index for an entity class and its primary key.
  primaryIndex.putNoReturn(employee);    // Updates an existing entity
  assert employee.id == 2;
 
- Since PrimaryIndex implements the EntityIndex interface,
+ 
Since PrimaryIndex implements the EntityIndex interface,
  it shares the common index methods for retrieving and deleting entities,
- opening cursors and using transactions.  See EntityIndex for more
+ opening cursors and using transactions.  See EntityIndex for more
  information on these topics.
 
  Note that when using an index, keys and values are stored and retrieved
@@ -266,1088 +265,1010 @@ The primary index for an entity class and its primary key.
  index.put(entity1);
  MyEntity entity2 = index.get(key);
  assert entity1 == entity2; // always fails!
-

- -

- +

- - - - - - - - - -

-Constructor Summary
`PrimaryIndex(Database database, - Class<PK> keyClass, - EntryBinding<PK> keyBinding, - Class<E> entityClass, - EntityBinding<E> entityBinding)` - - - Creates a primary index without using an `EntityStore`.

- +

+ + +

Constructor Summary

+ + + + + + + + +

Constructors
Constructor and Description
`PrimaryIndex(Database database, + java.lang.Class<PK> keyClass, + EntryBinding<PK> keyBinding, + java.lang.Class<E> entityClass, + EntityBinding<E> entityBinding)` + Creates a primary index without using an `EntityStore`. +

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-Method Summary
- `boolean`	`contains(K key)` - - - Checks for existence of a key in this index.
- `boolean`	`contains(Transaction txn, - K 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(K key)` - - - Deletes all entities with a given index key.
- `boolean`	`delete(Transaction txn, - K 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(K fromKey, - boolean fromInclusive, - K 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, - K fromKey, - boolean fromInclusive, - K 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.
- `Database`	`getDatabase()` - - - Returns the underlying database for this index.
- `EntityBinding<E>`	`getEntityBinding()` - - - Returns the entity binding for this index.
- `Class<E>`	`getEntityClass()` - - - Returns the entity class for this index.
- `EntryBinding<PK>`	`getKeyBinding()` - - - Returns the primary key binding for this index.
- `Class<PK>`	`getKeyClass()` - - - Returns the primary key class for this index.
- `EntityCursor<K>`	`keys()` - - - Opens a cursor for traversing all keys in this index.
- `EntityCursor<K>`	`keys(K fromKey, - boolean fromInclusive, - K toKey, - boolean toInclusive)` - - - Opens a cursor for traversing keys in a key range.
- `EntityCursor<K>`	`keys(Transaction txn, - CursorConfig config)` - - - Opens a cursor for traversing all keys in this index.
- `EntityCursor<K>`	`keys(Transaction txn, - K fromKey, - boolean fromInclusive, - K toKey, - boolean toInclusive, - CursorConfig config)` - - - Opens a cursor for traversing keys in a key range.
- `Map<PK,E>`	`map()` - - - Returns a standard Java map based on this entity index.
- `E`	`put(E entity)` - - - Inserts an entity and returns null, or updates it if the primary key - already exists and returns the existing entity.
- `E`	`put(Transaction txn, - E entity)` - - - Inserts an entity and returns null, or updates it if the primary key - already exists and returns the existing entity.
- `boolean`	`putNoOverwrite(E entity)` - - - Inserts an entity and returns true, or returns false if the primary key - already exists.
- `boolean`	`putNoOverwrite(Transaction txn, - E entity)` - - - Inserts an entity and returns true, or returns false if the primary key - already exists.
- `void`	`putNoReturn(E entity)` - - - Inserts an entity, or updates it if the primary key already exists (does - not return the existing entity).
- `void`	`putNoReturn(Transaction txn, - E entity)` - - - Inserts an entity, or updates it if the primary key already exists (does - not return the existing entity).
- `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`

- -

- +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`boolean`	`contains(K key)` + Checks for existence of a key in this index. +
`boolean`	`contains(Transaction txn, + K 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(K key)` + Deletes all entities with a given index key. +
`boolean`	`delete(Transaction txn, + K 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(K fromKey, + boolean fromInclusive, + K 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, + K fromKey, + boolean fromInclusive, + K 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. +
`Database`	`getDatabase()` + Returns the underlying database for this index. +
`EntityBinding<E>`	`getEntityBinding()` + Returns the entity binding for this index. +
`java.lang.Class<E>`	`getEntityClass()` + Returns the entity class for this index. +
`EntryBinding<PK>`	`getKeyBinding()` + Returns the primary key binding for this index. +
`java.lang.Class<PK>`	`getKeyClass()` + Returns the primary key class for this index. +
`EntityCursor<K>`	`keys()` + Opens a cursor for traversing all keys in this index. +
`EntityCursor<K>`	`keys(K fromKey, + boolean fromInclusive, + K toKey, + boolean toInclusive)` + Opens a cursor for traversing keys in a key range. +
`EntityCursor<K>`	`keys(Transaction txn, + CursorConfig config)` + Opens a cursor for traversing all keys in this index. +
`EntityCursor<K>`	`keys(Transaction txn, + K fromKey, + boolean fromInclusive, + K 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. +
`E`	`put(E entity)` + Inserts an entity and returns null, or updates it if the primary key + already exists and returns the existing entity. +
`E`	`put(Transaction txn, + E entity)` + Inserts an entity and returns null, or updates it if the primary key + already exists and returns the existing entity. +
`boolean`	`putNoOverwrite(E entity)` + Inserts an entity and returns true, or returns false if the primary key + already exists. +
`boolean`	`putNoOverwrite(Transaction txn, + E entity)` + Inserts an entity and returns true, or returns false if the primary key + already exists. +
`void`	`putNoReturn(E entity)` + Inserts an entity, or updates it if the primary key already exists (does + not return the existing entity). +
`void`	`putNoReturn(Transaction txn, + E entity)` + Inserts an entity, or updates it if the primary key already exists (does + not return the existing entity). +
`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
- -
-PrimaryIndex
-
```
-public PrimaryIndex(Database database,
-                    Class<PK> keyClass,
-                    EntryBinding<PK> keyBinding,
-                    Class<E> entityClass,
-                    EntityBinding<E> entityBinding)
-             throws DatabaseException
```
-
-
Creates a primary index without using an EntityStore. +
- + + +
  Constructor Detail
  + + + +
  - +
    PrimaryIndex
    +
    public PrimaryIndex(Database database, + java.lang.Class<PK> keyClass, + EntryBinding<PK> keyBinding, + java.lang.Class<E> entityClass, + EntityBinding<E> entityBinding) + throws DatabaseException
    +
    Creates a primary index without using an EntityStore.
    This constructor is not normally needed and is provided for applications that wish to use custom bindings along with the Direct - Persistence Layer. Normally, getPrimaryIndex is used instead.
    + Persistence Layer. Normally, getPrimaryIndex is used instead.
    
    Note that when this constructor is used directly, primary keys cannot be automatically assigned from a sequence. The key assignment feature requires knowledge of the primary key field, which is only available if an EntityStore is used. Of course, primary keys may be assigned from a sequence manually before calling the put - methods in this class.
    -
    -
    -
    Parameters:
    database - the primary database.
    keyClass - the class of the primary key.
    keyBinding - the binding to be used for primary keys.
    entityClass - the class of the entities stored in this index.
    entityBinding - the binding to be used for entities. -
    Throws: -
    DatabaseException - the base class for all BDB exceptions.
    -
- + methods in this class.

Parameters:: database - the primary database.; keyClass - the class of the primary key.; keyBinding - the binding to be used for primary keys.; entityClass - the class of the entities stored in this index.; entityBinding - the binding to be used for entities.
Throws:: DatabaseException - the base class for all BDB exceptions.

+ + + + - - - - - - -

-Method Detail

- -

-getDatabase

-public Database getDatabase()

Returns the underlying database for this index. -

Returns:: the database.

- -

-getKeyClass

-public Class<PK> getKeyClass()

Returns the primary key class for this index. -

Returns:: the key class.

- -

-getKeyBinding

-public EntryBinding<PK> getKeyBinding()

Returns the primary key binding for this index. -

Returns:: the key binding.

- -

-getEntityClass

-public Class<E> getEntityClass()

Returns the entity class for this index. -

Returns:: the entity class.

- -

-getEntityBinding

-public EntityBinding<E> getEntityBinding()

Returns the entity binding for this index. -

Returns:: the entity binding.

- -

-put

-public E put(E entity)
-      throws DatabaseException

Inserts an entity and returns null, or updates it if the primary key +

+ + +
Method Detail
+ + + +
- +
  getDatabase
  +
```
public Database getDatabase()
```
  +
  Returns the underlying database for this index.
  +
  Returns:
  the database.
  +
+ + + +
- +
  getKeyClass
  +
```
public java.lang.Class<PK> getKeyClass()
```
  +
  Returns the primary key class for this index.
  +
  Returns:
  the key class.
  +
+ + + +
- +
  getKeyBinding
  +
```
public EntryBinding<PK> getKeyBinding()
```
  +
  Returns the primary key binding for this index.
  +
  Returns:
  the key binding.
  +
+ + + +
- +
  getEntityClass
  +
```
public java.lang.Class<E> getEntityClass()
```
  +
  Returns the entity class for this index.
  +
  Returns:
  the entity class.
  +
+ + + +
- +
  getEntityBinding
  +
```
public EntityBinding<E> getEntityBinding()
```
  +
  Returns the entity binding for this index.
  +
  Returns:
  the entity binding.
  +
+ + + + + +
- +
  put
  +
```
public E put(E entity)
+      throws DatabaseException
```
  +
  Inserts an entity and returns null, or updates it if the primary key already exists and returns the existing entity. -
  If a PrimaryKey.sequence() is used and the primary key field of +
  If a PrimaryKey.sequence() is used and the primary key field of the given entity is null or zero, this method will assign the next value from the sequence to the primary key field of the given entity.
  -
  Auto-commit is used implicitly if the store is transactional.
  -
  -
  -
  Parameters:
  entity - the entity to be inserted or updated. -
  Returns:
  the existing entity that was updated, or null if the entity was - inserted. -
  Throws: -
  DatabaseException - the base class for all BDB exceptions.
  -
  -

- -

-put

-public E put(Transaction txn,
-             E entity)
-      throws DatabaseException

Inserts an entity and returns null, or updates it if the primary key +

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

Inserts an entity and returns true, or returns false if the primary key already exists. -

If a PrimaryKey.sequence() is used and the primary key field of +

If a PrimaryKey.sequence() is used and the primary key field of the given entity is null or zero, this method will assign the next value - from the sequence to the primary key field of the given entity.

Parameters:: txn - the transaction used to protect this operation, null to use - auto-commit, or null if the store is non-transactional.; entity - the entity to be inserted. -
Returns:: true if the entity was inserted, or false if an entity with the - same primary key is already present. -
Throws: -: 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.

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: -: 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. -

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

- -

-map

-public 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. -

Returns:: the map.

- -

-sortedMap

-public 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. -

Returns:: the map.

- -

-contains

-public boolean contains(K 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.

Specified by:: contains in interface EntityIndex<K,E>

Parameters:: key - the key to search for. -
Returns:: whether the key exists in the index. -
Throws: -: DatabaseException - the base class for all BDB exceptions.

- -

-contains

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

Description copied from interface: EntityIndex

Checks for existence of a key in this index. -

Specified by:: contains in interface EntityIndex<K,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: -: 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. + from the sequence to the primary key field of the given entity.

- -com.sleepycat.persist - -Class PrimaryIndex<PK,E>

Class PrimaryIndex<PK,E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

-PrimaryIndex

Constructor Detail

PrimaryIndex

-getDatabase

-getKeyClass

-getKeyBinding

-getEntityClass

-getEntityBinding

-put

Method Detail

getDatabase

getKeyClass

getKeyBinding

getEntityClass

getEntityBinding

put

-put

put

-putNoReturn

putNoReturn

-putNoReturn

putNoReturn

-putNoOverwrite

putNoOverwrite

-putNoOverwrite

putNoOverwrite

-get

-get

-map

-sortedMap

-contains

-contains

-count

get

get

map

sortedMap

contains

contains

count

-delete

-delete

-keys

delete

delete

keys

-keys

keys

-entities

entities

-entities

entities

-keys

keys

-keys

keys

-entities

entities

-entities

entities

- -com.sleepycat.persist -
-Class PrimaryIndex<PK,E>