com.sleepycat.persist.impl
Class Format

java.lang.Object
  extended by com.sleepycat.persist.impl.Format
All Implemented Interfaces:
Reader, RawType, Serializable
Direct Known Subclasses:
ComplexFormat, CompositeKeyFormat, EnumFormat, NonPersistentFormat, ObjectArrayFormat, PrimitiveArrayFormat, ProxiedFormat, SimpleFormat

public abstract class Format
extends Object
implements Reader, RawType, Serializable

The base class for all object formats. Formats are used to define the stored layout for all persistent classes, including simple types. The design documentation below describes the storage format for entities and its relationship to information stored per format in the catalog. Requirements ------------ + Provides EntityBinding for objects and EntryBinding for keys. + Provides SecondaryKeyCreator, SecondaryMultiKeyCreator and SecondaryMultiKeyNullifier (SecondaryKeyNullifier is redundant). + Works with reflection and bytecode enhancement. + For reflection only, works with any entity model not just annotations. + Bindings are usable independently of the persist API. + Performance is almost equivalent to hand coded tuple bindings. + Small performance penalty for compatible class changes (new fields, widening). + Secondary key create/nullify do not have to deserialize the entire record; in other words, store secondary keys at the start of the data. Class Format ------------ Every distinct class format is given a unique format ID. Class IDs are not equivalent to class version numbers (as in the version property of @Entity and @Persistent) because the format can change when the version number does not. Changes that cause a unique format ID to be assigned are: + Add field. + Widen field type. + Change primitive type to primitive wrapper class. + Add or drop secondary key. + Any incompatible class change. The last item, incompatible class changes, also correspond to a class version change. For each distinct class format the following information is conceptually stored in the catalog, keyed by format ID. - Class name - Class version number - Superclass format - Kind: simple, enum, complex, array - For kind == simple: - Primitive class - For kind == enum: - Array of constant names, sorted by name. - For kind == complex: - Primary key fieldInfo, or null if no primary key is declared - Array of secondary key fieldInfo, sorted by field name - Array of other fieldInfo, sorted by field name - For kind == array: - Component class format - Number of array dimensions - Other metadata for RawType Where fieldInfo is: - Field name - Field class - Other metadata for RawField Data Layout ----------- For each entity instance the data layout is as follows: instanceData: formatId keyFields... nonKeyFields... keyFields: fieldValue... nonKeyFields: fieldValue... The formatId is the (positive non-zero) ID of a class format, defined above. This is ID of the most derived class of the instance. It is stored as a packed integer. Following the format ID, zero or more sets of secondary key field values appear, followed by zero or more sets of other class field values. The keyFields are the sets of secondary key fields for each class in order of the highest superclass first. Within a class, fields are ordered by field name. The nonKeyFields are the sets of other non-key fields for each class in order of the highest superclass first. Within a class, fields are ordered by field name. A field value is: fieldValue: primitiveValue | nullId | instanceRef | instanceData | simpleValue | enumValue | arrayValue For a primitive type, a primitive value is used as defined for tuple bindings. For float and double, sorted float and sorted double tuple values are used. For a non-primitive type with a null value, a nullId is used that has a zero (illegal formatId) value. This includes String and other simple reference types. The formatId is stored as a packed integer, meaning that it is stored as a single zero byte. For a non-primitive type, an instanceRef is used for a non-null instance that appears earlier in the data byte array. An instanceRef is the negation of the byte offset of the instanceData that appears earlier. It is stored as a packed integer. The remaining rules apply only to reference types with non-null values that do not appear earlier in the data array. For an array type, an array formatId is used that identifies the component type and the number of array dimensions. This is followed by an array length (stored as a packed integer) and zero or more fieldValue elements. For an array with N+1 dimensions where N is greater than zero, the leftmost dimension is enumerated such that each fieldValue element is itself an array of N dimensions or null. arrayValue: formatId length fieldValue... For an enum type, an enumValue is used, consisting of a formatId that identifies the enum class and an enumIndex (stored as a packed integer) that identifies the constant name in the enum constant array of the enum class format: enumValue: formatId enumIndex For a simple type, a simpleValue is used. This consists of the formatId that identifies the class followed by the simple type value. For a primitive wrapper type the simple type value is the corresponding primitive, for a Date it is the milliseconds as a long primitive, and for BigInteger or BigDecimal it is a byte array as defined for tuple bindings of these types. simpleValue: formatId value For all other complex types, an instanceData is used, which is defined above. Secondary Keys -------------- For secondary key support we must account for writing and nullifying specific keys. Rather than instantiating the entity and then performing the secondary key operation, we strive to perform the secondary key operation directly on the byte format. To create a secondary key we skip over other fields and then copy the bytes of the embedded key. This approach is very efficient because a) the entity is not instantiated, and b) the secondary keys are stored at the beginning of the byte format and can be quickly read. To nullify we currently instantiate the raw entity, set the key field to null (or remove it from the array/collection), and convert the raw entity back to bytes. Although the performance of this approach is not ideal because it requires serialization, it avoids the complexity of modifying the packed serialized format directly, adjusting references to key objects, etc. Plus, when we nullify a key we are going to write the record, so the serialization overhead may not be significant. For the record, I tried implementing nullification of the bytes directly and found it was much too complex. Lifecycle --------- Format are managed by a Catalog class. Simple formats are managed by SimpleCatalog, and are copied from the SimpleCatalog by PersistCatalog. Other formats are managed by PersistCatalog. The lifecycle of a format instance is: - Constructed by the catalog when a format is requested for a Class that currently has no associated format. - The catalog calls setId() and adds the format to its format list (indexed by format id) and map (keyed by class name). - The catalog calls collectRelatedFormats(), where a format can create additional formats that it needs, or that should also be persistent. - The catalog calls initializeIfNeeded(), which calls the initialize() method of the format class. - initialize() should initialize any transient fields in the format. initialize() can assume that all related formats are available in the catalog. It may call initializeIfNeeded() for those related formats, if it needs to interact with an initialized related format; this does not cause a cycle, because initializeIfNeeded() does nothing for an already initialized format. - The catalog creates a group of related formats at one time, and then writes its entire list of formats to the catalog DB as a single record. This grouping reduces the number of writes. - When a catalog is opened and the list of existing formats is read. After a format is deserialized, its initializeIfNeeded() method is called. setId() and collectRelatedFormats() are not called, since the ID and related formats are stored in serialized fields. - There are two modes for opening an existing catalog: raw mode and normal mode. In raw mode, the old format is used regardless of whether it matches the current class definition; in fact the class is not accessed and does not need to be present. - In normal mode, for each existing format that is initialized, a new format is also created based on the current class and metadata definition. If the two formats are equal, the new format is discarded. If they are unequal, the new format becomes the current format and the old format's evolve() method is called. evolve() is responsible for adjusting the old format for class evolution. Any number of non-current formats may exist for a given class, and are setup to evolve the single current format for the class.

