Proposal : TileCodec API
                    ~~~~~~~~~~~~~~~~~~~~~~~~

Aastha Bhardwaj
Created: July 7, 2000
Revised: Oct 2, 2000
Revised: Dec 18, 2000

1. Motivation

The motivation for a TileCodec API can be summarized as follows:

a) To provide a means of persistent storage of tiles.

b) To be able to encode and decode tiles on the ends of a network
transmission for bandwidth conservation and security reasons.

2. API Classes

Here's all the major classes that are used in the API. 

2.1 Interface TileCodecDescriptor

package javax.media.jai.tilecodec;

/**
 * A class to describe a particular tile codec format. The <code>getName</code>
 * method of <code>RegistryElementDescriptor</code> should be implemented 
 * to return the name of the format in an implementation of this interface.
 * This name is also the String with which this
 * <code>TileCodecDescriptor</code> is associated in the 
 * <code>OperationRegistry</code>. There are two 
 * complemetary modes that TileCodecs are expected to function in, the
 * decoding mode specified by the "tileDecoder" String and the encoding
 * mode specified by the "tileEncoder" String. It is not recommended that
 * separate classes be used to implement the different modes, but if this
 * is done, then <code>includesSampleModelInfo()</code> and 
 * <code>includesLocationInfo()</code> methods must return the same values
 * from both the implementing classes.
 *
 * <p> In order to successfully decode an encoded tile data stream into a
 * decoded <code>Raster</code>, at the very least, a <code>Point</code>
 * specifying the top left corner of the <code>Raster</code>, a
 * <code>SampleModel</code> specifying the data layout described minimally
 * by the dataType, number of bands, width and height and a
 * <code>DataBuffer</code> with the decoded pixel data are needed. The
 * <code>DataBuffer</code> can be created from the information from the
 * <code>SampleModel</code> and the decoded data. Therefore the absolute
 * minimum information that is required in order to create a
 * <code>Raster</code> upon decoding (aside from the decoded data itself)
 * is the <code>Point</code> specifying the top left corner of the
 * <code>Raster</code>, the <code>SampleModel</code> specifying the data
 * layout. Some formats include this information about the layout of the
 * tile while others don't. The formats that do include this information
 * needed to create a <code>SampleModel</code> and a <code>Point</code>
 * should return true from the <code>includesSampleModelInfo()</code> and
 * <code>includesLocationInfo()</code> methods respectively. The formats 
 * that do not include this information in the encoded stream should return
 * false. For decoding, the <code>TileCodecParameterList</code> providing the
 * decoding parameters will in this case be expected to contain a parameter
 * named "sampleModel" with a non-null <code>SampleModel</code> as its value. 
 * This <code>SampleModel</code> will be used to create the decoded
 * <code>Raster</code> and is expected to be the same as the
 * <code>SampleModel</code> of the tiles to be encoded.
 *
 * <p> All <code>String</code>s are treated in a case-retentive and 
 * case-insensitive manner.
 *
 * @see TileDecoder
 * @see TileEncoder
 * @since 1.1
 */
public interface TileCodecDescriptor extends RegistryElementDescriptor {

    /**
     * Returns true if the format encodes layout information generally
     * specified via the <code>SampleModel</code> in the encoded data stream.
     */
    boolean includesSampleModelInfo();

    /**
     * Returns true if the format encodes in the data stream the location of 
     * the <code>Raster</code> with respect to its enclosing image.
     */
    boolean includesLocationInfo();

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    TileCodecParameterList getDefaultParameters(String modeName);

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>, adding a 
     * "sampleModel" parameter with the specified value to the parameter
     * list.
     * 
     * <p> This method should be used when includesSampleModelInfo()
     * returns false. If includesSampleModelInfo() returns true, the
     * supplied <code>SampleModel</code> is ignored.
     *
     * <p> If a parameter named "sampleModel" exists in the default 
     * parameter list, the supplied <code>SampleModel</code> will override
     * the value associated with this default parameter.
     *
     * @param sm The <code>SampleModel</code> used to create the 
     *           default decoding parameter list.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    TileCodecParameterList getDefaultParameters(String modeName, 
						SampleModel sm);

    /**
     * Returns a <code>TileCodecParameterList</code> valid for the 
     * specified modeName and compatible with the supplied
     * <code>TileCodecParameterList</code>.
     * For example, given a <code>TileCodecParameterList</code> used to
     * encode a tile with the modeName being specified as "tileDecoder", this
     * method will return a <code>TileCodecParameterList</code> sufficient
     * to decode that same encoded tile.
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     * @param otherParamList The parameter list for which a compatible
     *                       parameter list for the specified modeName is
     *                       to be returned.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    TileCodecParameterList getCompatibleParameters(String modeName, 
						   TileCodecParameterList 
                                                   otherParamList);
}


2.2 Abstract class TileCodecDescriptorImpl

package javax.media.jai.tilecodec;

/**
 * An abstract class that implements the <code>TileCodecDescriptor</code>
 * interface and is suitable for subclassing. This class provides default
 * implementations for some of the methods from
 * <code>TileCodecDescriptor</code>. Subclasses should override these methods
 * if they do not wish to retain the default implementation.
 *
 * All <code>String</code>s are treated in a case-retentive and 
 * case-insensitive manner.
 *
 * @since 1.1
 */
public abstract class TileCodecDescriptorImpl implements TileCodecDescriptor {
    
    /**
     * Creates a <code>TileCodecDescriptorImpl</code> with the given
     * format name and <code>boolean</code>s to specify whether layout
     * information is included in the encoded stream.
     *
     * @param formatName              The name of the format. This is also
     *                                the name under which this descriptor
     *                                will be registered under in the 
     *                                <code>OperationRegistry</code>.
     * @param includesSampleModelInfo Whether the format encodes the tile's
     *                                <code>SampleModel</code> or equivalent
     *                                information into the encoded stream.
     * @param includesLocationInfo    Whether the format encodes the tile's
     *                                upper left corner position or equivalent
     *                                information into the encoded stream.
     * @throws IllegalArgumentException if formatName is null.
     */
    public TileCodecDescriptorImpl(String formatName,
				   boolean includesSampleModelInfo,
				   boolean includesLocationInfo) {}

    /** 
     * Returns the name of the format.
     */
    public String getName() {}

    /**
     * Returns the registry modes supported by this descriptor. The
     * default implementation of this method in this class returns a 
     * <code>String</code> array containing the "tileDecoder" and 
     * "tileEncoder" strings. If the subclass does not support any of
     * these modes, it should override this method to return the names of
     * those modes that it supports.
     *
     * @see javax.media.jai.RegistryMode
     */
    public String[] getSupportedModes() {}

    /**
     * This method is implemented to return true if the specified 
     * registryModeName is either "tileDecoder" or "tileEncoder". If
     * the subclass doesn't support any one of these modes, it should
     * override this method to return true only for the supported mode(s).
     *
     * @param registryModeName The name of the registry mode to check 
     *                         support for.
     * @throws IllegalArgumentException if registryModeName is null.
     */
    public boolean isModeSupported(String registryModeName) {} 

    /**
     * Whether this descriptor supports properties.
     *
     * @return true, if the implementation of this descriptor supports
     * properties. false otherwise. Since tile codecs do not support
     * properties, so this default implementation returns false.
     *
     * @see PropertyGenerator
     */
    public boolean arePropertiesSupported() {}

    /**
     * Returns an array of <code>PropertyGenerator</code>s implementing
     * the property inheritance for this operation.  Since neither
     * <code>TileEncoder</code> or <code>TileDecoder</code> supports
     * properties, the default implementation throws an 
     * <code>UnsupportedOperationException</code>. Subclasses should
     * override this method if they wish to produce inherited properties.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws UnsupportedOperationException if
     * <code>arePropertiesSupported()</code> returns <code>false</code>
     */
    public PropertyGenerator[] getPropertyGenerators(String modeName) {}

    /**
     * Returns true if the format encodes layout information generally
     * specified via the <code>SampleModel</code> in the encoded data stream.
     */
    public boolean includesSampleModelInfo() {}

    /**
     * Returns true if the format encodes in the data stream the location of 
     * the <code>Raster</code> with respect to its enclosing image.
     */
    public boolean includesLocationInfo() {}    
}


2.3 Class TileDecoderRegistryMode

package javax.media.jai.registry;

/**
 * A class which provides information about the "tileDecoder" registry
 * mode. 
 *
 * @since 1.1
 */
public class TileDecoderRegistryMode extends RegistryMode {
    
    public static final String MODE_NAME = "tileDecoder";
    
    /**
     * Creates a <code>TileDecoderRegistryMode</code> for describing 
     * the "tileDecoder" registry mode.
     */
    public TileDecoderRegistryMode() {}
}


2.4 Class TileEncoderRegistryMode

package javax.media.jai.registry;

/**
 * A class which provides information about the "tileEncoder" registry
 * mode. 
 *
 * @since 1.1
 */
public class TileEncoderRegistryMode extends RegistryMode {

    public static final String MODE_NAME = "tileEncoder";

    /**
     * Creates a <code>TileEncoderRegistryMode</code> for describing 
     * the "tileEncoder" registry mode.
     */
    public TileEncoderRegistryMode() {}
}


2.5 Class TileCodecParameterList

package javax.media.jai.tilecodec;

/**
 * A subclass of <code>ParameterListImpl</code> that is specific to 
 * tile codecs. This class functions in either one or both of the two
 * registry modes supported by the <code>TileCodecDescriptor</code>
 * - "tileEncoder" and "tileDecoder".
 *
 * <p> This class is not intended to be subclassed for each individual
 * <code>TileEncoder</code> or <code>TileDecoder</code>. This is a generic
 * class which can be used as is for representing a parameter list for
 * any tile encoding/decoding format. The <code>ParameterListDescriptor</code>
 * provided as argument to the constructor should be the one returned from
 * the <code>getParameterListDescriptor()</code> method of the 
 * <code>TileCodecDescriptor</code> for the given format name. 
 *
 * <p> If the associated <code>TileCodecDescriptor</code>'s
 * <code>includesSampleModelInfo()</code> method returns false, then for the
 * "tileDecoder" mode, this class will be expected to contain a parameter
 * named "sampleModel" with a non-null <code>SampleModel</code> as its value.
 *
 * @since 1.1
 */
public class TileCodecParameterList extends ParameterListImpl {

    /**
     * Creates a <code>TileCodecParameterList</code>. The
     * <code>validModes</code> argument specifies the registry modes valid
     * for this <code>TileCodecParameterList</code>. This should contain 
     * the "tileEncoder" registry mode or the "tileDecoder" registry
     * mode or both. The supplied descriptor object specifies the names
     * and number of the valid parameters, their <code>Class</code> types, 
     * as well as the <code>Range</code> of valid values for each parameter.
     *
     * @param formatName The name of the format, parameters for which are
     *                   specified through this parameter list.
     * @param validModes An array of <code>String</code> objects specifying
     *                   which registry modes are valid for this parameter list.
     * @param descriptor The <code>ParameterListDescriptor</code> object that
     *                   describes all valid parameters for this format. This
     *                   must be the the same descriptor that is returned from
     *                   the <code>getParameterListDescriptor()</code> method of
     *                   the <code>TileCodecDescriptor</code> for the given
     *                   formatName.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if validModes is null.
     * @throws IllegalArgumentException if descriptor is null.
     */
    public TileCodecParameterList(String formatName,
                                  String validModes[],
                                  ParameterListDescriptor descriptor) {}

    /**
     * Returns the name of the format which this parameter list describes.
     */
    public String getFormatName() {}

    /**
     * Returns true if the parameters in this 
     * <code>TileCodecParameterList</code> are valid for the specified 
     * registry mode name, false otherwise. The valid modes for
     * this class are the "tileEncoder" registry mode, and the
     * "tileDecoder" registry mode.
     */
    public boolean isValidForMode(String registryModeName) {}

    /**
     * Returns all the modes that this <code>TileCodecParameterList</code>
     * is valid for, as a <code>String</code> array.
     */
    public String[] getValidModes() {}
}


2.6 Interface TileDecoder

package javax.media.jai.tilecodec;

/**
 * An interface describing objects that transform an <code>InputStream</code>
 * into a <code>Raster</code>.
 *
 * <p>This interface is designed to allow decoding of formats that
 * include information about the format of the encoded tile as well as ones
 * that don't. In order to create a <code>Raster</code>, at the very least,
 * a <code>Point</code> specifying the top left corner of the 
 * <code>Raster</code>, a <code>SampleModel</code> specifying the data layout
 * and a <code>DataBuffer</code> with the decoded pixel data are
 * needed. The <code>DataBuffer</code> can be created from the  
 * information from the <code>SampleModel</code> and the decoded data. 
 * Therefore the absolute minimum information that is required in order to
 * create a <code>Raster</code> on decoding (aside from the decoded data 
 * itself) is a <code>Point</code> specifying the top left corner of the
 * <code>Raster</code> and a <code>SampleModel</code> specifying the data
 * layout. The formats that do include this information should return true
 * from the <code>includesSampleModelInfo()</code> and 
 * <code>includesLocationInfo()</code> from the associated 
 * <code>TileCodecDescriptor</code> if they include information needed to
 * create a <code>SampleModel</code> and information needed to
 * create the <code>Point</code> respectively. The formats that do not
 * include this information in the encoded stream should return false. The
 * <code>TileCodecParameterList</code> providing the decoding parameters
 * will in this case be expected to contain a parameter named "sampleModel"
 * with a non-null <code>SampleModel</code> as its value. This 
 * <code>SampleModel</code> will be used to create the decoded 
 * <code>Raster</code>.
 *
 * <p> The formats that return true from <code>includesSampleModelInfo()</code>
 * should use the <code>decode()</code> method to cause the decoding to take
 * place, the ones that return false should specify the <code>Point</code>
 * location to the decoding process by using the <code>decode(Point)</code>
 * method. Similarly the <code>SampleModel</code> must be specified as a
 * parameter with a non-null value on the <code>TileCodecParameterList</code>
 * passed to this <code>TileDecoder</code> if
 * <code>includesSampleModelInfo()</code> returns false. It is expected that
 * the <code>SampleModel</code> specified in the parameter list is the
 * <code>SampleModel</code> of the encoded tiles, in order to get a
 * decoded <code>Raster</code> that is equivalent to the one encoded. If the
 * <code>SampleModel</code> specified through the parameter list is different 
 * from those of the encoded tiles, the result of decoding is undefined.
 *
 * <p> If <code>includesSampleModelInfo()</code> returns true, the
 * <code>SampleModel</code> (if present) on the
 * <code>TileCodecParameterList</code> is ignored.
 *
 * @see TileCodecDescriptor
 * @see TileEncoder
 *
 * @since 1.1
 */
public interface TileDecoder {

    /**
     * Returns the name of the format.
     */
    String getFormatName();

    /**
     * Returns the current parameters as an instance of the
     * <code>TileCodecParameterList</code> interface.
     */
    TileCodecParameterList getDecodeParameterList();

    /** 
     * Returns the <code>InputStream</code> containing the encoded data.
     */
    InputStream getInputStream();

    /**
     * Returns a <code>Raster</code> that contains the decoded contents 
     * of the <code>InputStream</code> associated with this 
     * <code>TileDecoder</code>. 
     *
     * <p>This method can perform the decoding correctly only when 
     * <code>includesLocationInfo()</code> returns true.
     *
     * @throws IOException if an I/O error occurs while reading from the
     * associated InputStream.
     * @throws IllegalArgumentException if the associated 
     * TileCodecDescriptor's includesLocationInfo() returns false. 
     */
    Raster decode() throws IOException;

    /**
     * Returns a <code>Raster</code> that contains the decoded contents 
     * of the <code>InputStream</code> associated with this 
     * <code>TileDecoder</code>. 
     *
     * <p>This method should be used when <code>includesLocationInfo()</code>
     * returns false. If <code>includesLocationInfo()</code> returns true, then
     * the supplied <code>Point</code> is ignored.
     *
     * @param location The <code>Point</code> specifying the upper
     *                 left corner of the Raster. 
     * @throws IOException if an I/O error occurs while reading from the
     * associated InputStream.
     * @throws IllegalArgumentException if includesLocationInfo() returns false 
     * and location is null.
     */
    Raster decode(Point location) throws IOException;
}


2.7 Abstract Class TileDecoderImpl

package javax.media.jai.tilecodec;

/**
 * A partial implementation of the <code>TileDecoder</code> interface
 * useful for subclassing.
 *
 * @since 1.1
 */
public abstract class TileDecoderImpl implements TileDecoder {

    /**
     * The name of the format.
     */
    protected String formatName;

    /**
     * The <code>InputStream</code> containing the encoded data to decode.
     */
    protected InputStream inputStream;

    /**
     * The <code>TileCodecParameterList</code> object containing the
     * decoding parameters. 
     */
    protected TileCodecParameterList paramList;

    /**
     * Constructs a <code>TileDecoderImpl</code>. An
     * <code>IllegalArgumentException</code> will be thrown if
     * <code>param</code>'s <code>getParameterListDescriptor()</code> 
     * method does not return the same descriptor as that from
     * the associated <code>TileCodecDescriptor</code>'s 
     * <code>getParameterListDescriptor</code> method for the "tileDecoder" 
     * registry mode. 
     *
     * <p> If param is null, then the default parameter list for decoding
     * as defined by the associated <code>TileCodecDescriptor</code>'s 
     * <code>getDefaultParameters()</code> method will be used for decoding.
     * If this too is null, an <code>IllegalArgumentException</code> will
     * be thrown if the <code>ParameterListDescriptor</code> associated
     * with the associated <code>TileCodecDescriptor</code> for the
     * "tileDecoder" registry mode, reports that the number of parameters
     * for this format is non-zero.
     *
     * @param formatName The name of the format.
     * @param input The <code>InputStream</code> to decode data from.
     * @param param  The object containing the tile decoding parameters.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if input is null.
     * @throws IllegalArgumentException if param's getFormatName() method does
     * not return the same formatName as the one specified to this method.
     * @throws IllegalArgumentException if the ParameterListDescriptor 
     * associated with the param and the associated TileCodecDescriptor are
     * not equal.
     * @throws IllegalArgumentException if param does not have "tileDecoder"
     * as one of the valid modes that it supports.
     * @throws IllegalArgumentException if the associated TileCodecDescriptor's
     * includesSampleModelInfo() returns false and a non-null value for the
     * "sampleModel" parameter is not supplied in the supplied parameter list.
     */
    public TileDecoderImpl(String formatName,
			   InputStream input, 
			   TileCodecParameterList param) {}
    
    /**
     * Returns the format name.
     */
    public String getFormatName() {}

    /**
     * Returns the current parameters as an instance of the
     * <code>TileCodecParameterList</code> interface.
     */
    public TileCodecParameterList getDecodeParameterList() {}

    /**
     * Returns the <code>InputStream</code> associated with this 
     * <code>TileDecoder</code>.
     */
    public InputStream getInputStream() {} 
}


2.8 Interface TileEncoder

package javax.media.jai.tilecodec;

/**
 * An interface describing objects that transform a <code>Raster</code>
 * into an <code>OutputStream</code>.
 *
 * If the <code>TileCodecDescriptor</code> for this format returns true from
 * its <code>includesSampleModelInfo()</code> and 
 * <code>includesLocationInfo()</code> methods, then the encoder must encode
 * this information in the encoded tiles. If these methods return false, then
 * this information (needed to create a <code>Raster</code> on decoding) must
 * be provided to the <code>TileDecoder</code> by setting the 
 * <code>SampleModel</code> on the <code>TileCodecParameterList</code> supplied
 * to the <code>TileDecoder</code> and supplying the tile upper left corner
 * location to the <code>TileDecoder</code> via the <code>TileDecoder</code>'s
 * <code>decode(Point location)</code> method. The <code>SampleModel</code>
 * value set on the <code>TileCodecParameterList</code> for the
 * <code>TileDecoder</code> should be the same as that of the 
 * <code>Raster</code> to be encoded, in order to get a <code>Raster</code>
 * on decoding that is equivalent to the one being encoded.
 *
 * @see TileCodecDescriptor
 * @see TileDecoder
 */
public interface TileEncoder {

    /**
     * Returns the format name of the encoding scheme.
     */
    String getFormatName();

    /**
     * Returns the current parameters as an instance of the
     * <code>TileCodecParameterList</code> interface.
     */
    TileCodecParameterList getEncodeParameterList();

    /** 
     * Returns the <code>OutputStream</code> to which the encoded data
     * will be written.
     */
    public OutputStream getOutputStream();

    /**
     * Encodes a <code>Raster</code> and writes the output
     * to the <code>OutputStream</code> associated with this 
     * <code>TileEncoder</code>.
     *
     * @param ras the <code>Raster</code> to encode.
     * @throws IOException if an I/O error occurs while writing to the 
     * OutputStream.
     * @throws IllegalArgumentException if ras is null.
     */
    public void encode(Raster ras) throws IOException;
}


2.9 Abstract Class TileEncoderImpl

package javax.media.jai.tilecodec;

/**
 * A partial implementation of the <code>TileEncoder</code> interface
 * useful for subclassing.
 */
public abstract class TileEncoderImpl implements TileEncoder {
    
    /**
     * The name of the format.
     */
    protected String formatName;

    /** 
     * The <code>OutputStream</code>  to write the encoded data to.
     */
    protected OutputStream outputStream;

    /**
     * The <code>TileCodecParameterList</code> object containing the
     * encoding parameters.
     */
    protected TileCodecParameterList paramList;

    /**
     * Constructs an <code>TileEncoderImpl</code>. An
     * <code>IllegalArgumentException</code> will be thrown if
     * <code>param</code>'s <code>getParameterListDescriptor()</code> method
     * does not return the same descriptor as that from the associated
     * <code>TileCodecDescriptor</code>'s 
     * <code>getParameterListDescriptor</code> method for the "tileEncoder" 
     * registry mode. 
     *
     * <p> If param is null, then the default parameter list for encoding
     * as defined by the associated <code>TileCodecDescriptor</code>'s 
     * <code>getDefaultParameters()</code> method will be used for encoding.
     * If this too is null, an <code>IllegalArgumentException</code> will
     * be thrown if the <code>ParameterListDescriptor</code> associated
     * with the associated <code>TileCodecDescriptor</code> for the
     * "tileEncoder" registry mode, reports that the number of parameters 
     * for this format is non-zero.
     *
     * @param formatName The name of the format.
     * @param output The <code>OutputStream</code> to write encoded data to.
     * @param param  The object containing the tile encoding parameters.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if output is null.
     * @throws IllegalArgumentException if param's getFormatName() method does
     * not return the same formatName as the one specified to this method.
     * @throws IllegalArgumentException if the ParameterListDescriptors 
     * associated with the param and the associated TileCodecDescriptor are
     * not equal.
     * @throws IllegalArgumentException if param does not have "tileEncoder"
     * as one of the valid modes that it supports. 
     */
    public TileEncoderImpl(String formatName,
			   OutputStream output,
			   TileCodecParameterList param) {}
    
    /**
     * Returns the format name of the encoding scheme.
     */
    public String getFormatName() {}

    /**
     * Returns the current parameters as an instance of the
     * <code>TileCodecParameterList</code> interface.
     */
    public TileCodecParameterList getEncodeParameterList() {}

    /** 
     * Returns the <code>OutputStream</code> to which the encoded data will
     * be written.
     */
    public OutputStream getOutputStream() {}
}


2.10 TileDecoderFactory

package javax.media.jai.tilecodec;

/**
 * A factory for creating <code>TileDecoder</code>s.
 *
 * <p> This class stipulates that the capabilities of the 
 * <code>TileDecoder</code> be specified by implementing the
 * <code>getDecodingCapability()</code> method. 
 *
 * @see javax.media.jai.remote.NegotiableCapability
 */
public interface TileDecoderFactory {
    
    /** 
     * Creates a <code>TileDecoder</code> capable of decoding the encoded 
     * data from the given <code>InputStream</code> using the specified
     * <code>TileCodecParameterList</code> containing the decoding
     * parameters to be used.
     *
     * <p> This method can return null if the <code>TileDecoder</code> is 
     * not capable of producing output for the given set of parameters.  
     * For example, if a <code>TileDecoder</code> is only capable of dealing
     * with a jpeg quality factor of 0.5, and the associated
     * <code>TileCodecParameterList</code> specifies a quality factor of 0.75,
     * null should be returned.
     *
     * <p>It is recommended that the data in the supplied 
     * <code>InputStream</code> not be used as a factor in determining
     * whether this <code>InputStream</code> can be successfully decoded,
     * unless the supplied <code>InputStream</code> is known to be rewindable
     * (i.e. its <code>markSupported()</code> method returns true or it has
     * additional functionality that allows backward seeking). It is required
     * that the <code>InputStream</code> contain the same data on 
     * returning from this method as before this method was called.
     * In other words, the <code>InputStream</code> should only be used as a
     * discriminator if it can be rewound to its starting position
     * before returning from this method. Note that wrapping the
     * incoming <code>InputStream</code> in a <code>PushbackInputStream</code>
     * and then rewinding the <code>PushbackInputStream</code> before returning
     * does not rewind the wrapped <code>InputStream</code>.
     *
     * <p> If the supplied <code>TileCodecParameterList</code> is null,
     * a default <code>TileCodecParameterList</code> from the
     * <code>TileCodecDescriptor</code> will be used to create the decoder.
     *
     * <p> Exceptions thrown by the <code>TileDecoder</code> will be
     * caught by this method and will not be propagated.
     *
     * @param input The <code>InputStream</code> containing the encoded data
     *              to decode.
     * @param param The parameters to be be used in the decoding process.
     * @throws IllegalArgumentException if input is null.
     */
    TileDecoder createDecoder(InputStream input, TileCodecParameterList param);

    /** 
     * Returns the capabilities of this <code>TileDecoder</code> as a
     * <code>NegotiableCapability</code>.
     *
     * @see javax.media.jai.remote.NegotiableCapability
     */
    NegotiableCapability getDecodeCapability();
}


2.11 TileEncoderFactory

package javax.media.jai.tilecodec;

/**
 * A factory for creating <code>TileEncoder</code>s.
 *
 * <p> This class stipulates that the capabilities of the 
 * <code>TileEncoder</code> be specified by implementing the
 * <code>getEncodingCapability()</code> method. 
 *
 * @see javax.media.jai.remote.NegotiableCapability
 */
public interface TileEncoderFactory {

    /**
     * Creates a <code>TileEncoder</code> capable of encoding a 
     * <code>Raster</code> with the specified <code>SampleModel</code>
     * using the encoding parameters specified via the
     * <code>TileCodecParameterList</code>, to the given
     * <code>OutputStream</code>.
     *
     * <p> This method can return null if the <code>TileEncoder</code> is not
     * capable of producing output for the given set of parameters.  
     * For example, if a <code>TileEncoder</code> is only capable of dealing
     * with a <code>PixelInterleavedSampleModel</code>, and the supplied 
     * <code>SampleModel</code> is not an instance of 
     * <code>PixelInterleavedSampleModel</code>, null should be
     * returned. The supplied <code>SampleModel</code> should be used to
     * decide whether it can be encoded by this class, and is not needed
     * to actually construct a <code>TileEncoder</code>.
     *
     * <p> If the supplied <code>TileCodecParameterList</code> is null,
     * a default <code>TileCodecParameterList</code> from the 
     * <code>TileCodecDescriptor</code> will be used to create the encoder.
     *
     * <p>Exceptions thrown by the <code>TileEncoder</code> 
     * will be caught by this method and will not be propagated.
     *
     * @param output      The <code>OutputStream</code> to write the encoded
     *                    data to.
     * @param paramList   The <code>TileCodecParameterList</code> containing
     *                    the encoding parameters.
     * @param sampleModel The <code>SampleModel</code> of the
     *                    <code>Raster</code> to be encoded.
     *
     * @throws IllegalArgumentException if output is null.
     * @throws IllegalArgumentException if sampleModel is null.
     */
    TileEncoder createEncoder(OutputStream output, 
			      TileCodecParameterList paramList,
			      SampleModel sampleModel);

    /** 
     * Returns the capabilities of this <code>TileEncoder</code> as a
     * <code>NegotiableCapability</code>.
     *
     * @see javax.media.jai.remote.NegotiableCapability
     */
    NegotiableCapability getEncodeCapability();
}

2.12 Class TileDecoderRegistry

package javax.media.jai.registry;

/**
 * Utility class to provide type-safe interaction with the
 * <code>OperationRegistry</code> for <code>TileDecoderFactory</code> objects.
 *
 * If the <code>OperationRegistry</code> specified as an argument to the
 * methods in this class is null, then <code>JAI.getOperationRegistry()</code> 
 * will be used.
 */
public final class TileDecoderRegistry  {

    /**
     * Registers the given <code>TileDecoderFactory</code> with the given 
     * <code>OperationRegistry</code> under the given formatName and 
     * productName.
     *
     * @param registry    The <code>OperationRegistry</code> to register the 
     *                    <code>TileDecoderFactory</code> with. If this is
     *                    <code>null</code>, then <code>
     *                    JAI.getDefaultInstance().getOperationRegistry()</code>
     *                    will be used.
     * @param formatName  The formatName to register the 
     *                    <code>TileDecoderFactory</code> under.
     * @param productName The productName to register the 
     *                    <code>TileDecoderFactory</code> under.
     * @param tdf         The <code>TileDecoderFactory</code> to register.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if tdf is null.
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>
     */
    public static void register(OperationRegistry registry,
                                String formatName,
                                String productName,
                                TileDecoderFactory tdf) {}

    /**
     * Unregisters the given <code>TileDecoderFactory</code> previously 
     * registered under the given formatName and productName in the given
     * <code>OperationRegistry</code>.
     *
     * @param registry    The <code>OperationRegistry</code> to unregister the 
     *                    <code>TileDecoderFactory</code> from. If this is
     *                    <code>null</code>, then <code>
     *                    JAI.getDefaultInstance().getOperationRegistry()</code>
     *                    will be used.
     * @param formatName  The formatName to unregister the
     *                    <code>TileDecoderFactory</code> from.
     * @param productName The productName to unregister the
     *                    <code>TileDecoderFactory</code> from.
     * @param tdf         The <code>TileDecoderFactory</code> to unregister.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if tdf is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>
     * @throws IllegalArgumentException if the tdf was not previously
     * registered against the given formatName and productName.
     */
    public static void unregister(OperationRegistry registry,
                                  String formatName,
                                  String productName,
                                  TileDecoderFactory tdf) {}

    /**
     * Sets a preference between the given two <code>TileDecoderFactory</code>
     * objects in the given <code>OperationRegistry</code> under the given
     * formatName and productName.
     *
     * @param registry     The <code>OperationRegistry</code> to set
     *                     preferences on. If this is
     *                     <code>null</code>, then <code>
     *                     JAI.getDefaultInstance().getOperationRegistry()</code>
     *                     will be used.
     * @param formatName   The formatName of the two
     *                     <code>TileDecoderFactory</code>s.
     * @param productName  The productName of the two
     *                     <code>TileDecoderFactory</code>s.
     * @param preferredTDF The preferred <code>TileDecoderFactory</code>.
     * @param otherTDF     The other <code>TileDecoderFactory</code>.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if preferredTDF is null.
     * @throws IllegalArgumentException if otherTDF is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>
     * @throws IllegalArgumentException if either of the two tdf's was 
     * not previously registered against the given formatName and productName.
     */
    public static void setPreference(OperationRegistry registry,
                                     String formatName,
                                     String productName,
                                     TileDecoderFactory preferredTDF,
                                     TileDecoderFactory otherTDF) {}

    /**
     * Unsets a preference previously set amongst the given two 
     * <code>TileDecoderFactory</code> objects in the given
     * <code>OperationRegistry</code> under the given formatName
     * and productName.
     *
     * @param registry     The <code>OperationRegistry</code> to unset
     *                     preferences on. If this is
     *                     <code>null</code>, then <code>
     *                     JAI.getDefaultInstance().getOperationRegistry()</code>
     *                     will be used.
     * @param formatName   The formatName of the two
     *                     <code>TileDecoderFactory</code>s.
     * @param productName  The productName  of the two
     *                     <code>TileDecoderFactory</code>s.
     * @param preferredTDF The preferred <code>TileDecoderFactory</code>.
     * @param otherTDF     The other <code>TileDecoderFactory</code>.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if preferredTDF is null.
     * @throws IllegalArgumentException if otherTDF is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>
     * @throws IllegalArgumentException if either of the two tdf's was
     * not previously registered against the given formatName and productName.
     */
    public static void unsetPreference(OperationRegistry registry,
                                       String formatName,
                                       String productName,
                                       TileDecoderFactory preferredTDF,
                                       TileDecoderFactory otherTDF) {}

    /**
     * Clears all preferences set for registered 
     * <code>TileDecoderFactory</code>s under the given formatName and
     * productName in the given <code>OperationRegistry</code>.
     *
     * @param registry    The <code>OperationRegistry</code> to clear
     *                    preferences from. If this is
     *                    <code>null</code>, then <code>
     *                    JAI.getDefaultInstance().getOperationRegistry()</code>
     *                    will be used.
     * @param formatName  The format name to clear preferences under.
     * @param productName The productName to clear preferences under.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static void clearPreferences(OperationRegistry registry,
					String formatName,
					String productName) {}

    /**
     * Returns a List of the <code>TileDecoderFactory</code>s registered in
     * the given <code>OperationRegistry</code> under the given formatName
     * and productName, in an ordering that satisfies all of the pairwise
     * preferences that have been set. Cycles will be broken in an
     * arbitrary manner.
     *
     * @param registry    The <code>OperationRegistry</code> to clear
     *                    preferences from. If this is
     *                    <code>null</code>, then <code>
     *                    JAI.getDefaultInstance().getOperationRegistry()</code>
     *                    will be used.
     * @param formatName  The format name to clear preferences under.
     * @param productName The productName to clear preferences under.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static List getOrderedList(OperationRegistry registry,
				      String formatName,
				      String productName) {}

    /**
      * Returns an <code>Iterator</code> over all 
      * <code>TileDecoderFactory</code> objects registered under the
      * given format name over all products. The order of the
      * <code>TileDecoderFactory</code> objects in the iteration will
      * be according to the pairwise preferences among products and
      * <code>TileDecoderFactory</code> objects within a product. The
      * <code>remove()</code> method of the <code>Iterator</code>
      * may not be implemented.
      *
      * @param registry    The <code>OperationRegistry</code> to use. If 
      *                     this is <code>null</code>, then <code>
      *                     JAI.getDefaultInstance().getOperationRegistry()</code>
      *                     will be used.
      * @param formatName  The format name.
      *
      * @return an <code>Iterator</code> over <code>TileDecoderFactory</code>
      * objects.
      *
      * @throws IllegalArgumentException if formatName is <code>null</code>
      * @throws IllegalArgumentException if there is no 
      * <code>TileCodecDescriptor</code> registered against the
      * given <code>formatName</code>.
      *
      * @since JAI 1.1
      */
    public static Iterator getIterator(OperationRegistry registry, 
				       String formatName) {}

    /**
      * Returns the the most preferred <code>TileDecoderFactory</code>
      * object registered against the given format name. This
      * method will return the first <code>TileDecoderFactory</code> that
      * would be encountered by the <code>Iterator</code> returned by the
      * <code>getIterator()</code> method.
      *
      * @param registry The <code>OperationRegistry</code> to use.
      *                 If this is <code>null</code>, then <code>
      *                 JAI.getDefaultInstance().getOperationRegistry()</code>
      *                 will be used.
      * @param formatName The format name as a <code>String</code>
      *
      * @return a registered <code>TileDecoderFactory</code> object
      *
      * @throws IllegalArgumentException if formatName is <code>null</code>.
      * @throws IllegalArgumentException if there is no 
      * <code>TileCodecDescriptor</code> registered against
      * the <code>formatName</code>
      */
    public static TileDecoderFactory get(OperationRegistry registry, 
				         String formatName) {}

    /**
     * Creates a <code>TileDecoder</code> for the specified format that is
     * capable of handling the supplied arguments.  
     *
     * <p> The preferences set amongst the <code>TileDecoderFactory</code>
     * objects registered with the <code>OperationRegistry</code> are used
     * to select the most prefered <code>TileDecoderFactory</code> whose
     * <code>createDecoder()</code> method returns a non-null value.
     *
     * <p> In order to do the decoding correctly, the caller should
     * retrieve the <code>TileCodecDescriptor</code> associated with the
     * returned <code>TileDecoder</code> from the
     * <code>OperationRegistry</code> and use it's
     * <code>includesLocationInfo()</code> method's return value to decide
     * which of the two versions of the <code>decode()</code> method on the
     * returned <code>TileDecoder</code> should be used.
     *
     * @param registry   The <code>OperationRegistry</code> to use to create
     *                   the <code>TileDecoder</code>. If 
     *                   this is <code>null</code>, then <code>
     *                   JAI.getDefaultInstance().getOperationRegistry()</code>
     *                   will be used.
     * @param formatName The format for which the <code>TileDecoder</code> is
     *                   to be created.
     * @param input      The <code>InputStream</code> to read encoded data from.
     * @param paramList  The object containing the tile decoding parameters.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if input is null.
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static TileDecoder create(OperationRegistry registry,
				     String formatName,
				     InputStream input,
				     TileCodecParameterList paramList) {}

    // Decode methods 

    /**
     * Decodes the data from the specified <code>InputStream</code>
     * using the given formatName and <code>TileCodecParameterList</code>. 
     * The <code>TileDecoder</code> which performs the decoding is the
     * one created from the most prefered <code>TileDecoderFactory</code>
     * whose <code>create</code> method returns a non-null result.
     *
     * <p> An <code>IllegalArgumentException</code> will be thrown if 
     * the specified format's <code>TileCodecDescriptor</code>'s
     * <code>includesLocationInfo()</code> method returns false, as no
     * location information is provided in this method.
     *     
     * <p> If the specified <code>TileCodecParameterList</code> is null, the 
     * default <code>TileCodecParameterList</code> retrieved by the specific
     * <code>TileDecoder.getDefaultParameters</code>() method for the
     * "tileDecoder" registry mode will be used.
     *
     * <p> For the specified format, if the associated 
     * <code>TileCodecDescriptor</code>'s <code>includesSampleModelInfo()</code> 
     * method returns false, and either the specified
     * <code>TileCodecParameterList</code> is null or if it doesn't contain
     * a non-value for the "sampleModel" parameter, an 
     * <code>IllegalArgumentException</code> will be thrown. 
     *
     * <p> If there are no <code>TileDecoder</code> objects that can decode
     * the specified <code>InputStream</code> according to the decoding
     * parameters supplied, null will be returned from this method.
     * 
     * <p> If multiple tiles are to be decoded from the same
     * <code>InputStream</code> in the same format using the same
     * <code>TileCodecParameterList</code>, it is advisable to create a
     * <code>TileDecoder</code> object and use the <code>decode()</code> method
     * on this decoder for each tile, thus creating and using only a single
     * <code>TileDecoder</code> object. The <code>decode()</code>
     * method on <code>TileDecoderRegistry</code> creates a new
     * <code>TileDecoder</code> object each time it is called.
     *
     * @param registry   The <code>OperationRegistry</code> to use to create
     *                   the <code>TileDecoder</code>. If 
     *                   this is <code>null</code>, then <code>
     *                   JAI.getDefaultInstance().getOperationRegistry()</code>
     *                   will be used.
     * @param formatName The format name associated with the decoder.
     * @param input      The <code>InputStream</code> containing the data 
     *                   to be decoded.
     * @param param      The <code>TileCodecParameterList</code> to be used.
     *
     * @throws IllegalArgumentException if formatName is null.  
     * @throws IllegalArgumentException if input is null.
     * @throws IllegalArgumentException if the specified format does not
     * encode the location information into the encoded data stream.
     * @throws IllegalArgumentException if the associated TileCodecDescriptor's
     * includesSampleModelInfo() returns false and a non-null value for the
     * "sampleModel" parameter is not supplied in the supplied parameter list.
     * @return The associated <code>TileDecoder</code>, or <code>null</code>.
     * @throws IOException if an I/O error occurs while reading from the
     * associated InputStream.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static Raster decode(OperationRegistry registry, 
				String formatName,
				InputStream input,
				TileCodecParameterList param) throws IOException {}
    
    /**
     * Decodes the data from the specified <code>InputStream</code>
     * using the given formatName and <code>TileCodecParameterList</code>.
     * The <code>TileDecoder</code> which performs the decoding is the
     * one created from the most prefered <code>TileDecoderFactory</code>
     * whose <code>create</code> method returns a non-null result. If
     * there are no <code>TileDecoder</code> objects that can decode
     * the specified <code>InputStream</code> according to the decoding
     * parameters supplied, null will be returned from this method.
     *
     * <p> If the specified <code>TileCodecParameterList</code> is null, the 
     * default <code>TileCodecParameterList</code> retrieved by the specific
     * <code>TileDecoder.getDefaultParameters()</code> method will be used.
     *
     * <p> If the specified location is null, and the associated 
     * <code>TileCodecDescriptor</code>'s <code>includesLocationInfo()</code>
     * method returns false, <code>IllegalArgumentException</code> will be thrown. 
     *
     * <p> For the specified format, if the associated 
     * <code>TileCodecDescriptor</code>'s <code>includesSampleModelInfo()</code> 
     * method returns false, and if the specified
     * <code>TileCodecParameterList</code> is null or if it doesn't contain
     * a non-value for the "sampleModel" parameter, an 
     * <code>IllegalArgumentException</code> will be thrown. 
     *
     * <p> If multiple tiles are to be decoded from the same
     * <code>InputStream</code> in the same format using the same
     * <code>TileCodecParameterList</code>, it is advisable to create a
     * <code>TileDecoder</code> object and use the <code>decode()</code> method
     * on this decoder for each tile, thus creating and using only a single
     * <code>TileDecoder</code> object. The <code>decode()</code>
     * method on <code>TileDecoderRegistry</code> creates a new
     * <code>TileDecoder</code> object each time it is called.
     *     
     * @param registry   The <code>OperationRegistry</code> to use to create
     *                   the <code>TileDecoder</code>. If 
     *                   this is <code>null</code>, then <code>
     *                   JAI.getDefaultInstance().getOperationRegistry()</code>
     *                   will be used.
     * @param formatName The format name associated with the decoder.
     * @param input      The <code>InputStream</code> containing the data to
     *                   be decoded.
     * @param param      The <code>TileCodecParameterList</code> to be used.
     * @param location   The <code>Point</code> specifying the upper left
     *                   corner of the <code>Raster</code>. 
     * @throws IllegalArgumentException if formatName is null.  
     * @throws IllegalArgumentException if input is null.
     * @throws IOException if an input/output error occurs during decoding.
     * @throws IllegalArgumentException if includesLocationInfo() returns false 
     * and location is null.  
     * @throws IllegalArgumentException if the associated TileCodecDescriptor's
     * includesSampleModelInfo() returns false and a non-null value for the
     * "sampleModel" parameter is not supplied in the supplied parameter list.
     * @return The associated <code>TileDecoder</code>, or <code>null</code>.
     * @throws IOException if an I/O error occurs while reading from the
     * associated InputStream.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static Raster decode(OperationRegistry registry,
				String formatName,
				InputStream input,
				TileCodecParameterList param,
				Point location) throws IOException {}
}


2.13 Class TileEncoderRegistry

package javax.media.jai.registry;

/**
 * Utility class to provide type-safe interaction with the
 * <code>OperationRegistry</code> for <code>TileEncoderFactory</code> objects.
 *
 * If the <code>OperationRegistry</code> specified as an argument to the
 * methods in this class is null, then <code>JAI.getOperationRegistry()</code>
 * will be used.
 */
public final class TileEncoderRegistry  {

    /**
     * Registers the given <code>TileEncoderFactory</code> with the given 
     * <code>OperationRegistry</code> under the given formatName and
     * productName.
     *
     * @param registry    The <code>OperationRegistry</code> to register the 
     *                    <code>TileEncoderFactory</code> with.
     * @param formatName  The formatName to register the 
     *                    <code>TileEncoderFactory</code> under.
     * @param productName The productName to register the 
     *                    <code>TileEncoderFactory</code> under.
     * @param tef         The <code>TileEncoderFactory</code> to register.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if tef is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static void register(OperationRegistry registry,
                                String formatName,
                                String productName,
                                TileEncoderFactory tef) {}

    /**
     * Unregisters the given <code>TileEncoderFactory</code> previously 
     * registered under the given formatName and productName in the given
     * <code>OperationRegistry</code>.
     *
     * @param registry    The <code>OperationRegistry</code> to unregister the 
     *                    <code>TileEncoderFactory</code> from.
     * @param formatName  The formatName to unregister the
     *                    <code>TileEncoderFactory</code> from.
     * @param productName The productName to unregister the
     *                    <code>TileEncoderFactory</code> from.
     * @param tef         The <code>TileEncoderFactory</code> to unregister.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if tef is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     * @throws IllegalArgumentException if the tef was not previously
     * registered against the given formatName and productName.
     */
    public static void unregister(OperationRegistry registry,
                                  String formatName,
                                  String productName,
                                  TileEncoderFactory tef) {}

    /**
     * Sets a preference between the given two <code>TileEncoderFactory</code> 
     * objects in the given <code>OperationRegistry</code> under the given
     * formatName and productName.
     *
     * @param registry     The <code>OperationRegistry</code> to set
     *                     preferences on.
     * @param formatName   The formatName of the two
     *                     <code>TileEncoderFactory</code>s.
     * @param productName  The productName of the two
     *                     <code>TileEncoderFactory</code>s.
     * @param preferredTEF The preferred <code>TileEncoderFactory</code>.
     * @param otherTEF     The other <code>TileEncoderFactory</code>.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if preferredTEF is null.
     * @throws IllegalArgumentException if otherTEF is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     * @throws IllegalArgumentException if either of the two tef's
     * was not previously registered against formatName and productName.
     */
    public static void setPreference(OperationRegistry registry,
                                     String formatName,
                                     String productName,
                                     TileEncoderFactory preferredTEF,
                                     TileEncoderFactory otherTEF) {}

    /**
     * Unsets a preference previously set amongst the given two 
     * <code>TileEncoderFactory</code> objects in the given
     * <code>OperationRegistry</code> under the given formatName and productName.
     *
     * @param registry     The <code>OperationRegistry</code> to unset
     *                     preferences on.
     * @param formanName   The formatName of the two
     *                     <code>TileEncoderFactory</code>s.
     * @param productName  The productName  of the two
     *                     <code>TileEncoderFactory</code>s.
     * @param preferredTEF The preferred <code>TileEncoderFactory</code>.
     * @param otherTEF     The other <code>TileEncoderFactory</code>.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.
     * @throws IllegalArgumentException if preferredTEF is null.
     * @throws IllegalArgumentException if otherTEF is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     * @throws IllegalArgumentException if either of the two tef's
     * was not previously registered against formatName and productName.
     */
    public static void unsetPreference(OperationRegistry registry,
                                       String formatName,
                                       String productName,
                                       TileEncoderFactory preferredTEF,
                                       TileEncoderFactory otherTEF) {}

    /**
     * Clears all preferences set for registered <code>TileEncoderFactory</code>s
     * under the given formatName and productName in the given
     * <code>OperationRegistry</code>.
     *
     * @param registry    The <code>OperationRegistry</code> to clear
     *                    preferences from.
     * @param formatName  The format name to clear preferences under.
     * @param productName The productName to clear preferences under.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static void clearPreferences(OperationRegistry registry,
                                        String formatName,
                                        String productName) {}

    /**
     * Returns a List of the <code>TileEncoderFactory</code>s registered in
     * the given <code>OperationRegistry</code> under the given formatName
     * and productName, in an ordering that satisfies all of the pairwise
     * preferences that have been set. Cycles will be broken in an
     * arbitrary manner.
     *
     * @param registry    The <code>OperationRegistry</code> to clear
     *                    preferences from.
     * @param formatName  The format name to clear preferences under.
     * @param productName The productName to clear preferences under.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if productName is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static List getOrderedList(OperationRegistry registry,
				      String formatName,
				      String productName) {}

    /**
      * Returns an <code>Iterator</code> over all 
      * <code>TileEncoderFactory</code> objects registered under the
      * given format name over all products. The order of the
      * <code>TileEncoderFactory</code> objects in the iteration will
      * be according to the pairwise preferences among products and
      * <code>TileEncoderFactory</code> objects within a product. The
      * <code>remove()</code> method of the <code>Iterator</code>
      * may not be implemented.
      *
      * @param registry    The <code>OperationRegistry</code> to use.
      * @param formatName  The format name.
      *
      * @return an <code>Iterator</code> over <code>TileEncoderFactory</code>
      * objects.
      *
      * @throws IllegalArgumentException if formatName is <code>null</code>
      * @throws IllegalArgumentException if there is no
      * <code>TileCodecDescriptor</code> registered against
      * the <code>formatName</code>.
      *
      * @since JAI 1.1
      */
    public static Iterator getIterator(OperationRegistry registry, 
				       String formatName) {}

    /**
      * Returns the the most preferred <code>TileEncoderFactory</code>
      * object registered against the given format name. This
      * method will return the first <code>TileEncoderFactory</code> that
      * would be encountered by the <code>Iterator</code> returned by the
      * <code>getIterator()</code> method.
      *
      * @param registry The <code>OperationRegistry</code> to use.
      *                 If this is <code>null</code>, then <code>
      *                 JAI.getDefaultInstance().getOperationRegistry()</code>
      *                 will be used.
      * @param formatName The format name as a <code>String</code>
      *
      * @return a registered <code>TileEncoderFactory</code> object
      *
      * @throws IllegalArgumentException if formatName is <code>null</code>.
      * @throws IllegalArgumentException if there is no <code>
      * TileCodecDescriptor</code> registered against the <code>formatName</code>
      */
    public static TileEncoderFactory get(OperationRegistry registry, 
				         String formatName) {}

    /**
     * Creates a <code>TileEncoder</code> for the specified format that is
     * capable of handling the supplied arguments.  
     *
     * <p> The preferences set amongst the <code>TileEncoderFactory</code>
     * objects registered with the <code>OperationRegistry</code> are used
     * to select the most prefered <code>TileEncoderFactory</code> whose
     * <code>createEncoder()</code> method returns a non-null value.
     *
     * @param registry    The <code>OperationRegistry</code> to use to create
     *                    the <code>TileEncoder</code>.
     * @param formatName  The format for which the <code>TileEncoder</code> is
     *                    to be created.
     * @param output      The <code>OutputStream</code> to write encoded data to.
     * @param paramList   The object containing the tile encoding parameters.
     * @param sampleModel The <code>SampleModel</code> of the 
     *                    <code>Raster</code> to be encoded.
     *
     * @throws IllegalArgumentException if formatName is null.
     * @throws IllegalArgumentException if output is null.
     * @throws IllegalArgumentException if sampleModel is null.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static TileEncoder create(OperationRegistry registry,
				     String formatName,
				     OutputStream output,
				     TileCodecParameterList paramList,
				     SampleModel sampleModel) {}

    /**
     * Encodes the given <code>Raster</code> using the given formatName and 
     * <code>TileCodecParameterList</code> and writes the encoded data to the 
     * specified <code>OutputStream</code>. 
     * The <code>TileEncoder</code> which performs the encoding is the
     * one created from the most prefered <code>TileEncoderFactory</code> 
     * whose <code>create</code> method returns a non-null result. If
     * there are no <code>TileEncoder</code> objects that can encode
     * the specified <code>Raster</code> according to the encoding
     * parameters supplied, nothing will be written to the specified
     * <code>OutputStream</code>.
     *
     * <p> If the specified <code>TileCodecParameterList</code> is null, the 
     * default <code>TileCodecParameterList</code> retrieved by the specific
     * <code>TileEncoder.getDefaultParameters()</code> method for the 
     * "tileEncoder" registry mode will be used.
     *
     * <p> If multiple tiles are to be encoded to the same 
     * <code>OutputStream</code> in the same format using the same
     * <code>TileCodecParameterList</code>, it is advisable to create a
     * <code>TileEncoder</code> object and use the <code>encode()</code> method
     * on this encoder to encode each tile, thus creating and using only a
     * single <code>TileEncoder</code> object. The <code>encode()</code>
     * method on <code>TileEncoderRegistry</code> creates a new
     * <code>TileEncoder</code> object each time it is called.
     *
     * @param registry   The <code>OperationRegistry</code> to use to create
     *                   the <code>TileEncoder</code>.
     * @param formatName The name of the format to encode the data in.
     * @param raster     The <code>Raster</code> to be encoded.
     * @param output     The <code>OutputStream</code> to write the encoded
     *                   data to.
     * @param param      The <code>TileCodecParameterList</code> to be used.
     * @throws IllegalArgumentException if formatName is null.  
     * @throws IllegalArgumentException if raster is null.
     * @throws IllegalArgumentException if output is null.
     * @throws IOException if an input/output error occurs during the encoding.
     * @return The associated <code>TileEncoder</code>, or <code>null</code>.   
     * @throws IllegalArgumentException if there is no 
     * <code>TileCodecDescriptor</code> registered against the 
     * given <code>formatName</code>.
     */
    public static void encode(OperationRegistry registry,
			      String formatName, 
			      Raster raster,
			      OutputStream output,
			      TileCodecParameterList param) throws IOException {}
}


3. Format specific TileCodecDescriptors

3.1 GZIPTileCodecDescriptor

package javax.media.jai.tilecodec;

/**
 * <p>This class is the descriptor for the "GZIP" tile codec. This codec
 * scheme uses "gzip" as the method of compressing tile data. This is a 
 * lossless tile codec. The format name for the gzip tile codec is "gzip".
 * The encoded stream contains the <code>SampleModel</code> and the tile's
 * upper left corner position, thus the <code>includesSampleModelInfo()</code>
 * and <code>includesLocationInfo()</code> methods in this descriptor return
 * true.
 *
 * <p> The "gzip" codec scheme does not support any parameters.
 *
 * <p><table border=1>
 * <caption>Resource List</caption>
 * <tr><th>Name</th>        <th>Value</th></tr>
 * <tr><td>Vendor</td>      <td>com.sun.media.jai</td></tr>
 * <tr><td>Description</td> <td>A descriptor to describe the lossless "gzip" 
 *                              codec scheme. </td></tr>
 * <tr><td>DocURL</td>      <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/tilecodec/GZIPTileCodecDescriptor.html</td></tr>
 * <tr><td>Version</td>     <td>1.2</td></tr>
 * </table></p>
 *
 * <p><table border=1>
 * <caption>Parameter List</caption>
 * <tr><th>Name</th>          <th>Class Type</th>
 *                            <th>Default Value</th></tr>
 * </table></p>
 *
 * @since 1.1
 */
public class GZIPTileCodecDescriptor extends TileCodecDescriptorImpl {

    /**
     * Creates a <code>GZIPTileCodecDescriptor</code> 
     */
    public GZIPTileCodecDescriptor() {}

    /**
     * Returns a <code>TileCodecParameterList</code> valid for the 
     * specified modeName and compatible with the supplied
     * <code>TileCodecParameterList</code>. For example, given a
     * <code>TileCodecParameterList</code> used to encode a tile with
     * the modeName being specified as "tileDecoder", this method will
     * return a <code>TileCodecParameterList</code> 
     * sufficient to decode that same tile. For the gzip tile codec, 
     * no parameters are used. So null will be returned for any valid 
     * modeName specified.
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     * @param otherParamList The parameter list for which a compatible 
     *                       parameter list for the complementary modeName is
     *                       to be found.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getCompatibleParameters(
				      String modeName,
				      TileCodecParameterList otherParamList) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>. For the 
     * gzip tile codec, no parameters are used. So null will be
     * returned for any valid modeName specified. 
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>, adding a 
     * "sampleModel" parameter with the specified value to the parameter
     * list. For the gzip tile codec, no parameters are used. So null will be
     * returned for any valid modeName specified.
     * 
     * <p> This method should be used when includesSampleModelInfo()
     * returns false. If includesSampleModelInfo() returns true, the
     * supplied <code>SampleModel</code> is ignored.
     *
     * <p> If a parameter named "sampleModel" exists in the default 
     * parameter list, the supplied SampleModel will override the value 
     * associated with this default parameter.
     *
     * @param modeName The registry mode to return a valid parameter list for.
     * @param sm       The <code>SampleModel</code> used to create the 
     *                 default decoding parameter list.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName, 
						       SampleModel sm) {}

    /**
     * Returns the <code>ParameterListDescriptor</code> that describes
     * the associated parameters (NOT sources). This method returns
     * null if there are no parameters for the specified modeName.
     * If the specified modeName supports parameters but the
     * implementing class does not have parameters, then this method
     * returns a non-null <code>ParameterListDescriptor</code> whose
     * <code>getNumParameters()</code> returns 0.
     *
     * @param modeName The mode to get the ParameterListDescriptor for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public ParameterListDescriptor getParameterListDescriptor(String modeName) {}    
}


3.2 JPEGTileCodecDescriptor

package javax.media.jai.tilecodec;

/**
 * This class is the descriptor for the "JPEG" tile codec. "jpeg" is a
 * lossy tile codec, which involves compressing the tile data using the
 * jpeg standard. The format name for the jpeg tile codec is "jpeg". 
 * The encoded stream contains the <code>SampleModel</code> and the
 * tile's upper left corner position, thus the
 * <code>includesSampleModelInfo()</code> and 
 * <code>includesLocationInfo()</code> methods in this descriptor return
 * true.
 *
 * <p> This JPEG tile codec works well only on byte type images with 1, 
 * 3 or 4 bands.
 *
 * <p> While both the "tileDecoder" and "tileEncoder" registry modes for
 * the "jpeg" tile codec scheme have the same set of parameters, the 
 * parameters for the "tileDecoder" mode are read-only and will be
 * ignored if values are set for them in the 
 * <code>TileCodecParameterList</code> passed to the <code>TileDecoder</code>.
 * The reason for this is that the parameter values needed to control
 * the decoding process are included in the encoded stream, therefore
 * parameter values specified externally are ignored. Once the decoding
 * is completed, the parameter values in the 
 * <code>TileCodecParameterList</code> are updated to reflect the values
 * specified in the encoded stream.
 *
 * <p><table border=1>
 * <caption>Resource List</caption>
 * <tr><th>Name</th>        <th>Value</th></tr>
 * <tr><td>Vendor</td>      <td>com.sun.media.jai</td></tr>
 * <tr><td>Description</td> <td>A descriptor to describe the lossy "jpeg" codec
 *                          scheme. </td></tr>
 * <tr><td>DocURL</td>      <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/tilecodec/JPEGTileCodecDescriptor.html</td></tr>
 * <tr><td>Version</td>     <td>1.2</td></tr>
 * <tr><td>quality</td>    <td>
 *                           <p>A factor that relates to the desired tradeoff
 *			     between image quality and the image data
 *			     compression ratio. The range of this parameter
 *			     is from 0.0 to 1.0. A setting of 1.0 produces the 
 *			     highest quality image at a lower compression
 *			     rate. A setting of 0.0 produces the highest 
 *			     compression ratio, with a sacrifice to image 
 *			     quality. The default value is 0.75. <p>In JPEG,
 *			     compression, there are two ways to control the 
 *			     quantization quality: one is define quantization
 *			     table for each image component; the other is 
 *			     define the quality. The later overrides the
 *			     former. If neither the quality nor quantization
 *			     tables are set, the default setting is used.
 *                           <p>When the quality is set, a group of
 *			     quantization tables are generated by rescaling 
 *			     the default quantization tables. For more
 *			     infomation, please refer to the links below.
 *                           </td></tr>
 * <tr><td>qualitySet</td>   <td>A boolean used to indicate that the 
 * 			     parameter <code>quality</code> is set or 
 *			     not.</td></tr>
 * <tr><td>horizontalSubsampling</td>    <td>The subsampling rate in the
 *				horizontal direction applied to each image
 *				component to reduce their resolution
 *				prior to encoding.</td></tr>
 * <tr><td>verticalSubsampling</td>    <td>The subsampling rate in the
 *                              vertical direction applied to each image
 *                              component to reduce their resolution
 *                              prior to encoding.</td></tr>
 * <tr><td>quantizationTableMapping</td>    <td>In JPEG compression, several 
 *				image components may share one quantization
 *				table. This is the mapping between the 
 *				image component and the quantization 
 *				tables.</td></tr>
 * <tr><td>quantizationTable0</td>    <td>A quantization table for JPEG codec
 *				is an array of 64 (8x8) expressed in zig-zag 
 *				order (see the JPEG spec section K.1). Since 
 *                              this descriptor defines a JPEG scheme where the
 *                              tile has at most 4 components, so at most 4
 *                              quantization tables will
 *				be used. This parameter is the first 
 *				quantization table. </td></tr>
 * <tr><td>quantizationTable1</td> <td>The second quantization table.</td></tr>
 * <tr><td>quantizationTable2</td> <td>The third quantization table.</td></tr>
 * <tr><td>quantizationTable3</td> <td>The fourth quantization table.</td></tr>
 * <tr><td>restartInterval</td>  <td>JPEG images use restart markers to define 
 *				multiple strips or tiles. The restart markers 
 *				are inserted periodically into the image data 
 *				to delineate image segments known as restart
 *			        intervals. To limit the effect of bitstream 
 *				errors to a single restart interval, JAI 
 *				provides methods to set the restart interval 
 *				in JPEG Minimum Coded Units (MCUs). 
 *				The default is zero (no restart interval 
 *				markers). </td></tr>
 * <tr><td>writeImageInfo</td>    <td>A boolean instructs the encoder to 
 *				write the image data to the output 
 *				stream. </td></tr>
 * <tr><td>writeTableInfo</td>    <td>A boolean instructs the encoder to 
 *				write the table data to the output 
 *				stream.</td></tr>
 * <tr><td>writeJFIFHeader</td>    <td>The JPEG File Interchange Format (JFIF) 
 *				is a minimal file format that enables JPEG 
 *				bitstreams to be exchanged between a wide 
 *				variety of platforms and applications. 
 *				The parameter instructs the encoder to write
 *				the output stream in the JFIF format.</td></tr>
 * </table></p>
 *
 * <p><table border=1>
 * <caption>Parameter List</caption>
 * <tr><th>Name</th>          <th>Class Type</th>
 *                            <th>Default Value</th></tr>
 * <tr><td>quality</td>       <td>java.lang.Float</td>
 *                            <td>0.75</td>
 * <tr><td>qualitySet</td>    <td>java.lang.Boolean</td>
 *                            <td>true</td>
 * <tr><td>horizontalSubsampling</td>          <td>integer array</td>
 *                            <td>{1,1,1}</td>
 * <tr><td>verticalSubsampling</td>          <td>integer array</td>
 *                            <td>{1,1,1}</td>
 * <tr><td>quantizationTableMapping</td>          <td>integer array</td>
 *                            <td>{0,1,1}</td>
 * <tr><td>quantizationTable0</td>          <td>integer array</td>
 *                            <td>The default Luminance table as defined in
 *                                section K.1 of the JPEG specification.</td>
 * <tr><td>quantizationTable1</td>          <td>integer array</td>
 *                            <td>The default Chrominance table as defined in
 *                                section K.1 of the JPEG specification.</td>
 * <tr><td>quantizationTable2</td>          <td>integer array</td>
 *                            <td>The default Chrominance table as defined in
 *                                section K.1 of the JPEG specification.</td>
 * <tr><td>quantizationTable3</td>          <td>integer array</td>
 *                            <td>The default Chrominance table as defined in
 *                                section K.1 of the JPEG specification.</td>
 * <tr><td>restartInterval</td>          <td>java.lang.Integer</td>
 *                            <td>0</td>
 * <tr><td>writeImageInfo</td>          <td>java.lang.Boolean</td>
 *                            <td>true</td>
 * <tr><td>writeTableInfo</td>          <td>java.lang.Boolean</td>
 *                            <td>true</td>
 * <tr><td>writeJFIFHeader</td>          <td>java.lang.Boolean</td>
 *                            <td>false</td>
 * </table></p>
 *
 * @see com.sun.image.codec.jpeg.JPEGQTable
 * @see com.sun.image.codec.jpeg.JPEGDecodeParam
 * @see com.sun.image.codec.jpeg.JPEGEncodeParam
 *
 * @since 1.1
 */
public class JPEGTileCodecDescriptor extends TileCodecDescriptorImpl {

