1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2000,2008 Oracle.  All rights reserved.
5 *
6 * $Id: MarshalledTupleKeyEntity.java,v 12.7 2008/02/07 17:12:25 mark Exp $
7 */
8
9package com.sleepycat.bind.tuple;
10
11/**
12 * A marshalling interface implemented by entity classes that represent keys as
13 * tuples. Since <code>MarshalledTupleKeyEntity</code> objects are instantiated
14 * using Java deserialization, no particular constructor is required by classes
15 * that implement this interface.
16 *
17 * <p>Note that a marshalled tuple key extractor is somewhat less efficient
18 * than a non-marshalled key tuple extractor because more conversions are
19 * needed.  A marshalled key extractor must convert the entry to an object in
20 * order to extract the key fields, while an unmarshalled key extractor does
21 * not.</p>
22 *
23 * @author Mark Hayes
24 * @see TupleTupleMarshalledBinding
25 * @see com.sleepycat.bind.serial.TupleSerialMarshalledBinding
26 */
27public interface MarshalledTupleKeyEntity {
28
29    /**
30     * Extracts the entity's primary key and writes it to the key output.
31     *
32     * @param keyOutput is the output tuple.
33     */
34    void marshalPrimaryKey(TupleOutput keyOutput);
35
36    /**
37     * Completes construction of the entity by setting its primary key from the
38     * stored primary key.
39     *
40     * @param keyInput is the input tuple.
41     */
42    void unmarshalPrimaryKey(TupleInput keyInput);
43
44    /**
45     * Extracts the entity's secondary key and writes it to the key output.
46     *
47     * @param keyName identifies the secondary key.
48     *
49     * @param keyOutput is the output tuple.
50     *
51     * @return true if a key was created, or false to indicate that the key is
52     * not present.
53     */
54    boolean marshalSecondaryKey(String keyName, TupleOutput keyOutput);
55
56    /**
57     * Clears the entity's secondary key fields for the given key name.
58     *
59     * <p>The specified index key should be changed by this method such that
60     * {@link #marshalSecondaryKey} for the same key name will return false.
61     * Other fields in the data object should remain unchanged.</p>
62     *
63     * <p>If {@link com.sleepycat.db.ForeignKeyDeleteAction#NULLIFY} was
64     * specified when opening the secondary database, this method is called
65     * when the entity for this foreign key is deleted.  If NULLIFY was not
66     * specified, this method will not be called and may always return
67     * false.</p>
68     *
69     * @param keyName identifies the secondary key.
70     *
71     * @return true if the key was cleared, or false to indicate that the key
72     * is not present and no change is necessary.
73     */
74    boolean nullifyForeignKey(String keyName);
75}
76