8317279: Standard library implementation of value classes and objects

.github/workflows/main.yml

@@ -170,6 +170,12 @@ jobs:
                 echo 'true'
                 return
               fi
+
+              # ...same for project branch
+              if [[ $BRANCH == "lworld" ]]; then
+                echo 'true'
+                return
+              fi
             fi
 
             echo 'false'

doc/testing.html

@@ -465,6 +465,44 @@ <h4 id="test_thread_factory">TEST_THREAD_FACTORY</h4>
 <code>test/jtreg_test_thread_factory/</code> directory. This class gets
 compiled during the test image build. The implementation of the Virtual
 class creates a new virtual thread for executing each test class.</p>
+<h4 id="value_class_plugin">VALUE_CLASS_PLUGIN</h4>
+<p>Enables the <code>ValueClassPlugin</code> javac plugin when compiling
+and running JTReg tests. This is a <strong>temporary mode</strong>
+intended for use while value classes (JEP 401) are a preview feature.
+The long-term plan is to replace classes annotated with
+<code>@jdk.test.lib.valueclass.AsValueClass</code> with plain
+<code>value class</code> declarations once value classes are
+finalized.</p>
+<p>In the meantime, this mode allows test sources to compile and run as
+either value classes or regular identity classes without source-level
+changes.</p>
+<p>When set to any non-empty value, the following options are appended to
+every JTReg invocation:</p>
+<ul>
+<li><code>-cpa:&lt;valueClassPlugin.jar&gt;</code> — appends the plugin
+JAR to the compile-time classpath (only when the JAR is present in the
+test image under
+<code>jtreg_value_class_plugin/valueClassPlugin.jar</code>).</li>
+<li><code>-vmoption:--enable-preview</code> — enables JVM preview
+features at runtime.</li>
+<li><code>-javacoption:-XDaccessInternalAPI</code> — grants the compiler
+access to internal APIs required by the plugin.</li>
+<li><code>-javacoption:--source &lt;version&gt; --enable-preview</code>
+— enables preview language features at compile time.</li>
+<li><code>-javacoption:-Xplugin:ValueClassPlugin</code> — activates the
+plugin.</li>
+</ul>
+<p>The plugin scans each compilation unit after parsing and converts any
+class annotated with
+<code>@jdk.test.lib.valueclass.AsValueClass</code> into a value class by
+setting the internal <code>VALUE_CLASS</code> modifier flag and clearing
+the <code>IDENTITY_TYPE</code> flag. This transformation only takes
+effect when <code>--enable-preview</code> is active; without it the
+annotation is a no-op and the class compiles as an ordinary identity
+class, so the same test source can exercise both code paths.</p>
+<p>Example:</p>
+<pre><code>$ make test TEST=jdk_lang JTREG="VALUE_CLASS_PLUGIN=true"
+</code></pre>
 <h4 id="jvmti_stress_agent">JVMTI_STRESS_AGENT</h4>
 <p>Executes JTReg tests with JVM TI stress agent. The stress agent is
 the part of test library and located in

doc/testing.md

@@ -403,6 +403,42 @@ the `test/jtreg_test_thread_factory/` directory. This class gets compiled
 during the test image build. The implementation of the Virtual class creates a
 new virtual thread for executing each test class.
 
+#### VALUE_CLASS_PLUGIN
+
+Enables the `ValueClassPlugin` javac plugin when compiling and running JTReg
+tests. This is a **temporary mode** intended for use while value classes
+(JEP 401) are a preview feature. The long-term plan is to replace classes
+annotated with `@jdk.test.lib.valueclass.AsValueClass` with plain
+`value class` declarations once value classes are finalized.
+
+In the meantime, this mode allows test sources to compile and run as either
+value classes or regular identity classes without source-level changes.
+
+When set to any non-empty value, the following options are appended to every
+JTReg invocation:
+
+* `-cpa:<valueClassPlugin.jar>` — appends the plugin JAR to the compile-time
+  classpath (only when the JAR is present in the test image under
+  `jtreg_value_class_plugin/valueClassPlugin.jar`).
+* `-vmoption:--enable-preview` — enables JVM preview features at runtime.
+* `-javacoption:-XDaccessInternalAPI` — grants the compiler access to internal
+  APIs required by the plugin.
+* `-javacoption:--source <version> --enable-preview` — enables preview language
+  features at compile time.
+* `-javacoption:-Xplugin:ValueClassPlugin` — activates the plugin.
+
+The plugin scans each compilation unit after parsing and converts any class
+annotated with `@jdk.test.lib.valueclass.AsValueClass` into a value class by
+setting the internal `VALUE_CLASS` modifier flag and clearing the
+`IDENTITY_TYPE` flag. This transformation only takes effect when
+`--enable-preview` is active; without it the annotation is a no-op and the
+class compiles as an ordinary identity class, so the same test source can
+exercise both code paths.
+
+Example:
+
+    $ make test TEST=jdk_lang JTREG="VALUE_CLASS_PLUGIN=true"
+
 #### JVMTI_STRESS_AGENT
 
 Executes JTReg tests with JVM TI stress agent. The stress agent is the part of

