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

com.sleepycat.je

## Interface SecondaryMultiKeyCreator

-     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) {
                   //
                   // 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

  WARNING: Key creator instances are shared by multiple threads and key creator methods are called without any special synchronization. Therefore, key creators must be thread safe. In general no shared state should be used and any caching of computed values must be done with proper synchronization.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `createSecondaryKeys(SecondaryDatabase secondary, DatabaseEntry key, DatabaseEntry data, 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,
                                 Set<DatabaseEntry> results)

      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.

      A `RuntimeException` may be thrown by this method if an error occurs attempting to create the secondary key. This exception will be thrown by the API method currently in progress, for example, a `put` method. However, this will cause the write operation to be incomplete. When databases are not configured to be transactional, caution should be used to avoid integrity problems. See Special considerations for using Secondary Databases with and without Transactions.

      Parameters:
        `secondary` - the database to which the secondary key will be added. This parameter is passed for informational purposes but is not commonly used. This parameter is always non-null.
        `key` - the primary key entry. This parameter must not be modified by this method. This parameter is always non-null.
        `data` - the primary data entry. This parameter must not be modified by this method. If `SecondaryConfig#setExtractFromPrimaryKeyOnly` is configured as `true`, the `data` param may be either null or non-null, and the implementation is expected to ignore it; otherwise, this parameter is always non-null.
        `results` - the set to contain the the secondary key DatabaseEntry objects created by this method.

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