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