com.persistit.encoding.KeyCoder Maven / Gradle / Ivy
Show all versions of akiban-persistit Show documentation
/**
* Copyright © 2005-2012 Akiban Technologies, Inc. All rights reserved.
*
* This program and the accompanying materials are made available
* under the terms of the Eclipse Public License v1.0 which
* accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* This program may also be available under different license terms.
* For more information, see www.akiban.com or contact [email protected].
*
* Contributors:
* Akiban Technologies, Inc.
*/
package com.persistit.encoding;
import com.persistit.Key;
import com.persistit.exception.ConversionException;
/**
*
* Interface for specialized encoding and decoding of an Object of
* arbitrary type to or from a {@link Key}. Persistit contains built-in logic to
* encode Objects of certain classes. By registering a KeyCoder
* with the current {@link 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
*/
public interface KeyCoder {
/**
*
* Append a key segment derived from an object to a {@link Key}. This method
* will be called only if this KeyCoder has been registered
* with the current {@link 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 {@link Key#getEncodedBytes},
* {@link Key#getEncodedSize} and {@link Key#setEncodedSize} 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.
*
*
* @param key
* The {@link Key} to append to
* @param object
* The object to encode
* @param context
* An arbitrary object that can optionally be supplied by the
* application to convey an application-specific context for the
* operation. (See {@link CoderContext}.) The default value is
* null.
*/
public void appendKeySegment(Key key, Object object, CoderContext context) throws ConversionException;
/**
*
* Decode a key segment as an Object value. This method is invoked when
* {@link Key#decode(Object)} attempts to decode a key segment that was
* previously append by the {@link #appendKeySegment} 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 {@link 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 {@link Key#getIndex()} will be the
* offset within the key of the first encoded byte. The key segment is
* zero-byte terminated.
*
*
* @param key
* The {@link Key} from which data should be decoded
* @param clazz
* The expected Class of the returned object
* @param context
* An arbitrary object that can optionally be supplied by the
* application to convey an application-specific context for the
* operation. (See {@link CoderContext}.) The default value is
* null.
* @throws ConversionException
*/
public Object decodeKeySegment(Key key, Class clazz, CoderContext context) 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
* {@link #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.
*
* @return whether this KeyCoder produces encodings guaranteed not to
* contain zero bytes
* @throws ConversionException
*/
public boolean isZeroByteFree() throws ConversionException;
}