Java Doc for SerializableRenderedImage.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » media » jai » remote » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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();
 }
 }
 

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.
Parameters:
  useDeepCopy - Whether a deep copy of the entire image Rasterwill be made during object serialization.
Parameters:
  registry - The OperationRegistry to use increating the TileEncoder. TheTileDecoder will of necessity becreated using the default OperationRegistryas the specified OperationRegistry is notserialized. If null the default registrywill be used.
Parameters:
  formatName - The name of the format used to encode the data.If null simple tile serialization willbe performed either directly or by use of a "raw"TileCodec.
Parameters:
  encodingParam - The parameters to be used for data encoding. Ifnull the default encodingTileCodecParameterList for thisformat will be used. Ignored ifformatName is null.
Parameters:
  decodingParam - The parameters to be used for data decoding. Ifnull a complementaryTileCodecParameterList will bederived from encodingParam. Ignoredif formatName is null.
exception:
  IllegalArgumentException - if sourceis null.
exception:
  IllegalArgumentException - if no Serializersare available for the types ofSampleModel, and ColorModelcontained in the specified image.

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.