1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: TupleTupleKeyCreator.java,v 12.10 2008/02/07 17:12:25 mark Exp $
7 */
8
9package com.sleepycat.bind.tuple;
10
11import com.sleepycat.db.DatabaseEntry;
12import com.sleepycat.db.DatabaseException;
13import com.sleepycat.db.ForeignKeyNullifier;
14import com.sleepycat.db.SecondaryDatabase;
15import com.sleepycat.db.SecondaryKeyCreator;
16
17/**
18 * An abstract key creator that uses a tuple key and a tuple data entry. This
19 * class takes care of converting the key and data entry to/from {@link
20 * TupleInput} and {@link TupleOutput} objects.
21 * The following abstract method must be implemented by a concrete subclass
22 * to create the index key using these objects
23 * <ul>
24 * <li> {@link #createSecondaryKey(TupleInput,TupleInput,TupleOutput)} </li>
25 * </ul>
26 * <p>If {@link com.sleepycat.db.ForeignKeyDeleteAction#NULLIFY} was
27 * specified when opening the secondary database, the following method must be
28 * overridden to nullify the foreign index key.  If NULLIFY was not specified,
29 * this method need not be overridden.</p>
30 * <ul>
31 * <li> {@link #nullifyForeignKey(TupleInput,TupleOutput)} </li>
32 * </ul>
33 * <p>If {@link com.sleepycat.db.ForeignKeyDeleteAction#NULLIFY} was
34 * specified when creating the secondary, this method is called when the
35 * entity for this foreign key is deleted.  If NULLIFY was not specified,
36 * this method will not be called and may always return false.</p>
37 *
38 * @author Mark Hayes
39 */
40public abstract class TupleTupleKeyCreator extends TupleBase
41    implements SecondaryKeyCreator, ForeignKeyNullifier {
42
43    /**
44     * Creates a tuple-tuple key creator.
45     */
46    public TupleTupleKeyCreator() {
47    }
48
49    // javadoc is inherited
50    public boolean createSecondaryKey(SecondaryDatabase db,
51                                      DatabaseEntry primaryKeyEntry,
52                                      DatabaseEntry dataEntry,
53                                      DatabaseEntry indexKeyEntry)
54        throws DatabaseException {
55
56        TupleOutput output = getTupleOutput(null);
57        TupleInput primaryKeyInput = entryToInput(primaryKeyEntry);
58        TupleInput dataInput = entryToInput(dataEntry);
59        if (createSecondaryKey(primaryKeyInput, dataInput, output)) {
60            outputToEntry(output, indexKeyEntry);
61            return true;
62        } else {
63            return false;
64        }
65    }
66
67    // javadoc is inherited
68    public boolean nullifyForeignKey(SecondaryDatabase db,
69                                     DatabaseEntry dataEntry)
70        throws DatabaseException {
71
72        TupleOutput output = getTupleOutput(null);
73        if (nullifyForeignKey(entryToInput(dataEntry), output)) {
74            outputToEntry(output, dataEntry);
75            return true;
76        } else {
77            return false;
78        }
79    }
80
81    /**
82     * Creates the index key from primary key tuple and data tuple.
83     *
84     * @param primaryKeyInput is the {@link TupleInput} for the primary key
85     * entry.
86     *
87     * @param dataInput is the {@link TupleInput} for the data entry.
88     *
89     * @param indexKeyOutput is the destination index key tuple.
90     *
91     * @return true if a key was created, or false to indicate that the key is
92     * not present.
93     */
94    public abstract boolean createSecondaryKey(TupleInput primaryKeyInput,
95                                               TupleInput dataInput,
96                                               TupleOutput indexKeyOutput);
97
98    /**
99     * Clears the index key in the tuple data entry.  The dataInput should be
100     * read and then written to the dataOutput, clearing the index key in the
101     * process.
102     *
103     * <p>The secondary key should be output or removed by this method such
104     * that {@link #createSecondaryKey} will return false.  Other fields in the
105     * data object should remain unchanged.</p>
106     *
107     * @param dataInput is the {@link TupleInput} for the data entry.
108     *
109     * @param dataOutput is the destination {@link TupleOutput}.
110     *
111     * @return true if the key was cleared, or false to indicate that the key
112     * is not present and no change is necessary.
113     */
114    public boolean nullifyForeignKey(TupleInput dataInput,
115                                     TupleOutput dataOutput) {
116
117        return false;
118    }
119}
120