Author:
Mark Hayes
See Also:
Serialized Form

Field Summary
(package private) static int ID_BIGDEC
          BigDecimal
(package private) static int ID_BIGINT
          BigInteger
(package private) static int ID_BOOL
          Boolean
(package private) static int ID_BOOL_W
           
(package private) static int ID_BYTE
          Byte
(package private) static int ID_BYTE_W
           
(package private) static int ID_CHAR
          Character
(package private) static int ID_CHAR_W
           
(package private) static int ID_DATE
          Date
(package private) static int ID_DOUBLE
          Double
(package private) static int ID_DOUBLE_W
           
(package private) static int ID_FLOAT
          Float
(package private) static int ID_FLOAT_W
           
(package private) static int ID_INT
          Integer
(package private) static int ID_INT_W
           
(package private) static int ID_LONG
          Long
(package private) static int ID_LONG_W
           
(package private) static int ID_NULL
          Null reference.
(package private) static int ID_NUMBER
          Number
(package private) static int ID_OBJECT
          Object
(package private) static int ID_PREDEFINED
          Last predefined ID, after which dynamic IDs are assigned.
(package private) static int ID_SHORT
          Short
(package private) static int ID_SHORT_W
           
(package private) static int ID_SIMPLE_MAX
          Last simple type.
(package private) static int ID_SIMPLE_MIN
          First simple type.
(package private) static int ID_STRING
          String
 
Constructor Summary
Format(Catalog catalog, Class type)
          Creates a new format for a given class.
