@(#)Serial.txt	1.7

		Proposal: Serialization Support
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Brian Burkhalter
Created: 1 September 2000
Revised: 12/18/00

CHANGES DURING COMMUNITY REVIEW
-------------------------------
. Allow Serializer to support subclasses.
. Modify SerializerFactory to work for subclasses.
. Allow Serializers of already-serializable classes.

PROPOSAL
--------
The intent of this proposal is to improve the serialization capabilities
provided by JAI. This entails adding some classes to a new package
javax.media.jai.remote and adding a few fields to the JAI Class.

For elaboration of the classes and methods discussed in this proposal please
refer to the respective HTML documentation. The HTML files for the following
javax.media.jai.remote classes should accompany this proposal:

SerializableRenderedImage
SerializableState
Serializer
SerializerFactory

1. A Serializable Wrapper for RenderedImage

A class SerializableRenderedImage will be added to the new package. This
class is effectively a wrapper for an arbitrary RenderedImage which may or may
not be generated by JAI. The class would support serialization by deep copy,
by default serialization of tiles (Rasters) over a socket connection, or by
tile serialization over a socket connection using the new TileCodec
architecture. In both cases of tile serialization data would be transmitted
on a by request basis.

2. Support for Serialization of Non-Serializable Classes

Thress classes will be added to the new package to support centralized
mechanism to manage serializable proxies for non-serializable classes.
These include the interfaces Serializer and SerializableState and the
class SerializerFactory.

The follow sub-sections detail the changes made during Community Review.

2.1 javax.media.jai.remote.Serializer [Serializer.html]

Modify the specification to allow a class (as opposed to an interface)
Serializer to work for a subclass of the supported class. This change would
only require that the object "o" for which a Serializer was required satisfy

     getSupportedClass().isAssignableFrom(o.getClass())

instead of

     getSupportedClass().equals(o.getClass())

This will better accomodate the situation wherein objects are created by a
factory class which may produce instances of classes which are unknown
a priori.

2.1.1 Add a method

/**
 * Returns <code>true</code> if and only if it is legal for this
 * <code>Serializer</code> to be used to serialize a subclass.  In
 * general this method should return <code>false</code>, i.e., a specific
 * <code>Serializer</code> should be registered explicitly for each class.
 * In some cases this is however not expedient.  An example of this is a
 * <code>Serializer</code> of classes created by a factory class: the
 * exact subclasses may not be known but sufficient information may be
 * able to be extracted from the subclass instance to permit its serialization
 * by the <code>Serializer</code> registered for the factory class.
 */
boolean permitsSubclasses();

2.2 javax.media.jai.remote.SerializerFactory [SerializerFactory.html]

Modify the specification of getSerializer() and isSupportedClass() to be
consistent with the above change to Serializer. This would require traversing
the superclass hierarchy until a supported class was encountered or the
root java.lang.Object was reached, which would be an error.

2.2.1 Add a method

/**
 * Determines the <code>Class</code> of which the deserialized form of the
 * supplied <code>Class</code> will be an instance.  Specifically, this
 * method returns the <code>Class</code> of the <code>Object</code> returned
 * by invoking <code>getObject()</code> on the <code>SerializableState</code>
 * returned by <code>getState()</code> after the state object has been
 * serialized and deserialized.  The returned value will equal the supplied
 * argument unless there is no <code>Serializer</code> explicitly registered
 * for this class but there is a <code>Serializer</code> registered for a
 * superclass with a <code>permitsSubclasses()</code> method that returns
 * <code>true</code>.
 *
 * @param The <code>Class</code> for which the deserialized class type is
 *        requested.
 * @return The deserialized <code>Class</code> or <code>null</code>.
 */
public static Class getDeserializedClass(Class c) {}

2.2.2 Javadoc

Correct list of classes supported by SerializerFactory.

2.3 Already-serializable Classes

Revise the specification to permit Serializers to be registered for classes
which are already serializable. This is useful for example for Serializers of
Collection classes which may in themselves be serializable but which may
contain non-serializable elements.

3. JAI Class

Constants will be added to provide global settings for tile serialization
by SerializableRenderedImage.

    /**
     * Key for specifying whether a deep copy of the image data should
     * be used when serializing images.  The corresponding
     * object must be a <code>Boolean</code>.
     * The common <code>RenderingHints</code> do not contain a default
     * hint corresponding to this key.
     */
    public static RenderingHints.Key KEY_SERIALIZE_DEEP_COPY;

    /**
     * Key for specifying the default format to be used for tile
     * serialization via <code>TileCodec</code>s.  The corresponding
     * object must be a <code>String</code>.
     * The common <code>RenderingHints</code> do not contain a default
     * hint corresponding to this key.
     */
    public static RenderingHints.Key KEY_TILE_CODEC_FORMAT;

    /**
     * Key for specifying the default encoding parameters to be used for
     * tile serialization via <code>TileCodec</code>s.  The corresponding
     * object must be a <code>TileCodecParameterList</code>.
     * The common <code>RenderingHints</code> do not contain a default
     * hint corresponding to this key.
     */
    public static RenderingHints.Key KEY_TILE_ENCODING_PARAM;

    /**
     * Key for specifying the default decoding parameters to be used for
     * tile serialization via <code>TileCodec</code>s.  The corresponding
     * object must be a <code>TileCodecParameterList</code>.
     * The common <code>RenderingHints</code> do not contain a default
     * hint corresponding to this key.
     */
    public static RenderingHints.Key KEY_TILE_DECODING_PARAM;

These constants would be used in the serialization methods of other classes
(such as RenderedOp) which might internally have to serialize a RenderedImage.