Code review request for 6628737: Specification of wrapper class valueOf static factories should require caching

[Joseph D. Darcy]

Hello.

Since JDK 5, to implement autoboxing, javac has relied on various static 
factory methods in the wrapper classes to perform the caching in the 
required range.  While the factories said they could cache, they did not 
state they would definitely cache in the required range given in JLSv3 
section 5.1.7:
http://java.sun.com/docs/books/jls/third_edition/html/conversions.html#5.1.7

Please review the patch below of my specification changes to mandate the 
caching.  The Boolean factory already mandates caching.  (For those 
interested in such things, tn parallel a ccc request has been filed to 
track the specification change.)

-Joe

--- old/src/share/classes/java/lang/Byte.java    2009-07-08 
18:38:11.000000000 -0700
+++ new/src/share/classes/java/lang/Byte.java    2009-07-08 
18:38:11.000000000 -0700
@@ -90,8 +90,8 @@
      * If a new {@code Byte} instance is not required, this method
      * should generally be used in preference to the constructor
      * {@link #Byte(byte)}, as this method is likely to yield
-     * significantly better space and time performance by caching
-     * frequently requested values.
+     * significantly better space and time performance since
+     * all byte values are cached.
      *
      * @param  b a byte value.
      * @return a {@code Byte} instance representing {@code b}.
--- old/src/share/classes/java/lang/Character.java    2009-07-08 
18:38:13.000000000 -0700
+++ new/src/share/classes/java/lang/Character.java    2009-07-08 
18:38:13.000000000 -0700
@@ -2571,6 +2571,10 @@
      * significantly better space and time performance by caching
      * frequently requested values.
      *
+     * This method will always cache values in the range '\u0000'
+     * to '\u007f'", inclusive, and may cache other values outside
+     * of this range.
+     *
      * @param  c a char value.
      * @return a <tt>Character</tt> instance representing <tt>c</tt>.
      * @since  1.5
--- old/src/share/classes/java/lang/Integer.java    2009-07-08 
18:38:14.000000000 -0700
+++ new/src/share/classes/java/lang/Integer.java    2009-07-08 
18:38:14.000000000 -0700
@@ -638,6 +638,9 @@
      * to yield significantly better space and time performance by
      * caching frequently requested values.
      *
+     * This method will always cache values in the range -128 to 127,
+     * inclusive, and may cache other values outside of this range.
+     *
      * @param  i an {@code int} value.
      * @return an {@code Integer} instance representing {@code i}.
      * @since  1.5
--- old/src/share/classes/java/lang/Long.java    2009-07-08 
18:38:16.000000000 -0700
+++ new/src/share/classes/java/lang/Long.java    2009-07-08 
18:38:16.000000000 -0700
@@ -560,6 +560,11 @@
      * significantly better space and time performance by caching
      * frequently requested values.
      *
+     * Note that unlike the {@linkplain Integer#valueOf(int)
+     * corresponding method} in the {@code Integer} class, this method
+     * is <em>not</em> required to cache values within a particular
+     * range.
+     *
      * @param  l a long value.
      * @return a {@code Long} instance representing {@code l}.
      * @since  1.5
--- old/src/share/classes/java/lang/Short.java    2009-07-08 
18:38:17.000000000 -0700
+++ new/src/share/classes/java/lang/Short.java    2009-07-08 
18:38:17.000000000 -0700
@@ -219,6 +219,9 @@
      * significantly better space and time performance by caching
      * frequently requested values.
      *
+     * This method will always cache values in the range -128 to 127,
+     * inclusive, and may cache other values outside of this range.
+     *
      * @param  s a short value.
      * @return a {@code Short} instance representing {@code s}.
      * @since  1.5