org.geotoolkit.image.io
Class ImageWriterAdapter

Object
  ImageWriter
      SpatialImageWriter
          ImageWriterAdapter

All Implemented Interfaces:

ImageTranscoder, Disposable, Localized, WarningProducer

Direct Known Subclasses:

WorldFileImageWriter

@Decorator(value=javax.imageio.ImageWriter.class)
public abstract class ImageWriterAdapter
extends SpatialImageWriter

Base class for writers which delegate most of their work to an other ImageWriter. This is used for reusing an existing image writer while adding some extra functionalities, like encoding geographic information found in SpatialMetadata.

The wrapped image writer is called the main writer. The output given to that writer is determined by the createOutput(String) method - it may or may not be the same output than the one given to this ImageWriterAdapter setOutput(Object) method.

The amount of methods declared in this class is large, but the only new methods are:

• createOutput(String)
• initialize()
• writeStreamMetadata(IIOMetadata)
• writeImageMetadata(IIOMetadata, int, ImageWriteParam)

All other methods override existing methods declared in parent classes, mostly ImageWriter and SpatialImageWriter. The default implementation of most methods delegate directly to the main writer.

Example
The World File format is composed of a classical image file (usually with the ".tiff", ".jpg" or ".png" extension) together with a small text file containing geolocalization information (often with the ".tfw" extension) and an other small text file containing projection information (".prj" extension). This ImageWriterAdapter class can be used for wrapping a TIFF image writer, augmented with the formatting of TFW and PRJ files. The information written in those files are fetched from the SpatialMetadata object given to the ImageWriter.write(IIOImage) method in this class.

Since:

3.07

Version:

3.18

Author:

Martin Desruisseaux (Geomatys)

See Also:

ImageReaderAdapter

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

static class

ImageWriterAdapter.Spi Service provider interface (SPI) for ImageWriterAdapters.

Field Summary

protected ImageWriter

main The writer to use for writing the pixel values.

Fields inherited from class ImageWriter

availableLocales, locale, originatingProvider, output, progressListeners, warningListeners, warningLocales

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

protected	ImageWriterAdapter(ImageWriterAdapter.Spi provider) Constructs a new image writer.
protected	ImageWriterAdapter(ImageWriterAdapter.Spi provider, ImageWriter main) Constructs a new image writer wrapping the given writer.

Method Summary

