com.sleepycat.je
Interface SecondaryMultiKeyCreator

All Known Implementing Classes:
PersistKeyCreator

public interface SecondaryMultiKeyCreator

The interface implemented for extracting multi-valued secondary keys from primary records.

The key creator object is specified by calling SecondaryConfig.setMultiKeyCreator. The secondary database configuration is specified when calling Environment.openSecondaryDatabase.

For example:

     class MyMultiKeyCreator implements SecondaryMultiKeyCreator {
         public void createSecondaryKeys(SecondaryDatabase secondary,
                                         DatabaseEntry key,
                                         DatabaseEntry data,
                                         Set<DatabaseEntry> results)
             throws DatabaseException {
             //
             // DO HERE: Extract the secondary keys from the primary key and
 // data.  For each key extracted, create a DatabaseEntry and add it
             // to the results set.
             //
         }
     }
     ...
     SecondaryConfig secConfig = new SecondaryConfig();
     secConfig.setMultiKeyCreator(new MyMultiKeyCreator());
     // Now pass secConfig to Environment.openSecondaryDatabase
 

Use this interface when any number of secondary keys may be present in a single primary record, in other words, for many-to-many and one-to-many relationships. When only zero or one secondary key is present (for many-to-one and one-to-one relationships) you may use the SecondaryKeyCreator interface instead. The table below summarizes how to create all four variations of relationships.

Relationship Interface Duplicates Example
One-to-one SecondaryKeyCreator No A person record with a unique social security number key.
Many-to-one SecondaryKeyCreator Yes A person record with a non-unique employer key.
One-to-many SecondaryMultiKeyCreator No A person record with multiple unique email address keys.
Many-to-many SecondaryMultiKeyCreator Yes A person record with multiple non-unique organization keys.

To configure a database for duplicates. pass true to DatabaseConfig.setSortedDuplicates(boolean).

Note that SecondaryMultiKeyCreator may also be used for single key secondaries (many-to-one and one-to-one); in this case, at most a single key is added to the results set. SecondaryMultiKeyCreator is only slightly less efficient than SecondaryKeyCreator in that two or three temporary sets must be created to hold the results. @see SecondaryConfig


Method Summary
 void createSecondaryKeys(SecondaryDatabase secondary, DatabaseEntry key, DatabaseEntry data, java.util.Set<DatabaseEntry> results)
          Creates a secondary key entry, given a primary key and data entry.
 

Method Detail

createSecondaryKeys

void createSecondaryKeys(SecondaryDatabase secondary,
                         DatabaseEntry key,
                         DatabaseEntry data,
                         java.util.Set<DatabaseEntry> results)
                         throws DatabaseException
Creates a secondary key entry, given a primary key and data entry.

A secondary key may be derived from the primary key, primary data, or a combination of the primary key and data. Zero or more secondary keys may be derived from the primary record and returned in the results parameter. To ensure the integrity of a secondary database the key creator method must always return the same results for a given set of input parameters.

Parameters:
secondary - the database to which the secondary key will be added. This parameter is passed for informational purposes but is not commonly used.
key - the primary key entry. This parameter must not be modified by this method.
data - the primary data entry. This parameter must not be modified by this method.
results - the set to contain the the secondary key DatabaseEntry objects created by this method.
Throws:
DatabaseException - if an error occurs attempting to create the secondary key.