1 ---

     2 # Copyright (c) 2005, 2017, 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 include-before: '[CONTENTS](index.html) | [PREV](output.html) | [NEXT](class.html)'

    24 include-after: '[CONTENTS](index.html) | [PREV](output.html) | [NEXT](class.html)'

    25 

    26 title: 'Java Object Serialization Specification: 3 - Object Input Classes'

    27 ---

    28 

    29 -   [The ObjectInputStream Class](#the-objectinputstream-class)

    30 -   [The ObjectInputStream.GetField

    31     Class](#the-objectinputstream.getfield-class)

    32 -   [The ObjectInputValidation Interface](#the-objectinputvalidation-interface)

    33 -   [The readObject Method](#the-readobject-method)

    34 -   [The readExternal Method](#the-readexternal-method)

    35 -   [The readResolve Method](#the-readresolve-method)

    36 

    37 -------------------------------------------------------------------------------

    38 

    39 ## 3.1 The ObjectInputStream Class

    40 

    41 Class `ObjectInputStream` implements object deserialization. It maintains the

    42 state of the stream including the set of objects already deserialized. Its

    43 methods allow primitive types and objects to be read from a stream written by

    44 `ObjectOutputStream`. It manages restoration of the object and the objects that

    45 it refers to from the stream.

    46 

    47 ```

    48 package java.io;

    49 

    50 public class ObjectInputStream

    51     extends InputStream

    52     implements ObjectInput, ObjectStreamConstants

    53 {

    54     public ObjectInputStream(InputStream in)

    55         throws StreamCorruptedException, IOException;

    56 

    57     public final Object readObject()

    58         throws OptionalDataException, ClassNotFoundException,

    59             IOException;

    60 

    61     public Object readUnshared()

    62         throws OptionalDataException, ClassNotFoundException,

    63             IOException;

    64 

    65     public void defaultReadObject()

    66         throws IOException, ClassNotFoundException,

    67             NotActiveException;

    68 

    69     public GetField readFields()

    70         throws IOException;

    71 

    72     public synchronized void registerValidation(

    73         ObjectInputValidation obj, int prio)

    74         throws NotActiveException, InvalidObjectException;

    75 

    76     protected ObjectStreamClass readClassDescriptor()

    77         throws IOException, ClassNotFoundException;

    78 

    79     protected Class resolveClass(ObjectStreamClass v)

    80         throws IOException, ClassNotFoundException;

    81 

    82     protected Object resolveObject(Object obj)

    83         throws IOException;

    84 

    85     protected boolean enableResolveObject(boolean enable)

    86         throws SecurityException;

    87 

    88     protected void readStreamHeader()

    89         throws IOException, StreamCorruptedException;

    90 

    91     public int read() throws IOException;

    92 

    93     public int read(byte[] data, int offset, int length)

    94         throws IOException

    95 

    96     public int available() throws IOException;

    97 

    98     public void close() throws IOException;

    99 

   100     public boolean readBoolean() throws IOException;

   101 

   102     public byte readByte() throws IOException;

   103 

   104     public int readUnsignedByte() throws IOException;

   105 

   106     public short readShort() throws IOException;

   107 

   108     public int readUnsignedShort() throws IOException;

   109 

   110     public char readChar() throws IOException;

   111 

   112     public int readInt() throws IOException;

   113 

   114     public long readLong() throws IOException;

   115 

   116     public float readFloat() throws IOException;

   117 

   118     public double readDouble() throws IOException;

   119 

   120     public void readFully(byte[] data) throws IOException;

   121 

   122     public void readFully(byte[] data, int offset, int size)

   123         throws IOException;

   124 

   125     public int skipBytes(int len) throws IOException;

   126 

   127     public String readLine() throws IOException;

   128 

   129     public String readUTF() throws IOException;

   130 

   131     // Class to provide access to serializable fields.

   132     static abstract public class GetField

   133     {

   134         public ObjectStreamClass getObjectStreamClass();

   135 

   136         public boolean defaulted(String name)

   137             throws IOException, IllegalArgumentException;

   138 

   139         public char get(String name, char default)

   140             throws IOException, IllegalArgumentException;

   141 

   142         public boolean get(String name, boolean default)

   143             throws IOException, IllegalArgumentException;

   144 

   145         public byte get(String name, byte default)

   146             throws IOException, IllegalArgumentException;

   147 

   148         public short get(String name, short default)

   149             throws IOException, IllegalArgumentException;

   150 

   151         public int get(String name, int default)

   152             throws IOException, IllegalArgumentException;

   153 

   154         public long get(String name, long default)

   155             throws IOException, IllegalArgumentException;

   156 

   157         public float get(String name, float default)

   158             throws IOException, IllegalArgumentException;

   159 

   160         public double get(String name, double default)

   161             throws IOException, IllegalArgumentException;

   162 

   163         public Object get(String name, Object default)

   164             throws IOException, IllegalArgumentException;

   165     }

   166 

   167     protected ObjectInputStream()

   168         throws StreamCorruptedException, IOException;

   169 

   170     protected readObjectOverride()

   171         throws OptionalDataException, ClassNotFoundException,

   172             IOException;

   173 }

   174 ```

   175 

   176 The single-argument `ObjectInputStream` constructor requires an `InputStream`.

   177 The constructor calls `readStreamHeader` to read and verifies the header and

   178 version written by the corresponding `ObjectOutputStream.writeStreamHeader`

   179 method. If a security manager is installed, this constructor checks for the

   180 `"enableSubclassImplementation"` `SerializablePermission` when invoked directly

   181 or indirectly by the constructor of a subclass which overrides the `readFields`

   182 and/or `readUnshared` methods.

   183 

   184 **Note:** The `ObjectInputStream` constructor blocks until it completes reading

   185 the serialization stream header. Code which waits for an `ObjectInputStream` to

   186 be constructed before creating the corresponding `ObjectOutputStream` for that

   187 stream will deadlock, since the `ObjectInputStream` constructor will block

   188 until a header is written to the stream, and the header will not be written to

   189 the stream until the `ObjectOutputStream` constructor executes. This problem

   190 can be resolved by creating the `ObjectOutputStream` before the

   191 `ObjectInputStream`, or otherwise removing the timing dependency between

   192 completion of `ObjectInputStream` construction and the creation of the

   193 `ObjectOutputStream`.

   194 

   195 The `readObject` method is used to deserialize an object from the stream. It

   196 reads from the stream to reconstruct an object.

   197 

   198 1.  If the `ObjectInputStream` subclass is overriding the implementation, call

   199     the `readObjectOverride` method and return. Reimplementation is described

   200     at the end of this section.

   201 

   202 2.  If a block data record occurs in the stream, throw a `BlockDataException`

   203     with the number of available bytes.

   204 

   205 3.  If the object in the stream is null, return null.

   206 

   207 4.  If the object in the stream is a handle to a previous object, return the

   208     object.

   209 

   210 5.  If the object in the stream is a `Class`, read its `ObjectStreamClass`

   211     descriptor, add it and its handle to the set of known objects, and return

   212     the corresponding `Class` object.

   213 

   214 6.  If the object in the stream is an `ObjectStreamClass`, read in its data

   215     according to the formats described in [Section 4.3, "Serialized

   216     Form"](class.html#serialized-form). Add it and its handle to the set of

   217     known objects. In versions 1.3 and later of the Java 2 SDK, Standard

   218     Edition, the `readClassDescriptor` method is called to read in the

   219     `ObjectStreamClass` if it represents a class that is not a dynamic proxy

   220     class, as indicated in the stream data. If the class descriptor represents

   221     a dynamic proxy class, call the `resolveProxyClass` method on the stream to

   222     get the local class for the descriptor; otherwise, call the `resolveClass`

   223     method on the stream to get the local class. If the class cannot be

   224     resolved, throw a ClassNotFoundException. Return the resulting

   225     `ObjectStreamClass` object.

   226 

   227 7.  If the object in the stream is a `String`, read its length information

   228     followed by the contents of the string encoded in modified UTF-8. For

   229     details, refer to [Section 6.2, "Stream

   230     Elements"](protocol.html#stream-elements). Add the `String` and its handle

   231     to the set of known objects, and proceed to Step 12.

   232 

   233 8.  If the object in the stream is an array, read its `ObjectStreamClass` and

   234     the length of the array. Allocate the array, and add it and its handle in

   235     the set of known objects. Read each element using the appropriate method

   236     for its type and assign it to the array. Proceed to Step 12.

   237 

   238 9.  If the object in the stream is an enum constant, read its

   239     `ObjectStreamClass` and the enum constant name. If the `ObjectStreamClass`

   240     represents a class that is not an enum type, an `InvalidClassException` is

   241     thrown. Obtain a reference to the enum constant by calling the

   242     `java.lang.Enum.valueOf` method, passing the enum type bound to the

   243     received `ObjectStreamClass` along with the received name as arguments. If

   244     the `valueOf` method throws an `IllegalArgumentException`, an

   245     `InvalidObjectException` is thrown with the `IllegalArgumentException` as

   246     its cause. Add the enum constant and its handle in the set of known

   247     objects, and proceed to Step 12.

   248 

   249 10. For all other objects, the `ObjectStreamClass` of the object is read from

   250     the stream. The local class for that `ObjectStreamClass` is retrieved. The

   251     class must be serializable or externalizable, and must not be an enum type.

   252     If the class does not satisfy these criteria, an `InvalidClassException` is

   253     thrown.

   254 

   255 11. An instance of the class is allocated. The instance and its handle are

   256     added to the set of known objects. The contents restored appropriately:

   257 

   258     a.  For serializable objects, the no-arg constructor for the first

   259         non-serializable supertype is run. For serializable classes, the fields

   260         are initialized to the default value appropriate for its type. Then the

   261         fields of each class are restored by calling class-specific

   262         `readObject` methods, or if these are not defined, by calling the

   263         `defaultReadObject` method. Note that field initializers and

   264         constructors are not executed for serializable classes during

   265         deserialization. In the normal case, the version of the class that

   266         wrote the stream will be the same as the class reading the stream. In

   267         this case, all of the supertypes of the object in the stream will match

   268         the supertypes in the currently-loaded class. If the version of the

   269         class that wrote the stream had different supertypes than the loaded

   270         class, the `ObjectInputStream` must be more careful about restoring or

   271         initializing the state of the differing classes. It must step through

   272         the classes, matching the available data in the stream with the classes

   273         of the object being restored. Data for classes that occur in the

   274         stream, but do not occur in the object, is discarded. For classes that

   275         occur in the object, but not in the stream, the class fields are set to

   276         default values by default serialization.

   277 

   278     b.  For externalizable objects, the no-arg constructor for the class is run

   279         and then the `readExternal` method is called to restore the contents of

   280         the object.

   281 

   282 12. Process potential substitutions by the class of the object and/or by a

   283     subclass of `ObjectInputStream`:

   284 

   285     a.  If the class of the object is not an enum type and defines the

   286         appropriate `readResolve` method, the method is called to allow the

   287         object to replace itself.

   288 

   289     b.  Then if previously enabled by `enableResolveObject,` the

   290         `resolveObject` method is called to allow subclasses of the stream to

   291         examine and replace the object. If the previous step did replace the

   292         original object, the `resolveObject` method is called with the

   293         replacement object. If a replacement took place, the table of known

   294         objects is updated so the replacement object is associated with the

   295         handle. The replacement object is then returned from `readObject`.

   296 

   297 All of the methods for reading primitives types only consume bytes from the

   298 block data records in the stream. If a read for primitive data occurs when the

   299 next item in the stream is an object, the read methods return *-1* or the

   300 `EOFException` as appropriate. The value of a primitive type is read by a

   301 `DataInputStream` from the block data record.

   302 

   303 The exceptions thrown reflect errors during the traversal or exceptions that

   304 occur on the underlying stream. If any exception is thrown, the underlying

   305 stream is left in an unknown and unusable state.

   306 

   307 When the reset token occurs in the stream, all of the state of the stream is

   308 discarded. The set of known objects is cleared.

   309 

   310 When the exception token occurs in the stream, the exception is read and a new

   311 `WriteAbortedException` is thrown with the terminating exception as an

   312 argument. The stream context is reset as described earlier.

   313 

   314 The `readUnshared` method is used to read "unshared" objects from the stream.

   315 This method is identical to `readObject`, except that it prevents subsequent

   316 calls to `readObject` and `readUnshared` from returning additional references

   317 to the deserialized instance returned by the original call to `readUnshared`.

   318 Specifically:

   319 

   320 -   If `readUnshared` is called to deserialize a back-reference (the stream

   321     representation of an object which has been written previously to the

   322     stream), an `ObjectStreamException` will be thrown.

   323 

   324 -   If `readUnshared` returns successfully, then any subsequent attempts to

   325     deserialize back-references to the stream handle deserialized by

   326     `readUnshared` will cause an `ObjectStreamException` to be thrown.

   327 

   328 Deserializing an object via `readUnshared` invalidates the stream handle

   329 associated with the returned object. Note that this in itself does not always

   330 guarantee that the reference returned by `readUnshared` is unique; the

   331 deserialized object may define a `readResolve` method which returns an object

   332 visible to other parties, or `readUnshared` may return a `Class` object or enum

   333 constant obtainable elsewhere in the stream or through external means. If the

   334 deserialized object defines a `readResolve` method and the invocation of that

   335 method returns an array, then `readUnshared` returns a shallow clone of that

   336 array; this guarantees that the returned array object is unique and cannot be

   337 obtained a second time from an invocation of `readObject` or `readUnshared` on

   338 the `ObjectInputStream`, even if the underlying data stream has been

   339 manipulated.

   340 

   341 The `defaultReadObject` method is used to read the fields and object from the

   342 stream. It uses the class descriptor in the stream to read the fields in the

   343 canonical order by name and type from the stream. The values are assigned to

   344 the matching fields by name in the current class. Details of the versioning

   345 mechanism can be found in [Section 5.5, "Compatible Java Type

   346 Evolution"](version.html#compatible-java-type-evolution). Any field of the

   347 object that does not appear in the stream is set to its default value. Values

   348 that appear in the stream, but not in the object, are discarded. This occurs

   349 primarily when a later version of a class has written additional fields that do

   350 not occur in the earlier version. This method may only be called from the

   351 `readObject` method while restoring the fields of a class. When called at any

   352 other time, the `NotActiveException` is thrown.

   353 

   354 The `readFields` method reads the values of the serializable fields from the

   355 stream and makes them available via the `GetField` class. The `readFields`

   356 method is only callable from within the `readObject` method of a serializable

   357 class. It cannot be called more than once or if `defaultReadObject` has been

   358 called. The `GetFields` object uses the current object's `ObjectStreamClass` to

   359 verify the fields that can be retrieved for this class. The `GetFields` object

   360 returned by `readFields` is only valid during this call to the classes

   361 `readObject` method. The fields may be retrieved in any order. Additional data

   362 may only be read directly from stream after `readFields` has been called.

   363 

   364 The `registerValidation` method can be called to request a callback when the

   365 entire graph has been restored but before the object is returned to the

   366 original caller of `readObject`. The order of validate callbacks can be

   367 controlled using the priority. Callbacks registered with higher values are

   368 called before those with lower values. The object to be validated must support

   369 the `ObjectInputValidation` interface and implement the `validateObject`

   370 method. It is only correct to register validations during a call to a class's

   371 `readObject` method. Otherwise, a `NotActiveException` is thrown. If the

   372 callback object supplied to `registerValidation` is null, an

   373 `InvalidObjectException` is thrown.

   374 

   375 Starting with the Java SDK, Standard Edition, v1.3, the `readClassDescriptor`

   376 method is used to read in all `ObjectStreamClass` objects.

   377 `readClassDescriptor` is called when the `ObjectInputStream` expects a class

   378 descriptor as the next item in the serialization stream. Subclasses of

   379 `ObjectInputStream` may override this method to read in class descriptors that

   380 have been written in non-standard formats (by subclasses of

   381 `ObjectOutputStream` which have overridden the `writeClassDescriptor` method).

   382 By default, this method reads class descriptors according to the format

   383 described in [Section 6.4, "Grammar for the Stream

   384 Format"](protocol.html#grammar-for-the-stream-format).

   385 

   386 The `resolveClass` method is called while a class is being deserialized, and

   387 after the class descriptor has been read. Subclasses may extend this method to

   388 read other information about the class written by the corresponding subclass of

   389 `ObjectOutputStream`. The method must find and return the class with the given

   390 name and `serialVersionUID`. The default implementation locates the class by

   391 calling the class loader of the closest caller of `readObject` that has a class

   392 loader. If the class cannot be found `ClassNotFoundException` should be thrown.

   393 Prior to JDK 1.1.6, the `resolveClass` method was required to return the same

   394 fully qualified class name as the class name in the stream. In order to

   395 accommodate package renaming across releases, `method` `resolveClass` only

   396 needs to return a class with the same base class name and `SerialVersionUID` in

   397 JDK 1.1.6 and later versions.

   398 

   399 The `resolveObject` method is used by trusted subclasses to monitor or

   400 substitute one object for another during deserialization. Resolving objects

   401 must be enabled explicitly by calling `enableResolveObject` before calling

   402 `readObject` for the first object to be resolved. Once enabled, `resolveObject`

   403 is called once for each serializable object just prior to the first time it is

   404 being returned from `readObject`. Note that the `resolveObject` method is not

   405 called for objects of the specially handled classes, `Class`,

   406 `ObjectStreamClass`, `String`, and arrays. A subclass's implementation of

   407 `resolveObject` may return a substitute object that will be assigned or

   408 returned instead of the original. The object returned must be of a type that is

   409 consistent and assignable to every reference of the original object or else a

   410 `ClassCastException` will be thrown. All assignments are type-checked. All

   411 references in the stream to the original object will be replaced by references

   412 to the substitute object.

   413 

   414 The `enableResolveObject` method is called by trusted subclasses of

   415 `ObjectOutputStream` to enable the monitoring or substitution of one object for

   416 another during deserialization. Replacing objects is disabled until

   417 `enableResolveObject` is called with a `true` value. It may thereafter be

   418 disabled by setting it to `false`. The previous setting is returned. The

   419 `enableResolveObject` method checks if the stream has permission to request

   420 substitution during serialization. To ensure that the private state of objects

   421 is not unintentionally exposed, only trusted streams may use `resolveObject`.

   422 Trusted classes are those classes with a class loader equal to null or belong

   423 to a security protection domain that provides permission to enable

   424 substitution.

   425 

   426 If the subclass of `ObjectInputStream` is not considered part of the system

   427 domain, a line has to be added to the security policy file to provide to a

   428 subclass of `ObjectInputStream` permission to call `enableResolveObject`. The

   429 `SerializablePermission` to add is `"enableSubstitution"`.

   430 `AccessControlException` is thrown if the protection domain of the subclass of

   431 `ObjectStreamClass` does not have permission to `"enableSubstitution"` by

   432 calling `enableResolveObject`. See the document Java Security Architecture (JDK

   433 1.2) for additional information about the security model.

   434 

   435 The `readStreamHeader` method reads and verifies the magic number and version

   436 of the stream. If they do not match, the `StreamCorruptedMismatch` is thrown.

   437 

   438 To override the implementation of deserialization, a subclass of

   439 `ObjectInputStream` should call the protected no-arg `ObjectInputStream`,

   440 constructor. There is a security check within the no-arg constructor for

   441 `SerializablePermission "enableSubclassImplementation"` to ensure that only

   442 trusted classes are allowed to override the default implementation. This

   443 constructor does not allocate any private data for `ObjectInputStream` and sets

   444 a flag that indicates that the final `readObject` method should invoke the

   445 `readObjectOverride` method and return. All other `ObjectInputStream` methods

   446 are not final and can be directly overridden by the subclass.

   447 

   448 ## 3.2 The ObjectInputStream.GetField Class

   449 

   450 The class `ObjectInputStream.GetField` provides the API for getting the values

   451 of serializable fields. The protocol of the stream is the same as used by

   452 `defaultReadObject.` Using `readFields` to access the serializable fields does

   453 not change the format of the stream. It only provides an alternate API to

   454 access the values which does not require the class to have the corresponding

   455 non-transient and non-static fields for each named serializable field. The

   456 serializable fields are those declared using `serialPersistentFields` or if it

   457 is not declared the non-transient and non-static fields of the object. When the

   458 stream is read the available serializable fields are those written to the

   459 stream when the object was serialized. If the class that wrote the stream is a

   460 different version not all fields will correspond to the serializable fields of

   461 the current class. The available fields can be retrieved from the

   462 `ObjectStreamClass` of the `GetField` object.

   463 

   464 The `getObjectStreamClass` method returns an `ObjectStreamClass` object

   465 representing the class in the stream. It contains the list of serializable

   466 fields.

   467 

   468 The `defaulted` method returns *true* if the field is not present in the

   469 stream. An `IllegalArgumentException` is thrown if the requested field is not a

   470 serializable field of the current class.

   471 

   472 Each `get` method returns the specified serializable field from the stream. I/O

   473 exceptions will be thrown if the underlying stream throws an exception. An

   474 `IllegalArgumentException` is thrown if the name or type does not match the

   475 name and type of an field serializable field of the current class. The default

   476 value is returned if the stream does not contain an explicit value for the

   477 field.

   478 

   479 ## 3.3 The ObjectInputValidation Interface

   480 

   481 This interface allows an object to be called when a complete graph of objects

   482 has been deserialized. If the object cannot be made valid, it should throw the

   483 `ObjectInvalidException`. Any exception that occurs during a call to

   484 `validateObject` will terminate the validation process, and the

   485 `InvalidObjectException` will be thrown.

   486 

   487 ```

   488 package java.io;

   489 

   490 public interface ObjectInputValidation

   491 {

   492     public void validateObject()

   493         throws InvalidObjectException;

   494 }

   495 ```

   496 

   497 ## 3.4 The readObject Method

   498 

   499 For serializable objects, the `readObject` method allows a class to control the

   500 deserialization of its own fields. Here is its signature:

   501 

   502 ```

   503 private void readObject(ObjectInputStream stream)

   504     throws IOException, ClassNotFoundException;

   505 ```

   506 

   507 Each subclass of a serializable object may define its own `readObject` method.

   508 If a class does not implement the method, the default serialization provided by

   509 `defaultReadObject` will be used. When implemented, the class is only

   510 responsible for restoring its own fields, not those of its supertypes or

   511 subtypes.

   512 

   513 The `readObject` method of the class, if implemented, is responsible for

   514 restoring the state of the class. The values of every field of the object

   515 whether transient or not, static or not are set to the default value for the

   516 fields type. Either `ObjectInputStream`'s `defaultReadObject` or `readFields`

   517 method must be called once (and only once) before reading any optional data

   518 written by the corresponding `writeObject` method; even if no optional data is

   519 read, `defaultReadObject` or `readFields` must still be invoked once. If the

   520 `readObject` method of the class attempts to read more data than is present in

   521 the optional part of the stream for this class, the stream will return `-1` for

   522 bytewise reads, throw an `EOFException` for primitive data reads (e.g.,

   523 `readInt`, `readFloat`), or throw an `OptionalDataException` with the `eof`

   524 field set to `true` for object reads.

   525 

   526 The responsibility for the format, structure, and versioning of the optional

   527 data lies completely with the class. The `@serialData` javadoc tag within the

   528 javadoc comment for the `readObject` method should be used to document the

   529 format and structure of the optional data.

   530 

   531 If the class being restored is not present in the stream being read, then its

   532 `readObjectNoData` method, if defined, is invoked (instead of `readObject`);

   533 otherwise, its fields are initialized to the appropriate default values. For

   534 further detail, see [Section 3.5, "The readObjectNoData

   535 Method"](#the-readobjectnodata-method).

   536 

   537 Reading an object from the `ObjectInputStream` is analogous to creating a new

   538 object. Just as a new object's constructors are invoked in the order from the

   539 superclass to the subclass, an object being read from a stream is deserialized

   540 from superclass to subclass. The `readObject` or `readObjectNoData` method is

   541 called instead of the constructor for each `Serializable` subclass during

   542 deserialization.

   543 

   544 One last similarity between a constructor and a `readObject` method is that

   545 both provide the opportunity to invoke a method on an object that is not fully

   546 constructed. Any overridable (neither private, static nor final) method called

   547 while an object is being constructed can potentially be overridden by a

   548 subclass. Methods called during the construction phase of an object are

   549 resolved by the actual type of the object, not the type currently being

   550 initialized by either its constructor or `readObject`/`readObjectNoData`

   551 method. Therefore, calling an overridable method from within a `readObject` or

   552 `readObjectNoData` method may result in the unintentional invocation of a

   553 subclass method before the superclass has been fully initialized.

   554 

   555 ## 3.5 The readObjectNoData Method

   556 

   557 For serializable objects, the `readObjectNoData` method allows a class to

   558 control the initialization of its own fields in the event that a subclass

   559 instance is deserialized and the serialization stream does not list the class

   560 in question as a superclass of the deserialized object. This may occur in cases

   561 where the receiving party uses a different version of the deserialized

   562 instance's class than the sending party, and the receiver's version extends

   563 classes that are not extended by the sender's version. This may also occur if

   564 the serialization stream has been tampered; hence, `readObjectNoData` is useful

   565 for initializing deserialized objects properly despite a "hostile" or

   566 incomplete source stream.

   567 

   568 ```

   569 private void readObjectNoData() throws ObjectStreamException;

   570 ```

   571 

   572 Each serializable class may define its own `readObjectNoData` method. If a

   573 serializable class does not define a `readObjectNoData` method, then in the

   574 circumstances listed above the fields of the class will be initialized to their

   575 default values (as listed in The Java Language Specification); this behavior is

   576 consistent with that of `ObjectInputStream` prior to version 1.4 of the Java 2

   577 SDK, Standard Edition, when support for `readObjectNoData` methods was

   578 introduced. If a serializable class does define a `readObjectNoData` method and

   579 the aforementioned conditions arise, then `readObjectNoData` will be invoked at

   580 the point during deserialization when a class-defined `readObject` method would

   581 otherwise be called had the class in question been listed by the stream as a

   582 superclass of the instance being deserialized.

   583 

   584 ## 3.6 The readExternal Method

   585 

   586 Objects implementing `java.io.Externalizable` must implement the `readExternal`

   587 method to restore the entire state of the object. It must coordinate with its

   588 superclasses to restore their state. All of the methods of `ObjectInput` are

   589 available to restore the object's primitive typed fields and object fields.

   590 

   591 ```

   592 public void readExternal(ObjectInput stream)

   593     throws IOException;

   594 ```

   595 

   596 **Note:** The `readExternal` method is public, and it raises the risk of a

   597 client being able to overwrite an existing object from a stream. The class may

   598 add its own checks to insure that this is only called when appropriate.

   599 

   600 A new stream protocol version has been introduced in JDK 1.2 to correct a

   601 problem with `Externalizable` objects. The old definition of `Externalizable`

   602 objects required the local virtual machine to find a `readExternal` method to

   603 be able to properly read an `Externalizable` object from the stream. The new

   604 format adds enough information to the stream protocol so serialization can skip

   605 an `Externalizable` object when the local `readExternal` method is not

   606 available. Due to class evolution rules, serialization must be able to skip an

   607 `Externalizable` object in the input stream if there is not a mapping for the

   608 object using the local classes.

   609 

   610 An additional benefit of the new `Externalizable` stream format is that

   611 `ObjectInputStream` can detect attempts to read more External data than is

   612 available, and can also skip by any data that is left unconsumed by a

   613 `readExternal` method. The behavior of `ObjectInputStream` in response to a

   614 read past the end of External data is the same as the behavior when a

   615 class-defined `readObject` method attempts to read past the end of its optional

   616 data: bytewise reads will return `-1`, primitive reads will throw

   617 `EOFException`s, and object reads will throw `OptionalDataException`s with the

   618 `eof` field set to `true`.

   619 

   620 Due to the format change, JDK 1.1.6 and earlier releases are not able to read

   621 the new format. `StreamCorruptedException` is thrown when JDK 1.1.6 or earlier

   622 attempts to read an `Externalizable` object from a stream written in

   623 `PROTOCOL_VERSION_2`. Compatibility issues are discussed in more detail in

   624 [Section 6.3, "Stream Protocol

   625 Versions"](protocol.html#stream-protocol-versions).

   626 

   627 ## 3.7 The readResolve Method

   628 

   629 For Serializable and Externalizable classes, the `readResolve` method allows a

   630 class to replace/resolve the object read from the stream before it is returned

   631 to the caller. By implementing the `readResolve` method, a class can directly

   632 control the types and instances of its own instances being deserialized. The

   633 method is defined as follows:

   634 

   635 ```

   636 ANY-ACCESS-MODIFIER Object readResolve()

   637             throws ObjectStreamException;

   638 ```

   639 

   640 The `readResolve` method is called when `ObjectInputStream` has read an object

   641 from the stream and is preparing to return it to the caller.

   642 `ObjectInputStream` checks whether the class of the object defines the

   643 `readResolve` method. If the method is defined, the `readResolve` method is

   644 called to allow the object in the stream to designate the object to be

   645 returned. The object returned should be of a type that is compatible with all

   646 uses. If it is not compatible, a `ClassCastException` will be thrown when the

   647 type mismatch is discovered.

   648 

   649 For example, a `Symbol` class could be created for which only a single instance

   650 of each symbol binding existed within a virtual machine. The `readResolve`

   651 method would be implemented to determine if that symbol was already defined and

   652 substitute the preexisting equivalent `Symbol` object to maintain the identity

   653 constraint. In this way the uniqueness of `Symbol` objects can be maintained

   654 across serialization.

   655 

   656 **Note:** The `readResolve` method is not invoked on the object until the

   657 object is fully constructed, so any references to this object in its object

   658 graph will not be updated to the new object nominated by `readResolve`.

   659 However, during the serialization of an object with the `writeReplace` method,

   660 all references to the original object in the replacement object's object graph

   661 are replaced with references to the replacement object. Therefore in cases

   662 where an object being serialized nominates a replacement object whose object

   663 graph has a reference to the original object, deserialization will result in an

   664 incorrect graph of objects. Furthermore, if the reference types of the object

   665 being read (nominated by `writeReplace`) and the original object are not

   666 compatible, the construction of the object graph will raise a

   667 `ClassCastException`.

   668 

   669 -------------------------------------------------------------------------------

   670 

   671 *[Copyright](../../../legal/SMICopyright.html) © 2005, 2017, Oracle

   672 and/or its affiliates. All rights reserved.*