Format(Catalog catalog, String className)
          Creates a format for class evolution when no class may be present.
 
Method Summary
 boolean allowEvolveFromProxy()
          Currently, only FBigDec will return true.
(package private)  boolean areNestedRefsProhibited()
          Certain formats (ProxiedFormat for example) prohibit nested fields that reference the parent object.
(package private) abstract  void collectRelatedFormats(Catalog catalog, Map<String,Format> newFormats)
          Calls catalog.createFormat for formats that this format depends on, or that should also be persistent.
(package private)  Object convertRawObject(Catalog catalog, boolean rawAccess, RawObject rawObject, IdentityHashMap converted)
          Converts a RawObject to a current class object and adds the converted pair to the converted map.
(package private)  void copySecKey(RecordInput input, RecordOutput output)
          Called after skipToSecKey() to copy the data bytes of a singular (XXX_TO_ONE) key field.
(package private)  void copySecMultiKey(RecordInput input, Format keyFormat, Set results)
          Called after skipToSecKey() to copy the data bytes of an array or collection (XXX_TO_MANY) key field.
(package private) abstract  boolean evolve(Format newFormat, Evolver evolver)
          Called for an existing format that may not equal the current format for the same class.
(package private)  boolean evolveMetadata(Format newFormat, Converter converter, Evolver evolver)
          Called when a Converter handles evolution of a class, but we may still need to evolve the metadata.
 Accessor getAccessor(boolean rawAccess)
           
(package private)  Catalog getCatalog()
           
 ClassMetadata getClassMetadata()
          Returns the original model class metadata used to create this class, or null if this is not a model class.
 String getClassName()
          Returns the class name for this type in the format specified by Class.getName().
 Format getComponentType()
          Returns the array component type, or null if this is not an array type.
 int getDimensions()
          Returns the number of array dimensions, or zero if this is not an array type.
(package private)  ComplexFormat getEntityFormat()
          For an entity class or subclass, returns the base entity class; returns null in other cases.
 EntityMetadata getEntityMetadata()
          Returns the original model entity metadata used to create this class, or null if this is not an entity class.
 List<String> getEnumConstants()
          Returns an unmodifiable list of the names of the enum instances, or null if this is not an enum type.
(package private)  boolean getEvolveNeeded()
          Overridden by ComplexFormat.
(package private)  Class getExistingType()
          Called to get the type when it is known to exist for an uninitialized format.
 Map<String,RawField> getFields()
          Returns a map of field name to raw field for each non-static non-transient field declared in this class, or null if this is not a complex type (in other words, this is a simple type or an array type).
 int getId()
          Returns the format ID.
(package private)  Format getLatestVersion()
          If this is the latest/evolved format, returns this; otherwise, returns the current version of this format.
(package private)  boolean getNewStringFormat()
          For an entity format, returns whether the entity was written using the new String format.
 String getOldKeyName(String keyName)
          For an entity class or subclass, returns the old key name for the given key name that has been renamed, or returns the given key name if it has not been renamed.
 Format getPreviousVersion()
          Returns the previous version of this format in the linked list of versions, or null if this is the only version.
(package private)  Format getProxiedFormat()
          Returns the format that is proxied by this format.
(package private)  Reader getReader()
          Returns the object for reading objects of the latest format.
(package private)  Format getSequenceKeyFormat()
          Validates and returns the simple integer key format for a sequence key associated with this format.
(package private)  Format getSuperFormat()
          Returns the format of the superclass.
 Format getSuperType()
          Returns the type of the superclass, or null if the superclass is Object or this is not a complex type (in other words, this is a simple type or an array type).
(package private)  Class getType()
          Returns the class that this format represents.
 int getVersion()
          Returns the class version for this type.
(package private)  Format getWrapperFormat()
          For primitive types only, returns their associated wrapper type.
(package private)  void initCatalog(Catalog catalog)
          Initialize transient catalog field after deserialization.
(package private) abstract  void initialize(Catalog catalog, EntityModel model, int initVersion)
          Initializes an uninitialized format, initializing its related formats (superclass formats and array component formats) first.
