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