com.sleepycat.persist

Class EntityJoin<PK,E>

java.lang.Object

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

public class EntityJoin<PK,E>
extends java.lang.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

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.

Type Parameters:

SK - the secondary key class.

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.

java.lang.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.

java.lang.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.

java.lang.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.

java.lang.IllegalStateException - if less than two conditions were added.

DatabaseException - the base class for all BDB exceptions.