Summary

Update the com.sun.management.OperatingSystemMXBean specification to make it clear that it reports values based on the current operating environment - such as a container environment.

Problem

When executing in a container, or other virtualized operating environment, we would like to know information specific to that environment - such as the amount of memory that is available to the JVM process. The existing com.sun.management.OperatingSystemMXBean interface was designed with only a native operating system in mind and its API reflects that in places. For example, some methods are named and specified in terms of "physical memory" as reported by the operating system. The notion of "physical memory" is out-dated in such operating environments, where we want to know the amount of memory available to the JVM process; further, information about "physical memory" may be unobtainable in these environments.

Solution

Clarify that the OperatingSystemMXBean reports values specific to the actual operating environment of the JVM process, whether native OS or virtualized OS, or container etc.

When executing in a container, or other virtualized operating environment, the following OperatingSystemMXBean methods return container specific information, if available. Otherwise, they return host specific data:

• getFreePhysicalMemorySize()
• getTotalPhysicalMemorySize()
• getFreeSwapSpaceSize()
• getTotalSwapSpaceSize()
• getSystemCpuLoad()

By doing this we provide consistency between what the JVM is actually using in a container, or other virtualized operating environment, and the OperatingSystemMXBean.

This CSR differs from the CSR of JDK 14 in the following way. No new methods in OperatingSystemMXBean are being introduced. Specifically, these methods won't be introduced.

• getFreeMemorySize()
• getTotalMemorySize()
• getCpuLoad()

Instead, only the Javadoc update will be done to clarify the changed behavior of com.sun.management.OperatingSystemMXBean.

Specification

        diff --git a/src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java b/src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java
--- a/src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java
+++ b/src/jdk.management/share/classes/com/sun/management/OperatingSystemMXBean.java
@@ -30,6 +30,12 @@
  * on which the Java virtual machine is running.
  *
  * <p>
+ * This interface provides information about the operating environment
+ * on which the Java virtual machine is running. That might be a native
+ * operating system, a virtualized operating system environment, or a
+ * container-managed environment.
+ *
+ * <p>
  * The {@code OperatingSystemMXBean} object returned by
  * {@link java.lang.management.ManagementFactory#getOperatingSystemMXBean()}
  * is an instance of the implementation class of this interface