javax.media.jai.registry
Class TileDecoderRegistry

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

public final class TileDecoderRegistry

extends 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:

JAI 1.1

Constructor Summary

TileDecoderRegistry()

Method Summary

static void	clearPreferences(OperationRegistry registry, String formatName, String productName) Clears all preferences set for registered TileDecoderFactorys under the given formatName and productName in the given OperationRegistry.
static TileDecoder	create(OperationRegistry registry, String formatName, InputStream input, TileCodecParameterList paramList) Creates a TileDecoder for the specified format that is capable of handling the supplied arguments.
static Raster	decode(OperationRegistry registry, String formatName, InputStream input, TileCodecParameterList param) Decodes the data from the specified InputStream using the given formatName and TileCodecParameterList.
static Raster	decode(OperationRegistry registry, String formatName, InputStream input, TileCodecParameterList param, Point location) Decodes the data from the specified InputStream using the given formatName and TileCodecParameterList.
static TileDecoderFactory	get(OperationRegistry registry, String formatName) Returns the the most preferred TileDecoderFactory object registered against the given format name.
static Iterator	getIterator(OperationRegistry registry, String formatName) Returns an Iterator over all TileDecoderFactory objects registered under the given format name over all products.
static List	getOrderedList(OperationRegistry registry, String formatName, String productName) Returns a List of the TileDecoderFactorys 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, String formatName, String productName, TileDecoderFactory tdf) Registers the given TileDecoderFactory with the given OperationRegistry under the given formatName and productName.
static void	setPreference(OperationRegistry registry, String formatName, 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, String formatName, 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, String formatName, 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,
                            String formatName,
                            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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if tdf is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName

unregister

public static void unregister(OperationRegistry registry,
                              String formatName,
                              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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if tdf is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName

IllegalArgumentException - if the tdf was not previously registered against the given formatName and productName.

setPreference

public static void setPreference(OperationRegistry registry,
                                 String formatName,
                                 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 TileDecoderFactorys.

productName - The productName of the two TileDecoderFactorys.

preferredTDF - The preferred TileDecoderFactory.

otherTDF - The other TileDecoderFactory.

Throws:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if preferredTDF is null.

IllegalArgumentException - if otherTDF is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName

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,
                                   String formatName,
                                   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 TileDecoderFactorys.

productName - The productName of the two TileDecoderFactorys.

preferredTDF - The preferred TileDecoderFactory.

otherTDF - The other TileDecoderFactory.

Throws:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if preferredTDF is null.

IllegalArgumentException - if otherTDF is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName

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,
                                    String formatName,
                                    String productName)

Clears all preferences set for registered TileDecoderFactorys 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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.

getOrderedList

public static List getOrderedList(OperationRegistry registry,
                                  String formatName,
                                  String productName)

Returns a List of the TileDecoderFactorys 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. Returns null if cycles exist.

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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if productName is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.

getIterator

public static Iterator getIterator(OperationRegistry registry,
                                   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:

IllegalArgumentException - if formatName is null

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.

get

public static TileDecoderFactory get(OperationRegistry registry,
                                     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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the formatName

create

public static TileDecoder create(OperationRegistry registry,
                                 String formatName,
                                 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.

Since this class is a simple type-safe wrapper around OperationRegistry's type-unsafe methods, no additional argument validation is performed in this method. Thus errors/exceptions may occur if incorrect values are provided for the input arguments.

Exceptions thrown by the TileDecoderFactorys used to create the TileDecoder will be caught by this method and will not be propagated.

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:

IllegalArgumentException - if formatName is null.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.

decode

public static Raster decode(OperationRegistry registry,
                            String formatName,
                            InputStream input,
                            TileCodecParameterList param)
                     throws 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.

Since this class is a simple type-safe wrapper around OperationRegistry's type-unsafe methods, no additional argument validation is performed in this method. Thus errors/exceptions may occur if incorrect values are provided for the input arguments.

Exceptions thrown by the TileDecoderFactorys used to create the TileDecoder will be caught by this method and will not be propagated.

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:

IllegalArgumentException - if formatName is null.

IOException - if an I/O error occurs while reading from the associated InputStream.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.

decode

public static Raster decode(OperationRegistry registry,
                            String formatName,
                            InputStream input,
                            TileCodecParameterList param,
                            Point location)
                     throws 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.

Since this class is a simple type-safe wrapper around OperationRegistry's type-unsafe methods, no additional argument validation is performed in this method. Thus errors/exceptions may occur if incorrect values are provided for the input arguments.

Exceptions thrown by the TileDecoderFactorys used to create the TileDecoder will be caught by this method and will not be propagated.

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:

IllegalArgumentException - if formatName is null.

IOException - if an inout/output error occurs while reading from the associated InputStream or during decoding.

IllegalArgumentException - if there is no TileCodecDescriptor registered against the given formatName.