(package private)  void initializeIfNeeded(Catalog catalog, EntityModel model)
          Called by the Catalog to initialize a format, and may also be called during initialize() for a related format to ensure that the related format is initialized.
 void initializeReader(Catalog catalog, EntityModel model, int initVersion, Format oldFormat)
          Called to initialize a separate Reader implementation.
 boolean isArray()
          Returns whether this is an array type.
(package private)  boolean isAssignableTo(Format format)
          Called by EntityOutput in rawAccess mode to determine whether an object type is allowed to be assigned to a given field type.
(package private)  boolean isCurrentVersion()
          Returns whether this format is the current format for its class.
 boolean isDeleted()
          Returns whether the class for this format was deleted.
(package private)  boolean isEntity()
          Returns whether this format class is an entity class.
 boolean isEnum()
          Returns whether this is an enum type.
(package private)  boolean isInitialized()
           
(package private)  boolean isModelClass()
          Returns whether this class is present in the EntityModel.
(package private)  boolean isNew()
           
(package private) static boolean isPredefined(Format format)
           
(package private)  boolean isPriKeyNullOrZero(Object o, boolean rawAccess)
          Returns whether the entity's primary key field is null or zero, as defined for primary keys that are assigned from a sequence.
 boolean isPrimitive()
          Returns whether this type is a Java primitive: char, byte, short, int, long, float or double.
(package private)  boolean isSameClass(Format other)
          Returns whether this format has the same class as the given format, irrespective of version changes and renaming.
 boolean isSimple()
          Returns whether this is a simple type: primitive, primitive wrapper, BigInteger, BigDecimal, String or Date.
(package private)  void migrateFromBeta(Map<String,Format> formatMap)
          Special handling for JE 3.0.12 beta formats.
(package private) abstract  Object newArray(int len)
          Creates an array of the format's class of the given length, as if Array.newInstance(getType(), len) were called.
abstract  Object newInstance(EntityInput input, boolean rawAccess)
          Creates a new instance of the target class using its default constructor.
(package private)  boolean nullifySecKey(Catalog catalog, Object entity, String keyName, Object keyElement)
          Nullifies the given key field in the given RawObject -- rawAccess mode is implied.
abstract  Object readObject(Object o, EntityInput input, boolean rawAccess)
          Called after newInstance() to read the rest of the data bytes and fill in the object contents.
 void readPriKey(Object o, EntityInput input, boolean rawAccess)
          Reads the primary key from the given input bytes and sets the primary key field in the given object.
(package private)  void setDeleted(boolean deleted)
          Called by the Evolver when applying a Deleter mutation.
(package private)  void setEvolveNeeded(boolean needed)
          Called by the Evolver with true when an entity format or any of its nested format were changed.
(package private)  void setId(int id)
          Called by the Catalog to set the format ID when a new format is added to the format list, before calling initializeIfNeeded().
(package private)  void setLatestVersion(Format newFormat)
          Called by Evolver to set the latest format when this old format is evolved.
(package private)  void setProxiedFormat(Format proxiedFormat)
          Called by ProxiedFormat to set the proxied format.
(package private)  void setReader(Reader reader)
          Changes the reader during format evolution.
(package private)  void setSuperFormat(Format superFormat)
          Called to set the format of the superclass during initialize().
(package private)  void setUnused(boolean unused)
          Called by the Evolver for a format that is never referenced.
(package private) abstract  void skipContents(RecordInput input)
          Skips over the object's contents, as if readObject() were called, but without returning an object.
(package private)  Format skipToSecKey(RecordInput input, String keyName)
          When extracting a secondary key, called to skip over all fields up to the given secondary key field.
 String toString()
          Returns an XML representation of the raw type.
(package private) abstract  void writeObject(Object o, EntityOutput output, boolean rawAccess)
          Writes a given instance of the target class to the output data bytes.
(package private)  void writePriKey(Object o, EntityOutput output, boolean rawAccess)
          Gets the primary key field from the given object and writes it to the given output data bytes.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ID_NULL

static final int ID_NULL
Null reference.

See Also:
Constant Field Values

ID_OBJECT

static final int ID_OBJECT
Object

See Also:
Constant Field Values

ID_BOOL

static final int ID_BOOL
Boolean

See Also:
Constant Field Values

ID_BOOL_W

static final int ID_BOOL_W
See Also:
Constant Field Values

ID_BYTE

static final int ID_BYTE
Byte

