SSecondaryMultiKeyCreator (Oracle - Berkeley DB Client-Server API)
Date: 2018-05-29

com.sleepycat.client

## Interface SSecondaryMultiKeyCreator

- Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface SSecondaryMultiKeyCreator

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

  The key creator object is specified by calling `SSecondaryConfig.setMultiKeyCreator(com.sleepycat.client.SSecondaryMultiKeyCreator)`. The secondary database configuration is specified when calling `SEnvironment.openSecondaryDatabase(com.sleepycat.client.STransaction, java.lang.String, java.lang.String, com.sleepycat.client.SDatabase, com.sleepycat.client.SSecondaryConfig)`.

  For example:

        class MyMultiKeyCreator implements SSecondaryMultiKeyCreator {
            public void createSecondaryKeys(SSecondaryDatabase secondary,
                    SDatabaseEntry key,
                    SDatabaseEntry data,
                    Set<SDatabaseEntry> results) throws SDatabaseException {
                //
                // DO HERE: Extract the secondary keys from the primary key and
                // data.  For each key extracted, create a SDatabaseEntry and add
                // it to the results set.
                //
            }
        }
        ...
        SSecondaryConfig secConfig = new SSecondaryConfig();
        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 SSecondaryKeyCreator interface instead. The table below summarizes how to create all four variations of relationships.

  Key creator for different relationships
  Relationship | Interface | Duplicates | Example
  --- | --- | --- | ---
  One-to-one | `SSecondaryKeyCreator` | No | A person record with a unique social security number key.
  Many-to-one | `SSecondaryKeyCreator` | Yes | A person record with a non-unique employer key.
  One-to-many | `SSecondaryMultiKeyCreator` | No | A person record with multiple unique email address keys.
  Many-to-many | `SSecondaryMultiKeyCreator` | Yes | A person record with multiple non-unique organization keys.

  To configure a database for duplicates, pass true to `SDatabaseConfig.setSortedDuplicates(boolean)`.

  Note that SSecondaryMultiKeyCreator 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. SSecondaryMultiKeyCreator is only slightly less efficient than SecondaryKeyCreator in that two or three temporary sets must be created to hold the results.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `createSecondaryKeys(SSecondaryDatabase secondary, SDatabaseEntry key, SDatabaseEntry data, java.util.Set<SDatabaseEntry> results)` Create multiple secondary key entries, given a primary key and data entry.

- - ### Method Detail

    - #### createSecondaryKeys

          void createSecondaryKeys(SSecondaryDatabase secondary,
                                   SDatabaseEntry key,
                                   SDatabaseEntry data,
                                   java.util.Set<SDatabaseEntry> results)
                            throws SDatabaseException

      Create multiple secondary key entries, 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 SDatabaseEntry objects created by this method.
      Throws:
        `SDatabaseException` - if an error occurs attempting to create the secondary key.

Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.