1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002,2008 Oracle. All rights reserved. 5 * 6 * $Id: SecondaryKeyCreator.java,v 12.7 2008/01/17 05:04:53 mjc Exp $ 7 */ 8 9package com.sleepycat.db; 10 11/** 12The interface implemented for extracting single-valued secondary keys from 13primary records. 14<p> 15The key creator object is specified by calling 16{@link SecondaryConfig#setKeyCreator SecondaryConfig.setKeyCreator}. 17The secondary database configuration is specified when calling 18{@link Environment#openSecondaryDatabase Environment.openSecondaryDatabase}. 19<p> 20For example: 21<pre> 22 class MyKeyCreator implements SecondaryKeyCreator { 23 public boolean createSecondaryKey(SecondaryDatabase secondary, 24 DatabaseEntry key, 25 DatabaseEntry data, 26 DatabaseEntry result) 27 throws DatabaseException { 28 // 29 // DO HERE: Extract the secondary key from the primary key and 30 // data, and set the secondary key into the result parameter. 31 // 32 return true; 33 } 34 } 35 ... 36 SecondaryConfig secConfig = new SecondaryConfig(); 37 secConfig.setKeyCreator(new MyKeyCreator()); 38 // Now pass secConfig to Environment.openSecondaryDatabase 39</pre> 40*/ 41public interface SecondaryKeyCreator { 42 /** 43 Creates a secondary key entry, given a primary key and data entry. 44 <p> 45 A secondary key may be derived from the primary key, primary data, or a 46 combination of the primary key and data. For secondary keys that are 47 optional, the key creator method may return false and the key/data pair 48 will not be indexed. To ensure the integrity of a secondary database the 49 key creator method must always return the same result for a given set of 50 input parameters. 51 <p> 52 @param secondary the database to which the secondary key will be added. 53 This parameter is passed for informational purposes but is not commonly 54 used. 55 <p> 56 @param key the primary key entry. This parameter must not be modified 57 by this method. 58 <p> 59 @param data the primary data entry. This parameter must not be modified 60 by this method. 61 <p> 62 @param result the secondary key created by this method. 63 <p> 64 @return true if a key was created, or false to indicate that the key is 65 not present. 66 <p> 67 @throws DatabaseException if an error occurs attempting to create the 68 secondary key. 69 */ 70 boolean createSecondaryKey(SecondaryDatabase secondary, 71 DatabaseEntry key, 72 DatabaseEntry data, 73 DatabaseEntry result) 74 throws DatabaseException; 75} 76