See Also:
Constant Field Values

ID_BYTE_W

static final int ID_BYTE_W
See Also:
Constant Field Values

ID_SHORT

static final int ID_SHORT
Short

See Also:
Constant Field Values

ID_SHORT_W

static final int ID_SHORT_W
See Also:
Constant Field Values

ID_INT

static final int ID_INT
Integer

See Also:
Constant Field Values

ID_INT_W

static final int ID_INT_W
See Also:
Constant Field Values

ID_LONG

static final int ID_LONG
Long

See Also:
Constant Field Values

ID_LONG_W

static final int ID_LONG_W
See Also:
Constant Field Values

ID_FLOAT

static final int ID_FLOAT
Float

See Also:
Constant Field Values

ID_FLOAT_W

static final int ID_FLOAT_W
See Also:
Constant Field Values

ID_DOUBLE

static final int ID_DOUBLE
Double

See Also:
Constant Field Values

ID_DOUBLE_W

static final int ID_DOUBLE_W
See Also:
Constant Field Values

ID_CHAR

static final int ID_CHAR
Character

See Also:
Constant Field Values

ID_CHAR_W

static final int ID_CHAR_W
See Also:
Constant Field Values

ID_STRING

static final int ID_STRING
String

See Also:
Constant Field Values

ID_BIGINT

static final int ID_BIGINT
BigInteger

See Also:
Constant Field Values

ID_BIGDEC

static final int ID_BIGDEC
BigDecimal

See Also:
Constant Field Values

ID_DATE

static final int ID_DATE
Date

See Also:
Constant Field Values

ID_NUMBER

static final int ID_NUMBER
Number

See Also:
Constant Field Values

ID_SIMPLE_MIN

static final int ID_SIMPLE_MIN
First simple type.

See Also:
Constant Field Values

ID_SIMPLE_MAX

static final int ID_SIMPLE_MAX
Last simple type.

See Also:
Constant Field Values

ID_PREDEFINED

static final int ID_PREDEFINED
Last predefined ID, after which dynamic IDs are assigned.

See Also:
Constant Field Values
Constructor Detail

Format

Format(Catalog catalog,
       Class type)
Creates a new format for a given class.


Format

Format(Catalog catalog,
       String className)
Creates a format for class evolution when no class may be present.

Method Detail

isPredefined

static boolean isPredefined(Format format)

migrateFromBeta

void migrateFromBeta(Map<String,Format> formatMap)
Special handling for JE 3.0.12 beta formats.


initCatalog

void initCatalog(Catalog catalog)
Initialize transient catalog field after deserialization. This must occur before any other usage.


isNew

final boolean isNew()

getCatalog

final Catalog getCatalog()

getId

public final int getId()
Returns the format ID.

Specified by:
getId in interface RawType

setId

final void setId(int id)
Called by the Catalog to set the format ID when a new format is added to the format list, before calling initializeIfNeeded().


getType

final Class getType()
Returns the class that this format represents. This method will return null in rawAccess mode, or for an unevolved format.


getExistingType

final Class getExistingType()
Called to get the type when it is known to exist for an uninitialized format.


getReader

final Reader getReader()
Returns the object for reading objects of the latest format. For the latest version format, 'this' is returned. For prior version formats, a reader that converts this version to the latest version is returned.


setReader

final void setReader(Reader reader)
Changes the reader during format evolution.


getSuperFormat

final Format getSuperFormat()
Returns the format of the superclass.


setSuperFormat

final void setSuperFormat(Format superFormat)
Called to set the format of the superclass during initialize().


getProxiedFormat

final Format getProxiedFormat()
Returns the format that is proxied by this format. If non-null is returned, then this format is a PersistentProxy.


setProxiedFormat

final void setProxiedFormat(Format proxiedFormat)
Called by ProxiedFormat to set the proxied format.


getLatestVersion

final Format getLatestVersion()
If this is the latest/evolved format, returns this; otherwise, returns the current version of this format. Note that this WILL return a format for a deleted class if the latest format happens to be deleted.


getPreviousVersion

public final Format getPreviousVersion()
Returns the previous version of this format in the linked list of versions, or null if this is the only version.


setLatestVersion

final void setLatestVersion(Format newFormat)
Called by Evolver to set the latest format when this old format is evolved.


