1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2002,2008 Oracle.  All rights reserved.
5 *
6 * $Id: SecondaryMultiKeyCreator.java,v 12.5 2008/01/17 05:04:53 mjc Exp $
7 */
8
9package com.sleepycat.db;
10
11import java.util.Set;
12
13/**
14The interface implemented for extracting multi-valued secondary keys from
15primary records.
16<p>
17The key creator object is specified by calling
18{@link SecondaryConfig#setMultiKeyCreator SecondaryConfig.setMultiKeyCreator}.
19The secondary database configuration is specified when calling
20{@link Environment#openSecondaryDatabase Environment.openSecondaryDatabase}.
21<p>
22For example:
23<pre>
24    class MyMultiKeyCreator implements SecondaryMultiKeyCreator {
25    public void createSecondaryKeys(SecondaryDatabase secondary,
26                                        DatabaseEntry key,
27                                        DatabaseEntry data,
28                                        Set results)
29            throws DatabaseException {
30            //
31            // DO HERE: Extract the secondary keys from the primary key and
32            // data.  For each key extracted, create a DatabaseEntry and add it
33            // to the results set.
34            //
35        }
36    }
37    ...
38    SecondaryConfig secConfig = new SecondaryConfig();
39    secConfig.setMultiKeyCreator(new MyMultiKeyCreator());
40    // Now pass secConfig to Environment.openSecondaryDatabase
41</pre>
42<p>
43Use this interface when any number of secondary keys may be present in a single
44primary record, in other words, for many-to-many and one-to-many relationships.
45When only zero or one secondary key is present (for many-to-one and one-to-one
46relationships) you may use the {@link SecondaryKeyCreator} interface instead.
47The table below summarizes how to create all four variations of relationships.
48<div>
49<table border="yes">
50    <tr><th>Relationship</th>
51        <th>Interface</th>
52        <th>Duplicates</th>
53        <th>Example</th>
54    </tr>
55    <tr><td>One-to-one</td>
56        <td>{@link SecondaryKeyCreator}</td>
57        <td>No</td>
58        <td>A person record with a unique social security number key.</td>
59    </tr>
60    <tr><td>Many-to-one</td>
61        <td>{@link SecondaryKeyCreator}</td>
62        <td>Yes</td>
63        <td>A person record with a non-unique employer key.</td>
64    </tr>
65    <tr><td>One-to-many</td>
66        <td>{@link SecondaryMultiKeyCreator}</td>
67        <td>No</td>
68        <td>A person record with multiple unique email address keys.</td>
69    </tr>
70    <tr><td>Many-to-many</td>
71        <td>{@link SecondaryMultiKeyCreator}</td>
72        <td>Yes</td>
73        <td>A person record with multiple non-unique organization keys.</td>
74    </tr>
75</table>
76</div>
77<p>To configure a database for duplicates. pass true to {@link
78DatabaseConfig#setSortedDuplicates}.</p>
79<p>
80Note that <code>SecondaryMultiKeyCreator</code> may also be used for single key
81secondaries (many-to-one and one-to-one); in this case, at most a single key is
82added to the results set.  <code>SecondaryMultiKeyCreator</code> is only
83slightly less efficient than {@link SecondaryKeyCreator} in that two or three
84temporary sets must be created to hold the results.
85@see SecondaryConfig
86*/
87public interface SecondaryMultiKeyCreator {
88    /**
89    Creates a secondary key entry, given a primary key and data entry.
90    <p>
91    A secondary key may be derived from the primary key, primary data, or a
92    combination of the primary key and data.  Zero or more secondary keys may
93    be derived from the primary record and returned in the results parameter.
94    To ensure the integrity of a secondary database the key creator method must
95    always return the same results for a given set of input parameters.
96    <p>
97    @param secondary the database to which the secondary key will be added.
98    This parameter is passed for informational purposes but is not commonly
99    used.
100    <p>
101    @param key the primary key entry.  This parameter must not be modified
102    by this method.
103    <p>
104    @param data the primary data entry.  This parameter must not be modified
105    by this method.
106    <p>
107    @param results the set to contain the the secondary key DatabaseEntry
108    objects created by this method.
109    <p>
110    @throws DatabaseException if an error occurs attempting to create the
111    secondary key.
112    */
113    public void createSecondaryKeys(SecondaryDatabase secondary,
114                                    DatabaseEntry key,
115                                    DatabaseEntry data,
116                                    Set results)
117        throws DatabaseException;
118}
119