void	abort() Requests that any current write operation be aborted.
void	addIIOWriteProgressListener(IIOWriteProgressListener listener) Adds the given listener to the list of registered progress listeners.
void	addIIOWriteWarningListener(IIOWriteWarningListener listener) Adds the given listener to the list of registered warning listeners.
boolean	canReplacePixels(int imageIndex) Returns true if the writer allows pixels of the given image to be replaced using the replacePixels methods.
boolean	canWriteRasters() Returns true if the methods that take an IIOImage parameter are capable of dealing with a Raster.
boolean	canWriteSequence() Returns true if the writer is able to append an image to an image stream that already contains header information and possibly prior images.
protected void	close() Closes the output stream created by createOutput(String).
protected Object	createOutput(String writerID) Creates the output to give to the main writer, or to an other writer identified by the writerID argument.
void	dispose() Allows any resources held by this object to be released.
void	endReplacePixels() Terminates a sequence of calls to replacePixels.
void	endWriteSequence() Completes the writing of a sequence of images begun with prepareWriteSequence.
protected void	finalize() Invokes the close() method when this writer is garbage-collected.
Locale[]	getAvailableLocales() Returns the locales that may be used to localize warning listeners.
SpatialMetadata	getDefaultImageMetadata(ImageTypeSpecifier imageType, ImageWriteParam param) Returns a metadata object containing default values for encoding an image of the given type.
SpatialMetadata	getDefaultStreamMetadata(ImageWriteParam param) Returns a metadata object containing default values for encoding a stream of images.
SpatialImageWriteParam	getDefaultWriteParam() Returns a default parameter object appropriate for this format.
Locale	getLocale() Returns the locale used to localize warning listeners.
int	getNumThumbnailsSupported(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata) Returns the number of thumbnails suported by the format being written, or -1 if unknown.
Dimension[]	getPreferredThumbnailSizes(ImageTypeSpecifier imageType, ImageWriteParam param, IIOMetadata streamMetadata, IIOMetadata imageMetadata) Returns the legal size ranges for thumbnail images as they will be encoded in the output file or stream.
protected void	initialize() Invoked automatically when the main writer has been given a new output.
void	prepareReplacePixels(int imageIndex, Rectangle region) Prepares the writer to handle a series of calls to the replacePixels methods.
void	prepareWriteSequence(IIOMetadata streamMetadata) Prepares a stream to accept a series of subsequent writeToSequence calls.
void	removeAllIIOWriteProgressListeners() Removes all currently registered progress listeners.
void	removeAllIIOWriteWarningListeners() Removes all currently registered warning listeners.
void	removeIIOWriteProgressListener(IIOWriteProgressListener listener) Removes the given listener from the list of registered progress listeners.
void	removeIIOWriteWarningListener(IIOWriteWarningListener listener) Removes the given listener from the list of registered warning listeners.
void	replacePixels(Raster raster, ImageWriteParam param) Replaces a portion of an image already present in the output with a portion of the given raster.
void	replacePixels(RenderedImage image, ImageWriteParam param) Replaces a portion of an image already present in the output with a portion of the given image.
void	reset() Restores the ImageWriter to its initial state.
void	setLocale(Locale locale) Sets the locale used to localize warning listeners.
void	write(IIOMetadata streamMetadata, IIOImage image, ImageWriteParam param) Appends a complete image stream containing a single image and associated stream and image metadata and thumbnails to the output.
protected void	writeImageMetadata(IIOMetadata metadata, int imageIndex, ImageWriteParam param) Invoked by the write methods when image metadata needs to be written.
protected void	writeStreamMetadata(IIOMetadata metadata) Invoked by the write methods when stream metadata needs to be written.
void	writeToSequence(IIOImage image, ImageWriteParam param) Appends a single image and possibly associated metadata to the output.

Methods inherited from class SpatialImageWriter

computeSize, convertImageMetadata, convertStreamMetadata, createRectIter, getSampleModel, processImageComplete, processImageStarted, processThumbnailComplete, processThumbnailStarted, processWarningOccurred, processWarningOccurred, setOutput, warningOccurred

Methods inherited from class ImageWriter

abortRequested, canInsertEmpty, canInsertImage, canRemoveImage, canReplaceImageMetadata, canReplaceStreamMetadata, canWriteEmpty, clearAbortRequest, endInsertEmpty, endWriteEmpty, getOriginatingProvider, getOutput, prepareInsertEmpty, prepareWriteEmpty, processImageProgress, processImageStarted, processThumbnailProgress, processThumbnailStarted, processWarningOccurred, processWarningOccurred, processWriteAborted, removeImage, replaceImageMetadata, replaceStreamMetadata, write, write, writeInsert

Methods inherited from class Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

main

protected final ImageWriter main

The writer to use for writing the pixel values.

Constructor Detail

ImageWriterAdapter

protected ImageWriterAdapter(ImageWriterAdapter.Spi provider)
                      throws IOException

Constructs a new image writer. The provider argument is mandatory for this constructor. If the provider is unknown, use the next constructor below instead.

Parameters:

provider - The ImageWriterSpi that is constructing this object.

Throws:

IOException - If an error occurred while creating the main writer.

ImageWriterAdapter

protected ImageWriterAdapter(ImageWriterAdapter.Spi provider,
                             ImageWriter main)

Constructs a new image writer wrapping the given writer.

Parameters:

provider - The ImageWriterSpi that is constructing this object, or null.

main - The writer to use for writing the pixel values.

Method Detail

createOutput

