com.persistit.encoding

Class CollectionValueCoder

java.lang.Object

com.persistit.encoding.CollectionValueCoder

All Implemented Interfaces:

ValueCoder, ValueDisplayer, ValueRenderer

public class CollectionValueCoder
extends Object
implements ValueRenderer, ValueDisplayer

Implements ValueCoder, ValueRenderer and ValueDisplayer for selected classes in the Java Collections API. By default an instance of this coder is registered for each of the following concrete classes:

• java.util.ArrayList
• java.util.LinkedList
• java.util.Stack
• java.util.Vector
• java.util.Properties
• java.util.HashMap
• java.util.HashSet
• java.util.Hashtable
• java.util.TreeMap
• java.util.TreeSet
• java.util.LinkedHashMap (Java 1.4+)
• java.util.LinkedHashSet (Java 1.4+)

The stored data consist only of items accessible through the Collection or Map interfaces. For example, implementation details such as the current loadFactor for a HashMap are not stored. For any Collection (including List and Set), the stored format is simply a list of all the values in the order returned by an Iterator. For a Map the stored format is simply a key/value pair for each entry in the order returned by the Iterator returned by the entrySet() method of the Map.

Because customer-written Collection and Map implementations may contain additional internal state that may also need to be stored when they are serialized, this coder is registered only for specific implementations provided by the JRE. You may register and use this ValueCoder for any custom Collection or Map that does not need to serialize additional data.

Note that for ArrayList, Vector, Stack , and other List implementations that do not extend AbstractSequentialList, the serialization logic uses the get(index) method of List to acquire each member rather than constructing an Iterator. Subclasses of AbstractSequentialList are serialized by using an Iterator because access by index may be inefficient.

Since:

1.1

Version:

1.1

Constructor Summary

Constructors

Constructor and Description
CollectionValueCoder()

Method Summary

Modifier and Type	Method and Description
void	display(Value value, StringBuilder target, Class<?> clazz, CoderContext context) Writes a String representation of the value into a supplied StringBuilder.
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.
void	put(Value value, Object object, CoderContext context) Encodes the supplied Object into 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionValueCoder

public CollectionValueCoder()

Method Detail

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 collection. 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

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

display

public void display(Value value,
                    StringBuilder target,
                    Class<?> clazz,
                    CoderContext context)
             throws ConversionException

Writes a String representation of the value into a supplied StringBuilder. This is used in utility programs to display stored content without actually deserialized Objects represented by the value.

This method will be called only if this ValueDisplayer 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:

display in interface ValueDisplayer

Parameters:

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

target - The Appendable 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