/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2002,2008 Oracle.  All rights reserved.
 *
 * $Id: Accessor.java,v 1.1 2008/02/07 17:12:27 mark Exp $
 */

package com.sleepycat.persist.impl;

/**
 * Field binding operations implemented via reflection (ReflectionAccessor) or
 * bytecode enhancement (EnhancedAccessor).
 *
 * <p>Normally we read the set of all secondary key fields first and then the
 * set of all non-key fields, reading each set in order of field name.  But
 * when reading an old format record we must account for the following
 * class evolution conversions:</p>
 * <ul>
 * <li>Convert a field: pass value thru converter</li>
 * <li>Widen a field type: pass value thru widener</li>
 * <li>Add a field: don't read the new field</li>
 * <li>Delete a field: skip the deleted field</li>
 * <li>Rename a field: read field in a different order</li>
 * </ul>
 * <p>To support these operations, the methods for reading fields allow reading
 * specific ranges of fields as well as all fields.  For example, all fields
 * up to a deleted field could be read, and then all fields from the following
 * field onward.</p>
 *
 * @author Mark Hayes
 */
interface Accessor {

    /**
     * A large field value to use instead of Integer.MAX_VALUE, to work around
     * Java JIT compiler bug when doing an (X <= Integer.MAX_VALUE) as would be
     * done in readXxxKeyFields methods.
     */
    final int MAX_FIELD_NUM = Integer.MAX_VALUE - 1;

    /**
     * Creates a new instance of the target class using its default
     * constructor.
     */
    Object newInstance();

    /**
     * Creates a new one dimensional array of the given length, having the
     * target class as its component type.
     *
     * <p>Using a special method for a one dimensional array, which can be
     * implemented by bytecode generation, is a compromise.  We use reflection
     * to create multidimensional arrays.  We could in the future generate code
     * to create arrays as they are encountered, if there is a need to avoid
     * reflection for multidimensional arrays.</p>
     */
    Object newArray(int len);

    /**
     * Returns whether the primary key field is null (for a reference type) or
     * zero (for a primitive integer type).  Null and zero are used as an
     * indication that the key should be assigned from a sequence.
     */
    boolean isPriKeyFieldNullOrZero(Object o);

    /**
     * Writes the primary key field value to the given EntityOutput.
     *
     * <p>To write a primary key with a reference type, this method must call
     * EntityOutput.writeKeyObject.</p>
     *
     * @param o is the object whose primary key field is to be written.
     *
     * @param output the output data to write to.
     */
    void writePriKeyField(Object o, EntityOutput output);

    /**
     * Reads the primary key field value from the given EntityInput.
     *
     * <p>To read a primary key with a reference type, this method must call
     * EntityInput.readKeyObject.</p>
     *
     * @param o is the object whose primary key field is to be read.
     *
     * @param input the input data to read from.
     */
    void readPriKeyField(Object o, EntityInput input);

    /**
     * Writes all secondary key field values to the given EntityOutput,
     * writing fields in super classes first and in name order within class.
     *
     * @param o is the object whose secondary key fields are to be written.
     *
     * <p>If the primary key has a reference type, this method must call
     * EntityOutput.registerPriKeyObject before writing any other fields.</p>
     *
     * @param output the output data to write to.
     */
    void writeSecKeyFields(Object o, EntityOutput output);

    /**
     * Reads a range of secondary key field values from the given EntityInput,
     * reading fields in super classes first and in name order within class.
     *
     * <p>If the primary key has a reference type, this method must call
     * EntityInput.registerPriKeyObject before reading any other fields.</p>
     *
     * <p>To read all fields, pass -1 for superLevel, zero for startField and
     * MAX_FIELD_NUM for endField.  Fields from super classes are read
     * first.</p>
     *
     * <p>To read a specific range of fields, pass a non-negative number for
     * superLevel and the specific indices of the field range to be read in the
     * class at that level.</p>
     *
     * @param o is the object whose secondary key fields are to be read.
     *
     * @param input the input data to read from.
     *
     * @param startField the starting field index in the range of fields to
     * read.  To read all fields, the startField should be zero.
     *
     * @param endField the ending field index in the range of fields to read.
     * To read all fields, the endField should be MAX_FIELD_NUM.
     *
     * @param superLevel is a non-negative number to read the fields of the
     * class that is the Nth super instance; or a negative number to read
     * fields in all classes.
     */
    void readSecKeyFields(Object o,
                          EntityInput input,
                          int startField,
                          int endField,
                          int superLevel);

    /**
     * Writes all non-key field values to the given EntityOutput, writing
     * fields in super classes first and in name order within class.
     *
     * @param o is the object whose non-key fields are to be written.
     *
     * @param output the output data to write to.
     */
    void writeNonKeyFields(Object o, EntityOutput output);

    /**
     * Reads a range of non-key field values from the given EntityInput,
     * reading fields in super classes first and in name order within class.
     *
     * <p>To read all fields, pass -1 for superLevel, zero for startField and
     * MAX_FIELD_NUM for endField.  Fields from super classes are read
     * first.</p>
     *
     * <p>To read a specific range of fields, pass a non-negative number for
     * superLevel and the specific indices of the field range to be read in the
     * class at that level.</p>
     *
     * @param o is the object whose non-key fields are to be read.
     *
     * @param input the input data to read from.
     *
     * @param startField the starting field index in the range of fields to
     * read.  To read all fields, the startField should be zero.
     *
     * @param endField the ending field index in the range of fields to read.
     * To read all fields, the endField should be MAX_FIELD_NUM.
     *
     * @param superLevel is a non-negative number to read the fields of the
     * class that is the Nth super instance; or a negative number to read
     * fields in all classes.
     */
    void readNonKeyFields(Object o,
                          EntityInput input,
                          int startField,
                          int endField,
                          int superLevel);

    /**
     * Returns the value of a given field, representing primitives as primitive
     * wrapper objects.
     *
     * @param o is the object containing the key field.
     *
     * @param field is the field index.
     *
     * @param superLevel is a positive number to identify the field of the
     * class that is the Nth super instance; or zero to identify the field in
     * this class.
     *
     * @param isSecField is true for a secondary key field or false for a
     * non-key field.
     *
     * @return the current field value, or null for a reference type field
     * that is null.
     */
    Object getField(Object o,
                    int field,
                    int superLevel,
                    boolean isSecField);

    /**
     * Changes the value of a given field, representing primitives as primitive
     * wrapper objects.
     *
     * @param o is the object containing the key field.
     *
     * @param field is the field index.
     *
     * @param superLevel is a positive number to identify the field of the
     * class that is the Nth super instance; or zero to identify the field in
     * this class.
     *
     * @param isSecField is true for a secondary key field or false for a
     * non-key field.
     *
     * @param value is the new value of the field, or null to set a reference
     * type field to null.
     */
    void setField(Object o,
                  int field,
                  int superLevel,
                  boolean isSecField,
                  Object value);
}