1 /*
   2  * Copyright (c) 1996, 2013, 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.io;
  27 
  28 /**
  29  * Serializability of a class is enabled by the class implementing the
  30  * java.io.Serializable interface.
  31  *
  32  * <p><strong>Warning: Deserialization of untrusted data is inherently dangerous
  33  * and should be avoided. Untrusted data should be carefully validated according to the
  34  * "Serialization and Deserialization" section of the
  35  * {@extLink secure_coding_guidelines_javase Secure Coding Guidelines for Java SE}.
  36  * {@extLink serialization_filter_guide Serialization Filtering} describes best
  37  * practices for defensive use of serial filters.
  38  * </strong></p>
  39  *
  40  * Classes that do not implement this
  41  * interface will not have any of their state serialized or
  42  * deserialized.  All subtypes of a serializable class are themselves
  43  * serializable.  The serialization interface has no methods or fields
  44  * and serves only to identify the semantics of being serializable. <p>
  45  *
  46  * To allow subtypes of non-serializable classes to be serialized, the
  47  * subtype may assume responsibility for saving and restoring the
  48  * state of the supertype's public, protected, and (if accessible)
  49  * package fields.  The subtype may assume this responsibility only if
  50  * the class it extends has an accessible no-arg constructor to
  51  * initialize the class's state.  It is an error to declare a class
  52  * Serializable if this is not the case.  The error will be detected at
  53  * runtime. <p>
  54  *
  55  * During deserialization, the fields of non-serializable classes will
  56  * be initialized using the public or protected no-arg constructor of
  57  * the class.  A no-arg constructor must be accessible to the subclass
  58  * that is serializable.  The fields of serializable subclasses will
  59  * be restored from the stream. <p>
  60  *
  61  * When traversing a graph, an object may be encountered that does not
  62  * support the Serializable interface. In this case the
  63  * NotSerializableException will be thrown and will identify the class
  64  * of the non-serializable object. <p>
  65  *
  66  * Classes that require special handling during the serialization and
  67  * deserialization process must implement special methods with these exact
  68  * signatures:
  69  *
  70  * <PRE>
  71  * private void writeObject(java.io.ObjectOutputStream out)
  72  *     throws IOException
  73  * private void readObject(java.io.ObjectInputStream in)
  74  *     throws IOException, ClassNotFoundException;
  75  * private void readObjectNoData()
  76  *     throws ObjectStreamException;
  77  * </PRE>
  78  *
  79  * <p>The writeObject method is responsible for writing the state of the
  80  * object for its particular class so that the corresponding
  81  * readObject method can restore it.  The default mechanism for saving
  82  * the Object's fields can be invoked by calling
  83  * out.defaultWriteObject. The method does not need to concern
  84  * itself with the state belonging to its superclasses or subclasses.
  85  * State is saved by writing the individual fields to the
  86  * ObjectOutputStream using the writeObject method or by using the
  87  * methods for primitive data types supported by DataOutput.
  88  *
  89  * <p>The readObject method is responsible for reading from the stream and
  90  * restoring the classes fields. It may call in.defaultReadObject to invoke
  91  * the default mechanism for restoring the object's non-static and
  92  * non-transient fields.  The defaultReadObject method uses information in
  93  * the stream to assign the fields of the object saved in the stream with the
  94  * correspondingly named fields in the current object.  This handles the case
  95  * when the class has evolved to add new fields. The method does not need to
  96  * concern itself with the state belonging to its superclasses or subclasses.
  97  * State is restored by reading data from the ObjectInputStream for
  98  * the individual fields and making assignments to the appropriate fields
  99  * of the object. Reading primitive data types is supported by DataInput.
 100  *
 101  * <p>The readObjectNoData method is responsible for initializing the state of
 102  * the object for its particular class in the event that the serialization
 103  * stream does not list the given class as a superclass of the object being
 104  * deserialized.  This may occur in cases where the receiving party uses a
 105  * different version of the deserialized instance's class than the sending
 106  * party, and the receiver's version extends classes that are not extended by
 107  * the sender's version.  This may also occur if the serialization stream has
 108  * been tampered; hence, readObjectNoData is useful for initializing
 109  * deserialized objects properly despite a "hostile" or incomplete source
 110  * stream.
 111  *
 112  * <p>Serializable classes that need to designate an alternative object to be
 113  * used when writing an object to the stream should implement this
 114  * special method with the exact signature:
 115  *
 116  * <PRE>
 117  * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
 118  * </PRE><p>
 119  *
 120  * This writeReplace method is invoked by serialization if the method
 121  * exists and it would be accessible from a method defined within the
 122  * class of the object being serialized. Thus, the method can have private,
 123  * protected and package-private access. Subclass access to this method
 124  * follows java accessibility rules. <p>
 125  *
 126  * Classes that need to designate a replacement when an instance of it
 127  * is read from the stream should implement this special method with the
 128  * exact signature.
 129  *
 130  * <PRE>
 131  * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
 132  * </PRE><p>
 133  *
 134  * This readResolve method follows the same invocation rules and
 135  * accessibility rules as writeReplace.<p>
 136  *
 137  * The serialization runtime associates with each serializable class a version
 138  * number, called a serialVersionUID, which is used during deserialization to
 139  * verify that the sender and receiver of a serialized object have loaded
 140  * classes for that object that are compatible with respect to serialization.
 141  * If the receiver has loaded a class for the object that has a different
 142  * serialVersionUID than that of the corresponding sender's class, then
 143  * deserialization will result in an {@link InvalidClassException}.  A
 144  * serializable class can declare its own serialVersionUID explicitly by
 145  * declaring a field named <code>"serialVersionUID"</code> that must be static,
 146  * final, and of type <code>long</code>:
 147  *
 148  * <PRE>
 149  * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
 150  * </PRE>
 151  *
 152  * If a serializable class does not explicitly declare a serialVersionUID, then
 153  * the serialization runtime will calculate a default serialVersionUID value
 154  * for that class based on various aspects of the class, as described in the
 155  * Java(TM) Object Serialization Specification.  However, it is <em>strongly
 156  * recommended</em> that all serializable classes explicitly declare
 157  * serialVersionUID values, since the default serialVersionUID computation is
 158  * highly sensitive to class details that may vary depending on compiler
 159  * implementations, and can thus result in unexpected
 160  * <code>InvalidClassException</code>s during deserialization.  Therefore, to
 161  * guarantee a consistent serialVersionUID value across different java compiler
 162  * implementations, a serializable class must declare an explicit
 163  * serialVersionUID value.  It is also strongly advised that explicit
 164  * serialVersionUID declarations use the <code>private</code> modifier where
 165  * possible, since such declarations apply only to the immediately declaring
 166  * class--serialVersionUID fields are not useful as inherited members. Array
 167  * classes cannot declare an explicit serialVersionUID, so they always have
 168  * the default computed value, but the requirement for matching
 169  * serialVersionUID values is waived for array classes.
 170  *
 171  * @author  unascribed
 172  * @see java.io.ObjectOutputStream
 173  * @see java.io.ObjectInputStream
 174  * @see java.io.ObjectOutput
 175  * @see java.io.ObjectInput
 176  * @see java.io.Externalizable
 177  * @since   1.1
 178  */
 179 public interface Serializable {
 180 }