Package com.persistit.encoding

Implements extended encoding of objects and strings to and from Keys and Values.

See: Description

Interface Summary

Interface	Description
CoderContext	A marker interface for an application-specific object that may be passed to a KeyCoder or ValueCoder.
CoderManager	Manages the collections of KeyCoders and ValueCoders that encode and decode object values in Persistit™.
HandleCache	Interface for an object that can receive and supply an int-valued handle.
KeyCoder	Interface for specialized encoding and decoding of an Object of arbitrary type to or from a Key.
KeyDisplayer	An extension of KeyCoder that adds the KeyDisplayer.displayKeySegment(com.persistit.Key, java.lang.Appendable, java.lang.Class<?>, com.persistit.encoding.CoderContext) method.
KeyRenderer	An extended KeyCoder that can populate a supplied Object with data that was formerly written to a Key by the KeyCoder .
ObjectCoder	Combines the KeyCoder, KeyRenderer, ValueCoder and ValueRenderer into a single interface that allows Persistit to store and retrieve arbitrary objects - even non-Serializable objects - without byte-code enhancement, without incurring the space or time overhead of Java serialization, or the need to modify the class to perform custom serialization.
ValueCoder	Interface for specialized encoding and decoding of Objects of arbitrary type in a Value.
ValueDisplayer	An extension of ValueCoder that adds the ValueDisplayer.display(com.persistit.Value, java.lang.StringBuilder, java.lang.Class<?>, com.persistit.encoding.CoderContext) method.
ValueRenderer	An extended ValueCoder that can populate a supplied Object with data that was formerly written to a Value by the ValueCoder.

Class Summary

Class	Description
CollectionValueCoder	Implements ValueCoder, ValueRenderer and ValueDisplayer for selected classes in the Java Collections API.
EnumValueCoder
ObjectCache	A simple cache for deserialized objects.
SerialValueCoder	A ValueCoder that uses standard Java serialization to store and retrieve object values.

Package com.persistit.encoding Description

Implements extended encoding of objects and strings to and from Keys and Values.

There are three kinds of encoding mechanisms used in Persistit™:

1. Encoding and decoding of objects to and from Keys,
2. Specialized encoding and decoding of java.lang.Strings to and from Keys, and
3. Encoding and decoding of objects to and from Values.

These mechanisms are each slightly different because the correct collation of key values depends on the encoding of primitive values and Objects into Keys, whereas collation is not an issue for the encoding of Values. The encoding of Keys also differs from the encoding of Values because although collation is not an issue for Values, generally the kinds of objects serialized into Values will be much more complex than those usefully encoded into Keys.

Logic for these two different uses is specified by twp different interfaces, KeyCoder and ValueCoder. Each of these has methods to translate an Object to and from an array of bytes.

The specific KeyCoder or ValueCoder to use in encoding or decoding a Key or Value is determined by the current CoderManager. Persistit has a singleton CoderManager at all times. The DefaultCoderManager is a simple implementation that permits applications to register a KeyCoder and ValueCoder implementation for each class that requires extended encoding and decoding.

Note that a ValueCoder registered for a given class overrides default serialization behavior for that class. A ValueCoder can encode state information from a class that is not marked java.io.Serializable or java.io.Externalizable. In addition, a ValueCoder typically represents the state of an object much more concisely than standard object serialization because all class names are represented by system-wide handles rather than class names. (See the ClassIndex class for details on how classes are mapped to small integer handles.)

KeyRenderer and ValueRenderer

The interfaces KeyRenderer and ValueRenderer extends KeyCoder and ValueCoder by adding a render method. The purpose is to allow the application to pass a mutable object that the renderer populates with decoded data, rather than creating a new object for each decoded value. This mutable object, called the target, may be of a different class than the originally encoded value. It is up to the KeyRenderer or ValueRenderer implementation to determine whether a target object is a suitable recipient for the decoded data.

This mechanism can be used to retrieve a subset of all the information that was originally encoded as part of a complex object into a simpler "rendition" object. For example, to display the name, sex and date of birth of numerous complex Person objects, the application could define a class called PersonNameSexDob having only those fields. It could then define a ValueRenderer registered to the Person class that reads and populates only the three relevant fields and skips the rest. The resulting PersonNameSexDob object could then provide the data for a summarized listing of Person objects.

The DefaultObjectCoder class provides a convenient implementation of these interfaces. It uses Java reflection to read and write the fields of an object to and from Persistit Values and Keys.

Finally, the ObjectCache class provides a simple cache for previously loaded objects. Unlike the Persistit buffer pool, ObjectCache caches a fully realized object, rather than pages containing byte arrays from which objects can be deserialized. ObjectCache is similar to a java.util.WeakHashMap, but implements different removal rules that are more appropriate for caching persistent objects.