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