1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/mini/src/main/java/java/io/Serializable.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,170 @@
1.4 +/*
1.5 + * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.io;
1.30 +
1.31 +/**
1.32 + * Serializability of a class is enabled by the class implementing the
1.33 + * java.io.Serializable interface. Classes that do not implement this
1.34 + * interface will not have any of their state serialized or
1.35 + * deserialized. All subtypes of a serializable class are themselves
1.36 + * serializable. The serialization interface has no methods or fields
1.37 + * and serves only to identify the semantics of being serializable. <p>
1.38 + *
1.39 + * To allow subtypes of non-serializable classes to be serialized, the
1.40 + * subtype may assume responsibility for saving and restoring the
1.41 + * state of the supertype's public, protected, and (if accessible)
1.42 + * package fields. The subtype may assume this responsibility only if
1.43 + * the class it extends has an accessible no-arg constructor to
1.44 + * initialize the class's state. It is an error to declare a class
1.45 + * Serializable if this is not the case. The error will be detected at
1.46 + * runtime. <p>
1.47 + *
1.48 + * During deserialization, the fields of non-serializable classes will
1.49 + * be initialized using the public or protected no-arg constructor of
1.50 + * the class. A no-arg constructor must be accessible to the subclass
1.51 + * that is serializable. The fields of serializable subclasses will
1.52 + * be restored from the stream. <p>
1.53 + *
1.54 + * When traversing a graph, an object may be encountered that does not
1.55 + * support the Serializable interface. In this case the
1.56 + * NotSerializableException will be thrown and will identify the class
1.57 + * of the non-serializable object. <p>
1.58 + *
1.59 + * Classes that require special handling during the serialization and
1.60 + * deserialization process must implement special methods with these exact
1.61 + * signatures: <p>
1.62 + *
1.63 + * <PRE>
1.64 + * private void writeObject(java.io.ObjectOutputStream out)
1.65 + * throws IOException
1.66 + * private void readObject(java.io.ObjectInputStream in)
1.67 + * throws IOException, ClassNotFoundException;
1.68 + * private void readObjectNoData()
1.69 + * throws ObjectStreamException;
1.70 + * </PRE>
1.71 + *
1.72 + * <p>The writeObject method is responsible for writing the state of the
1.73 + * object for its particular class so that the corresponding
1.74 + * readObject method can restore it. The default mechanism for saving
1.75 + * the Object's fields can be invoked by calling
1.76 + * out.defaultWriteObject. The method does not need to concern
1.77 + * itself with the state belonging to its superclasses or subclasses.
1.78 + * State is saved by writing the individual fields to the
1.79 + * ObjectOutputStream using the writeObject method or by using the
1.80 + * methods for primitive data types supported by DataOutput.
1.81 + *
1.82 + * <p>The readObject method is responsible for reading from the stream and
1.83 + * restoring the classes fields. It may call in.defaultReadObject to invoke
1.84 + * the default mechanism for restoring the object's non-static and
1.85 + * non-transient fields. The defaultReadObject method uses information in
1.86 + * the stream to assign the fields of the object saved in the stream with the
1.87 + * correspondingly named fields in the current object. This handles the case
1.88 + * when the class has evolved to add new fields. The method does not need to
1.89 + * concern itself with the state belonging to its superclasses or subclasses.
1.90 + * State is saved by writing the individual fields to the
1.91 + * ObjectOutputStream using the writeObject method or by using the
1.92 + * methods for primitive data types supported by DataOutput.
1.93 + *
1.94 + * <p>The readObjectNoData method is responsible for initializing the state of
1.95 + * the object for its particular class in the event that the serialization
1.96 + * stream does not list the given class as a superclass of the object being
1.97 + * deserialized. This may occur in cases where the receiving party uses a
1.98 + * different version of the deserialized instance's class than the sending
1.99 + * party, and the receiver's version extends classes that are not extended by
1.100 + * the sender's version. This may also occur if the serialization stream has
1.101 + * been tampered; hence, readObjectNoData is useful for initializing
1.102 + * deserialized objects properly despite a "hostile" or incomplete source
1.103 + * stream.
1.104 + *
1.105 + * <p>Serializable classes that need to designate an alternative object to be
1.106 + * used when writing an object to the stream should implement this
1.107 + * special method with the exact signature: <p>
1.108 + *
1.109 + * <PRE>
1.110 + * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
1.111 + * </PRE><p>
1.112 + *
1.113 + * This writeReplace method is invoked by serialization if the method
1.114 + * exists and it would be accessible from a method defined within the
1.115 + * class of the object being serialized. Thus, the method can have private,
1.116 + * protected and package-private access. Subclass access to this method
1.117 + * follows java accessibility rules. <p>
1.118 + *
1.119 + * Classes that need to designate a replacement when an instance of it
1.120 + * is read from the stream should implement this special method with the
1.121 + * exact signature.<p>
1.122 + *
1.123 + * <PRE>
1.124 + * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
1.125 + * </PRE><p>
1.126 + *
1.127 + * This readResolve method follows the same invocation rules and
1.128 + * accessibility rules as writeReplace.<p>
1.129 + *
1.130 + * The serialization runtime associates with each serializable class a version
1.131 + * number, called a serialVersionUID, which is used during deserialization to
1.132 + * verify that the sender and receiver of a serialized object have loaded
1.133 + * classes for that object that are compatible with respect to serialization.
1.134 + * If the receiver has loaded a class for the object that has a different
1.135 + * serialVersionUID than that of the corresponding sender's class, then
1.136 + * deserialization will result in an {@link InvalidClassException}. A
1.137 + * serializable class can declare its own serialVersionUID explicitly by
1.138 + * declaring a field named <code>"serialVersionUID"</code> that must be static,
1.139 + * final, and of type <code>long</code>:<p>
1.140 + *
1.141 + * <PRE>
1.142 + * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
1.143 + * </PRE>
1.144 + *
1.145 + * If a serializable class does not explicitly declare a serialVersionUID, then
1.146 + * the serialization runtime will calculate a default serialVersionUID value
1.147 + * for that class based on various aspects of the class, as described in the
1.148 + * Java(TM) Object Serialization Specification. However, it is <em>strongly
1.149 + * recommended</em> that all serializable classes explicitly declare
1.150 + * serialVersionUID values, since the default serialVersionUID computation is
1.151 + * highly sensitive to class details that may vary depending on compiler
1.152 + * implementations, and can thus result in unexpected
1.153 + * <code>InvalidClassException</code>s during deserialization. Therefore, to
1.154 + * guarantee a consistent serialVersionUID value across different java compiler
1.155 + * implementations, a serializable class must declare an explicit
1.156 + * serialVersionUID value. It is also strongly advised that explicit
1.157 + * serialVersionUID declarations use the <code>private</code> modifier where
1.158 + * possible, since such declarations apply only to the immediately declaring
1.159 + * class--serialVersionUID fields are not useful as inherited members. Array
1.160 + * classes cannot declare an explicit serialVersionUID, so they always have
1.161 + * the default computed value, but the requirement for matching
1.162 + * serialVersionUID values is waived for array classes.
1.163 + *
1.164 + * @author unascribed
1.165 + * @see java.io.ObjectOutputStream
1.166 + * @see java.io.ObjectInputStream
1.167 + * @see java.io.ObjectOutput
1.168 + * @see java.io.ObjectInput
1.169 + * @see java.io.Externalizable
1.170 + * @since JDK1.1
1.171 + */
1.172 +public interface Serializable {
1.173 +}