com.persistit.encoding.CoderManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of akiban-persistit Show documentation
Java B+Tree Key-Value Store Library
There is a newer version: 3.3.0
/**
 * 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 java.util.Map;

import com.persistit.DefaultCoderManager;
import com.persistit.Exchange;
import com.persistit.Key;

/**
 * 
 * Manages the collections of {@link KeyCoder}s and {@link ValueCoder}s that
 * encode and decode object values in Persistit™. An application should
 * register all KeyCoder and ValueCoder
 * implementations before storing or accessing objects of the associated classes
 * in Persistit.
 * 
 * 
 * When Persistit is initialized, a instance of {@link DefaultCoderManager} is
 * installed as the current CoderManager. Applications can refer to
 * it through the method {@link com.persistit.Persistit#getCoderManager}.
 * Applications should register KeyCoder and
 * ValueCoder instances as follows: 

 * 
 *  * ValueCoder vc1 = new MyClassValueCoder();
 * KeyCoder kc1 = new MyClassKeyCoder();
 * Persistit.getInstance().getCoderManager().registerValueCoder(MyClass.class, kc1);
 * Persistit.getInstance().getCoderManager().registerKeyCoder(MyClass.class, kc1);
 * 
 * 
 *  Subsequently, any time the application appends an instance of a
 * MyClass to a Key, the MyClassKeyCoder
 * will be used to convert the interior state of the MyClass into a
 * representation within the Key. Likewise, whenever the
 * application puts an object of class MyClass into a
 * Value, the registered MyClassValueCoder will be
 * used to encode it. Persistit uses the {@link #lookupKeyCoder} and
 * {@link #lookupValueCoder} methods to acquire the appropriate coder.
 * 
 * 
 * An application may replace the default implementation provided by
 * DefaultCoderManager. Such a custom implementation might, for
 * example, handle the relationship between certain classes and their associated
 * coders in a special way.
 * 
 * 
 * An application can create and install a customized CoderManager
 * as follows: 

 * 
 *  * CoderManager myCoderManager = new MyCoderManager(Persistit.getInstance().getCoderManager());
 * Persistit.getInstance().setCoderManager(myCoderManager);
 * 
 * 
 * 
 Note that the MyCoderManager instance receives the
 * previously installed CoderManager as an argument of its
 * constructor. The new CoderManager should return the previously
 * installed one as the value of its {@link #getParent} method, and the
 * {@link #lookupKeyCoder} and {@link #lookupValueCoder} should delegate any
 * lookups not handled by the customized CoderManager back to the
 * parent.
 * 
 * Key Ordering
 * 
 * The encoding of key values determines the ordering of traversal for
 * {@link Exchange#traverse} and associated methods. See {@link Key} for
 * definition of the ordering among the types for which built-in encoding
 * exists. The ordering of key values based on objects that are encoded by
 * custom KeyCoders is determined by the implementation of each
 * KeyCoder.
 * 
 * This leaves the question of how keys that may contain encoded objects of
 * different classes are ordered. For example, consider the code fragment shown
 * here: 
 * 
 *  *  Exchange exchange = new Exchange(...);
 *  Object a = new MyClass1();  // where MyClass1 and MyClass2
 *  Object b = new MyClass2();  // have registered KeyCoders
 *  exchange.to(a).store();     // store something with a's value as key
 *  exchange.to(b).store();     // store something with b's value as key
 *  exchange.to(Key.BEFORE)
 *  while (exchange.next())
 *  {
 *      System.out.println(exchange.indexTo(-1).getTypeName());
 *  }
 * 
 * 
 *  This code will insert two records incorporating the values
 * a and b into Persistit, and will then traverse the
 * resulting tree and print the names of the classes of the key values. The
 * question is whether "MyClass2" will be printed before or after "MyClass2".
 * 
 * 
 * The answer depends on the order in which MyClass1 and MyClass2 were first
 * registered within Persistit. At the time a new class is first registered,
 * Persistit assigns a permanent int-valued class handle to the
 * class. Whenever an instance of that class is encoded within either a
 * Key or a Value, that handle value, rather than the
 * class name, is used. This reduces disk, memory and CPU consumption whenever
 * Persistit stores or retrieves objects. Handles are assigned in increasing
 * numeric order as classes are registered. Thus if MyClass1 was
 * registered before MyClass2, it will precede
 * MyClass2 in traversal order. Otherwise it will follow
 * MyClass2.
 * 
 * 
 * @version 1.0
 */
