01: /*
02: * $RCSfile: Serializer.java,v $
03: *
04: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
05: *
06: * Use is subject to license terms.
07: *
08: * $Revision: 1.1 $
09: * $Date: 2005/02/11 04:57:53 $
10: * $State: Exp $
11: */
12: package javax.media.jai.remote;
13:
14: import java.awt.RenderingHints;
15:
16: /**
17: * An interface to be implemented by classes which are capable of
18: * converting an instance of a supported class into a state representation
19: * of the object which is serializable. Supported classes may in fact be
20: * classes or interfaces.
21: *
22: * <p> When possible, classes (not interfaces) should be supported explicitly,
23: * i.e., the <code>getObjectClass()</code> method of the
24: * <code>SerializableState</code> returned by <code>getState(Object)</code>
25: * should return the same value which would be returned by invoking
26: * <code>getClass()</code> on the object passed to
27: * <code>getState(Object)</code>. In particular, whenever feasible a
28: * <code>Serializer</code> should not be used to serialize a given object
29: * into a form which when deserialized would yield an instance of the
30: * superclass of the class of which the object is an instance. When it is
31: * not possible to provide a class-specific <code>Serializer</code>, such
32: * as when a factory class generate subclasses of itself via
33: * factory methods, then <code>permitsSubclasses()</code> should return
34: * <code>true</code>; in the case of class-specific <code>Serializer</code>s
35: * it should return <code>false</code>.
36: *
37: * @see SerializableState
38: * @see java.io.Serializable
39: *
40: * @since JAI 1.1
41: */
42: public interface Serializer {
43:
44: /**
45: * Returns the class or interface which is supported by this
46: * <code>Serializer</code>.
47: *
48: * @return The supported <code>Class</code>.
49: */
50: Class getSupportedClass();
51:
52: /**
53: * Returns <code>true</code> if and only if it is legal for this
54: * <code>Serializer</code> to be used to serialize a subclass. In
55: * general this method should return <code>false</code>, i.e., a specific
56: * <code>Serializer</code> should be registered explicitly for each class.
57: * In some cases this is however not expedient. An example of this is a
58: * <code>Serializer</code> of classes created by a factory class: the
59: * exact subclasses may not be known but sufficient information may be
60: * able to be extracted from the subclass instance to permit its
61: * serialization by the <code>Serializer</code> registered for the factory
62: * class.
63: */
64: boolean permitsSubclasses();
65:
66: /**
67: * Converts an object into a state-preserving object which may be
68: * serialized. If the value returned by <code>getSupportedClass()</code>
69: * is a class, i.e., not an interface, then the parameter of
70: * <code>getState()</code> should be an instance of that class; if
71: * <code>getSupportedClass()</code> returns an interface, then the
72: * parameter of <code>getState()</code> should implement that interface.
73: * If the apposite condition is not satisfied then an
74: * <code>IllegalArgumentException</code> will be thrown.
75: *
76: * <p> If the class of the parameter is supported explicitly, i.e., is an
77: * instance of the class returned by <code>getSupportedClass()</code>, then
78: * the object returned by the <code>getObject()</code> method of the
79: * generated <code>SerializableState</code> will be an instance of the
80: * same class. If <code>getSupportedClass()</code> returns an interface
81: * which the class of the parameter implements, then the object returned
82: * by the <code>getObject()</code> method of the generated
83: * <code>SerializableState</code> will be an instance of an unspecified
84: * class which implements that interface.
85: *
86: * @param o The object to be converted into a serializable form.
87: * @param h Configuration parameters the exact nature of which is
88: * <code>Serializer</code>-dependent. If <code>null</code>,
89: * reasonable default settings should be used.
90: * @return A serializable form of the supplied object.
91: * @exception IllegalArgumentException if <code>o</code> is
92: * <code>null</code>, the supported class is an interface
93: * not implemented by the class of which <code>o</code> is
94: * an instance, or the supported class is not an interface
95: * and <code>getSupportedClass().equals(o.getClass())</code>
96: * returns <code>false</code>.
97: */
98: SerializableState getState(Object o, RenderingHints h);
99: }
|