make/CompileJavaModules.gmk

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2014, 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2014, 2026, 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
@@ -30,6 +30,8 @@ include MakeFileStart.gmk
 include JavaCompilation.gmk
 include Modules.gmk
 
+include CopyFiles.gmk
+
 ################################################################################
 # If this is an imported module that has prebuilt classes, only compile
 # module-info.java.
@@ -98,13 +100,15 @@ endif
 ################################################################################
 # Setup the main compilation
 
+COMPILATION_OUTPUTDIR := $(if $($(MODULE)_BIN), $($(MODULE)_BIN), $(JDK_OUTPUTDIR)/modules)
+
 $(eval $(call SetupJavaCompilation, $(MODULE), \
     SMALL_JAVA := false, \
     MODULE := $(MODULE), \
     SRC := $(wildcard $(MODULE_SRC_DIRS)), \
     INCLUDES := $(JDK_USER_DEFINED_FILTER), \
     FAIL_NO_SRC := $(FAIL_NO_SRC), \
-    BIN := $(if $($(MODULE)_BIN), $($(MODULE)_BIN), $(JDK_OUTPUTDIR)/modules), \
+    BIN := $(COMPILATION_OUTPUTDIR), \
     HEADERS := $(SUPPORT_OUTPUTDIR)/headers, \
     CREATE_API_DIGEST := true, \
     CLEAN := $(CLEAN), \
@@ -126,6 +130,67 @@ $(eval $(call SetupJavaCompilation, $(MODULE), \
 
 TARGETS += $($(MODULE))
 
+################################################################################
+# Setup compilation for preview classes in the module
+# TBD: When $(DOCLINT) was included there was an NPE in JavacTypes.getOverriddenMethods
+
+# Directory and file name suffix for jar file containing preview classes/resources.
+PREVIEW_CLASSES_LABEL := preview
+# Module relative path in which preview classes/resources are placed.
+PREVIEW_PATH := META-INF/preview
+
+MODULE_PREVIEW_SRC_DIRS := $(call FindModulePreviewSrcDirs, $(MODULE))
+MODULE_PREVIEW_SOURCEPATH := $(call GetModulePreviewSrcPath)
+ifneq ($(MODULE_PREVIEW_SRC_DIRS),)
+  # Compile preview classes into a separate directory, and then copy into the
+  # correct output path location. We cannot compile directly into the desired
+  # directory because it's the compiler which creates the original
+  # '<module>/<classpath>/...' hierarchy.
+  PREVIEW_OUTPUTDIR := $(SUPPORT_OUTPUTDIR)/$(PREVIEW_CLASSES_LABEL)
+  PATCH_COMMAND := $(MODULE)=$(call strip, $(COMPILATION_OUTPUTDIR)/$(MODULE))
+
+  $(eval $(call SetupJavaCompilation, $(MODULE)-$(PREVIEW_CLASSES_LABEL), \
+      SMALL_JAVA := false, \
+      MODULE := $(MODULE), \
+      SRC := $(wildcard $(MODULE_PREVIEW_SRC_DIRS)), \
+      INCLUDES := $(JDK_USER_DEFINED_FILTER), \
+      FAIL_NO_SRC := $(FAIL_NO_SRC), \
+      BIN := $(PREVIEW_OUTPUTDIR)/, \
+      HEADERS := $(SUPPORT_OUTPUTDIR)/headers, \
+      DISABLED_WARNINGS := $(DISABLED_WARNINGS_java) preview, \
+      EXCLUDES := $(EXCLUDES), \
+      EXCLUDE_FILES := $(EXCLUDE_FILES), \
+      KEEP_ALL_TRANSLATIONS := $(KEEP_ALL_TRANSLATIONS), \
+      DEPENDS := $($(MODULE)), \
+      JAVAC_FLAGS := \
+          $(JAVAC_FLAGS) \
+          --module-source-path $(MODULE_PREVIEW_SOURCEPATH) \
+          --module-path $(MODULEPATH) \
+          --patch-module $(PATCH_COMMAND) \
+          --system none \
+          --enable-preview -source $(JDK_SOURCE_TARGET_VERSION), \
+  ))
+
+  # Don't add '$($(MODULE)-$(PREVIEW_CLASSES_LABEL))' to TARGETS (it's transient).
+  # The 'preview' target below depends on it, and that's the non-transient
+  # result we care about.
+
+  # Copy compiled output from "$(PREVIEW_OUTPUTDIR)/$(MODULE)/<classpath>/..."
+  # to "$(COMPILATION_OUTPUTDIR)/$(MODULE)/$(PREVIEW_PATH)/<classpath>/...".
+  MOD_SRC := $(PREVIEW_OUTPUTDIR)/$(MODULE)
+  MOD_DST := $(COMPILATION_OUTPUTDIR)/$(MODULE)
+
+  # NOTE: We cannot use '$(CP) -R $(MOD_SRC)/*/ ...' to select sub-directories (it
+  # does not work on MacOS/BSD). Use 'filter-out' to explicitly exclude marker files.
+  $(MOD_DST)/_the.$(MODULE).preview: $($(MODULE)-$(PREVIEW_CLASSES_LABEL))
+		$(RM) -r $(@D)/$(PREVIEW_PATH)
+		$(MKDIR) -p $(@D)/$(PREVIEW_PATH)
+		$(CP) -R $(filter-out $(MOD_SRC)/_%, $(wildcard $(MOD_SRC)/*)) $(@D)/$(PREVIEW_PATH)
+		$(TOUCH) $@
+
+  TARGETS += $(MOD_DST)/_the.$(MODULE).preview
+endif
+
 # Declare dependencies between java compilations of different modules.
 # Since the other modules are declared in different invocations of this file,
 # use the macro to find the correct target file to depend on.

make/Docs.gmk

@@ -93,9 +93,10 @@ JAVADOC_DISABLED_DOCLINT_WARNINGS := missing
 JAVADOC_DISABLED_DOCLINT_PACKAGES := org.w3c.* javax.smartcardio
 
 # The initial set of options for javadoc
-JAVADOC_OPTIONS := -use -keywords -notimestamp \
+JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
     -serialwarn -encoding utf-8 -docencoding utf-8 -breakiterator \
     -splitIndex --system none -javafx --expand-requires transitive \
+    --enable-preview -source $(JDK_SOURCE_TARGET_VERSION) \
     --override-methods=summary
 
 # The reference options must stay stable to allow for comparisons across the

make/Images.gmk

@@ -138,74 +138,79 @@ CDS_DUMP_FLAGS = -Xmx128M -Xms128M
 #
 # Param1 - VM variant (e.g., server, client, zero, ...)
 # Param2 - _nocoops, _nocoh, _nocoops_nocoh, or empty
+# Param3 - _preview, or empty
 define CreateCDSArchive
   $1_$2_COOPS_OPTION := $(if $(findstring _nocoops, $2),-XX:-UseCompressedOops)
   # enable and also explicitly disable coh as needed.
   ifeq ($(call isTargetCpuBits, 64), true)
     $1_$2_NOCOH_OPTION := -XX:+UnlockExperimentalVMOptions \
                         $(if $(findstring _nocoh, $2),-XX:-UseCompactObjectHeaders,-XX:+UseCompactObjectHeaders)
   endif
-  $1_$2_DUMP_EXTRA_ARG := $$($1_$2_COOPS_OPTION) $$($1_$2_NOCOH_OPTION)
-  $1_$2_DUMP_TYPE      := $(if $(findstring _nocoops, $2),-NOCOOPS,)$(if $(findstring _nocoh, $2),-NOCOH,)
+  $1_$2_$3_DUMP_EXTRA_ARG := $$($1_$2_COOPS_OPTION) $$($1_$2_NOCOH_OPTION) $(if $(findstring _preview, $3), --enable-preview,)
+  $1_$2_$3_DUMP_TYPE      := $(if $(findstring _nocoops, $2),-NOCOOPS,)$(if $(findstring _nocoh, $2),-NOCOH,)$(if $(findstring _preview, $3),-PREVIEW,)
 
-  $1_$2_CDS_DUMP_FLAGS := $(CDS_DUMP_FLAGS) $(if $(filter g1gc, $(JVM_FEATURES_$1)), -XX:+UseG1GC)
+  $1_$2_$3_CDS_DUMP_FLAGS := $(CDS_DUMP_FLAGS) $(if $(filter g1gc, $(JVM_FEATURES_$1)), -XX:+UseG1GC)
 
   ifeq ($(OPENJDK_TARGET_OS), windows)
-    $1_$2_CDS_ARCHIVE := bin/$1/classes$2.jsa
+    $1_$2_$3_CDS_ARCHIVE := bin/$1/classes$2$3.jsa
   else
-    $1_$2_CDS_ARCHIVE := lib/$1/classes$2.jsa
+    $1_$2_$3_CDS_ARCHIVE := lib/$1/classes$2$3.jsa
   endif
 
   ifneq ($(COMPARE_BUILD), )
     DEBUG_CDS_ARCHIVE := true
   endif
 
   ifeq ($(DEBUG_CDS_ARCHIVE), true)
-    $1_$2_CDS_DUMP_FLAGS += -Xlog:aot+map*=trace:file=$$(JDK_IMAGE_DIR)/$$($1_$2_CDS_ARCHIVE).cdsmap:none:filesize=0
+    $1_$2_$3_CDS_DUMP_FLAGS += -Xlog:aot+map*=trace:file=$$(JDK_IMAGE_DIR)/$$($1_$2_$3_CDS_ARCHIVE).cdsmap:none:filesize=0
   endif
 
-  $$(eval $$(call SetupExecute, $1_$2_gen_cds_archive_jdk, \
-      WARN := Creating CDS$$($1_$2_DUMP_TYPE) archive for jdk image for $1, \
-      INFO := Using CDS flags for $1: $$($1_$2_CDS_DUMP_FLAGS), \
+  $$(eval $$(call SetupExecute, $1_$2_$3_gen_cds_archive_jdk, \
+      WARN := Creating CDS$$($1_$2_$3_DUMP_TYPE) archive for jdk image for $1, \
+      INFO := Using CDS flags for $1: $$($1_$2_$3_CDS_DUMP_FLAGS), \
       DEPS := $$(jlink_jdk), \
-      OUTPUT_FILE := $$(JDK_IMAGE_DIR)/$$($1_$2_CDS_ARCHIVE), \
+      OUTPUT_FILE := $$(JDK_IMAGE_DIR)/$$($1_$2_$3_CDS_ARCHIVE), \
       SUPPORT_DIR := $$(JDK_IMAGE_SUPPORT_DIR), \
       COMMAND := $$(FIXPATH) $$(JDK_IMAGE_DIR)/bin/java -Xshare:dump \
-          -XX:SharedArchiveFile=$$(JDK_IMAGE_DIR)/$$($1_$2_CDS_ARCHIVE) \
-          -$1 $$($1_$2_DUMP_EXTRA_ARG) $$($1_$2_CDS_DUMP_FLAGS) $$(LOG_INFO), \
+          -XX:SharedArchiveFile=$$(JDK_IMAGE_DIR)/$$($1_$2_$3_CDS_ARCHIVE) \
+          -$1 $$($1_$2_$3_DUMP_EXTRA_ARG) $$($1_$2_$3_CDS_DUMP_FLAGS) $$(LOG_INFO), \
   ))
 
-  JDK_TARGETS += $$($1_$2_gen_cds_archive_jdk)
+  JDK_TARGETS += $$($1_$2_$3_gen_cds_archive_jdk)
 
-  $$(eval $$(call SetupExecute, $1_$2_gen_cds_archive_jre, \
-      WARN := Creating CDS$$($1_$2_DUMP_TYPE) archive for jre image for $1, \
-      INFO := Using CDS flags for $1: $$($1_$2_CDS_DUMP_FLAGS), \
+  $$(eval $$(call SetupExecute, $1_$2_$3_gen_cds_archive_jre, \
+      WARN := Creating CDS$$($1_$2_$3_DUMP_TYPE) archive for jre image for $1, \
+      INFO := Using CDS flags for $1: $$($1_$2_$3_CDS_DUMP_FLAGS), \
       DEPS := $$(jlink_jre), \
-      OUTPUT_FILE := $$(JRE_IMAGE_DIR)/$$($1_$2_CDS_ARCHIVE), \
+      OUTPUT_FILE := $$(JRE_IMAGE_DIR)/$$($1_$2_$3_CDS_ARCHIVE), \
       SUPPORT_DIR := $$(JRE_IMAGE_SUPPORT_DIR), \
       COMMAND := $$(FIXPATH) $$(JRE_IMAGE_DIR)/bin/java -Xshare:dump \
-          -XX:SharedArchiveFile=$$(JRE_IMAGE_DIR)/$$($1_$2_CDS_ARCHIVE) \
-          -$1 $$($1_$2_DUMP_EXTRA_ARG) $$($1_$2_CDS_DUMP_FLAGS) $$(LOG_INFO), \
+          -XX:SharedArchiveFile=$$(JRE_IMAGE_DIR)/$$($1_$2_$3_CDS_ARCHIVE) \
+          -$1 $$($1_$2_$3_DUMP_EXTRA_ARG) $$($1_$2_$3_CDS_DUMP_FLAGS) $$(LOG_INFO), \
   ))
 
-  JRE_TARGETS += $$($1_$2_gen_cds_archive_jre)
+  JRE_TARGETS += $$($1_$2_$3_gen_cds_archive_jre)
 endef
 
 ifeq ($(BUILD_CDS_ARCHIVE), true)
   $(foreach v, $(JVM_VARIANTS), \
-    $(eval $(call CreateCDSArchive,$v,)) \
+    $(eval $(call CreateCDSArchive,$v,,)) \
+    $(eval $(call CreateCDSArchive,$v,,_preview)) \
   )
 
   ifeq ($(call isTargetCpuBits, 64), true)
     $(foreach v, $(JVM_VARIANTS), \
-      $(eval $(call CreateCDSArchive,$v,_nocoops)) \
+      $(eval $(call CreateCDSArchive,$v,_nocoops,)) \
+      $(eval $(call CreateCDSArchive,$v,_nocoops,_preview)) \
     )
     ifeq ($(BUILD_CDS_ARCHIVE_NOCOH), true)
       $(foreach v, $(JVM_VARIANTS), \
         $(eval $(call CreateCDSArchive,$v,_nocoh)) \
+        $(eval $(call CreateCDSArchive,$v,_nocoh,_preview)) \
       )
       $(foreach v, $(JVM_VARIANTS), \
         $(eval $(call CreateCDSArchive,$v,_nocoops_nocoh)) \
+        $(eval $(call CreateCDSArchive,$v,_nocoops_nocoh,_preview)) \
       )
     endif
   endif

make/Main.gmk

@@ -794,6 +794,20 @@ ifeq ($(BUILD_JTREG_TEST_THREAD_FACTORY), true)
   ))
 endif
 
+# Builds the value class plugin jtreg extension (JEP 401)
+$(eval $(call SetupTarget, build-test-value-class-plugin, \
+    MAKEFILE := test/BuildJtregValueClassPlugin, \
+    TARGET := build, \
+    DEPS := interim-langtools exploded-image, \
+))
+
+# Copies the value class plugin into the test image
+$(eval $(call SetupTarget, test-image-value-class-plugin, \
+    MAKEFILE := test/BuildJtregValueClassPlugin, \
+    TARGET := images, \
+    DEPS := build-test-value-class-plugin, \
+))
+
 $(eval $(call SetupTarget, build-microbenchmark, \
     MAKEFILE := test/BuildMicrobenchmark, \
     DEPS := interim-langtools exploded-image build-test-lib, \
@@ -1310,6 +1324,8 @@ ifeq ($(BUILD_JTREG_TEST_THREAD_FACTORY), true)
   test-image: test-image-test-thread-factory
 endif
 
+test-image: test-image-value-class-plugin
+
 ifneq ($(JMH_CORE_JAR), )
   test-image: build-microbenchmark
 endif

make/MainSupport.gmk

@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2011, 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2011, 2026, 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
@@ -107,6 +107,7 @@ define Clean-java
 	@$(PRINTF) "Cleaning java %s..." "$(if $1,for $(strip $1) )"
 	@$(ECHO) "" $(LOG_DEBUG)
 	$(RM) -r $(JDK_OUTPUTDIR)/modules/$(strip $1)
+	$(RM) -r $(SUPPORT_OUTPUTDIR)/preview/$(strip $1)
 	$(RM) -r $(SUPPORT_OUTPUTDIR)/special_classes/$(strip $1)
 	$(ECHO) " done"
 	$(PRINTF) "Cleaning headers %s..." "$(if $1,for $(strip $1) )"