01: /*-
02: * See the file LICENSE for redistribution information.
03: *
04: * Copyright (c) 2000,2008 Oracle. All rights reserved.
05: *
06: * $Id: MarshalledTupleKeyEntity.java,v 1.22.2.2 2008/01/07 15:14:06 cwl Exp $
07: */
08:
09: package 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: */
27: public 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: * <!-- begin JE only -->
64: * <p>If {@link com.sleepycat.je.ForeignKeyDeleteAction#NULLIFY} was
65: * specified when opening the secondary database, this method is called
66: * when the entity for this foreign key is deleted. If NULLIFY was not
67: * specified, this method will not be called and may always return
68: * false.</p>
69: * <!-- end JE only -->
70: *
71: * @param keyName identifies the secondary key.
72: *
73: * @return true if the key was cleared, or false to indicate that the key
74: * is not present and no change is necessary.
75: */
76: boolean nullifyForeignKey(String keyName);
77: }
|