isDeleted

public final boolean isDeleted()
Returns whether the class for this format was deleted.

Specified by:
isDeleted in interface RawType

setDeleted

final void setDeleted(boolean deleted)
Called by the Evolver when applying a Deleter mutation.


setUnused

final void setUnused(boolean unused)
Called by the Evolver for a format that is never referenced.


setEvolveNeeded

void setEvolveNeeded(boolean needed)
Called by the Evolver with true when an entity format or any of its nested format were changed. Called by Store.evolve when an entity has been fully converted. Overridden by ComplexFormat.


getEvolveNeeded

boolean getEvolveNeeded()
Overridden by ComplexFormat.


getNewStringFormat

boolean getNewStringFormat()
For an entity format, returns whether the entity was written using the new String format. For a non-entity format, this method should not be called. Overridden by ComplexFormat.


isInitialized

final boolean isInitialized()

initializeIfNeeded

final void initializeIfNeeded(Catalog catalog,
                              EntityModel model)
Called by the Catalog to initialize a format, and may also be called during initialize() for a related format to ensure that the related format is initialized. This latter case is allowed to support bidirectional dependencies. This method will do nothing if the format is already intialized.


initializeReader

public void initializeReader(Catalog catalog,
                             EntityModel model,
                             int initVersion,
                             Format oldFormat)
Called to initialize a separate Reader implementation. This method is called when no separate Reader exists, and does nothing.

Specified by:
initializeReader in interface Reader

areNestedRefsProhibited

