From 780b92ada9afcf1d58085a83a0b9e6bc982203d1 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Tue, 17 Feb 2015 17:25:57 +0000 Subject: Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz. --- docs/java/com/sleepycat/persist/EntityIndex.html | 1428 +++++++++++----------- 1 file changed, 691 insertions(+), 737 deletions(-) (limited to 'docs/java/com/sleepycat/persist/EntityIndex.html') diff --git a/docs/java/com/sleepycat/persist/EntityIndex.html b/docs/java/com/sleepycat/persist/EntityIndex.html index 78a4fa6f..ff27a7d1 100644 --- a/docs/java/com/sleepycat/persist/EntityIndex.html +++ b/docs/java/com/sleepycat/persist/EntityIndex.html @@ -1,106 +1,100 @@ - - - - - -EntityIndex (Oracle - Berkeley DB Java API) - - - - - - - - - - - - -
- - +//--> + + - - - - - - - - - - - - - - - - -
-Berkeley DB
version 5.3.21
-
- + + +
+ + +
+ + + - -
-

- -com.sleepycat.persist -
-Interface EntityIndex<K,V>

-
-
All Known Implementing Classes:
PrimaryIndex, SecondaryIndex
-
-
-
-
public interface EntityIndex<K,V>
- - -

-The interface for accessing keys and entities via a primary or secondary +

+
com.sleepycat.persist
+

Interface EntityIndex<K,V>

+
+
+
+
    +
  • +
    +
    All Known Implementing Classes:
    +
    PrimaryIndex, SecondaryIndex
    +
    +
    +
    +
    public interface EntityIndex<K,V>
    +
    The interface for accessing keys and entities via a primary or secondary index.

    EntityIndex objects are thread-safe. Multiple threads may safely @@ -108,25 +102,25 @@ The interface for accessing keys and entities via a primary or secondary

    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 + other libraries that use the standard Java Map or SortedMap interfaces, an EntityIndex may be accessed via these standard - interfaces by calling the map() or sortedMap() methods.

    + interfaces by calling the map() or 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.

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

    @@ -156,7 +150,7 @@ The interface for accessing keys and entities via a primary or secondary 4SalesJim Smith

    -

    PrimaryIndex maps primary keys to entities:

    +

    PrimaryIndex maps primary keys to entities:

      PrimaryIndex<Long, Employee> primaryIndex =
    @@ -171,7 +165,7 @@ The interface for accessing keys and entities via a primary or secondary
        44SalesJim Smith
      

    -

    SecondaryIndex maps secondary keys to entities:

    +

    SecondaryIndex maps secondary keys to entities:

      SecondaryIndex<String, Long, Employee> secondaryIndex =
    @@ -186,7 +180,7 @@ The interface for accessing keys and entities via a primary or secondary
        Sales4SalesJim Smith
      

    -

    SecondaryIndex.keysIndex maps secondary keys to primary +

    SecondaryIndex.keysIndex maps secondary keys to primary keys:

    @@ -201,7 +195,7 @@ The interface for accessing keys and entities via a primary or secondary
        Sales4
      

    -

    SecondaryIndex.subIndex(SK) maps primary keys to entities, for the +

    SecondaryIndex.subIndex(SK) maps primary keys to entities, for the subset of entities having a specified secondary key:

    @@ -219,24 +213,24 @@ The interface for accessing keys and entities via a primary or secondary
      

    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(E) family of methods in - the PrimaryIndex class.

    + and update entities, use the PrimaryIndex.put(E) family of methods in + the PrimaryIndex class.

    An EntityIndex supports two mechanisms for retrieving entities:

      -
    1. The get(K) method returns a single value for a given key. If there +
    2. The get(K) method 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.
    3. -
    4. An EntityCursor can be obtained using the keys() and - entities() family of methods. A cursor can be used to return all +
    5. An EntityCursor can be obtained using the keys() and + 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 get(K) on the primary +

    Using the example entities above, calling get(K) on the primary index will always return the employee with the given ID, or null if no such - ID exists. But calling get(K) on the secondary index will retrieve + ID exists. But calling get(K) on the secondary index will retrieve the first employee in the given department, which may not be very useful:

    @@ -303,7 +297,7 @@ The interface for accessing keys and entities via a primary or secondary
      Employee emp = subIndex.get(2);
    -

    For more information on using cursors and cursor ranges, see EntityCursor.

    +

    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 @@ -320,7 +314,7 @@ The interface for accessing keys and entities via a primary or secondary

    Deleting from the Index

    Any type of index may be used to delete entities with a specified key by - calling delete(K). The important thing to keep in mind is that + calling delete(K). The important thing to keep in mind is that all entities with the specified key are deleted. In a primary index, at most a single entity is deleted:

    @@ -334,7 +328,7 @@ The interface for accessing keys and entities via a primary or secondary

    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().

    + entity using a cursor, the entity can be deleted by calling EntityCursor.delete().

    Transactions

    @@ -346,9 +340,9 @@ The interface for accessing keys and entities via a primary or secondary href="../../../../gsg_txn/JAVA/index.html">Writing Transactional Applications.

    -

    Transactions may be used only with a transactional EntityStore, - which is one for which StoreConfig.setTransactional(true) has been called. Likewise, a - transactional store may only be used with a transactional Environment, which is one for which EnvironmentConfig.setTransactional(true) +

    Transactions may be used only with a transactional EntityStore, + which is one for which StoreConfig.setTransactional(true) has been called. Likewise, a + transactional store may only be used with a transactional Environment, which is one for which EnvironmentConfig.setTransactional(true) has been called. For example:

    @@ -362,20 +356,20 @@ The interface for accessing keys and entities via a primary or secondary
      storeConfig.setAllowCreate(true);
      EntityStore store = new EntityStore(env, "myStore", storeConfig);
    -

    Transactions are represented by Transaction objects, which are - part of the Base API. Transactions are created - using the Environment.beginTransaction +

    Transactions are represented by Transaction objects, which are + part of the Base API. Transactions are created + using the 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. + 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 +

    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:

    @@ -395,7 +389,7 @@ The interface for accessing keys and entities via a primary or secondary

    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 + aborted in the face of exceptions, call Transaction.abort() in a finally block.

    For a transactional store, storage and deletion operations are always @@ -423,8 +417,8 @@ The interface for accessing keys and entities via a primary or secondary

    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, delete(K) may be called - instead of delete(Transaction,Object). For example, the following + a null transaction argument. For example, delete(K) may be called + instead of delete(Transaction,Object). For example, the following code is equivalent to the code above where null was passed for the transaction:

    @@ -433,8 +427,8 @@ The interface for accessing keys and entities via a primary or secondary 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 + 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

    @@ -444,7 +438,7 @@ The interface for accessing keys and entities via a primary or secondary 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:

    + following code will throw DatabaseException when the EntityCursor.delete() method is called:

      // Does not work with a transactional store!
    @@ -457,7 +451,7 @@ The interface for accessing keys and entities via a primary or secondary
          cursor.close();
      }
    -

    Instead, the entities(Transaction,CursorConfig) signature must +

    Instead, the entities(Transaction,CursorConfig) signature must be used and a non-null transaction must be passed:

    @@ -525,12 +519,12 @@ The interface for accessing keys and entities via a primary or secondary
      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
    + 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 + 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 improves concurrency.

    @@ -545,12 +539,12 @@ The interface for accessing keys and entities via a primary or secondary cursor.close(); }
    -

    The LockMode parameter specifies locking behavior on a - per-operation basis. If null or LockMode.DEFAULT is specified, the +

    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 + using CursorConfig. The example below is equivalent to the example above:

    @@ -633,658 +627,618 @@ The interface for accessing keys and entities via a primary or secondary
      

    Low Level Access

    Each Direct Persistence Layer index is associated with an underlying - Database or SecondaryDatabase defined in the Base API. At this level, an index is a Btree managed by + Database or SecondaryDatabase defined in the 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 + 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() + the PrimaryIndex.getDatabase() or SecondaryIndex.getDatabase() method to get the underlying 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().

    -

    - -

    -


    - -

    - + objects and DatabaseEntry objects at this level, use the bindings + returned by PrimaryIndex.getEntityBinding(), PrimaryIndex.getKeyBinding(), and SecondaryIndex.getKeyBinding().

    +
  • +
