1 /*
 2  * Copyright (c) 2024, 2026, 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 package jdk.internal.value;
26 
27 import java.lang.annotation.Retention;
28 import java.lang.annotation.RetentionPolicy;
29 import java.lang.annotation.Target;
30 
31 import static java.lang.annotation.ElementType.CONSTRUCTOR;
32 import static java.lang.annotation.ElementType.METHOD;
33 
34 /**
35  * A JDK internal annotation that facilitates serialization and deserialization of non-record
36  * value classes without requiring those value classes to implement the {@code writeReplace()}
37  * and {@code readObject()} methods.
38  * <p>
39  * Non-record value classes, unless they implement the {@code writeReplace()}
40  * and {@code readObject()} methods, cannot be serialized or deserialized. Certain pre-existing
41  * {@code Serializable} identity classes within the JDK are value classes in preview-mode, and
42  * must remain compatible. Such a value class may choose to annotate a constructor or a static
43  * method in that class with the {@code Deserializer} annotation. During serialization and
44  * deserialization of value objects of those classes, the {@code java.io.ObjectOutputStream} and
45  * {@code java.io.ObjectInputStream} will check for the presence of this annotation and when
46  * present, will relax the requirement of {@code writeReplace()} and {@code readObject()}
47  * methods in that class.
48  * <p>
49  * During deserialization, the constructor or the method annotated with the {@code Deserializer}
50  * will be invoked to create the value object instance from the stream.
51  * <p>
52  * {@code Deserializer} is a temporary measure for legacy serialization migration compatibility;
53  * future value object persistence would be handled by other mechanisms. The {@code Deserializer}
54  * annotation isn't for general purpose usage, even in the classes that belong to the JDK; it is
55  * meant to be used only by a very select few classes and the legacy serialization places several
56  * unspecified restrictions on its usage.
57  * <p>
58  * This annotation only takes effect for classes loaded by the boot loader. The presence of this
59  * annotation in classes loaded outside of the boot loader is ignored.
60  *
61  * @since 28
62  */
63 @Retention(RetentionPolicy.RUNTIME)
64 @Target(value = {CONSTRUCTOR, METHOD})
65 public @interface Deserializer {
66     /**
67      * The names of the serial fields that the constructor or static method,
68      * annotated with {@code Deserializer}, expects to be passed when invoked during
69      * deserialization of the value object from the stream. The serial field types are
70      * the corresponding parameter types.
71      */
72     String[] value();
73 }