EntityJoin (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.persist

## Class EntityJoin<PK,E>

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

-     public class EntityJoin<PK,E>
      extends Object

  Performs an equality join on two or more secondary keys.

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

  An equality join is a match on all entities in a given primary index that have two or more specific secondary key values. Note that key ranges may not be matched by an equality join, only exact keys are matched.

  For example:

        // Index declarations -- see package summary example.
        //
        PrimaryIndex<String, Person> personBySsn;
        SecondaryIndex<String, String, Person> personByParentSsn;
        SecondaryIndex<Long, String, Person> personByEmployerIds;
        Employer employer = ...;

        // Match on all Person objects having parentSsn "111-11-1111" and also
        // containing an employerId of employer.id.  In other words, match on all
        // of Bob's children that work for a given employer.
        //
        EntityJoin<String, Person> join = new EntityJoin(personBySsn);
        join.addCondition(personByParentSsn, "111-11-1111");
        join.addCondition(personByEmployerIds, employer.id);

        // Perform the join operation by traversing the results with a cursor.
        //
        ForwardCursor<Person> results = join.entities();
        try {
            for (Person person : results) {
                System.out.println(person.ssn + ' ' + person.name);
            }
        } finally {
            results.close();
        }

  Author:
    Mark Hayes

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EntityJoin(PrimaryIndex<PK,E> index)` Creates a join object for a given primary index.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `<SK> void` | `addCondition(SecondaryIndex<SK,PK,E> index, SK key)` Adds a secondary key condition to the equality join.
    `ForwardCursor<E>` | `entities()` Opens a cursor that returns the entities qualifying for the join.
    `ForwardCursor<E>` | `entities(Transaction txn, CursorConfig config)` Opens a cursor that returns the entities qualifying for the join.
    `ForwardCursor<PK>` | `keys()` Opens a cursor that returns the primary keys of entities qualifying for the join.
    `ForwardCursor<PK>` | `keys(Transaction txn, CursorConfig config)` Opens a cursor that returns the primary keys of entities qualifying for the join.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### EntityJoin

          public EntityJoin(PrimaryIndex<PK,E> index)

      Creates a join object for a given primary index.
      Parameters:
        `index` - the primary index on which the join will operate.

  - ### Method Detail

    - #### addCondition

          public <SK> void addCondition(SecondaryIndex<SK,PK,E> index,
                               SK key)

      Adds a secondary key condition to the equality join. Only entities having the given key value in the given secondary index will be returned by the join operation.
      Parameters:
        `index` - the secondary index containing the given key value.
        `key` - the key value to match during the join.

    - #### entities

          public ForwardCursor<E> entities()
                                    throws DatabaseException

      Opens a cursor that returns the entities qualifying for the join. The join operation is performed as the returned cursor is accessed.

      The operations performed with the cursor will not be transaction protected, and `CursorConfig.DEFAULT` is used implicitly.

      Returns:
        the cursor.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if less than two conditions were added.
        `DatabaseException` - the base class for all BDB exceptions.

    - #### entities

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

      Opens a cursor that returns the entities qualifying for the join. The join operation is performed as the returned cursor is accessed.
      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:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if less than two conditions were added.
        `DatabaseException` - the base class for all BDB exceptions.

    - #### keys

          public ForwardCursor<PK> keys()
                                 throws DatabaseException

      Opens a cursor that returns the primary keys of entities qualifying for the join. The join operation is performed as the returned cursor is accessed.

      The operations performed with the cursor will not be transaction protected, and `CursorConfig.DEFAULT` is used implicitly.

      Returns:
        the cursor.
      Throws:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if less than two conditions were added.
        `DatabaseException` - the base class for all BDB exceptions.

    - #### keys

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

      Opens a cursor that returns the primary keys of entities qualifying for the join. The join operation is performed as the returned cursor is accessed.
      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:
        `OperationFailureException` - if one of the Read Operation Failures occurs.
        `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
        `IllegalStateException` - if less than two conditions were added.
        `DatabaseException` - the base class for all BDB exceptions.

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.