|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sleepycat.persist.impl.Format
public abstract class Format
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 (see Mutations), 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 evolveTo(newFormat) method is called. evolveTo() 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.
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_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(Class type)
Creates a new format for a given class. |
Method Summary | |
---|---|
(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) void |
copySecKey(EntityInput input,
EntityOutput output)
Called after skipToSecKey() to copy the data bytes of a singular (XXX_TO_ONE) key field. |
(package private) void |
copySecMultiKey(EntityInput input,
Format keyFormat,
Set results)
Called after skipToSecKey() to copy the data bytes of an array or collection (XXX_TO_MANY) key field. |
boolean |
equals(Object other)
Used to compare the current version and an old version, to determine whether class evolution is needed. |
(package private) Format |
evolveTo(Format newFormat)
Called for an existing format that does not equal the current format for the same class. |
(package private) 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) Format |
getEntityFormat()
For an entity class or subclass, returns the base entity class; returns null in other cases. |
(package private) 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. |
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). |
(package private) int |
getId()
Returns the format ID. |
(package private) Format |
getProxiedFormat()
Returns the format that is proxied by 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) abstract void |
initialize(Catalog catalog)
Initializes an uninitialized format, initializing its related formats (superclass formats and array component formats) first. |
(package private) void |
initializeIfNeeded(Catalog catalog)
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. |
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. |
(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 |
isModelClass()
Returns whether this class is present in the EntityModel. |
(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. |
boolean |
isSimple()
Returns whether this is a simple type: primitive, primitive wrapper, String or Date. |
(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. |
(package private) 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. |
(package private) abstract void |
readObject(Object o,
EntityInput input,
boolean rawAccess)
Called after newInstance() to read the rest of the data bytes and fill in the object contents. |
(package private) 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 |
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 |
setProxiedFormat(Format proxiedFormat)
Called by ProxiedFormat to set the proxied format. |
(package private) void |
setSuperFormat(Format superFormat)
Called to set the format of the superclass during initialize(). |
(package private) abstract void |
skipContents(EntityInput input)
Skips over the object's contents, as if readObject() were called, but without returning an object. |
(package private) Format |
skipToSecKey(EntityInput input,
String keyName)
When extracting a secondary key, called to skip over all fields up to the given secondary key field. |
(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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
static final int ID_NULL
static final int ID_OBJECT
static final int ID_BOOL
static final int ID_BOOL_W
static final int ID_BYTE
static final int ID_BYTE_W
static final int ID_SHORT
static final int ID_SHORT_W
static final int ID_INT
static final int ID_INT_W
static final int ID_LONG
static final int ID_LONG_W
static final int ID_FLOAT
static final int ID_FLOAT_W
static final int ID_DOUBLE
static final int ID_DOUBLE_W
static final int ID_CHAR
static final int ID_CHAR_W
static final int ID_STRING
static final int ID_BIGINT
static final int ID_BIGDEC
static final int ID_DATE
static final int ID_SIMPLE_MIN
static final int ID_SIMPLE_MAX
static final int ID_PREDEFINED
Constructor Detail |
---|
Format(Class type)
Method Detail |
---|
static boolean isPredefined(Format format)
final int getId()
final void setId(int id)
final Class getType()
final Format getSuperFormat()
final void setSuperFormat(Format superFormat)
final Format getProxiedFormat()
final void setProxiedFormat(Format proxiedFormat)
final void initializeIfNeeded(Catalog catalog)
Format evolveTo(Format newFormat)
boolean isCurrentVersion()
public String getClassName()
RawType
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
.
getClassName
in interface RawType
public int getVersion()
RawType
getVersion
in interface RawType
Entity.version()
,
Persistent.version()
public Format getSuperType()
RawType
getSuperType
in interface RawType
public boolean isSimple()
RawType
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
.
isSimple
in interface RawType
public boolean isPrimitive()
RawType
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
.
isPrimitive
in interface RawType
public boolean isEnum()
RawType
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()
).
isEnum
in interface RawType
public List<String> getEnumConstants()
RawType
getEnumConstants
in interface RawType
public boolean isArray()
RawType
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()
).
isArray
in interface RawType
public int getDimensions()
RawType
getDimensions
in interface RawType
public Format getComponentType()
RawType
getComponentType
in interface RawType
public Map<String,RawField> getFields()
RawType
getFields
in interface RawType
boolean isAssignableTo(Format format)
Format getWrapperFormat()
boolean isEntity()
boolean isModelClass()
ClassMetadata getClassMetadata()
EntityMetadata getEntityMetadata()
Format getEntityFormat()
public boolean equals(Object other)
equals
in class Object
abstract void initialize(Catalog catalog)
abstract void collectRelatedFormats(Catalog catalog, Map<String,Format> newFormats)
abstract Object newArray(int len)
abstract Object newInstance(EntityInput input, boolean rawAccess)
abstract void readObject(Object o, EntityInput input, boolean rawAccess)
abstract void writeObject(Object o, EntityOutput output, boolean rawAccess)
abstract void skipContents(EntityInput input)
Format skipToSecKey(EntityInput input, String keyName)
void copySecKey(EntityInput input, EntityOutput output)
void copySecMultiKey(EntityInput input, Format keyFormat, Set results)
boolean nullifySecKey(Catalog catalog, Object entity, String keyName, Object keyElement)
boolean isPriKeyNullOrZero(Object o, boolean rawAccess)
void writePriKey(Object o, EntityOutput output, boolean rawAccess)
void readPriKey(Object o, EntityInput input, boolean rawAccess)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |