## javax.media.jai.registry
Class TileDecoderRegistry

    java.lang.Object
      |
      +--javax.media.jai.registry.TileDecoderRegistry

public final class TileDecoderRegistry
extends java.lang.Object

Utility class to provide type-safe interaction with the `OperationRegistry` for `TileDecoderFactory` objects. If the `OperationRegistry` specified as an argument to the methods in this class is null, then `JAI.getOperationRegistry()` will be used.

Since:
  1.1

Constructor Summary
`TileDecoderRegistry()`

Method Summary
`static void` `clearPreferences(OperationRegistry registry, java.lang.String formatName, java.lang.String productName)` Clears all preferences set for registered `TileDecoderFactory`s under the given formatName and productName in the given `OperationRegistry`.
`static TileDecoder` `create(OperationRegistry registry, java.lang.String formatName, java.io.InputStream input, TileCodecParameterList paramList)` Creates a `TileDecoder` for the specified format that is capable of handling the supplied arguments.
`static java.awt.image.Raster` `decode(OperationRegistry registry, java.lang.String formatName, java.io.InputStream input, TileCodecParameterList param)` Decodes the data from the specified `InputStream` using the given formatName and `TileCodecParameterList`.
`static java.awt.image.Raster` `decode(OperationRegistry registry, java.lang.String formatName, java.io.InputStream input, TileCodecParameterList param, java.awt.Point location)` Decodes the data from the specified `InputStream` using the given formatName and `TileCodecParameterList`.
`static TileDecoderFactory` `get(OperationRegistry registry, java.lang.String formatName)` Returns the the most preferred `TileDecoderFactory` object registered against the given format name.
`static java.util.Iterator` `getIterator(OperationRegistry registry, java.lang.String formatName)` Returns an `Iterator` over all `TileDecoderFactory` objects registered under the given format name over all products.
`static java.util.List` `getOrderedList(OperationRegistry registry, java.lang.String formatName, java.lang.String productName)` Returns a List of the `TileDecoderFactory`s registered in the given `OperationRegistry` under the given formatName and productName, in an ordering that satisfies all of the pairwise preferences that have been set.
`static void` `register(OperationRegistry registry, java.lang.String formatName, java.lang.String productName, TileDecoderFactory tdf)` Registers the given `TileDecoderFactory` with the given `OperationRegistry` under the given formatName and productName.
`static void` `setPreference(OperationRegistry registry, java.lang.String formatName, java.lang.String productName, TileDecoderFactory preferredTDF, TileDecoderFactory otherTDF)` Sets a preference between the given two `TileDecoderFactory` objects in the given `OperationRegistry` under the given formatName and productName.
`static void` `unregister(OperationRegistry registry, java.lang.String formatName, java.lang.String productName, TileDecoderFactory tdf)` Unregisters the given `TileDecoderFactory` previously registered under the given formatName and productName in the given `OperationRegistry`.
`static void` `unsetPreference(OperationRegistry registry, java.lang.String formatName, java.lang.String productName, TileDecoderFactory preferredTDF, TileDecoderFactory otherTDF)` Unsets a preference previously set amongst the given two `TileDecoderFactory` objects in the given `OperationRegistry` under the given formatName and productName.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### TileDecoderRegistry

    public TileDecoderRegistry()

Method Detail

### register

    public static void register(OperationRegistry registry,
                                java.lang.String formatName,
                                java.lang.String productName,
                                TileDecoderFactory tdf)

  Registers the given `TileDecoderFactory` with the given `OperationRegistry` under the given formatName and productName.
  Parameters:
    `registry` - The `OperationRegistry` to register the `TileDecoderFactory` with. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The formatName to register the `TileDecoderFactory` under.
    `productName` - The productName to register the `TileDecoderFactory` under.
    `tdf` - The `TileDecoderFactory` to register.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if tdf is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`

### unregister

    public static void unregister(OperationRegistry registry,
                                  java.lang.String formatName,
                                  java.lang.String productName,
                                  TileDecoderFactory tdf)

  Unregisters the given `TileDecoderFactory` previously registered under the given formatName and productName in the given `OperationRegistry`.
  Parameters:
    `registry` - The `OperationRegistry` to unregister the `TileDecoderFactory` from. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The formatName to unregister the `TileDecoderFactory` from.
    `productName` - The productName to unregister the `TileDecoderFactory` from.
    `tdf` - The `TileDecoderFactory` to unregister.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if tdf is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`
    `java.lang.IllegalArgumentException` - if the tdf was not previously registered against the given formatName and productName.

