1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2002,2008 Oracle.  All rights reserved.
5 *
6 * $Id: Enhanced.java,v 1.1 2008/02/07 17:12:27 mark Exp $
7 */
8
9package com.sleepycat.persist.impl;
10
11/**
12 * Interface implemented by a persistent class via bytecode enhancement.
13 *
14 * <p>See {@link Accessor} for method documentation.  {@link EnhancedAccessor}
15 * implements Accessor and forwards all calls to methods in the Enhanced
16 * class.</p>
17 *
18 * <p>Each class that implements this interface (including its subclasses and
19 * superclasses except for Object) must also implement a static block that
20 * registers a prototype instance by calling
21 * EnhancedAccessor.registerPrototype.  Other instances are created from the
22 * protype instance using {@link #bdbNewInstance}.</p>
23 *
24 * <pre>static { EnhancedAccessor.registerPrototype(new Xxx()); }</pre>
25 *
26 * <p>An example of the generated code for reading and writing fields is shown
27 * below.</p>
28 *
29 * <pre>
30 *  private int f1;
31 *  private String f2;
32 *  private MyClass f3;
33 *
34 *  public void bdbWriteNonKeyFields(EntityOutput output) {
35 *
36 *      super.bdbWriteNonKeyFields(output);
37 *
38 *      output.writeInt(f1);
39 *      output.writeObject(f2, null);
40 *      output.writeObject(f3, null);
41 *  }
42 *
43 *  public void bdbReadNonKeyFields(EntityInput input,
44 *                                  int startField,
45 *                                  int endField,
46 *                                  int superLevel) {
47 *
48 *      if (superLevel != 0) {
49 *          super.bdbReadNonKeyFields(input, startField, endField,
50 *                                    superLevel - 1);
51 *      }
52 *      if (superLevel &lt;= 0) {
53 *          switch (startField) {
54 *          case 0:
55 *              f1 = input.readInt();
56 *              if (endField == 0) break;
57 *          case 1:
58 *              f2 = (String) input.readObject();
59 *              if (endField == 1) break;
60 *          case 2:
61 *              f3 = (MyClass) input.readObject();
62 *          }
63 *      }
64 *  }
65 * </pre>
66 *
67 * @author Mark Hayes
68 */
69public interface Enhanced {
70
71    /**
72     * @see Accessor#newInstance
73     */
74    Object bdbNewInstance();
75
76    /**
77     * @see Accessor#newArray
78     */
79    Object bdbNewArray(int len);
80
81    /**
82     * Calls the super class method if this class does not contain the primary
83     * key field.
84     *
85     * @see Accessor#isPriKeyFieldNullOrZero
86     */
87    boolean bdbIsPriKeyFieldNullOrZero();
88
89    /**
90     * Calls the super class method if this class does not contain the primary
91     * key field.
92     *
93     * @see Accessor#writePriKeyField
94     */
95    void bdbWritePriKeyField(EntityOutput output, Format format);
96
97    /**
98     * Calls the super class method if this class does not contain the primary
99     * key field.
100     *
101     * @see Accessor#readPriKeyField
102     */
103    void bdbReadPriKeyField(EntityInput input, Format format);
104
105    /**
106     * @see Accessor#writeSecKeyFields
107     */
108    void bdbWriteSecKeyFields(EntityOutput output);
109
110    /**
111     * @see Accessor#readSecKeyFields
112     */
113    void bdbReadSecKeyFields(EntityInput input,
114                             int startField,
115                             int endField,
116                             int superLevel);
117
118    /**
119     * @see Accessor#writeNonKeyFields
120     */
121    void bdbWriteNonKeyFields(EntityOutput output);
122
123    /**
124     * @see Accessor#readNonKeyFields
125     */
126    void bdbReadNonKeyFields(EntityInput input,
127                             int startField,
128                             int endField,
129                             int superLevel);
130
131    /**
132     * @see Accessor#getField
133     */
134    Object bdbGetField(Object o,
135                       int field,
136                       int superLevel,
137                       boolean isSecField);
138
139    /**
140     * @see Accessor#setField
141     */
142    void bdbSetField(Object o,
143                     int field,
144                     int superLevel,
145                     boolean isSecField,
146                     Object value);
147}
148