/**
 * Copyright 2005-2012 Akiban Technologies, Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.persistit.encoding;

import com.persistit.Key;
import com.persistit.exception.ConversionException;

/**
 * <p>
 * An extended {@link KeyCoder} that can populate a supplied <code>Object</code>
 * with data that was formerly written to a {@link Key} by the
 * <code>KeyCoder</code> .
 * </p>
 * <p>
 * A <code>KeyRenderer</code> implements an additional method called
 * {@link #renderKeySegment} that populates a supplied target object rather than
 * creating a new object instance.
 * </p>
 * 
 * 
 * @version 1.0
 */
public interface KeyRenderer extends KeyCoder {

    /**
     * <p>
     * Populate the state of the supplied target <code>Object</code> by decoding
     * the next key segment of the supplied <code>Key</code>. This method will
     * be called only if this <code>KeyRenderer</code> has been registered with
     * the current {@link CoderManager} to encode objects having the supplied
     * <code>Class</code> value. In addition, Persistit will never call this
     * method to decode a value that was <code>null</code> when written because
     * null values are handled by built-in encoding logic.
     * </p>
     * <p>
     * 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.
     * </p>
     * 
     * @param key
     *            The <code>Key</code> from which interior fields of the object
     *            are to be retrieved
     * 
     * @param target
     *            An object into which the key segment is to be written
     * 
     * @param clazz
     *            The class of the object that was originally encoded into
     *            Value.
     * 
     * @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
     *            <code>null</code>.
     * 
     * @throws ConversionException
     */
    public void renderKeySegment(Key key, Object target, Class<?> clazz, CoderContext context)
            throws ConversionException;

}