protected Object createOutput(String writerID)
                       throws IllegalStateException,
                              IOException

Creates the output to give to the main writer, or to an other writer identified by the writerID argument. The default ImageWriterAdapter implementation invokes this method with a writerID argument value equals to "main" when the main writer needs to be used for the first time. This may happen at any time after the setOutput method has been invoked.

The only writerID argument value accepted by the default implementation is "main"; any other argument value causes a null value to be returned. However subclasses can override this method for supporting more writer types. The table below summarizes a few types supported by this writer and different subclasses:

Writer type	Defined by	Usage
"main"	ImageWriterAdapter	The output to be given to the main writer.
"tfw"	WorldFileImageWriter	The output for the World File.
"prj"	WorldFileImageWriter	The output for the Map Projection file.

The default implementation first checks if the main writer accepts directly the output of this writer. If so, then that output is returned with no change. Otherwise the output is wrapped in an ImageOutputStream, which is returned. The output stream assigned to the main writer will be closed by the close() method.

Parameters:

writerID - Identifier of the writer for which an output is needed.

Returns:

The output to give to the identified writer, or null if this method can not create such output.

Throws:

IllegalStateException - if the output has not been set.

IOException - If an error occurred while creating the output for the writer.

See Also:

ImageReaderAdapter.createInput(String)

initialize

protected void initialize()
                   throws IOException

Invoked automatically when the main writer has been given a new output. When this method is invoked, the main writer output has already been set to the value returned by createOutput("main").

The default implementation does nothing. Subclasses can override this method for performing additional initialization.

Throws:

IOException - If an error occurred while initializing the main writer.

getDefaultWriteParam

public SpatialImageWriteParam getDefaultWriteParam()

Returns a default parameter object appropriate for this format.

Overrides:

getDefaultWriteParam in class SpatialImageWriter

Returns:

An ImageWriteParam object which may be used.

getDefaultStreamMetadata

public SpatialMetadata getDefaultStreamMetadata(ImageWriteParam param)

Returns a metadata object containing default values for encoding a stream of images. The default implementation returns the union of the metadata formats declared by the main writer, and the Geotk stream metadata format.

Subclasses can override the writeStreamMetadata(IIOMetadata) method for writing those metadata to the output.

Overrides:

getDefaultStreamMetadata in class SpatialImageWriter

Parameters:

param - Parameters that will be used to encode the image (in cases where it may affect the structure of the metadata), or null.

Returns:

The metadata, or null.

getDefaultImageMetadata

public SpatialMetadata getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                               ImageWriteParam param)

Returns a metadata object containing default values for encoding an image of the given type. The default implementation returns the union of the metadata formats declared by the main writer, and the Geotk image metadata format.

Subclasses can override the writeImageMetadata(IIOMetadata, int, ImageWriteParam) method for writing those metadata to the output.

Overrides:

getDefaultImageMetadata in class SpatialImageWriter

Parameters:

imageType - The format of the image to be written later.

param - Parameters that will be used to encode the image (in cases where it may affect the structure of the metadata), or null.

Returns:

The metadata, or null.

writeStreamMetadata

protected void writeStreamMetadata(IIOMetadata metadata)
                            throws IOException

Invoked by the write methods when stream metadata needs to be written. The metadata written by the main writer are not concerned by this method.

The default implementation does nothing. Subclasses can override this method for writing spatial metadata.

Parameters:

metadata - The stream metadata, or null if none.

Throws:

IOException - If an error occurred while writing the metadata.

See Also:

MetadataHelper

writeImageMetadata

protected void writeImageMetadata(IIOMetadata metadata,
                                  int imageIndex,
                                  ImageWriteParam param)
                           throws IOException

Invoked by the write methods when image metadata needs to be written. The metadata written by the main writer are not concerned by this method.

The default implementation does nothing. Subclasses can override this method for writing spatial metadata.

Parameters:

metadata - The stream metadata, or null if none.

