From ffe4ebba87d78d4da242adb6e95d2976bd796d91 Mon Sep 17 00:00:00 2001 From: Michael Koch Date: Mon, 24 Mar 2003 08:27:28 +0000 Subject: DataInputStream.java (): Wrapped documentation line. 2003-03-24 Michael Koch * java/io/DataInputStream.java (): Wrapped documentation line. (): Fixed @return tag. * java/io/DataOutputStream.java (written): Moved to top of class. (all methods): Merged documentation from classpath. * java/io/File.java: Merged copyright year with classpath. * java/io/FileInputStream.java (all methods): Merged documentation from classpath. * java/io/LineNumberReader.java (getLineNumber): Fixed @return tag. * java/io/ObjectInputStream.java. Reformatted. * java/io/ObjectOutputStream.java: Reformatted, fixed some @see tags. * java/io/OutputStreamWriter.java: Deleted empty line. * java/io/Writer.java: Reformatted. From-SVN: r64780 --- libjava/java/io/ObjectOutputStream.java | 325 ++++++++++++++++---------------- 1 file changed, 161 insertions(+), 164 deletions(-) (limited to 'libjava/java/io/ObjectOutputStream.java') diff --git a/libjava/java/io/ObjectOutputStream.java b/libjava/java/io/ObjectOutputStream.java index a051a96..afa0acb 100644 --- a/libjava/java/io/ObjectOutputStream.java +++ b/libjava/java/io/ObjectOutputStream.java @@ -49,86 +49,85 @@ import gnu.java.lang.reflect.TypeSignature; import gnu.classpath.Configuration; /** - An ObjectOutputStream can be used to write objects - as well as primitive data in a platform-independent manner to an - OutputStream. - - The data produced by an ObjectOutputStream can be read - and reconstituted by an ObjectInputStream. - - writeObject (Object) is used to write Objects, the - write<type> methods are used to write primitive - data (as in DataOutputStream). Strings can be written - as objects or as primitive data. - - Not all objects can be written out using an - ObjectOutputStream. Only those objects that are an - instance of java.io.Serializable can be written. - - Using default serialization, information about the class of an - object is written, all of the non-transient, non-static fields of - the object are written, if any of these fields are objects, they are - written out in the same manner. - - An object is only written out the first time it is encountered. If - the object is encountered later, a reference to it is written to - the underlying stream. Thus writing circular object graphs - does not present a problem, nor are relationships between objects - in a graph lost. - - Example usage: - 
-   Hashtable map = new Hashtable ();
-   map.put ("one", new Integer (1));
-   map.put ("two", new Integer (2));
-
-   ObjectOutputStream oos =
-   new ObjectOutputStream (new FileOutputStream ("numbers"));
-   oos.writeObject (map);
-   oos.close ();
-
-   ObjectInputStream ois =
-   new ObjectInputStream (new FileInputStream ("numbers"));
-   Hashtable newmap = (Hashtable)ois.readObject ();
-
-   System.out.println (newmap);
-
- - The default serialization can be overriden in two ways. - - By defining a method private void - writeObject (ObjectOutputStream), a class can dictate exactly - how information about itself is written. - defaultWriteObject () may be called from this method to - carry out default serialization. This method is not - responsible for dealing with fields of super-classes or subclasses. - - By implementing java.io.Externalizable. This gives - the class complete control over the way it is written to the - stream. If this approach is used the burden of writing superclass - and subclass data is transfered to the class implementing - java.io.Externalizable. - - @see java.io.DataOutputStream - @see java.io.Externalizable - @see java.io.ObjectInputStream - @see java.io.Serializable - @see XXX: java serialization spec -*/ + * An ObjectOutputStream can be used to write objects + * as well as primitive data in a platform-independent manner to an + * OutputStream. + * + * The data produced by an ObjectOutputStream can be read + * and reconstituted by an ObjectInputStream. + * + * writeObject (Object) is used to write Objects, the + * write<type> methods are used to write primitive + * data (as in DataOutputStream). Strings can be written + * as objects or as primitive data. + * + * Not all objects can be written out using an + * ObjectOutputStream. Only those objects that are an + * instance of java.io.Serializable can be written. + * + * Using default serialization, information about the class of an + * object is written, all of the non-transient, non-static fields of + * the object are written, if any of these fields are objects, they are + * written out in the same manner. + * + * An object is only written out the first time it is encountered. If + * the object is encountered later, a reference to it is written to + * the underlying stream. Thus writing circular object graphs + * does not present a problem, nor are relationships between objects + * in a graph lost. + * + * Example usage: + * 
+ * Hashtable map = new Hashtable ();
+ * map.put ("one", new Integer (1));
+ * map.put ("two", new Integer (2));
+ *
+ * ObjectOutputStream oos =
+ * new ObjectOutputStream (new FileOutputStream ("numbers"));
+ * oos.writeObject (map);
+ * oos.close ();
+ *
+ * ObjectInputStream ois =
+ * new ObjectInputStream (new FileInputStream ("numbers"));
+ * Hashtable newmap = (Hashtable)ois.readObject ();
+ *
+ * System.out.println (newmap);
+ *
+ * + * The default serialization can be overriden in two ways. + * + * By defining a method private void + * writeObject (ObjectOutputStream), a class can dictate exactly + * how information about itself is written. + * defaultWriteObject () may be called from this method to + * carry out default serialization. This method is not + * responsible for dealing with fields of super-classes or subclasses. + * + * By implementing java.io.Externalizable. This gives + * the class complete control over the way it is written to the + * stream. If this approach is used the burden of writing superclass + * and subclass data is transfered to the class implementing + * java.io.Externalizable. + * + * @see java.io.DataOutputStream + * @see java.io.Externalizable + * @see java.io.ObjectInputStream + * @see java.io.Serializable + */ public class ObjectOutputStream extends OutputStream implements ObjectOutput, ObjectStreamConstants { /** - Creates a new ObjectOutputStream that will do all of - its writing onto out. This method also initializes - the stream by writing the header information (stream magic number - and stream version). - - @exception IOException Writing stream header to underlying - stream cannot be completed. - - @see writeStreamHeader () - */ + * Creates a new ObjectOutputStream that will do all of + * its writing onto out. This method also initializes + * the stream by writing the header information (stream magic number + * and stream version). + * + * @exception IOException Writing stream header to underlying + * stream cannot be completed. + * + * @see #writeStreamHeader() + */ public ObjectOutputStream (OutputStream out) throws IOException { realOutput = new DataOutputStream (out); @@ -145,26 +144,25 @@ public class ObjectOutputStream extends OutputStream writeStreamHeader (); } - /** - Writes a representation of obj to the underlying - output stream by writing out information about its class, then - writing out each of the objects non-transient, non-static - fields. If any of these fields are other objects, - they are written out in the same manner. - - This method can be overriden by a class by implementing - private void writeObject (ObjectOutputStream). - - If an exception is thrown from this method, the stream is left in - an undefined state. - - @exception NotSerializableException An attempt was made to - serialize an Object that is not serializable. - - @exception IOException Exception from underlying - OutputStream. - */ + * Writes a representation of obj to the underlying + * output stream by writing out information about its class, then + * writing out each of the objects non-transient, non-static + * fields. If any of these fields are other objects, + * they are written out in the same manner. + * + * This method can be overriden by a class by implementing + * private void writeObject (ObjectOutputStream). + * + * If an exception is thrown from this method, the stream is left in + * an undefined state. + * + * @exception NotSerializableException An attempt was made to + * serialize an Object that is not serializable. + * + * @exception IOException Exception from underlying + * OutputStream. + */ public final void writeObject (Object obj) throws IOException { if (useSubclassMethod) @@ -494,7 +492,7 @@ public class ObjectOutputStream extends OutputStream @exception IOException if version is not a valid protocol - @see setDefaultProtocolVersion (int) + @see #setDefaultProtocolVersion(int) */ public void useProtocolVersion (int version) throws IOException { @@ -517,7 +515,7 @@ public class ObjectOutputStream extends OutputStream @exception IOException if version is not a valid protocol - @see useProtocolVersion (int) + @see #useProtocolVersion(int) */ public static void setDefaultProtocolVersion (int version) throws IOException @@ -538,7 +536,7 @@ public class ObjectOutputStream extends OutputStream @exception IOException Exception from underlying OutputStream. - @see java.io.ObjectInputStream#resolveClass (java.io.ObjectStreamClass) + @see ObjectInputStream#resolveClass(java.io.ObjectStreamClass) */ protected void annotateClass (Class cl) throws IOException {} @@ -558,7 +556,7 @@ public class ObjectOutputStream extends OutputStream @exception IOException Exception from underlying OutputStream. - @see enableReplaceObject (boolean) + @see #enableReplaceObject(boolean) */ protected Object replaceObject (Object obj) throws IOException { @@ -606,16 +604,16 @@ public class ObjectOutputStream extends OutputStream /** - Protected constructor that allows subclasses to override - serialization. This constructor should be called by subclasses - that wish to override writeObject (Object). This - method does a security check NOTE: currently not - implemented, then sets a flag that informs - writeObject (Object) to call the subclasses - writeObjectOverride (Object) method. - - @see writeObjectOverride (Object) - */ + * Protected constructor that allows subclasses to override + * serialization. This constructor should be called by subclasses + * that wish to override writeObject (Object). This + * method does a security check NOTE: currently not + * implemented, then sets a flag that informs + * writeObject (Object) to call the subclasses + * writeObjectOverride (Object) method. + * + * @see #writeObjectOverride(Object) + */ protected ObjectOutputStream () throws IOException, SecurityException { SecurityManager sec_man = System.getSecurityManager (); @@ -626,17 +624,17 @@ public class ObjectOutputStream extends OutputStream /** - This method allows subclasses to override the default - serialization mechanism provided by - ObjectOutputStream. To make this method be used for - writing objects, subclasses must invoke the 0-argument - constructor on this class from there constructor. - - @see ObjectOutputStream () - - @exception NotActiveException Subclass has arranged for this - method to be called, but did not implement this method. - */ + * This method allows subclasses to override the default + * serialization mechanism provided by + * ObjectOutputStream. To make this method be used for + * writing objects, subclasses must invoke the 0-argument + * constructor on this class from there constructor. + * + * @see #ObjectOutputStream() + * + * @exception NotActiveException Subclass has arranged for this + * method to be called, but did not implement this method. + */ protected void writeObjectOverride (Object obj) throws NotActiveException, IOException { @@ -645,8 +643,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#write (int) - */ + * @see DataOutputStream#write(int) + */ public void write (int data) throws IOException { if (writeDataAsBlocks) @@ -662,8 +660,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#write (byte[]) - */ + * @see DataOutputStream#write(byte[]) + */ public void write (byte[] b) throws IOException { write (b, 0, b.length); @@ -671,8 +669,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#write (byte[],int,int) - */ + * @see DataOutputStream#write(byte[],int,int) + */ public void write (byte[] b, int off, int len) throws IOException { if (writeDataAsBlocks) @@ -698,8 +696,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#flush () - */ + * @see DataOutputStream#flush() + */ public void flush () throws IOException { drain (); @@ -708,12 +706,12 @@ public class ObjectOutputStream extends OutputStream /** - Causes the block-data buffer to be written to the underlying - stream, but does not flush underlying stream. - - @exception IOException Exception from underlying - OutputStream. - */ + * Causes the block-data buffer to be written to the underlying + * stream, but does not flush underlying stream. + * + * @exception IOException Exception from underlying + * OutputStream. + */ protected void drain () throws IOException { if (blockDataCount == 0) @@ -727,8 +725,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#close () - */ + * @see java.io.DataOutputStream#close () + */ public void close () throws IOException { flush (); @@ -737,8 +735,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeBoolean (boolean) - */ + * @see java.io.DataOutputStream#writeBoolean (boolean) + */ public void writeBoolean (boolean data) throws IOException { blockDataOutput.writeBoolean (data); @@ -746,8 +744,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeByte (int) - */ + * @see java.io.DataOutputStream#writeByte (int) + */ public void writeByte (int data) throws IOException { blockDataOutput.writeByte (data); @@ -755,8 +753,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeShort (int) - */ + * @see java.io.DataOutputStream#writeShort (int) + */ public void writeShort (int data) throws IOException { blockDataOutput.writeShort (data); @@ -764,8 +762,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeChar (int) - */ + * @see java.io.DataOutputStream#writeChar (int) + */ public void writeChar (int data) throws IOException { blockDataOutput.writeChar (data); @@ -773,8 +771,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeInt (int) - */ + * @see java.io.DataOutputStream#writeInt (int) + */ public void writeInt (int data) throws IOException { blockDataOutput.writeInt (data); @@ -782,8 +780,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeLong (long) - */ + * @see java.io.DataOutputStream#writeLong (long) + */ public void writeLong (long data) throws IOException { blockDataOutput.writeLong (data); @@ -791,8 +789,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeFloat (float) - */ + * @see java.io.DataOutputStream#writeFloat (float) + */ public void writeFloat (float data) throws IOException { blockDataOutput.writeFloat (data); @@ -800,8 +798,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeDouble (double) - */ + * @see java.io.DataOutputStream#writeDouble (double) + */ public void writeDouble (double data) throws IOException { blockDataOutput.writeDouble (data); @@ -809,8 +807,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeBytes (java.lang.String) - */ + * @see java.io.DataOutputStream#writeBytes (java.lang.String) + */ public void writeBytes (String data) throws IOException { blockDataOutput.writeBytes (data); @@ -818,8 +816,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeChars (java.lang.String) - */ + * @see java.io.DataOutputStream#writeChars (java.lang.String) + */ public void writeChars (String data) throws IOException { dataOutput.writeChars (data); @@ -827,8 +825,8 @@ public class ObjectOutputStream extends OutputStream /** - @see java.io.DataOutputStream#writeUTF (java.lang.String) - */ + * @see java.io.DataOutputStream#writeUTF (java.lang.String) + */ public void writeUTF (String data) throws IOException { dataOutput.writeUTF (data); @@ -836,11 +834,11 @@ public class ObjectOutputStream extends OutputStream /** - This class allows a class to specify exactly which fields should - be written, and what values should be written for these fields. - - XXX: finish up comments - */ + * This class allows a class to specify exactly which fields should + * be written, and what values should be written for these fields. + * + * XXX: finish up comments + */ public static abstract class PutField { public abstract void put (String name, boolean value) @@ -864,7 +862,6 @@ public class ObjectOutputStream extends OutputStream public abstract void write (ObjectOutput out) throws IOException; } - public PutField putFields () throws IOException { markFieldsWritten (); -- cgit v1.1