javax.media.jai.remote
Class SerializableRenderedImage

java.lang.Object
  javax.media.jai.remote.SerializableRenderedImage

All Implemented Interfaces:

RenderedImage, Serializable

public final class SerializableRenderedImage

extends Object

implements RenderedImage, Serializable

A serializable wrapper class for classes which implement the RenderedImage interface.

A SerializableRenderedImage provides a means to serialize a RenderedImage. Transient fields are handled using Serializers registered with SerializerFactory. Two means are available for providing the wrapped RenderedImage data to a remote version of a SerializableRenderedImage object: either via deep copy or by "on-demand" copying. If a deep copy is requested, the entire image Raster is copied during object serialization and tiles are extracted from it as needed using the Raster.createChild() method. If a deep copy is not used, the image data are transmitted "on-demand" using socket communications. If the request is made on the local host, the image data are provided in both cases merely by forwarding the request to the wrapped RenderedImage. Note that a single SerializableRenderedImage object should be able to service multiple remote hosts.

The properties associated with the RenderedImage being wrapped are serialized and accessible to a remote version of a SerializableRenderedImage object. However it should be noted that only those properties which are serializable are available to the SerializableRenderedImage object.

This class makes no guarantee as to the stability of the data of the wrapped image, at least in the case where a deep copy is not made. Consequently if the data of a RenderedImage change but affected tiles have already been transmitted then the modifications will not be visible remotely. For example, this implies that a SerializableRenderedImage should not be used to wrap a RenderedOp the data of which are subject to change if the chain in which the node is present is edited. Instead the SerializableRenderedImage should be used to wrap the image returned by invoking either getRendering() or createInstance() on the RenderedOp. A similar situation will obtain if the wrapped image is a WritableRenderedImage. If in this case the wrapped image is also a PlanarImage, then the image returned by createSnapshot() should be wrapped instead.

An example of the usage of this class is as follows:

 import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.Serializable;

 public class SomeSerializableClass implements Serializable {
     protected transient RenderedImage image;

     // Fields omitted.

     public SomeSerializableClass(RenderedImage image) {
         this.image = image;
     }

     // Methods omitted.

     // Serialization method.
     private void writeObject(ObjectOutputStream out) throws IOException {
         out.defaultWriteObject();
         out.writeObject(new SerializableRenderedImage(image));
     }

     // Deserialization method.
     private void readObject(ObjectInputStream in)
         throws IOException, ClassNotFoundException {
         in.defaultReadObject();
         image = (RenderedImage)in.readObject();
     }
 }
 

Since:

JAI 1.1

See Also:

RenderedImage, WritableRenderedImage, PlanarImage, RenderedOp, Serialized Form

Constructor Summary

SerializableRenderedImage(RenderedImage source)
Constructs a SerializableRenderedImage wrapper for a RenderedImage source.

SerializableRenderedImage(RenderedImage source, boolean useDeepCopy)
Constructs a SerializableRenderedImage wrapper for a RenderedImage source.

SerializableRenderedImage(RenderedImage source, boolean useDeepCopy, OperationRegistry registry, String formatName, TileCodecParameterList encodingParam, TileCodecParameterList decodingParam)
Constructs a SerializableRenderedImage wrapper for a RenderedImage source.

Method Summary

WritableRaster	copyData(WritableRaster dest)
void	dispose() Provides a hint that an image will no longer be accessed from a reference in user space.
protected void	finalize() If a deep copy is not being used, unset the data server availability flag and wait for the server thread to rejoin the current thread.
ColorModel	getColorModel()
Raster	getData()
Raster	getData(Rectangle rect)
int	getHeight()
Object	getImageID() Returns a unique identifier (UID) for this RenderedImage.
int	getMinTileX()
int	getMinTileY()
int	getMinX()
int	getMinY()
int	getNumXTiles()
int	getNumYTiles()
Object	getProperty(String name)
String[]	getPropertyNames()
SampleModel	getSampleModel()
Vector	getSources() If this SerializableRenderedImage has not been serialized, this method returns a Vector containing only the RenderedImage passed to the constructor; if this image has been deserialized, it returns null.
Raster	getTile(int tileX, int tileY)
int	getTileGridXOffset()
int	getTileGridYOffset()
int	getTileHeight()
int	getTileWidth()
int	getWidth()

Methods inherited from class java.lang.Object

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

Constructor Detail

SerializableRenderedImage

public SerializableRenderedImage(RenderedImage source,
                                 boolean useDeepCopy,
                                 OperationRegistry registry,
                                 String formatName,
                                 TileCodecParameterList encodingParam,
                                 TileCodecParameterList decodingParam)
                          throws NotSerializableException

Constructs a SerializableRenderedImage wrapper for a RenderedImage source. Image data may be serialized tile-by-tile or via a single deep copy. Tile encoding and decoding may be effected via a TileEncoder and TileDecoder specified by format name.

It may be noted that if the TileCodec utilizes Serializers for encoding the image data, and none is available for the DataBuffer of the supplied image, an error/exception may be encountered.

Parameters:

source - The RenderedImage source.

useDeepCopy - Whether a deep copy of the entire image Raster will be made during object serialization.