imageIndex - The index of the image being written.

param - The user-specified parameter, or null if none.

Throws:

IOException - If an error occurred while writing the metadata.

See Also:

MetadataHelper

write

public void write(IIOMetadata streamMetadata,
                  IIOImage image,
                  ImageWriteParam param)
           throws IOException

Appends a complete image stream containing a single image and associated stream and image metadata and thumbnails to the output. The default implementation performs the following steps:

1. Ensures that the main writer has been initialized
2. Invokes writeStreamMetadata(IIOMetadata) with the given streamMetadata argument.
3. Invokes writeImageMetadata(IIOMetadata, int, ImageWriteParam) with the metadata obtained from the image argument.
4. Delegates the writing of pixel values to the main writer.

Specified by:

write in class ImageWriter

Throws:

IOException

canWriteRasters

public boolean canWriteRasters()

Returns true if the methods that take an IIOImage parameter are capable of dealing with a Raster. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

canWriteRasters in class SpatialImageWriter

canWriteSequence

public boolean canWriteSequence()

Returns true if the writer is able to append an image to an image stream that already contains header information and possibly prior images. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

canWriteSequence in class ImageWriter

prepareWriteSequence

public void prepareWriteSequence(IIOMetadata streamMetadata)
                          throws IOException

Prepares a stream to accept a series of subsequent writeToSequence calls. The default implementation performs the following steps:

1. Ensures that the main writer has been initialized
2. Invokes writeStreamMetadata(IIOMetadata) with the given streamMetadata argument.
3. Delegates to the main writer.

Overrides:

prepareWriteSequence in class ImageWriter

Throws:

IOException

writeToSequence

public void writeToSequence(IIOImage image,
                            ImageWriteParam param)
                     throws IOException

Appends a single image and possibly associated metadata to the output. The default implementation performs the following steps:

1. Invokes writeImageMetadata(IIOMetadata, int, ImageWriteParam) with the metadata obtained from the image argument.
2. Delegates to the main writer.

Overrides:

writeToSequence in class ImageWriter

Throws:

IOException

endWriteSequence

public void endWriteSequence()
                      throws IOException

Completes the writing of a sequence of images begun with prepareWriteSequence. The default implementation delegates to the main writer.

Overrides:

endWriteSequence in class ImageWriter

Throws:

IOException

canReplacePixels

public boolean canReplacePixels(int imageIndex)
                         throws IOException

Returns true if the writer allows pixels of the given image to be replaced using the replacePixels methods. The default implementation ensures that the main writer has been initialized, then delegates to that writer.

Overrides:

canReplacePixels in class ImageWriter

Throws:

IOException

prepareReplacePixels

public void prepareReplacePixels(int imageIndex,
                                 Rectangle region)
                          throws IOException

Prepares the writer to handle a series of calls to the replacePixels methods. The default implementation ensures that the main writer has been initialized, then delegates to that writer.

Overrides:

prepareReplacePixels in class ImageWriter

Throws:

IOException

replacePixels

public void replacePixels(RenderedImage image,
                          ImageWriteParam param)
                   throws IOException

Replaces a portion of an image already present in the output with a portion of the given image. The default implementation delegates to the main writer.

Overrides:

replacePixels in class ImageWriter

Throws:

IOException

replacePixels

public void replacePixels(Raster raster,
                          ImageWriteParam param)
                   throws IOException

Replaces a portion of an image already present in the output with a portion of the given raster. The default implementation delegates to the main writer.

Overrides:

replacePixels in class ImageWriter

Throws:

IOException

endReplacePixels

public void endReplacePixels()
                      throws IOException

Terminates a sequence of calls to replacePixels. The default implementation delegates to the main writer.

Overrides:

endReplacePixels in class ImageWriter

Throws:

IOException

getNumThumbnailsSupported

public int getNumThumbnailsSupported(ImageTypeSpecifier imageType,
                                     ImageWriteParam param,
                                     IIOMetadata streamMetadata,
                                     IIOMetadata imageMetadata)