public interface CoderManager {
    /**
     * Create a Map of Classes to registered
     * ValueCoders. The map is an unmodifiable, is sorted by class
     * name, and does not change with subsequent registrations or
     * unregistrations of ValueCoders.
     * 
     * @return Map of Classes to
     *         ValueCoders.
     */
    public Map, ? extends ValueCoder> getRegisteredValueCoders();

    /**
     * Create a Map of Classes to registered
     * KeyCoder s. The map is an unmodifiable, and is sorted by
     * class name, and does not change with subsequent registrations or
     * unregistrations of KeyCoders.
     * 
     * @return Map of Classes to KeyCoder
     *         s.
     */
    public Map, ? extends KeyCoder> getRegisteredKeyCoders();

    /**
     * Register the provided KeyCoder to encode and decode
     * instances of supplied class.
     * 
     * @param clazz
     *            The Class for which this KeyCoder will provide
     *            encoding and decoding services
     * @param coder
     *            The KeyCoder to register
     * @return The KeyCoder formerly registered for this
     *         Class , or null if there was none.
     */
    public KeyCoder registerKeyCoder(Class clazz, KeyCoder coder);

    /**
     * Remove the registered KeyCoder for the supplied class.
     * 
     * @param clazz
     *            The Class from which to remove a
     *            KeyCoder, if present
     * @return The KeyCoder that was removed, or null
     *         if there was none.
     */
    public KeyCoder unregisterKeyCoder(Class clazz);

    /**
     * Remove the supplied KeyCoder from all classes to which it
     * was previously registered.
     * 
     * @param coder
     *            The KeyCoder to remove.
     * @return The count of classes this KeyCoder was registered
     *         for.
     */
    public int unregisterKeyCoder(KeyCoder coder);

    /**
     * Returns the KeyCoder registered for the supplied
     * Class, or null if no KeyCoder is
     * registered.
     * 
     * @param clazz
     *            The Class
     * @return The KeyCoder or null if there is none.
     */
    public KeyCoder lookupKeyCoder(Class clazz);

    /**
     * Register the provided ValueCoder to encode and decode
     * instances of supplied class.
     * 
     * @param clazz
     *            The Class for which this ValueCoder will provide
     *            encoding and decoding services
     * @param coder
     *            The ValueCoder to register
     * @return The ValueCoder that was removed, or
     *         null if there was none.
     */
    public ValueCoder registerValueCoder(Class clazz, ValueCoder coder);

    /**
     * Remove the registered ValueCoder for the supplied class.
     * 
     * @param clazz
     *            The Class from which to remove a
     *            ValueCoder, if present
     * @return The ValueCoder that was removed, or
     *         null if there was none.
     */
    public ValueCoder unregisterValueCoder(Class clazz);

    /**
     * Remove the supplied ValueCoder from all classes to which it
     * was previously registered.
     * 
     * @param coder
     *            The ValueCoder to remove.
     * @return The count of classes this ValueCoder was registered
     *         for.
     */
    public int unregisterValueCoder(ValueCoder coder);

    /**
     * Returns the ValueCoder registered for the supplied
     * Class, or null if no ValueCoder is
     * registered.
     * 
     * @param clazz
     *            The Class
     * @return The ValueCoder or null if there is
     *         none.
     */
    public ValueCoder lookupValueCoder(Class clazz);

    /**
     * Return a ValueCoder for the supplied Class. If
     * there is none registered, implicitly create one and register it.
     * 
     * @param clazz
     * @return The ValueCoder
     */
    public ValueCoder getValueCoder(Class clazz);

    /**
     * Return the parent CoderManager implementation, or
     * null if there is none.
     * 
     * @return The parent CoderManager
     */
    public CoderManager getParent();

}