1/*
2 * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23
24/*
25 *
26 *
27 */
28
29import java.io.*;
30import java.security.*;
31import java.lang.reflect.Field;
32import java.lang.reflect.Method;
33import java.lang.reflect.Modifier;
34import java.lang.reflect.InvocationTargetException;
35import java.io.IOException;
36import java.io.OutputStream;
37import java.io.ObjectOutputStream;
38
39/**
40 * This class provides a means for a subclass to re-implement Serialization
41 * while preserving the existing public API to Serialization. A complimentary
42 * subclass of AbstractObjectInputStream must also be implemented to
43 * deserializa the new implementation.<p>
44 *
45 * Since serialization must override java access rules in order to
46 * access private, protected and package accessible Serializable fields,
47 * only trusted classes are allowed to subclass AbstractObjectInputStream.
48 * Subclasses of AbstractObjectOututStream must have SerializablePermission
49 * "enableAbstractSubclass" or this constructor will throw a
50 * SecurityException.Implementations of this class should protect themselves
51 * from being subclassed in a way that will provide access to object
52 * references and other sensitive info. Specifically, writeObjectOverride()
53 * should be made final.
54 *
55 * A subclass of AbstractObjectOutputStream writes primitive data types
56 * and graphs of Java objects to an ObjectOutputStream.  The objects can be read
57 * (reconstituted) using he complimentary subclass of AbstractObjectInputStream.<p>
58 * Persistent storage of objects can be accomplished by using a file for
59 * the stream. If the stream is a network socket stream, the objects can
60 * be reconstituted on another host or in another process. <p>
61 *
62 * Only objects that support the java.io.Serializable interface can be
63 * written to streams.<p>
64 *
65 * The method <STRONG>writeObjectOverride</STRONG> is used to write an object
66 * to the stream.  Any object, including Strings and arrays, is
67 * written with writeObject. Multiple objects or primitives can be
68 * written to the stream.  The objects must be read back from the
69 * corresponding subclass of AbstractObjectInputstream with the same types
70 * and in the same order as they were written.<p>
71 *
72 * Primitive data types can also be written to the stream using the
73 * appropriate methods from DataOutput. Strings can also be written
74 * using the writeUTF method.<p>
75 *
76 * The default serialization mechanism for an object is defined by
77 * defaultWriteObject(). References to other objects
78 * (except in transient or static fields) cause those objects to be
79 * written also. Multiple references to a single object are encoded
80 * using a reference sharing mechanism so that graphs of objects can
81 * be restored to the same shape as when the original was written. <p>
82 *
83 * Classes that require special handling during the serialization and deserialization
84 * process must implement special methods with these exact signatures: <p>
85 *
86 * <PRE>
87 * private void readObject(java.io.ObjectInputStream stream)
88 *     throws IOException, ClassNotFoundException;
89 * private void writeObject(java.io.ObjectOutputStream stream)
90 *     throws IOException
91 * </PRE><p>
92 * The writeObject method is responsible for writing the state of
93 * the object for its particular class so that the corresponding
94 * readObject method can restore it.
95 * The method does not need to concern itself with the
96 * state belonging to the object's superclasses or subclasses.
97 * State is saved by writing the individual fields to the ObjectOutputStream
98 * using the writeObject method or by using the methods for
99 * primitive data types supported by DataOutput. <p>
100 *
101 * Serialization does not write out the fields of any object that does
102 * not implement the java.io.Serializable interface.  Subclasses of
103 * Objects that are not serializable can be serialized. In this case
104 * the non-serializable class must have a no-arg constructor to allow
105 * its fields to be initialized.  In this case it is the
106 * responsibility of the subclass to save and restore the state of the
107 * non-serializable class. It is frequently the case that the fields
108 * of that class are accessible (public, package, or protected) or
109 * that there are get and set methods that can be used to restore the
110 * state. <p>
111 *
112 * Serialization of an object can be prevented by implementing writeObject
113 * and readObject methods that throw the NotSerializableException.
114 * The exception will be caught by the ObjectOutputStream and abort the
115 * serialization process.
116 *
117 * Implementing the Externalizable interface allows the object to
118 * assume complete control over the contents and format of the object's
119 * serialized form.  The methods of the Externalizable interface,
120 * writeExternal and readExternal, are called to save and restore the
121 * objects state.  When implemented by a class they can write and read
122 * their own state using all of the methods of ObjectOutput and
123 * ObjectInput.  It is the responsibility of the objects to handle any
124 * versioning that occurs.
125 *
126 * @author      Joe Fialli
127 *
128 * @see java.io.ObjectOutputStream
129 * @see java.io.DataOutput
130 * @see java.io.Serializable
131 * @see java.io.Externalizable
132 * @see java.io.Replaceable
133 * @see java.io.ext.AbstractObjectInputStream
134 *
135 * @since       JDK1.2
136 */
137public abstract class AbstractObjectOutputStream extends ObjectOutputStream
138{
139    protected OutputStream out;
140    /* Stream Management Methods. */
141
142    /**
143     * Creates an ObjectOutputStream that writes to the specified OutputStream.
144     *
145     * Add the following line to the security policy file to enable
146     * subclassing.
147     *
148     * <PRE>
149     *     permission SerializablePermission "enableAbstractSubclass" ;
150     * </PRE><p>
151     *
152     * @exception IOException Any exception thrown by the underlying OutputStream.
153     * @see java.io.ObjectOutputStream#writeStreamHeader()
154     */
155    public AbstractObjectOutputStream(OutputStream out) throws IOException {
156        this.out = out;
157    }
158
159    public abstract void reset() throws IOException;
160    protected abstract void drain() throws IOException;
161    public abstract void close() throws IOException;
162
163    /*******************************************************************/
164
165    /* Write Objects to Stream */
166
167    /**
168     * Write the specified object to a subclass of AbstractObjectOutputStream.<p>
169     *
170     * NOTE: The override method of this class should have the modifier final.<p>
171     *
172     * Default serialization for a class can be
173     * overridden by defining writeObject and the readObject methods
174     * for the Serializable class. Objects referenced by this object are
175     * written transitively so that a complete equivalent graph of objects
176     * can be reconstructed by an ObjectInputStream.  <p>
177     *
178     * This method must implement the substitution semantics on the
179     * object to be written, write Externalizable objects with its classes
180     * override of writeExternal, and it must call annotateClass when
181     * writing an ObjectStreamClass to the stream.
182     *
183     * Exceptions can be thrown for problems with the OutputStream and
184     * for classes that should not be serialized.
185     *
186     * For security's sake, any overrides of this method should be final.
187     * Serialization typically needs to disable java access rules
188     * to serialize private, protected and package accessible Serializable
189     * fields. This method gets called for ALL Serializable objects.
190     *
191     * @exception InvalidClassException Something is wrong with a class used by
192     *     serialization.
193     * @exception NotSerializableException Some object to be serialized does not
194     *    implement the java.io.Serializable interface.
195     * @exception IOException Any exception thrown by the underlying OutputStream.
196     * @see java.io.Externalizable
197     * @see java.io.ObjectOutputStream#replaceObject(Object)
198     * @see java.io.Replaceable
199     * @see java.io.ObjectOutputStream#annotateClass(Class)
200     */
201    protected void writeObjectOverride(Object obj)
202        throws IOException
203    {
204    }
205
206    /**
207     * Write the Serializable fields of the current object to this stream.<p>
208     *
209     * Note: The object being serialized is not passed to this method.
210     *       For security purposes, the initial implementation maintained
211     *       the state of the last object to be passed to writeObject and
212     *       only allowed this method to be invoked for this object.<p>
213     *
214     * @exception NotActiveException  Thrown if a writeObject method is not
215     *                                active.
216     */
217    public abstract void defaultWriteObject() throws IOException;
218
219    /*************************************************************/
220    /* Use the methods of PutField to map between Serializable fields
221     * and actual fields of a Serializable class.
222     */
223
224    public abstract ObjectOutputStream.PutField putFields() throws IOException;
225
226    /**
227     * Note: The PutField being serialized is not passed to this method.
228     *       For security purposes, the initial implementation maintained
229     *       the state of the last putFields call and
230     *       only allowed this method to be invoked for that PutFields object.
231     */
232    public abstract void writeFields() throws IOException;
233
234    protected abstract boolean enableReplaceObject(boolean enable) throws SecurityException;
235
236    /*******************************************************************/
237    /* Write Primitive Data to stream.  DataOutput methods. */
238
239    public abstract void write(int data) throws IOException;
240    public abstract void write(byte b[]) throws IOException;
241    public abstract void write(byte b[], int off, int len) throws IOException;
242    public abstract void writeBoolean(boolean data) throws IOException;
243    public abstract void writeByte(int data) throws IOException;
244    public abstract void writeShort(int data)  throws IOException;
245    public abstract void writeChar(int data)  throws IOException;
246    public abstract void writeInt(int data)  throws IOException;
247    public abstract void writeLong(long data)  throws IOException;
248    public abstract void writeFloat(float data) throws IOException;
249    public abstract void writeDouble(double data) throws IOException;
250    public abstract void writeBytes(String data) throws IOException;
251    public abstract void writeChars(String data) throws IOException;
252    public abstract void writeUTF(String data) throws IOException;
253};
254