Returns the number of thumbnails suported by the format being written, or -1 if unknown. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

getNumThumbnailsSupported in class ImageWriter

getPreferredThumbnailSizes

public Dimension[] getPreferredThumbnailSizes(ImageTypeSpecifier imageType,
                                              ImageWriteParam param,
                                              IIOMetadata streamMetadata,
                                              IIOMetadata imageMetadata)

Returns the legal size ranges for thumbnail images as they will be encoded in the output file or stream. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

getPreferredThumbnailSizes in class ImageWriter

getAvailableLocales

public Locale[] getAvailableLocales()

Returns the locales that may be used to localize warning listeners. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

getAvailableLocales in class ImageWriter

getLocale

public Locale getLocale()

Returns the locale used to localize warning listeners. The default implementation delegates to the main writer. No output needs to be set for this method.

Specified by:

getLocale in interface Localized

Overrides:

getLocale in class ImageWriter

setLocale

public void setLocale(Locale locale)

Sets the locale used to localize warning listeners. The default implementation delegates to the main writer. No output needs to be set for this method.

Overrides:

setLocale in class ImageWriter

addIIOWriteWarningListener

public void addIIOWriteWarningListener(IIOWriteWarningListener listener)

Adds the given listener to the list of registered warning listeners. Thie listener is added both to this writer and to the main writer.

Overrides:

addIIOWriteWarningListener in class ImageWriter

removeIIOWriteWarningListener

public void removeIIOWriteWarningListener(IIOWriteWarningListener listener)

Removes the given listener from the list of registered warning listeners.

Overrides:

removeIIOWriteWarningListener in class ImageWriter

removeAllIIOWriteWarningListeners

public void removeAllIIOWriteWarningListeners()

Removes all currently registered warning listeners.

Overrides:

removeAllIIOWriteWarningListeners in class ImageWriter

addIIOWriteProgressListener

public void addIIOWriteProgressListener(IIOWriteProgressListener listener)

Adds the given listener to the list of registered progress listeners. This method adds the listener only to the main writer, not to this writer, in order to ensure that progress methods are invoked only once.

Overrides:

addIIOWriteProgressListener in class ImageWriter

removeIIOWriteProgressListener

public void removeIIOWriteProgressListener(IIOWriteProgressListener listener)

Removes the given listener from the list of registered progress listeners.

Overrides:

removeIIOWriteProgressListener in class ImageWriter

removeAllIIOWriteProgressListeners

public void removeAllIIOWriteProgressListeners()

Removes all currently registered progress listeners.

Overrides:

removeAllIIOWriteProgressListeners in class ImageWriter

abort

public void abort()

Requests that any current write operation be aborted. The default implementation delegates to both the main writer and to the super-class method.

Overrides:

abort in class ImageWriter

reset

public void reset()

Restores the ImageWriter to its initial state. The default implementation delegates to both the main writer and to the super-class method.

Overrides:

reset in class ImageWriter

dispose

public void dispose()

Allows any resources held by this object to be released. The default implementation delegates to both the main writer and to the super-class method.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class SpatialImageWriter

close

protected void close()
              throws IOException

Closes the output stream created by createOutput(String). This method does nothing if the output used by the main writer is the one given by the user to the setOutput method. Otherwise, if the output of the main writer is an instance of ImageOutputStream or Closeable, then it is closed.

This method is invoked automatically by setOutput(...), reset(), dispose() or finalize() methods and doesn't need to be invoked explicitly. It has protected access only in order to allow overriding by subclasses. Overriding methods shall make sure that super.close() is invoked even in case of failure.

Throws:

IOException - if an error occurred while closing the stream.

finalize

protected void finalize()
                 throws Throwable

Invokes the close() method when this writer is garbage-collected. Note that this will actually close the stream only if it has been created by this writer, rather than supplied by the user.

Overrides:

finalize in class Object

Throws:

Throwable