+
+
+
    +
  • - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    -Method Summary
    - booleancontains(K key) - -
    -          Checks for existence of a key in this index.
    - booleancontains(Transaction txn, - K key, - LockMode lockMode) - -
    -          Checks for existence of a key in this index.
    - longcount() - -
    -          Returns a non-transactional count of the entities in this index.
    - booleandelete(K key) - -
    -          Deletes all entities with a given index key.
    - booleandelete(Transaction txn, - K key) - -
    -          Deletes all entities with a given index key.
    - EntityCursor<V>entities() - -
    -          Opens a cursor for traversing all entities in this index.
    - EntityCursor<V>entities(K fromKey, - boolean fromInclusive, - K toKey, - boolean toInclusive) - -
    -          Opens a cursor for traversing entities in a key range.
    - EntityCursor<V>entities(Transaction txn, - CursorConfig config) - -
    -          Opens a cursor for traversing all entities in this index.
    - EntityCursor<V>entities(Transaction txn, - K fromKey, - boolean fromInclusive, - K toKey, - boolean toInclusive, - CursorConfig config) - -
    -          Opens a cursor for traversing entities in a key range.
    - Vget(K key) - -
    -          Gets an entity via a key of this index.
    - Vget(Transaction txn, - K key, - LockMode lockMode) - -
    -          Gets an entity via a key of 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<K,V>map() - -
    -          Returns a standard Java map based on this entity index.
    - SortedMap<K,V>sortedMap() - -
    -          Returns a standard Java sorted map based on this entity index.
    -  -

    - +

      +
    • + + +

      Method Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Methods 
      Modifier and TypeMethod and Description
      booleancontains(K key) +
      Checks for existence of a key in this index.
      +
      booleancontains(Transaction txn, + K key, + LockMode lockMode) +
      Checks for existence of a key in this index.
      +
      longcount() +
      Returns a non-transactional count of the entities in this index.
      +
      booleandelete(K key) +
      Deletes all entities with a given index key.
      +
      booleandelete(Transaction txn, + K key) +
      Deletes all entities with a given index key.
      +
      EntityCursor<V>entities() +
      Opens a cursor for traversing all entities in this index.
      +
      EntityCursor<V>entities(K fromKey, + boolean fromInclusive, + K toKey, + boolean toInclusive) +
      Opens a cursor for traversing entities in a key range.
      +
      EntityCursor<V>entities(Transaction txn, + CursorConfig config) +
      Opens a cursor for traversing all entities in this index.
      +
      EntityCursor<V>entities(Transaction txn, + K fromKey, + boolean fromInclusive, + K toKey, + boolean toInclusive, + CursorConfig config) +
      Opens a cursor for traversing entities in a key range.
      +
      Vget(K key) +
      Gets an entity via a key of this index.
      +
      Vget(Transaction txn, + K key, + LockMode lockMode) +
      Gets an entity via a key of 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<K,V>map() +
      Returns a standard Java map based on this entity index.
      +
      java.util.SortedMap<K,V>sortedMap() +
      Returns a standard Java sorted map based on this entity index.
      +
      +
    • +
    +
  • +