boolean areNestedRefsProhibited()
Certain formats (ProxiedFormat for example) prohibit nested fields that reference the parent object. [#15815]


getClassName

public String getClassName()
Description copied from interface: RawType
Returns the class name for this type in the format specified by Class.getName().

If this class currently exists (has not been removed or renamed) then the class name may be passed to Class.forName(java.lang.String) to get the current Class object. However, if this raw type is not the current version of the class, this type information may differ from that of the current Class.

Specified by:
getClassName in interface RawType

getVersion

public int getVersion()
Description copied from interface: RawType
Returns the class version for this type. For simple types, zero is always returned.

Specified by:
getVersion in interface RawType
See Also:
Entity.version(), Persistent.version()

getSuperType

public Format getSuperType()
Description copied from interface: RawType
Returns the type of the superclass, or null if the superclass is Object or this is not a complex type (in other words, this is a simple type or an array type).

Specified by:
getSuperType in interface RawType

isSimple

public boolean isSimple()
Description copied from interface: RawType
Returns whether this is a simple type: primitive, primitive wrapper, BigInteger, BigDecimal, String or Date.

If true is returned, RawType.isPrimitive() can be called for more information, and a raw value of this type is represented as a simple type object (not as a RawObject).

If false is returned, this is a complex type, an array type (see RawType.isArray()), or an enum type, and a raw value of this type is represented as a RawObject.

Specified by:
isSimple in interface RawType

isPrimitive

public boolean isPrimitive()
Description copied from interface: RawType
Returns whether this type is a Java primitive: char, byte, short, int, long, float or double.

If true is returned, this is also a simple type. In other words, primitive types are a subset of simple types.

If true is returned, a raw value of this type is represented as a non-null instance of the primitive type's wrapper class. For example, an int raw value is represented as an Integer.

Specified by:
isPrimitive in interface RawType

isEnum

public boolean isEnum()
Description copied from interface: RawType
Returns whether this is an enum type.

If true is returned, a value of this type is a RawObject and the enum constant String is available via RawObject.getEnum().

If false is returned, then this is a complex type, an array type (see RawType.isArray()), or a simple type (see RawType.isSimple()).

Specified by:
isEnum in interface RawType

getEnumConstants

public List<String> getEnumConstants()
Description copied from interface: RawType
Returns an unmodifiable list of the names of the enum instances, or null if this is not an enum type.

Specified by:
getEnumConstants in interface RawType

isArray

public boolean isArray()
Description copied from interface: RawType
Returns whether this is an array type. Raw value arrays are represented as RawObject instances.

If true is returned, the array component type is returned by RawType.getComponentType() and the number of array dimensions is returned by RawType.getDimensions().

If false is returned, then this is a complex type, an enum type (see RawType.isEnum()), or a simple type (see RawType.isSimple()).

Specified by:
isArray in interface RawType

getDimensions

public int getDimensions()
Description copied from interface: RawType
Returns the number of array dimensions, or zero if this is not an array type.

Specified by:
getDimensions in interface RawType

getComponentType

public Format getComponentType()
Description copied from interface: RawType
Returns the array component type, or null if this is not an array type.

Specified by:
getComponentType in interface RawType

getFields

public Map<String,RawField> getFields()
Description copied from interface: RawType
Returns a map of field name to raw field for each non-static non-transient field declared in this class, or null if this is not a complex type (in other words, this is a simple type or an array type).

Specified by:
getFields in interface RawType

getClassMetadata

public ClassMetadata getClassMetadata()
Description copied from interface: RawType
Returns the original model class metadata used to create this class, or null if this is not a model class.

Specified by:
getClassMetadata in interface RawType

getEntityMetadata

public EntityMetadata getEntityMetadata()
Description copied from interface: RawType
Returns the original model entity metadata used to create this class, or null if this is not an entity class.

Specified by:
getEntityMetadata in interface RawType

isAssignableTo

boolean isAssignableTo(Format format)
Called by EntityOutput in rawAccess mode to determine whether an object type is allowed to be assigned to a given field type.


getWrapperFormat

Format getWrapperFormat()
For primitive types only, returns their associated wrapper type.


isEntity

boolean isEntity()
Returns whether this format class is an entity class.


isModelClass

boolean isModelClass()
Returns whether this class is present in the EntityModel. Returns false for a simple type, array type, or enum type.


getEntityFormat

ComplexFormat getEntityFormat()
For an entity class or subclass, returns the base entity class; returns null in other cases.


evolve

abstract boolean evolve(Format newFormat,
                        Evolver evolver)
Called for an existing format that may not equal the current format for the same class.

If this method returns true, then it must have determined one of two things: - that the old and new formats are equal, and it must have called Evolver.useOldFormat; or - that the old format can be evolved to the new format, and it must have called Evolver.useEvolvedFormat.

If this method returns false, then it must have determined that the old format could not be evolved to the new format, and it must have called Evolver.addInvalidMutation, addMissingMutation or addEvolveError.


evolveMetadata

boolean evolveMetadata(Format newFormat,
                       Converter converter,
                       Evolver evolver)
Called when a Converter handles evolution of a class, but we may still need to evolve the metadata.


isCurrentVersion

final boolean isCurrentVersion()
Returns whether this format is the current format for its class. If false is returned, this format is setup to evolve to the current format.


isSameClass

final boolean isSameClass(Format other)
Returns whether this format has the same class as the given format, irrespective of version changes and renaming.


initialize

abstract void initialize(Catalog catalog,
                         EntityModel model,
                         int initVersion)
Initializes an uninitialized format, initializing its related formats (superclass formats and array component formats) first.


collectRelatedFormats

abstract void collectRelatedFormats(Catalog catalog,
                                    Map<String,Format> newFormats)
Calls catalog.createFormat for formats that this format depends on, or that should also be persistent.


newArray

abstract Object newArray(int len)
Creates an array of the format's class of the given length, as if Array.newInstance(getType(), len) were called. Formats implement this method for specific classes, or call the accessor, to avoid the reflection overhead of Array.newInstance.


newInstance

public abstract Object newInstance(EntityInput input,
                                   boolean rawAccess)
                            throws RefreshException
Creates a new instance of the target class using its default constructor. Normally this creates an empty object, and readObject() is called next to fill in the contents. This is done in two steps to allow the instance to be registered by EntityInput before reading the contents. This allows the fields in an object or a nested object to refer to the parent object in a graph. Alternatively, this method may read all or the first portion of the data, rather than that being done by readObject(). This is required for simple types and enums, where the object cannot be created without reading the data. In these cases, there is no possibility that the parent object will be referenced by the child object in the graph. It should not be done in other cases, or the graph references may not be maintained faithfully. Is public only in order to implement the Reader interface. Note that this method should only be called directly in raw conversion mode or during conversion of an old format. Normally it should be called via the getReader method and the Reader interface.

Specified by:
newInstance in interface Reader
Throws:
RefreshException

readObject

public abstract Object readObject(Object o,
                                  EntityInput input,
                                  boolean rawAccess)
                           throws RefreshException
Called after newInstance() to read the rest of the data bytes and fill in the object contents. If the object was read completely by newInstance(), this method does nothing. Is public only in order to implement the Reader interface. Note that this method should only be called directly in raw conversion mode or during conversion of an old format. Normally it should be called via the getReader method and the Reader interface.

Specified by:
readObject in interface Reader
Throws:
RefreshException

writeObject

abstract void writeObject(Object o,
                          EntityOutput output,
                          boolean rawAccess)
                   throws RefreshException
Writes a given instance of the target class to the output data bytes. This is the complement of the newInstance()/readObject() pair.

Throws:
RefreshException

skipContents

abstract void skipContents(RecordInput input)
                    throws RefreshException
Skips over the object's contents, as if readObject() were called, but without returning an object. Used for extracting secondary key bytes without having to instantiate the object. For reference types, the format ID is read just before calling this method, so this method is responsible for skipping everything following the format ID.

Throws:
RefreshException

skipToSecKey

Format skipToSecKey(RecordInput input,
                    String keyName)
              throws RefreshException
When extracting a secondary key, called to skip over all fields up to the given secondary key field. Returns the format of the key field found, or null if the field is not present (nullified) in the object.

Throws:
RefreshException

copySecKey

void copySecKey(RecordInput input,
                RecordOutput output)
Called after skipToSecKey() to copy the data bytes of a singular (XXX_TO_ONE) key field.


copySecMultiKey

void copySecMultiKey(RecordInput input,
                     Format keyFormat,
                     Set results)
               throws RefreshException
Called after skipToSecKey() to copy the data bytes of an array or collection (XXX_TO_MANY) key field.

Throws:
RefreshException

nullifySecKey

boolean nullifySecKey(Catalog catalog,
                      Object entity,
                      String keyName,
                      Object keyElement)
Nullifies the given key field in the given RawObject -- rawAccess mode is implied.


isPriKeyNullOrZero

boolean isPriKeyNullOrZero(Object o,
                           boolean rawAccess)
Returns whether the entity's primary key field is null or zero, as defined for primary keys that are assigned from a sequence.


writePriKey

void writePriKey(Object o,
                 EntityOutput output,
                 boolean rawAccess)
           throws RefreshException
Gets the primary key field from the given object and writes it to the given output data bytes. This is a separate operation because the primary key data bytes are stored separately from the rest of the record.

Throws:
RefreshException

readPriKey

public void readPriKey(Object o,
                       EntityInput input,
                       boolean rawAccess)
                throws RefreshException
Reads the primary key from the given input bytes and sets the primary key field in the given object. This is complement of writePriKey(). Is public only in order to implement the Reader interface. Note that this method should only be called directly in raw conversion mode or during conversion of an old format. Normally it should be called via the getReader method and the Reader interface.

Specified by:
readPriKey in interface Reader
Throws:
RefreshException

getOldKeyName

public String getOldKeyName(String keyName)
For an entity class or subclass, returns the old key name for the given key name that has been renamed, or returns the given key name if it has not been renamed.


getSequenceKeyFormat

Format getSequenceKeyFormat()
Validates and returns the simple integer key format for a sequence key associated with this format. For a composite key type, the format of the one and only field is returned. For a simple integer type, this format is returned. Otherwise (the default implementation), an IllegalArgumentException is thrown.


convertRawObject

Object convertRawObject(Catalog catalog,
                        boolean rawAccess,
                        RawObject rawObject,
                        IdentityHashMap converted)
                  throws RefreshException
Converts a RawObject to a current class object and adds the converted pair to the converted map.

Throws:
RefreshException

allowEvolveFromProxy

public boolean allowEvolveFromProxy()
Currently, only FBigDec will return true. It is a workaround for reading the BigDecimal data stored by BigDecimal proxy before je4.1.


getAccessor

public Accessor getAccessor(boolean rawAccess)
Specified by:
getAccessor in interface Reader

toString

public String toString()
Description copied from interface: RawType
Returns an XML representation of the raw type.

Specified by:
toString in interface RawType
Overrides:
toString in class Object


Copyright (c) 2004-2012 Oracle. All rights reserved.