com.persistit

Class DefaultValueCoder

java.lang.Object

com.persistit.DefaultValueCoder

All Implemented Interfaces:

HandleCache, ValueCoder, ValueRenderer

Direct Known Subclasses:

DefaultObjectCoder

public class DefaultValueCoder
extends Object
implements ValueRenderer, HandleCache

A ValueCoder that uses reflection to access and modify the fields of an object. This implementation provides the default serialization mechanism for Persistit version 1.1. See Persistit JSA 1.1 Object Serialization for details.

DefaultValueCoder may only be used to serialize and deserialize serializable objects (i.e., instances of classes that implement java.io.Serializable). To the extent possible, the semantics of serialization within this DefaultValueCoder match the Java Object Serialization Specification.

In particular, for Serializable classes, objects are constructed using the no-argument constructor of the nearest non-serializable superclass, as required by the specification. (This behavior can be modified with the constructorOverride system property.) To do so, this implementation invokes a platform-specific, non-public API method of java.io.ObjectStreamClass or java.io.ObjectInputStream.

This implementation invokes the readExternal and writeExternal methods of Externalizable classes, and the readObject, writeObject, readResolve and writeReplace methods of Serializable classes as required by the specification. A special extended ObjectInputStream or ObjectOutputStream implementation is provided when necessary. Although the semantics of the specification are followed, the format of serialized data is optimized for Persistit and does not conform to the specification.

Currently the readObjectNoData method, the readLine method, and the PutField/GetField API elements are not implemented by DefaultValueCoder.

Since:

1.1

Version:

1.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DefaultValueCoder.Builder A component of a DefaultValueCoder that reads and writes data values to and from properties or fields of a client object.

Constructor Summary

Constructors

Constructor and Description
DefaultValueCoder(Persistit persistit, Class clientClass) Contructs a DefaultValueCoder for the specified clientClass.
DefaultValueCoder(Persistit persistit, Class clientClass, Field[] fields) Contructs a DefaultValueCoder for the specified clientClass.

Method Summary

Modifier and Type	Method and Description
Object	get(Value value, Class clazz, CoderContext context) Creates an instance of the supplied class, populates its state by decoding the supplied Value, and returns it.
Class	getClientClass() Return the class that this ObjectCoder serves.
int	getHandle()
DefaultValueCoder.Builder	getValueBuilder() Return the Builder that copies data values between a Value and a client object.
void	put(Value value, Object object, CoderContext context) Encodes the supplied Object into the supplied Value.
void	putDefaultFields(Value value, Object object) Writes the fields of the supplied object to the supplied Value.
void	render(Value value, Object target, Class clazz, CoderContext context) Populates the state of the supplied (mutable) target Object by decoding the supplied Value.
void	setHandle(int handle) Store a supplied handle.
String	toString() Return a String description of this DefaultValueCoder.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultValueCoder

public DefaultValueCoder(Persistit persistit,
                         Class clientClass)
                  throws SecurityException

Contructs a DefaultValueCoder for the specified clientClass. The resulting coder is capable of efficiently serializing and deserializing instances of the class in Persistit records.