registry - The OperationRegistry to use in creating the TileEncoder. The TileDecoder will of necessity be created using the default OperationRegistry as the specified OperationRegistry is not serialized. If null the default registry will be used.

formatName - The name of the format used to encode the data. If null simple tile serialization will be performed either directly or by use of a "raw" TileCodec.

encodingParam - The parameters to be used for data encoding. If null the default encoding TileCodecParameterList for this format will be used. Ignored if formatName is null.

decodingParam - The parameters to be used for data decoding. If null a complementary TileCodecParameterList will be derived from encodingParam. Ignored if formatName is null.

Throws:

IllegalArgumentException - if source is null.

IllegalArgumentException - if no Serializers are available for the types of SampleModel, and ColorModel contained in the specified image.

NotSerializableException

SerializableRenderedImage

public SerializableRenderedImage(RenderedImage source,
                                 boolean useDeepCopy)

Constructs a SerializableRenderedImage wrapper for a RenderedImage source. Image data may be serialized tile-by-tile or via a single deep copy. No TileCodec will be used, i.e., data will be transmitted using the serialization protocol for Rasters.

Parameters:

source - The RenderedImage source.

useDeepCopy - Whether a deep copy of the entire image Raster will be made during object serialization.

Throws:

IllegalArgumentException - if source is null.

IllegalArgumentException - if no Serializers are available for the types of DataBuffer, SampleModel, and ColorModel contained in the specified image.

SerializableRenderedImage

public SerializableRenderedImage(RenderedImage source)

Constructs a SerializableRenderedImage wrapper for a RenderedImage source. Image data will be serialized tile-by-tile if possible. No TileCodec will be used, i.e., data will be transmitted using the serialization protocol for Rasters.

Parameters:

source - The RenderedImage source.

Throws:

IllegalArgumentException - if source is null.

IllegalArgumentException - if no Serializers are available for the types of DataBuffer, SampleModel, and ColorModel contained in the specified image.

Method Detail

copyData

public WritableRaster copyData(WritableRaster dest)

Specified by:

copyData in interface RenderedImage

getColorModel

public ColorModel getColorModel()

Specified by:

getColorModel in interface RenderedImage

getData

public Raster getData()

Specified by:

getData in interface RenderedImage

getData

public Raster getData(Rectangle rect)

Specified by:

getData in interface RenderedImage

getHeight

public int getHeight()

Specified by:

getHeight in interface RenderedImage

getMinTileX

public int getMinTileX()

Specified by:

getMinTileX in interface RenderedImage

getMinTileY

public int getMinTileY()

Specified by:

getMinTileY in interface RenderedImage

getMinX

public int getMinX()

Specified by:

getMinX in interface RenderedImage

getMinY

public int getMinY()

Specified by:

getMinY in interface RenderedImage

getNumXTiles

public int getNumXTiles()

Specified by:

getNumXTiles in interface RenderedImage

getNumYTiles

public int getNumYTiles()

Specified by:

getNumYTiles in interface RenderedImage

getProperty

public Object getProperty(String name)

Specified by:

getProperty in interface RenderedImage

getPropertyNames

public String[] getPropertyNames()

Specified by:

getPropertyNames in interface RenderedImage

getSampleModel

public SampleModel getSampleModel()

Specified by:

getSampleModel in interface RenderedImage

getSources

public Vector getSources()

If this SerializableRenderedImage has not been serialized, this method returns a Vector containing only the RenderedImage passed to the constructor; if this image has been deserialized, it returns null.

Specified by:

getSources in interface RenderedImage

getTile

public Raster getTile(int tileX,
                      int tileY)

Specified by:

getTile in interface RenderedImage

getImageID

public Object getImageID()

Returns a unique identifier (UID) for this RenderedImage. This UID may be used when the potential redundancy of the value returned by the hashCode() method is unacceptable. An example of this is in generating a key for storing image tiles in a cache.

getTileGridXOffset

public int getTileGridXOffset()

Specified by:

getTileGridXOffset in interface RenderedImage

getTileGridYOffset

public int getTileGridYOffset()

Specified by:

getTileGridYOffset in interface RenderedImage

getTileHeight

public int getTileHeight()

Specified by:

getTileHeight in interface RenderedImage

getTileWidth

public int getTileWidth()

Specified by:

getTileWidth in interface RenderedImage

getWidth

public int getWidth()

Specified by:

getWidth in interface RenderedImage

finalize

protected void finalize()
                 throws Throwable

If a deep copy is not being used, unset the data server availability flag and wait for the server thread to rejoin the current thread.

Throws:

Throwable

dispose

public void dispose()

Provides a hint that an image will no longer be accessed from a reference in user space. The results are equivalent to those that occur when the program loses its last reference to this image, the garbage collector discovers this, and finalize is called. This can be used as a hint in situations where waiting for garbage collection would be overly conservative, e.g., there are a large number of socket connections which may be opened to transmit tile data.

SerializableRenderedImage defines this method to behave as follows:

• if the image is acting as a server, i.e., has never been serialized and may be providing data to serialized versions of itself, it makes itself unavailable to further client requests and closes its socket;
• if the image is acting as a client, i.e., has been serialized and may be requesting data from a remote, pre-serialization version of itself, it sends a message to its remote self indicating that it will no longer be making requests.

The results of referencing an image after a call to dispose() are undefined.