com.sleepycat.je.SecondaryMultiKeyCreator Maven / Gradle / Ivy
/*-
* Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
*
* This file was distributed by Oracle as part of a version of Oracle Berkeley
* DB Java Edition made available at:
*
* http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
*
* Please see the LICENSE file included in the top-level directory of the
* appropriate version of Oracle Berkeley DB Java Edition for a copy of the
* license and additional information.
*/
package com.sleepycat.je;
import java.util.Set;
/**
* The interface implemented for extracting multi-valued secondary keys from
* primary records.
*
* The key creator object is specified by calling {@link
* SecondaryConfig#setMultiKeyCreator SecondaryConfig.setMultiKeyCreator}. The
* secondary database configuration is specified when calling {@link
* Environment#openSecondaryDatabase 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 {@link
* SecondaryKeyCreator} interface instead. The table below summarizes how to
* create all four variations of relationships.
*
*
* Relationship
* Interface
* Duplicates
* Example
* One-to-one
* {@link SecondaryKeyCreator}
* No
* A person record with a unique social security number key.
* Many-to-one
* {@link SecondaryKeyCreator}
* Yes
* A person record with a non-unique employer key.
* One-to-many
* {@link SecondaryMultiKeyCreator}
* No
* A person record with multiple unique email address keys.
* Many-to-many
* {@link SecondaryMultiKeyCreator}
* Yes
* A person record with multiple non-unique organization keys.
*
*
*
*
* To configure a database for duplicates. pass true to {@link
* DatabaseConfig#setSortedDuplicates}.
*
* 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
* {@link 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.
*/
public interface SecondaryMultiKeyCreator {
/**
* 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 {@code 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 {@link
* Database#put 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.
*
* @param 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.
*
* @param key the primary key entry. This parameter must not be modified
* by this method. This parameter is always non-null.
*
* @param data the primary data entry. This parameter must not be modified
* by this method. If {@link SecondaryConfig#setExtractFromPrimaryKeyOnly}
* is configured as {@code true}, the {@code data} param may be either null
* or non-null, and the implementation is expected to ignore it; otherwise,
* this parameter is always non-null.
*
* @param results the set to contain the the secondary key DatabaseEntry
* objects created by this method.
*/
public void createSecondaryKeys(SecondaryDatabase secondary,
DatabaseEntry key,
DatabaseEntry data,
Set results);
}