Add toolchain type for Java bootstrap runtime

The `bootclasspath` rule in `rules_java` will soon use this toolchain type instead of the regular Java runtime toolchain type, which naturally carries a constraint on the target platform.

Also adds more detailed explanations of the now three Java toolchain types.

Work towards bazelbuild#17085
Work towards bazelbuild#18265
Work towards bazelbuild/rules_java#64
Split off from bazelbuild#18262

Closes bazelbuild#18841.

PiperOrigin-RevId: 545756139
Change-Id: Ib9dd7a1c20c32315375722d6a023a89859daea9c

tools/jdk/BUILD.tools

@@ -18,20 +18,48 @@ load("//tools/python:private/defs.bzl", "py_binary", "py_test")
 
 package(default_visibility = ["//visibility:public"])
 
-# Used to distinguish toolchains used for Java development, ie the JavaToolchainProvider.
-toolchain_type(name = "toolchain_type")
+load("@rules_python//python:defs.bzl", "py_binary", "py_test")
 
-# Used to distinguish toolchains used for Java execution, ie the JavaRuntimeInfo.
-toolchain_type(name = "runtime_toolchain_type")
+exports_files([
+    "BUILD.java_tools",
+    "java_stub_template.txt",
+])
+
+# A single binary distribution of a JDK (e.g., OpenJDK 17 for Windows arm64) provides three
+# different types of toolchains from the perspective of Bazel:
 
-# Points to toolchain[":runtime_toolchain_type"] (was :legacy_current_java_runtime)
-java_runtime_alias(name = "current_java_runtime")
+# The compilation toolchain, which provides the Java runtime used to execute the Java compiler, as
+# well as various helper tools and settings.
+#
+# Toolchains of this type typically have constraints on the execution platform so that their Java
+# runtime can run the compiler, but not on the target platform as Java compilation outputs are
+# platform independent.
+#
+# Obtain the associated JavaToolchainInfo via:
+#   ctx.toolchains["@bazel_tools//tools/jdk:toolchain_type"].java
+toolchain_type(name = "toolchain_type")
 
-# Host configuration of ":current_java_runtime"
-java_host_runtime_alias(name = "current_host_java_runtime")
+# The Java runtime that executable Java compilation outputs (e.g., java_binary with
+# create_executable = True) will run on.
+#
+# Toolchains of this type typically have constraints on the target platform so that the runtime's
+# native 'java' binary can be run there, but not on the execution platform as building an executable
+# Java target only requires copying or symlinking the runtime, which can be done on any platform.
+#
+# Obtain the associated JavaRuntimeInfo via:
+#   ctx.toolchains["@bazel_tools//tools/jdk:runtime_toolchain_type"].java_runtime
+toolchain_type(name = "runtime_toolchain_type")
 
-# Points to toolchain[":toolchain_type"] (was :legacy_current_java_toolchain)
-java_toolchain_alias(name = "current_java_toolchain")
+# The Java runtime to extract the bootclasspath from that is then used to compile Java sources.
+#
+# As the bootclasspath is platform independent, toolchains of this type may have no constraints.
+# Purely as an optimization to prevent unnecessary fetches of remote runtimes for other
+# architectures, toolchains of this type may have constraints on the execution platform that match
+# those on the corresponding compilation toolchain.
+#
+# Toolchains of this type are only consumed internally by the bootclasspath rule and should not be
+# accessed from Starlark.
+toolchain_type(name = "bootstrap_runtime_toolchain_type")
 
 # Aliases value of --plugins flag as a JavaPluginInfo
 java_plugins_flag_alias(