com.persistit.encoding

Interface KeyCoder

All Known Subinterfaces:

KeyDisplayer, KeyRenderer, ObjectCoder

All Known Implementing Classes:

DefaultObjectCoder

public interface KeyCoder

Interface for specialized encoding and decoding of an Object of arbitrary type to or from a Key. Persistit contains built-in logic to encode Objects of certain classes. By registering a KeyCoder with the current CoderManager you can add encoding for classes that otherwise are not able to be included in Persistit key values.

A KeyCoder implements methods to convert an object of some class to an array of bytes and back again. The byte array is used to identify (or partially identify) a record in a Persistit Tree. A typical KeyCoder simply appends identifying fields of the object.

Version:

1.0

Method Summary

Modifier and Type	Method and Description
void	appendKeySegment(Key key, Object object, CoderContext context) Append a key segment derived from an object to a Key.
Object	decodeKeySegment(Key key, Class<?> clazz, CoderContext context) Decode a key segment as an Object value.
boolean	isZeroByteFree() Since a key segment is terminated by a zero byte value the encoded portion of the segment must not contain zeroes.

Method Detail

appendKeySegment

void appendKeySegment(Key key,
                      Object object,
                      CoderContext context)
               throws ConversionException

Append a key segment derived from an object to a Key. This method will be called only if this KeyCoder 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 Key and its size should be updated to reflect the appended key segment. Use the methods Key.getEncodedBytes(), Key.getEncodedSize() and Key.setEncodedSize(int) to manipulate the byte array directly. More commonly, the implementation of this method will simply append appropriate identifying fields within the object to the key.

This method is not responsible for encoding the class of the object being appended. The caller encodes the identity of the class. This method merely needs to encode the state of the object.

Parameters:

key - The Key to append to

object - The object to encode

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

decodeKeySegment

Object decodeKeySegment(Key key,
                        Class<?> clazz,
                        CoderContext context)
                 throws ConversionException

Decode a key segment as an Object value. This method is invoked when Key.decode(Object) attempts to decode a key segment that was previously append by the appendKeySegment(com.persistit.Key, java.lang.Object, com.persistit.encoding.CoderContext) method. Thus the implementation of this method must precisely decode the same bytes that were generated by the companion appendKeySegment method of this ValueCoder.

This method will be called only if this KeyCoder is registered with the current CoderManager to encode and decode objects of the class that is actually represented in the Key . The class with which the key was encoded is provided as an argument. This permits one KeyCoder to handle multiple classes because the implementation can dispatch to code appropriate for the particular supplied class. The implementation should construct and return an Object having the same class as the supplied class.

When this method is called the value Key.getIndex() will be the offset within the key of the first encoded byte. The key segment is zero-byte terminated.

Parameters:

key - The Key from which data should be decoded

clazz - The expected Class of the returned object

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

isZeroByteFree

boolean isZeroByteFree()
                throws ConversionException

Since a key segment is terminated by a zero byte value the encoded portion of the segment must not contain zeroes. This method should indicate whether the encoding implemented by this KeyCoder produces zero bytes.

If this method returns false then Persistit will insert escape sequences into the encoding produced by appendKeySegment(Key, Object, CoderContext) to a form with no zeroes.

If this method returns true then Persistit will verify that there are no zero bytes and throw an ConversionException otherwise.

Returns:

whether this KeyCoder produces encodings guaranteed not to contain zero bytes

Throws:

ConversionException