1. /*
  2. * @(#)Serializable.java 1.22 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.io;
  8. /**
  9. * Serializability of a class is enabled by the class implementing the
  10. * java.io.Serializable interface. Classes that do not implement this
  11. * interface will not have any of their state serialized or
  12. * deserialized. All subtypes of a serializable class are themselves
  13. * serializable. The serialization interface has no methods or fields
  14. * and serves only to identify the semantics of being serializable. <p>
  15. *
  16. * To allow subtypes of non-serializable classes to be serialized, the
  17. * subtype may assume responsibility for saving and restoring the
  18. * state of the supertype's public, protected, and (if accessible)
  19. * package fields. The subtype may assume this responsibility only if
  20. * the class it extends has an accessible no-arg constructor to
  21. * initialize the class's state. It is an error to declare a class
  22. * Serializable if this is not the case. The error will be detected at runtime. <p>
  23. *
  24. * During deserialization, the fields of non-serializable classes will
  25. * be initialized using the public or protected no-arg constructor of
  26. * the class. A no-arg constructor must be accessible to the subclass
  27. * that is serializable. The fields of serializable subclasses will
  28. * be restored from the stream. <p>
  29. *
  30. * When traversing a graph, an object may be encountered that does not
  31. * support the Serializable interface. In this case the
  32. * NotSerializableException will be thrown and will identify the class
  33. * of the non-serializable object. <p>
  34. *
  35. * Classes that require special handling during the serialization and
  36. * deserialization process must implement special methods with these exact
  37. * signatures: <p>
  38. *
  39. * <PRE>
  40. * private void writeObject(java.io.ObjectOutputStream out)
  41. * throws IOException
  42. * private void readObject(java.io.ObjectInputStream in)
  43. * throws IOException, ClassNotFoundException;
  44. * </PRE><p>
  45. *
  46. * The writeObject method is responsible for writing the state of the
  47. * object for its particular class so that the corresponding
  48. * readObject method can restore it. The default mechanism for saving
  49. * the Object's fields can be invoked by calling
  50. * out.defaultWriteObject. The method does not need to concern
  51. * itself with the state belonging to its superclasses or subclasses.
  52. * State is saved by writing the individual fields to the
  53. * ObjectOutputStream using the writeObject method or by using the
  54. * methods for primitive data types supported by DataOutput. <p>
  55. *
  56. * The readObject method is responsible for reading from the stream and
  57. * restoring the classes fields. It may call in.defaultReadObject to invoke
  58. * the default mechanism for restoring the object's non-static and non-transient
  59. * fields. The defaultReadObject method uses information in the stream to
  60. * assign the fields of the object saved in the stream with the correspondingly
  61. * named fields in the current object. This handles the case when the class
  62. * has evolved to add new fields. The method does not need to concern
  63. * itself with the state belonging to its superclasses or subclasses.
  64. * State is saved by writing the individual fields to the
  65. * ObjectOutputStream using the writeObject method or by using the
  66. * methods for primitive data types supported by DataOutput. <p>
  67. *
  68. * Serializable classes that need to designate an alternative object to be
  69. * used when writing an object to the stream should implement this
  70. * special method with the exact signature: <p>
  71. *
  72. * <PRE>
  73. * ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException;
  74. * </PRE><p>
  75. *
  76. * This writeReplace method is invoked by serialization if the method
  77. * exists and it would be accessible from a method defined within the
  78. * class of the object being serialized. Thus, the method can have private,
  79. * protected and package-private access. Subclass access to this method
  80. * follows java accessibility rules. <p>
  81. *
  82. * Classes that need to designate a replacement when an instance of it
  83. * is read from the stream should implement this special method with the
  84. * exact signature.<p>
  85. *
  86. * <PRE>
  87. * ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException;
  88. * </PRE><p>
  89. *
  90. * This readResolve method follows the same invocation rules and
  91. * accessibility rules as writeReplace.<p>
  92. *
  93. * The serialization runtime associates with each serializable class a version
  94. * number, called a serialVersionUID, which is used during deserialization to
  95. * verify that the sender and receiver of a serialized object have loaded
  96. * classes for that object that are compatible with respect to serialization.
  97. * If the receiver has loaded a class for the object that has a different
  98. * serialVersionUID than that of the corresponding sender's class, then
  99. * deserialization will result in an {@link InvalidClassException}. A
  100. * serializable class can declare its own serialVersionUID explicitly by
  101. * declaring a field named <code>"serialVersionUID"</code> that must be static,
  102. * final, and of type <code>long</code>:<p>
  103. *
  104. * <PRE>
  105. * ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;
  106. * </PRE>
  107. *
  108. * If a serializable class does not explicitly declare a serialVersionUID, then
  109. * the serialization runtime will calculate a default serialVersionUID value
  110. * for that class based on various aspects of the class, as described in the
  111. * Java(TM) Object Serialization Specification. However, it is <em>strongly
  112. * recommended</em> that all serializable classes explicitly declare
  113. * serialVersionUID values, since the default serialVersionUID computation is
  114. * highly sensitive to class details that may vary depending on compiler
  115. * implementations, and can thus result in unexpected
  116. * <code>InvalidClassException</code>s during deserialization. Therefore, to
  117. * guarantee a consistent serialVersionUID value across different java compiler
  118. * implementations, a serializable class must declare an explicit
  119. * serialVersionUID value. It is also strongly advised that explicit
  120. * serialVersionUID declarations use the <code>private</code> modifier where
  121. * possible, since such declarations apply only to the immediately declaring
  122. * class--serialVersionUID fields are not useful as inherited members.
  123. *
  124. * @author unascribed
  125. * @version 1.22, 12/19/03
  126. * @see java.io.ObjectOutputStream
  127. * @see java.io.ObjectInputStream
  128. * @see java.io.ObjectOutput
  129. * @see java.io.ObjectInput
  130. * @see java.io.Externalizable
  131. * @since JDK1.1
  132. */
  133. public interface Serializable {
  134. }