changeset 53404:30b442c98ce4 intrinsics-project

Automatic merge with jep-334
author mcimadamore
date Tue, 13 Nov 2018 14:45:40 +0100
parents 161f50ac07ea 6d0439b38280
children d1bdbb71f3a0
files
diffstat 3 files changed, 39 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Mon Nov 12 11:35:33 2018 -0400
+++ b/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Tue Nov 13 14:45:40 2018 +0100
@@ -41,13 +41,17 @@
  * {@link Class} constant.
  *
  * <p>For common system types, including all the primitive types, there are
- * predefined {@linkplain ClassDesc} constants in {@link ConstantDescs}.  To create
- * a {@linkplain ClassDesc} for a class or interface type, use {@link #of} or
+ * predefined {@linkplain ClassDesc} constants in {@link ConstantDescs}.
+ * (The {@code java.lang.constant} APIs consider {@code void} to be a primitive type.)
+ * To create a {@linkplain ClassDesc} for a class or interface type, use {@link #of} or
  * {@link #ofDescriptor(String)}; to create a {@linkplain ClassDesc} for an array
  * type, use {@link #ofDescriptor(String)}, or first obtain a
  * {@linkplain ClassDesc} for the component type and then call the {@link #arrayType()}
  * or {@link #arrayType(int)} methods.
  *
+ * <p>Two {@linkplain ClassDesc} objects are considered {@link Object#equals(Object)}
+ * if they describe exactly the same type.
+ *
  * @apiNote In the future, if the Java language permits, {@linkplain ClassDesc}
  * may become a {@code sealed} interface, which would prohibit subclassing except
  * by explicitly permitted types.  Non-platform classes should not implement
@@ -62,9 +66,9 @@
                 TypeDescriptor.OfField<ClassDesc> {
 
     /**
-     * Create a {@linkplain ClassDesc} given the name of a class or interface
-     * type, such as {@code "java.lang.String"}.  (To create a descriptor for an
-     * array type, either use {@link #ofDescriptor(String)}
+     * Create a {@linkplain ClassDesc} for a class or interface type,
+     * given the name of the class or interface, such as {@code "java.lang.String"}.
+     * (To create a descriptor for an array type, either use {@link #ofDescriptor(String)}
      * or {@link #arrayType()}; to create a descriptor for a primitive type, use
      * {@link #ofDescriptor(String)} or use the predefined constants in
      * {@link ConstantDescs}).
@@ -81,11 +85,14 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} given a package name and an unqualified
-     * class name.
+     * Create a {@linkplain ClassDesc} for a class or interface type,
+     * given a package name and the unqualified (simple) name for the
+     * class or interface.
      *
-     * @param packageName the package name (dot-separated)
-     * @param className the unqualified class name
+     * @param packageName the package name (dot-separated); if the package
+     *                    name is the empty string, the class is considered to
+     *                    be in the unnamed package
+     * @param className the unqualified (simple) class name
      * @return a {@linkplain ClassDesc} describing the desired class
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the package name or class name are
@@ -101,7 +108,20 @@
     }
 
     /**
-     * Create a {@linkplain ClassDesc} given a descriptor string.
+     * Create a {@linkplain ClassDesc} given a descriptor string for a class,
+     * interface, array, or primitive type.
+     *
+     * @apiNote
+     *
+     * A field type descriptor string for a non-array type is either
+     * a one-letter code corresponding to a primitive type
+     * ({@code J,I,C,S,B,D,F,Z,V}), or the letter {@code L}, followed
+     * by the fully qualified binary name of a class, followed by {@code ;}.
+     * A field type descriptor for an array type is the character {@code [}
+     * followed by the field descriptor for the component type.  Examples of
+     * valid type descriptor strings include {@code Ljava/lang/String;}, {@code I},
+     * {@code [I}, {@code V}, {@code [Ljava/lang/String;}, etc.  See JVMS 4.3.2
+     * for more detail.
      *
      * @param descriptor a field descriptor string, as per JVMS 4.3.2
      * @return a {@linkplain ClassDesc} describing the desired class
@@ -221,13 +241,11 @@
      * a class or interface type.
      *
      * @return the package name, or the empty string if the class is in the
-     * default package
-     * @throws IllegalStateException if this {@linkplain ClassDesc} does not
-     * describe a class or interface type
+     * default package, or this {@linkplain ClassDesc} does not describe a class or interface type
      */
     default String packageName() {
         if (!isClassOrInterface())
-            throw new IllegalStateException("not a class or interface");
+            return "";
         String className = internalToBinary(ConstantUtils.dropFirstAndLastChar(descriptorString()));
         int index = className.lastIndexOf('.');
         return (index == -1) ? "" : className.substring(0, index);
--- a/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Mon Nov 12 11:35:33 2018 -0400
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Tue Nov 13 14:45:40 2018 +0100
@@ -46,6 +46,9 @@
  * {@link MethodHandle}.  A {@linkplain DirectMethodHandleDescImpl} corresponds to
  * a {@code Constant_MethodHandle_info} entry in the constant pool of a classfile.
  *
+ * <p>Two {@linkplain DirectMethodHandleDesc} objects are considered {@link Object#equals(Object)}
+ * if they describe the same invocation kind, owning class, method name, and method type.
+ *
  * @apiNote In the future, if the Java language permits, {@linkplain DirectMethodHandleDesc}
  * may become a {@code sealed} interface, which would prohibit subclassing except
  * by explicitly permitted types.  Non-platform classes should not implement
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Mon Nov 12 11:35:33 2018 -0400
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDesc.java	Tue Nov 13 14:45:40 2018 +0100
@@ -34,6 +34,10 @@
  * A <a href="package-summary.html#nominal">nominal descriptor</a> for a
  * {@linkplain MethodType} constant.
  *
+ * <p>Two {@linkplain MethodTypeDesc} objects are considered {@link Object#equals(Object)}
+ * if they have the same arity, their return types are equal, and each pair of corresponding
+ * parameter types are equal.
+ *
  * @apiNote In the future, if the Java language permits, {@linkplain MethodTypeDesc}
  * may become a {@code sealed} interface, which would prohibit subclassing except
  * by explicitly permitted types.  Non-platform classes should not implement