The resulting DefaultValueCoder serializes and deserializes the fields defined by standard Java serialization (see the Java Object Serialization Specification. If there is a final static field serialPersistitFields then it defines the fields to be serialized. Otherwise all non-static, non-transient fields, including those defined in superclasses, are included.

Parameters:

clientClass - A (java.io.Serializable) Class of objects to be serialized and deserialized by this DefaultValueCoder

Throws:

SecurityException - if permission to make a non-public field accessible is not granted by the current security policy

ConversionException - if the clientClass does not implement java.io.Serializable, or if the attempt to find an appropriate method for constructing deserialized objects fails.

DefaultValueCoder

public DefaultValueCoder(Persistit persistit,
                         Class clientClass,
                         Field[] fields)

Contructs a DefaultValueCoder for the specified clientClass. The resulting coder is capable of efficiently serializing and deserializing instances of the class in Persistit records. The resulting DefaultValueCoder serializes and deserializes only the specified fields.

Parameters:

clientClass - A (java.io.Serializable) Class of objects to be serialized and deserialized by this DefaultValueCoder

fields - An array of Fields of this class to serialize and deserialize.

Throws:

SecurityException - if permission to make a non-public field accessible is not granted by the current security policy

ConversionException - if the clientClass does not implement java.io.Serializable, or if the attempt to find an appropriate method for constructing deserialized objects fails.

Method Detail

getClientClass

public Class getClientClass()

Return the class that this ObjectCoder serves.

Returns:

The class

put

public void put(Value value,
                Object object,
                CoderContext context)
         throws ConversionException

Encodes the supplied Object into the supplied Value. This method will be called only if this ValueCoder has been registered with the current CoderManager to encode objects having the class of the supplied object.

Upon completion of this method, the backing byte array of the Value and its size should be updated to reflect the serialized object. Use the methods Value.getEncodedBytes(), Value.getEncodedSize() and Value.setEncodedSize(int) to manipulate the byte array directly. More commonly, the implementation of this method will simply call the appropriate put methods to write the interior field values into the Value object.

Specified by:

put in interface ValueCoder

Parameters:

value - The Value to which the interior data of the supplied Object should be encoded

object - The object value to encode. This parameter will never be null because Persistit encodes nulls with a built-in encoding.

context - An arbitrary object that can optionally be supplied by the application to convey an application-specific context for the operation. (See CoderContext.) The default value is null.

Throws:

ConversionException

putDefaultFields

public void putDefaultFields(Value value,
                             Object object)
                      throws ConversionException

Writes the fields of the supplied object to the supplied Value. This method is called directly by put(com.persistit.Value, java.lang.Object, com.persistit.encoding.CoderContext) unless the class defines a writeObject method for custom serialization. This method is also called indirectly by the defaultWriteObject method of the ObjectOutputStream passed to writeObject is called. The collection and ordering of fields to be written is determined by the Java Serialization Specification.

Parameters:

value - The Value into which fields should be put

object - The object whose fields are to be serialized

Throws:

ConversionException

get

public Object get(Value value,
                  Class clazz,
                  CoderContext context)
           throws ConversionException

Creates an instance of the supplied class, populates its state by decoding the supplied Value, and returns it. This method will be called only if this ValueCoder has been registered with the current CoderManager to encode objects having supplied Class value. Persistit will never call this method to decode a value that was null when written because null values are handled by built-in encoding logic.

Specified by:

get in interface ValueCoder

Parameters:

value - The Value from which interior fields of the object are to be retrieved

clazz - The class of the object to be returned.

context - An arbitrary object that can optionally be supplied by the application to convey an application-specific context for the operation. (See CoderContext.) The default value is null.

Returns:

An Object having the same class as the suppled clazz parameter.

Throws:

ConversionException

render

public void render(Value value,
                   Object target,
                   Class clazz,
                   CoderContext context)
            throws ConversionException

Populates the state of the supplied (mutable) target Object by decoding the supplied Value. This method will be called only if this ValueRenderer has been registered with the current CoderManager to encode objects having the supplied Class value. Persistit will never call this method to decode a value that was null when written because null values are handled by built-in encoding logic.

Specified by:

render in interface ValueRenderer

Parameters:

value - The Value from which interior fields of the object are to be retrieved

target - The object into which the decoded value is to be written

clazz - The class of the object that was originally encoded into Value.

context - An arbitrary object that can optionally be supplied by the application to convey an application-specific context for the operation. (See CoderContext.) The default value is null.

Throws:

ConversionException

getValueBuilder

public DefaultValueCoder.Builder getValueBuilder()

Return the Builder that copies data values between a Value and a client object.

Returns:

The Builder

toString

public String toString()

Return a String description of this DefaultValueCoder. The String includes the client class name, and the property or field names identifying the properties and/or fields this coder accesses and modifies.

Overrides:

toString in class Object

Returns:

A String description.

setHandle

public void setHandle(int handle)

Description copied from interface: HandleCache

Store a supplied handle.

Specified by:

setHandle in interface HandleCache

getHandle

public int getHandle()

Specified by:

getHandle in interface HandleCache

Returns:

the stored handle value