+
+
+
    +
  • - - - - - - -
    -Method Detail
    - -

    -contains

    -
    -boolean contains(K key)
    -                 throws DatabaseException
    -
    -
    Checks for existence of a key in this index. - -

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

    -

    -

    -
    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

    -
    -boolean contains(Transaction txn,
    -                 K key,
    -                 LockMode lockMode)
    -                 throws DatabaseException
    -
    -
    Checks for existence of a key in 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:
    whether the key exists in the index. -
    Throws: -
    DatabaseException - the base class for all BDB exceptions.
    -
    -
    -
    - -

    -get

    -
    -V get(K key)
    -      throws DatabaseException
    -
    -
    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

    -
    -V get(Transaction txn,
    -      K key,
    -      LockMode lockMode)
    -      throws DatabaseException
    -
    -
    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.
    -
    -
    -
    - -

    -count

    -
    -long count()
    -           throws DatabaseException
    -
    -
    Returns a non-transactional count of the entities in this index. +
      +
    • + + +

      Method Detail

      + + + + + +
        +
      • +

        contains

        +
        boolean contains(K key)
        +                 throws DatabaseException
        +
        Checks for existence of a key in this index. + +

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

        +
        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

        +
        boolean contains(Transaction txn,
        +               K key,
        +               LockMode lockMode)
        +                 throws DatabaseException
        +
        Checks for existence of a key in 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:
        whether the key exists in the index.
        +
        Throws:
        +
        DatabaseException - the base class for all BDB exceptions.
        +
      • +
      + + + + + +
        +
      • +

        get

        +
        V get(K key)
        +      throws DatabaseException
        +
        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

        +
        V get(Transaction txn,
        +    K key,
        +    LockMode lockMode)
        +      throws DatabaseException
        +
        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.
        +
      • +
      + + + +
        +
      • +

        count

        +
        long count()
        +           throws DatabaseException
        +
        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.

        -

        -

        - -
        Returns:
        the number of entities in this index. -
        Throws: -
        DatabaseException - the base class for all BDB exceptions.
        -
        -
    -
    - -

    -delete

    -
    -boolean delete(K key)
    -               throws DatabaseException
    -
    -
    Deletes all entities with a given index key. - -

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

    -

    -

    -
    Parameters:
    key - the key to search for. -
    Returns:
    whether any entities were deleted. -
    Throws: -
    DatabaseException - the base class for all BDB exceptions.
    -
    -
    -
    - -

    -delete

    -
    -boolean delete(Transaction txn,
    -               K key)
    -               throws DatabaseException
    -
    -
    Deletes all entities with a given index key. -

    -

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

    -keys

    -
    -EntityCursor<K> keys()
    -                     throws DatabaseException
    -
    -
    Opens a cursor for traversing all keys in this index. + operation.

+
Returns:
the number of entities in this index.
+
Throws:
+
DatabaseException - the base class for all BDB exceptions.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ -
- - - - - - - - - - - - - - - - - - -
-Berkeley DB
version 5.3.21
-
- + + +
+ + +
+ + + - -
-Copyright (c) 1996, 2012 Oracle and/or its affiliates. All rights reserved. - - +

Copyright (c) 1996, 2015 Oracle and/or its affiliates. All rights reserved.

+ + -- cgit v1.2.1