Home » openjdk-7 » java » io » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2005, 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. Classes that do not implement this
   31    * interface will not have any of their state serialized or
   32    * deserialized.  All subtypes of a serializable class are themselves
   33    * serializable.  The serialization interface has no methods or fields
   34    * and serves only to identify the semantics of being serializable. <p>
   35    *
   36    * To allow subtypes of non-serializable classes to be serialized, the
   37    * subtype may assume responsibility for saving and restoring the
   38    * state of the supertype's public, protected, and (if accessible)
   39    * package fields.  The subtype may assume this responsibility only if
   40    * the class it extends has an accessible no-arg constructor to
   41    * initialize the class's state.  It is an error to declare a class
   42    * Serializable if this is not the case.  The error will be detected at
   43    * runtime. <p>
   44    *
   45    * During deserialization, the fields of non-serializable classes will
   46    * be initialized using the public or protected no-arg constructor of
   47    * the class.  A no-arg constructor must be accessible to the subclass
   48    * that is serializable.  The fields of serializable subclasses will
   49    * be restored from the stream. <p>
   50    *
   51    * When traversing a graph, an object may be encountered that does not
   52    * support the Serializable interface. In this case the
   53    * NotSerializableException will be thrown and will identify the class
   54    * of the non-serializable object. <p>
   55    *
   56    * Classes that require special handling during the serialization and
   57    * deserialization process must implement special methods with these exact
   58    * signatures: <p>
   59    *
   60    * <PRE>
   61    * private void writeObject(java.io.ObjectOutputStream out)
   62    *     throws IOException
   63    * private void readObject(java.io.ObjectInputStream in)
   64    *     throws IOException, ClassNotFoundException;
   65    * private void readObjectNoData()
   66    *     throws ObjectStreamException;
   67    * </PRE>
   68    *
   69    * <p>The writeObject method is responsible for writing the state of the
   70    * object for its particular class so that the corresponding
   71    * readObject method can restore it.  The default mechanism for saving
   72    * the Object's fields can be invoked by calling
   73    * out.defaultWriteObject. The method does not need to concern
   74    * itself with the state belonging to its superclasses or subclasses.
   75    * State is saved by writing the individual fields to the
   76    * ObjectOutputStream using the writeObject method or by using the
   77    * methods for primitive data types supported by DataOutput.
   78    *
   79    * <p>The readObject method is responsible for reading from the stream and
   80    * restoring the classes fields. It may call in.defaultReadObject to invoke
   81    * the default mechanism for restoring the object's non-static and
   82    * non-transient fields.  The defaultReadObject method uses information in
   83    * the stream to assign the fields of the object saved in the stream with the
   84    * correspondingly named fields in the current object.  This handles the case
   85    * when the class has evolved to add new fields. The method does not need to
   86    * concern itself with the state belonging to its superclasses or subclasses.
   87    * State is saved by writing the individual fields to the
   88    * ObjectOutputStream using the writeObject method or by using the
   89    * methods for primitive data types supported by DataOutput.
   90    *
   91    * <p>The readObjectNoData method is responsible for initializing the state of
   92    * the object for its particular class in the event that the serialization
   93    * stream does not list the given class as a superclass of the object being
   94    * deserialized.  This may occur in cases where the receiving party uses a
   95    * different version of the deserialized instance's class than the sending
   96    * party, and the receiver's version extends classes that are not extended by
   97    * the sender's version.  This may also occur if the serialization stream has
   98    * been tampered; hence, readObjectNoData is useful for initializing
   99    * deserialized objects properly despite a "hostile" or incomplete source
  100    * stream.
  101    *
  102    * <p>Serializable classes that need to designate an alternative object to be
  103    * used when writing an object to the stream should implement this
  104    * special method with the exact signature: <p>
  105    *
  106    * <PRE>
  107    * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
  108    * </PRE><p>
  109    *
  110    * This writeReplace method is invoked by serialization if the method
  111    * exists and it would be accessible from a method defined within the
  112    * class of the object being serialized. Thus, the method can have private,
  113    * protected and package-private access. Subclass access to this method
  114    * follows java accessibility rules. <p>
  115    *
  116    * Classes that need to designate a replacement when an instance of it
  117    * is read from the stream should implement this special method with the
  118    * exact signature.<p>
  119    *
  120    * <PRE>
  121    * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
  122    * </PRE><p>
  123    *
  124    * This readResolve method follows the same invocation rules and
  125    * accessibility rules as writeReplace.<p>
  126    *
  127    * The serialization runtime associates with each serializable class a version
  128    * number, called a serialVersionUID, which is used during deserialization to
  129    * verify that the sender and receiver of a serialized object have loaded
  130    * classes for that object that are compatible with respect to serialization.
  131    * If the receiver has loaded a class for the object that has a different
  132    * serialVersionUID than that of the corresponding sender's class, then
  133    * deserialization will result in an {@link InvalidClassException}.  A
  134    * serializable class can declare its own serialVersionUID explicitly by
  135    * declaring a field named <code>"serialVersionUID"</code> that must be static,
  136    * final, and of type <code>long</code>:<p>
  137    *
  138    * <PRE>
  139    * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
  140    * </PRE>
  141    *
  142    * If a serializable class does not explicitly declare a serialVersionUID, then
  143    * the serialization runtime will calculate a default serialVersionUID value
  144    * for that class based on various aspects of the class, as described in the
  145    * Java(TM) Object Serialization Specification.  However, it is <em>strongly
  146    * recommended</em> that all serializable classes explicitly declare
  147    * serialVersionUID values, since the default serialVersionUID computation is
  148    * highly sensitive to class details that may vary depending on compiler
  149    * implementations, and can thus result in unexpected
  150    * <code>InvalidClassException</code>s during deserialization.  Therefore, to
  151    * guarantee a consistent serialVersionUID value across different java compiler
  152    * implementations, a serializable class must declare an explicit
  153    * serialVersionUID value.  It is also strongly advised that explicit
  154    * serialVersionUID declarations use the <code>private</code> modifier where
  155    * possible, since such declarations apply only to the immediately declaring
  156    * class--serialVersionUID fields are not useful as inherited members. Array
  157    * classes cannot declare an explicit serialVersionUID, so they always have
  158    * the default computed value, but the requirement for matching
  159    * serialVersionUID values is waived for array classes.
  160    *
  161    * @author  unascribed
  162    * @see java.io.ObjectOutputStream
  163    * @see java.io.ObjectInputStream
  164    * @see java.io.ObjectOutput
  165    * @see java.io.ObjectInput
  166    * @see java.io.Externalizable
  167    * @since   JDK1.1
  168    */
  169   public interface Serializable {
  170   }

Home » openjdk-7 » java » io » [javadoc | source]