### setPreference

    public static void setPreference(OperationRegistry registry,
                                     java.lang.String formatName,
                                     java.lang.String productName,
                                     TileDecoderFactory preferredTDF,
                                     TileDecoderFactory otherTDF)

  Sets a preference between the given two `TileDecoderFactory` objects in the given `OperationRegistry` under the given formatName and productName.
  Parameters:
    `registry` - The `OperationRegistry` to set preferences on. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The formatName of the two `TileDecoderFactory`s.
    `productName` - The productName of the two `TileDecoderFactory`s.
    `preferredTDF` - The preferred `TileDecoderFactory`.
    `otherTDF` - The other `TileDecoderFactory`.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if preferredTDF is null.
    `java.lang.IllegalArgumentException` - if otherTDF is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`
    `java.lang.IllegalArgumentException` - if either of the two tdf's was not previously registered against the given formatName and productName.

### unsetPreference

    public static void unsetPreference(OperationRegistry registry,
                                       java.lang.String formatName,
                                       java.lang.String productName,
                                       TileDecoderFactory preferredTDF,
                                       TileDecoderFactory otherTDF)

  Unsets a preference previously set amongst the given two `TileDecoderFactory` objects in the given `OperationRegistry` under the given formatName and productName.
  Parameters:
    `registry` - The `OperationRegistry` to unset preferences on. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The formatName of the two `TileDecoderFactory`s.
    `productName` - The productName of the two `TileDecoderFactory`s.
    `preferredTDF` - The preferred `TileDecoderFactory`.
    `otherTDF` - The other `TileDecoderFactory`.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if preferredTDF is null.
    `java.lang.IllegalArgumentException` - if otherTDF is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`
    `java.lang.IllegalArgumentException` - if either of the two tdf's was not previously registered against the given formatName and productName.

### clearPreferences

    public static void clearPreferences(OperationRegistry registry,
                                        java.lang.String formatName,
                                        java.lang.String productName)

  Clears all preferences set for registered `TileDecoderFactory`s under the given formatName and productName in the given `OperationRegistry`.
  Parameters:
    `registry` - The `OperationRegistry` to clear preferences from. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name to clear preferences under.
    `productName` - The productName to clear preferences under.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.

### getOrderedList

    public static java.util.List getOrderedList(OperationRegistry registry,
                                                java.lang.String formatName,
                                                java.lang.String productName)

  Returns a List of the `TileDecoderFactory`s registered in the given `OperationRegistry` 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.
  Parameters:
    `registry` - The `OperationRegistry` to clear preferences from. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name to clear preferences under.
    `productName` - The productName to clear preferences under.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if productName is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.

### getIterator

    public static java.util.Iterator getIterator(OperationRegistry registry,
                                                 java.lang.String formatName)

  Returns an `Iterator` over all `TileDecoderFactory` objects registered under the given format name over all products. The order of the `TileDecoderFactory` objects in the iteration will be according to the pairwise preferences among products and `TileDecoderFactory` objects within a product. The `remove()` method of the `Iterator` may not be implemented.
  Parameters:
    `registry` - The `OperationRegistry` to use. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name.
  Returns:
    an `Iterator` over `TileDecoderFactory` objects.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is `null`
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.
  Since:
    JAI 1.1

### get

    public static TileDecoderFactory get(OperationRegistry registry,
                                         java.lang.String formatName)

  Returns the the most preferred `TileDecoderFactory` object registered against the given format name. This method will return the first `TileDecoderFactory` that would be encountered by the `Iterator` returned by the `getIterator()` method.
  Parameters:
    `registry` - The `OperationRegistry` to use. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name as a `String`
  Returns:
    a registered `TileDecoderFactory` object
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is `null`.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the `formatName`

### create

    public static TileDecoder create(OperationRegistry registry,
                                     java.lang.String formatName,
                                     java.io.InputStream input,
                                     TileCodecParameterList paramList)

  Creates a `TileDecoder` for the specified format that is capable of handling the supplied arguments.

  The preferences set amongst the `TileDecoderFactory` objects registered with the `OperationRegistry` are used to select the most prefered `TileDecoderFactory` whose `createDecoder()` method returns a non-null value.

  In order to do the decoding correctly, the caller should retrieve the `TileCodecDescriptor` associated with the returned `TileDecoder` from the `OperationRegistry` and use it's `includesLocationInfo()` method's return value to decide which of the two versions of the `decode()` method on the returned `TileDecoder` should be used.

  Parameters:
    `registry` - The `OperationRegistry` to use to create the `TileDecoder`. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format for which the `TileDecoder` is to be created.
    `input` - The `InputStream` to read encoded data from.
    `paramList` - The object containing the tile decoding parameters.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if input is null.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.

