== Why is this an issue?

According to the documentation,

____
A program may produce unpredictable results if it attempts to distinguish two references to equal values of a value-based class, whether directly via reference equality or indirectly via an appeal to synchronization, identity hashing, serialization...
____


For example (credit to Brian Goetz), imagine Foo is a value-based class:

----
Foo[] arr = new Foo[2];
arr[0] = new Foo(0);
arr[1] = new Foo(0);
----
Serialization promises that on deserialization of arr, elements 0 and 1 will not be aliased.  Similarly, in:

----
Foo[] arr = new Foo[2];
arr[0] = new Foo(0);
arr[1] = arr[0];
----
Serialization promises that on deserialization of ``++arr++``, elements 0 and 1 *will* be aliased.


While these promises are coincidentally fulfilled in current implementations of Java, that is not guaranteed in the future, particularly when true value types are introduced in the language.


This rule raises an issue when a ``++Serializable++`` class defines a non-transient, non-static field field whose type is a known serializable value-based class. Known serializable value-based classes are: all the classes in the ``++java.time++`` package except ``++Clock++``; the date classes for alternate calendars: ``++HijrahDate++``, ``++JapaneseDate++``, ``++MinguoDate++``, ``++ThaiBuddhistDate++``.


=== Noncompliant code example

[source,java]
----
class MyClass implements Serializable {
  private HijrahDate date;  // Noncompliant; mark this transient
  // ...
}
----


=== Compliant solution

[source,java]
----
class MyClass implements Serializable {
  private transient HijrahDate date;
  // ...
}
----


== Resources

* https://docs.oracle.com/javase/8/docs/api/java/lang/doc-files/ValueBased.html[Value-based classes]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Make this value-based field transient so it is not included in the serialization of this class.


'''
== Comments And Links
(visible only on this page)

=== on 14 Jul 2016, 15:06:54 Yves Dubois-Pèlerin wrote:
As discussed with Ann and confirmed by Michael, we remove the [de]serialization case from this RSPEC. If the user dives into the details [de]serializing, using ObjectOutput#writeObject or ObjectInput#readObject, we assume the user knows what they are doing.

=== on 18 Jul 2016, 09:45:59 Michael Gumowski wrote:
The optional classes ``++Optional++``, ``++OptionalDouble++``, ``++OptionalLong++``, ``++OptionalInt++`` are already handled by RSPEC-1948

=== on 18 Jul 2016, 14:23:51 Yves Dubois-Pèlerin wrote:
Hello Michael, please validate this implementation.

I apologize for not making a separate commit for the factorization of method hasSpecialHandlingSerializationMethods (and dependent method methodThrows) into class SerializableContract.

endif::env-github,rspecator-view[]
