Skip to content
Permalink
Browse files
8256679: Update serialization javadoc once JOSS changes for records a…
…re complete

Reviewed-by: chegar, rriggs
  • Loading branch information
Julia Boes committed Dec 7, 2020
1 parent 7620124 commit d05401d886125815f2e5704eef79667bd9be8ec0
Show file tree
Hide file tree
Showing 5 changed files with 24 additions and 50 deletions.
@@ -223,39 +223,14 @@
* Similarly, any serialPersistentFields or serialVersionUID field declarations
* are also ignored--all enum types have a fixed serialVersionUID of 0L.
*
* @implSpec
* <a id="record-serialization"></a>
* Records are serialized differently than ordinary serializable or externalizable
* objects. The serialized form of a record object is a sequence of values derived
* from the record components. The stream format of a record object is the same as
* that of an ordinary object in the stream. During deserialization, if the local
* class equivalent of the specified stream class descriptor is a record class,
* then first the stream fields are read and reconstructed to serve as the record's
* component values; and second, a record object is created by invoking the
* record's <i>canonical</i> constructor with the component values as arguments (or the
* default value for component's type if a component value is absent from the
* stream).
* Like other serializable or externalizable objects, record objects can function
* as the target of back references appearing subsequently in the serialization
* stream. However, a cycle in the graph where the record object is referred to,
* either directly or transitively, by one of its components, is not preserved.
* The record components are deserialized prior to the invocation of the record
* constructor, hence this limitation (see
* <a href="{@docRoot}/../specs/serialization/serial-arch.html#cyclic-references">
* <cite>Java Object Serialization Specification,</cite>
* Section 1.14, "Circular References"</a> for additional information).
* The process by which record objects are serialized or externalized cannot be
* customized; any class-specific writeObject, readObject, readObjectNoData,
* writeExternal, and readExternal methods defined by record classes are
* ignored during serialization and deserialization. However, a substitute object
* to be serialized or a designate replacement may be specified, by the
* writeReplace and readResolve methods, respectively. Any
* serialPersistentFields field declaration is ignored. Documenting serializable
* fields and data for record classes is unnecessary, since there is no variation
* in the serial form, other than whether a substitute or replacement object is
* used. The serialVersionUID of a record class is 0L unless explicitly
* declared. The requirement for matching serialVersionUID values is waived for
* record classes.
* <p>Records are serialized differently than ordinary serializable or externalizable
* objects. During deserialization the record's canonical constructor is invoked
* to construct the record object. Certain serialization-related methods, such
* as readObject and writeObject, are ignored for serializable records. See
* <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
* <cite>Java Object Serialization Specification,</cite> Section 1.13,
* "Serialization of Records"</a> for additional information.
*
* @author Mike Warres
* @author Roger Riggs
@@ -1,5 +1,5 @@
/*
* Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -150,8 +150,7 @@
* defaultWriteObject and writeFields initially terminate any existing
* block-data record.
*
* @implSpec
* Records are serialized differently than ordinary serializable or externalizable
* <p>Records are serialized differently than ordinary serializable or externalizable
* objects, see <a href="ObjectInputStream.html#record-serialization">record serialization</a>.
*
* @author Mike Warres
@@ -1483,7 +1482,6 @@ private void writeExternalData(Externalizable obj) throws IOException {
}

/** Writes the record component values for the given record object. */
@SuppressWarnings("preview")
private void writeRecordData(Object obj, ObjectStreamClass desc)
throws IOException
{
@@ -490,11 +490,6 @@ Thread getOwner() {
}
}

@SuppressWarnings("preview")
private static boolean isRecord(Class<?> cls) {
return cls.isRecord();
}

/**
* Creates local class descriptor representing given class.
*/
@@ -503,7 +498,7 @@ private ObjectStreamClass(final Class<?> cl) {
name = cl.getName();
isProxy = Proxy.isProxyClass(cl);
isEnum = Enum.class.isAssignableFrom(cl);
isRecord = isRecord(cl);
isRecord = cl.isRecord();
serializable = Serializable.class.isAssignableFrom(cl);
externalizable = Externalizable.class.isAssignableFrom(cl);

@@ -718,7 +713,7 @@ void initNonProxy(ObjectStreamClass model,
}

if (model.serializable == osc.serializable &&
!cl.isArray() && !isRecord(cl) &&
!cl.isArray() && !cl.isRecord() &&
suid != osc.getSerialVersionUID()) {
throw new InvalidClassException(osc.name,
"local class incompatible: " +
@@ -780,7 +775,7 @@ void initNonProxy(ObjectStreamClass model,
deserializeEx = localDesc.deserializeEx;
}
domains = localDesc.domains;
assert isRecord(cl) ? localDesc.cons == null : true;
assert cl.isRecord() ? localDesc.cons == null : true;
cons = localDesc.cons;
}

@@ -1590,9 +1585,8 @@ private static Constructor<?> getSerializableConstructor(Class<?> cl) {
* the not found ( which should never happen for correctly generated record
* classes ).
*/
@SuppressWarnings("preview")
private static MethodHandle canonicalRecordCtr(Class<?> cls) {
assert isRecord(cls) : "Expected record, got: " + cls;
assert cls.isRecord() : "Expected record, got: " + cls;
PrivilegedAction<MethodHandle> pa = () -> {
Class<?>[] paramTypes = Arrays.stream(cls.getRecordComponents())
.map(RecordComponent::getType)
@@ -1743,7 +1737,7 @@ private static ObjectStreamField[] getSerialFields(Class<?> cl)
return NO_FIELDS;

ObjectStreamField[] fields;
if (isRecord(cl)) {
if (cl.isRecord()) {
fields = getDefaultSerialFields(cl);
Arrays.sort(fields);
} else if (!Externalizable.class.isAssignableFrom(cl) &&
@@ -2663,7 +2657,6 @@ static final class RecordSupport {
* and return
* {@code Object}
*/
@SuppressWarnings("preview")
static MethodHandle deserializationCtr(ObjectStreamClass desc) {
// check the cached value 1st
MethodHandle mh = desc.deserializationCtr;
@@ -139,6 +139,12 @@
* serialization and deserialization. Any declarations of the special
* handling methods discussed above are ignored for enum types.<p>
*
* Record classes can implement {@code Serializable} and receive treatment defined
* by the <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
* <cite>Java Object Serialization Specification,</cite> Section 1.13,
* "Serialization of Records"</a>. Any declarations of the special
* handling methods discussed above are ignored for record types.<p>
*
* The serialization runtime associates with each serializable class a version
* number, called a serialVersionUID, which is used during deserialization to
* verify that the sender and receiver of a serialized object have loaded
@@ -74,8 +74,10 @@
* deserialization the record's canonical constructor is invoked to construct
* the record object. Certain serialization-related methods, such as readObject
* and writeObject, are ignored for serializable records. More information about
* serializable records can be found in
* <a href="{@docRoot}/java.base/java/io/ObjectInputStream.html#record-serialization">record serialization</a>.
* serializable records can be found in the
* <a href="{@docRoot}/../specs/serialization/serial-arch.html#serialization-of-records">
* <cite>Java Object Serialization Specification,</cite> Section 1.13,
* "Serialization of Records"</a>.
*
* @jls 8.10 Record Types
* @since 16

1 comment on commit d05401d

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.