    /**
     * Creates a <code>JPEGTileCodecDescriptor</code> 
     */
    public JPEGTileCodecDescriptor() {}

    /**
     * Returns a <code>TileCodecParameterList</code> valid for the 
     * specified modeName and compatible with the supplied
     * <code>TileCodecParameterList</code>. For example, given a
     * <code>TileCodecParameterList</code> used to encode a tile with
     * the modeName being specified as "tileDecoder", this method will return
     * a <code>TileCodecParameterList</code> sufficient to decode that
     * same tile. 
     *
     * <p> If the supplied modeName is one of the valid mode names as
     * ascertained from the <code>getSupportedNames()</code> method, 
     * this method returns a <code>TileCodecParameterList</code> that 
     * contains values that are compatible for the supplied mode name.
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     * @param otherParamList The parameter list for which a compatible 
     *                       parameter list for the complementary modeName is
     *                       to be found.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getCompatibleParameters(
				      String modeName,
				      TileCodecParameterList otherParamList) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>. If the supplied
     * modeName is one of the valid mode names as ascertained from the 
     * <code>getSupportedNames()</code> method, this method returns the
     * default parameters for that mode.
     *
     * @param modeName  The mode to return the default parameters for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>, adding a 
     * "sampleModel" parameter with the specified value to the parameter
     * list. If the supplied modeName is one of the valid mode names as
     * ascertained from the <code>getSupportedNames()</code> method, this
     * method returns the default parameters for that mode.
     *
     * <p> This method should be used when includesSampleModelInfo()
     * returns false. If includesSampleModelInfo() returns true, the
     * supplied <code>SampleModel</code> is ignored. 
     *
     * <p>For the JPEG codec, includesSampleModelInfo() returns true, so 
     * the supplied <code> SampleModel</code> is ignored.
     *
     * @param modeName  The mode to return the default parameters for.
     * @param sm    The <code>SampleModel</code> used to create the 
     *              default decoding parameter list.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName, 
						       SampleModel sm) {}

    /**
     * Returns the <code>ParameterListDescriptor</code> that describes
     * the associated parameters (NOT sources). If the supplied modeName
     * is one of the valid mode names as ascertained from the 
     * <code>getSupportedNames()</code> method, this method returns a
     * non-null <code>ParameterListDescriptor</code> with the appropriate
     * parameters. 
     *
     * @param modeName  The mode to return the ParameterListDescriptor for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public ParameterListDescriptor getParameterListDescriptor(String modeName) {}
}


3.3 RawTileCodecDescriptor

package javax.media.jai.tilecodec ;

/**
 * This class is the descriptor for the "Raw" tile codec. The "Raw" tile
 * codec scheme involves simply writing out the raw pixel data to the
 * encoded stream. The format name for the raw tile codec is "raw". 
 * Since the encoded stream contains the <code>Raster</code>, it 
 * automatically contains the <code>SampleModel</code> and the tile's
 * upper left corner position. Therefore the
 * <code>includesSampleModelInfo()</code> and 
 * <code>includesLocationInfo()</code> methods in this descriptor return
 * true.
 *
 * <p> The "Raw" codec scheme does not support any parameters.
 *
 * <p><table border=1>
 * <caption>Resource List</caption>
 * <tr><th>Name</th>        <th>Value</th></tr>
 * <tr><td>Vendor</td>      <td>com.sun.media.jai</td></tr>
 * <tr><td>Description</td> <td>A descriptor to describe the lossless
 *                              "raw" codec scheme. </td></tr>
 * <tr><td>DocURL</td>      <td>http://java.sun.com/products/java-media/jai/forDevelopers/jai-apidocs/javax/media/jai/tilecodec/RawTileCodecDescriptor.html</td></tr>
 * <tr><td>Version</td>     <td>1.2</td></tr>
 * </table></p>
 *
 * <p><table border=1>
 * <caption>Parameter List</caption>
 * <tr><th>Name</th>          <th>Class Type</th>
 *                            <th>Default Value</th></tr>
 * </table></p>
 *
 * @since 1.1
 */
public class RawTileCodecDescriptor extends TileCodecDescriptorImpl {

    /**
     * Creates a <code>RawTileCodecDescriptor</code>.
     */
    public RawTileCodecDescriptor( ) {}

    /**
     * Returns a <code>TileCodecParameterList</code> valid for the 
     * specified modeName and compatible with the supplied
     * <code>TileCodecParameterList</code>. For example, given a
     * <code>TileCodecParameterList</code> used to encode a tile with
     * the modeName being specified as "tileDecoder", this method will return
     * a <code>TileCodecParameterList</code> sufficient to decode that
     * same tile. For the raw tile codec, no parameters are used. So null
     * will be returned for any valid modeName specified.
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     * @param otherParamList The parameter list for which a compatible 
     *                       parameter list for the complementary modeName is
     *                       to be found.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getCompatibleParameters(
				      String modeName,
				      TileCodecParameterList otherParamList) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>. For the 
     * raw tile codec, no parameters are used. So null will be
     * returned for any valid modeName specified.
     *
     * @param modeName       The registry mode to return a valid parameter 
     *                       list for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName) {}

    /**
     * Returns the default parameters for the specified modeName as an
     * instance of the <code>TileCodecParameterList</code>, adding a 
     * "sampleModel" parameter with the specified value to the parameter
     * list. For the raw tile codec, no parameters is used. So null will be
     * returned for any valid modeName specified.
     * 
     * <p> This method should be used when includesSampleModelInfo()
     * returns false. If includesSampleModelInfo() returns true, the
     * supplied <code>SampleModel</code> is ignored.
     *
     * <p> If a parameter named "sampleModel" exists in the default 
     * parameter list, the supplied SampleModel will override the value 
     * associated with this default parameter.
     *
     * @param modeName The registry mode to return a valid parameter list for.
     * @param sm   The <code>SampleModel</code> used to create the 
     *             default decoding parameter list.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public TileCodecParameterList getDefaultParameters(String modeName, 
						       SampleModel sm) {}

    /**
     * Returns the <code>ParameterListDescriptor</code> that describes
     * the associated parameters (NOT sources). This method returns
     * null if there are no parameters for the specified modeName.
     * If the specified modeName supports parameters but the
     * implementing class does not have parameters, then this method
     * returns a non-null <code>ParameterListDescriptor</code> whose
     * <code>getNumParameters()</code> returns 0.
     *
     * @param modeName The mode to return a ParameterListDescriptor for.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     *
     * @throws IllegalArgumentException if <code>modeName</code> is null.
     * @throws IllegalArgumentException if <code>modeName</code> is not
     * one of the modes valid for this descriptor, i.e those returned
     * from the getSupportedNames() method.
     */
    public ParameterListDescriptor getParameterListDescriptor(String modeName) {}    
}