1 % Migration of JDK Classes to Value Classes
2
3 ## Introduction
4
5 The Value Objects feature introduces value objects and migrates suitable classes
6 to value classes. This means that when preview features are enabled, different
7 class files are used for the migrated classes in the Java class library.
8
9 To accomplish this, a built JDK uses *preview-specific* files in `META-INF/preview`,
10 which overrides the regular files of the same name. For example,
11 `META-INF/preview/java/lang/Integer.class` overrides `java/lang/Integer.class`.
12
13 The JDK generates preview-specific source files (they may use preview language
14 features), compiles class files from them, and distributes these class files in
15 `META-INF/preview`.
16
17 ## The Build Process
18
19 ### The Custom Handling for the Value Objects JEP
20
21 The Value Objects JEP requires a few select classes in the `java.base` module
22 to become value classes when preview features are enabled.
23
24 The build of `java.base` module first creates the source code of those value
25 classes, done in
26 [`GensrcValueClasses.gmk`](../make/modules/java.base/gensrc/GensrcValueClasses.gmk).
27
28 1. A hardcoded list of regular source files are selected for preview-specific
29 generation.
30
31 2. Extract the content of each regular source file, search for any occurrences
32 of `/*value*/ class` or `/*value*/ record`, and replace with `value class`
33 or `value record`.
34
35 3. The replaced contents are written to the preview-specific generated files,
36 located in `support/gensrc-valueclasses/java.base/`. The regular source
37 files remain unchanged in their original locations.
38
39 4. The general preview source to binary build pipeline recognizes the
40 `support/gensrc-valueclasses/java.base/` directory as where the `java.base`
41 module places its preview-specific source files.
42
43 ### The General Preview Source to Binary Pipeline
44
45 Once the preview-specific source files are ready, they are picked up by the
46 build system into a fully automated pipeline handling all modules and all
47 outcome images.
48
49 1. The `GENERATED_PREVIEW_SUBDIRS` variable in [`make/common/Modules.gmk`](../make/common/Modules.gmk)
50 indicates where the source files are found.
51
52 2. For each module that has preview-specific source files, a goal is created
53 to compile these source files into class files.
54
55 3. The class files from each of these tasks reside in `support/preview/<module>`
56 for each module.
57
58 4. These preview-specific class files and other resources are copied to the
59 `META-INF/preview` directory of the regular output directory.
60
61 5. At run-time, jimage will pick up the preview-specific overrides from
62 `META-INF/preview` only when preview features are enabled.
63
64 6. The interim javac used by the build system cannot pick up the
65 preview-specific overrides; they must be supplied explicitly with the
66 following javac flag for every single module where overrides are significant:
67
68 ```
69 --patch-module <module>=$(SUPPORT_OUTPUTDIR)/preview/<module>
70 ```
71
72 See [`BuildMicroBenchmarks.gmk`](../make/test/BuildMicrobenchmark.gmk) for an example.
73
74 ### Non-Goals
75
76 The Value Objects JEP only plans to introduce value classes that are:
77
78 1. In the `java.base` module.
79
80 There's no plan to migrate other classes in other modules.
81
82 2. Migrated from existing classes.
83
84 These classes are available as identity classes when preview features are
85 disabled. There's no plan to introduce completely new value classes.
86
87 Support for other value classes would require significant changes to the build
88 system.
89
90 ## Testing
91
92 In addition to tests that require preview features to be enabled, tests that do
93 not depend on preview features wish to run with preview features enabled to
94 ensure compatibility:
95
96 1. Some tests wish to run against the Java SE class library with value classes.
97
98 The jtreg tests may be run with `JTREG=VM_OPTIONS=--enable-preview`.
99
100 2. Some tests wish to run against their own classes migrated to value classes.
101
102 The jtreg [VALUE_CLASS_PLUGIN](testing.html#VALUE_CLASS_PLUGIN) allows tests
103 to migrate their own classes to value classes when running with the plugin.
104
105 ## Wrapper Class Caches
106
107 Currently, wrapper class caches are retained even when preview features are
108 enabled to address performance losses. They have no semantic impact to value
109 objects.
110
111 In interpreter or C1 execution in Hotspot, allocations of a value object to the
112 heap as a full object with header happen when a value object is:
113
114 1. Loaded from a flat storage (field or array)
115 2. Created by a constructor
116 3. If C2 uses scalarized calling convention, at C2 to C1/interpreter calls and returns
117
118 Ideally, C2 can eliminate such allocations, but this does not work if the
119 resulting object is stored into references. Unfortunately, many uses of boxing
120 conversions store the resulting wrapper objects as references.
121
122 For the uses that store wrapper objects to references, if the boxing
123 conversion is:
124
125 1. Returning a value object from a flat cache array
126 2. Calling the value class constructor
127
128 Then we would have heap allocation on every single use.
129
130 To avoid the allocations, we fall back to returning a value object from a
131 reference cache array, from which the loaded reference is directly storable
132 into a destination that wants a reference without any allocation.
133
134 Since Hotspot may create flat arrays if an array of value objects is requested
135 by regular Java array creation mechanisms, we use `ValueClass.newReferenceArray`
136 to ensure we always create a reference cache array.
137
138 The cache array for value objects may be removed without notice if the
139 performance losses from allocations are no longer significant.
140
141 ## Editing This Document
142
143 If you want to contribute changes to this document, edit `doc/value-class-preview.md`
144 and then run `make update-build-docs` to generate the same changes in
145 `doc/value-class-preview.html`.
146
147 ---
148 # Override styles from the base CSS file that are not ideal for this document.
149 header-includes:
150 - '<style type="text/css">pre, code, tt { color: #1d6ae5; }</style>'
151 ---