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. Replace methods that refer to "physical" or "system" values with ones that do not, by adding new (better-named) methods, deprecating the existing ones, and require that the existing methods return the same value as the new methods.

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.

Define new methods in the `OperatingSystemMXBean` to replace those that are expressed in terms of "physical" or "system" values; deprecate the existing methods and update them to return the same values as the new methods e.g:

 - `getFreeMemorySize()`
 - `getTotalMemorySize()`
 -  `getCpuLoad()`

By doing this we both provide the desired, useful, information to existing users of the API, whilst providing an updated API for them to migrate to, which avoids potentially confusing references to "physical" and "system" values.

Specification
-------------

    *** 28,37 ****
    --- 28,43 ----
      /**
       * Platform-specific management interface for the operating system
       * 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
       * or {@link UnixOperatingSystemMXBean} interface depending on
       * its underlying operating system.
    *** 80,117 ****
    --- 86,176 ----
          public long getProcessCpuTime();
      
          /**
           * Returns the amount of free physical memory in bytes.
           *
    +      * @deprecated Use {@link #getFreeMemorySize()} instead of
    +      * this historically named method.
    +      *
    +      * @implSpec This implementation must return the same value
    +      * as {@link #getFreeMemorySize()}.
    +      *
           * @return the amount of free physical memory in bytes.
           */
    +     @Deprecated(since="14")
          public default long getFreePhysicalMemorySize() { return getFreeMemorySize(); }
      
          /**
    +      * Returns the amount of free memory in bytes.
    +      *
    +      * @return the amount of free memory in bytes.
    +      * @since 14
    +      */
    +     public long getFreeMemorySize();
    + 
    +     /**
           * Returns the total amount of physical memory in bytes.
           *
    +      * @deprecated Use {@link #getMemorySize()} instead of
    +      * this historically named method.
    +      *
    +      * @implSpec This implementation must return the same value
    +      * as {@link #getMemorySize()}.
    +      *
           * @return the total amount of physical memory in  bytes.
           */
    +     @Deprecated(since="14")
          public default long getTotalPhysicalMemorySize() { return getTotalMemorySize(); }
      
          /**
    +      * Returns the total amount of memory in bytes.
    +      *
    +      * @return the total amount of memory in  bytes.
    +      * @since 14
    +      */
    +     public long getTotalMemorySize();
    + 
    +     /**
           * Returns the "recent cpu usage" for the whole system. This value is a
           * double in the [0.0,1.0] interval. A value of 0.0 means that all CPUs
           * were idle during the recent period of time observed, while a value
           * of 1.0 means that all CPUs were actively running 100% of the time
           * during the recent period being observed. All values betweens 0.0 and
           * 1.0 are possible depending of the activities going on in the system.
           * If the system recent cpu usage is not available, the method returns a
           * negative value.
           *
    +      * @deprecated Use {@link #getCpuLoad()} instead of
    +      * this historically named method.
    +      *
    +      * @implSpec This implementation must return the same value
    +      * as {@link #getCpuLoad()}.
    +      *
           * @return the "recent cpu usage" for the whole system; a negative
           * value if not available.
           * @since   1.7
           */
    +     @Deprecated(since="14")
          public default double getSystemCpuLoad() { return getCpuLoad(); }
      
          /**
    +      * Returns the "recent cpu usage" for the operating environment. This value
    +      * is a double in the [0.0,1.0] interval. A value of 0.0 means that all CPUs
    +      * were idle during the recent period of time observed, while a value
    +      * of 1.0 means that all CPUs were actively running 100% of the time
    +      * during the recent period being observed. All values betweens 0.0 and
    +      * 1.0 are possible depending of the activities going on.
    +      * If the recent cpu usage is not available, the method returns a
    +      * negative value.
    +      *
    +      * @return the "recent cpu usage" for the whole operating environment;
    +      * a negative value if not available.
    +      * @since 14
    +      */
    +     public double getCpuLoad();
    +