### decode

    public static java.awt.image.Raster decode(OperationRegistry registry,
                                               java.lang.String formatName,
                                               java.io.InputStream input,
                                               TileCodecParameterList param)
                                        throws java.io.IOException

  Decodes the data from the specified `InputStream` using the given formatName and `TileCodecParameterList`. The `TileDecoder` which performs the decoding is the one created from the most prefered `TileDecoderFactory` whose `create` method returns a non-null result.

  An `IllegalArgumentException` will be thrown if the specified format's `TileCodecDescriptor`'s `includesLocationInfo()` method returns false, as no location information is provided in this method.

  If the specified `TileCodecParameterList` is null, the default `TileCodecParameterList` retrieved by the specific `TileDecoder.getDefaultParameters`() method for the "tileDecoder" registry mode will be used.

  For the specified format, if the associated `TileCodecDescriptor`'s `includesSampleModelInfo()` method returns false, and either the specified `TileCodecParameterList` is null or if it doesn't contain a non-value for the "sampleModel" parameter, an `IllegalArgumentException` will be thrown.

  If there are no `TileDecoder` objects that can decode the specified `InputStream` according to the decoding parameters supplied, null will be returned from this method.

  If multiple tiles are to be decoded from the same `InputStream` in the same format using the same `TileCodecParameterList`, it is advisable to create a `TileDecoder` object and use the `decode()` method on this decoder for each tile, thus creating and using only a single `TileDecoder` object. The `decode()` method on `TileDecoderRegistry` creates a new `TileDecoder` object each time it is called.

  Parameters:
    `registry` - The `OperationRegistry` to use to create the `TileDecoder`. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name associated with the decoder.
    `input` - The `InputStream` containing the data to be decoded.
    `param` - The `TileCodecParameterList` to be used.
  Returns:
    The associated `TileDecoder`, or `null`.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if input is null.
    `java.lang.IllegalArgumentException` - if the specified format does not encode the location information into the encoded data stream.
    `java.lang.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.
    `java.io.IOException` - if an I/O error occurs while reading from the associated InputStream.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.

### decode

    public static java.awt.image.Raster decode(OperationRegistry registry,
                                               java.lang.String formatName,
                                               java.io.InputStream input,
                                               TileCodecParameterList param,
                                               java.awt.Point location)
                                        throws java.io.IOException

  Decodes the data from the specified `InputStream` using the given formatName and `TileCodecParameterList`. The `TileDecoder` which performs the decoding is the one created from the most prefered `TileDecoderFactory` whose `create` method returns a non-null result. If there are no `TileDecoder` objects that can decode the specified `InputStream` according to the decoding parameters supplied, null will be returned from this method.

  If the specified `TileCodecParameterList` is null, the default `TileCodecParameterList` retrieved by the specific `TileDecoder.getDefaultParameters()` method will be used.

  If the specified location is null, and the associated `TileCodecDescriptor`'s `includesLocationInfo()` method returns false, `IllegalArgumentException` will be thrown.

  For the specified format, if the associated `TileCodecDescriptor`'s `includesSampleModelInfo()` method returns false, and if the specified `TileCodecParameterList` is null or if it doesn't contain a non-value for the "sampleModel" parameter, an `IllegalArgumentException` will be thrown.

  If multiple tiles are to be decoded from the same `InputStream` in the same format using the same `TileCodecParameterList`, it is advisable to create a `TileDecoder` object and use the `decode()` method on this decoder for each tile, thus creating and using only a single `TileDecoder` object. The `decode()` method on `TileDecoderRegistry` creates a new `TileDecoder` object each time it is called.

  Parameters:
    `registry` - The `OperationRegistry` to use to create the `TileDecoder`. If this is `null`, then `JAI.getDefaultInstance().getOperationRegistry()` will be used.
    `formatName` - The format name associated with the decoder.
    `input` - The `InputStream` containing the data to be decoded.
    `param` - The `TileCodecParameterList` to be used.
    `location` - The `Point` specifying the upper left corner of the `Raster`.
  Returns:
    The associated `TileDecoder`, or `null`.
  Throws:
    `java.lang.IllegalArgumentException` - if formatName is null.
    `java.lang.IllegalArgumentException` - if input is null.
    `java.io.IOException` - if an input/output error occurs during decoding.
    `java.lang.IllegalArgumentException` - if includesLocationInfo() returns false and location is null.
    `java.lang.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.
    `java.io.IOException` - if an I/O error occurs while reading from the associated InputStream.
    `java.lang.IllegalArgumentException` - if there is no `TileCodecDescriptor` registered against the given `formatName`.