changeset 53474:edca251bb4de jep-334

More spec updates based on CSR feedback
author briangoetz
date Tue, 27 Nov 2018 14:56:13 -0500
parents 66e1b5ed2833
children 86d27ae2cc27 c5905f5d6d45 03bb8789f5a1
files src/java.base/share/classes/java/lang/constant/ClassDesc.java src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java
diffstat 8 files changed, 41 insertions(+), 120 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ClassDesc.java	Tue Nov 27 14:56:13 2018 -0500
@@ -141,10 +141,6 @@
      * Create a {@linkplain ClassDesc} for an array type whose component type
      * is described by this {@linkplain ClassDesc}.
      *
-     * @implSpec
-     * The default implementation returns the result of calling {@link #arrayType(int)},
-     * with rank equals to 1
-     *
      * @return a {@linkplain ClassDesc} describing the array type
      */
     default ClassDesc arrayType() {
@@ -155,14 +151,6 @@
      * Create a {@linkplain ClassDesc} for an array type of the specified rank,
      * whose component type is described by this {@linkplain ClassDesc}.
      *
-     * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     if (rank <= 0)
-     *         throw new IllegalArgumentException("rank: " + rank);
-     *     return ClassDesc.ofDescriptor("[".repeat(rank) + descriptorString());
-     * }</pre>
-     *
      * @param rank the rank of the array
      * @return a {@linkplain ClassDesc} describing the array type
      * @throws IllegalArgumentException if the rank is zero or negative
@@ -177,15 +165,6 @@
      * Create a {@linkplain ClassDesc} for an inner class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
-     * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     validateMemberName(innerName);
-     *     if (!isClassOrInterface())
-     *         throw new IllegalStateException("Outer class is not a class or interface type");
-     *     return ClassDesc.ofDescriptor(String.format("%s$%s;", dropLastChar(descriptorString()), innerName));
-     * }</pre>
-     *
      * @param innerName the unqualified name of the inner class
      * @return a {@linkplain ClassDesc} describing the inner class
      * @throws NullPointerException if any argument is {@code null}
@@ -203,16 +182,6 @@
      * Create a {@linkplain ClassDesc} for an inner class of the class or
      * interface type described by this {@linkplain ClassDesc}.
      *
-     * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     if (!isClassOrInterface())
-     *         throw new IllegalStateException("Outer class is not a class or interface type");
-     *     return moreInnerNames.length == 0
-     *            ? inner(firstInnerName)
-     *            : inner(firstInnerName + Stream.of(moreInnerNames).collect(joining("$", "$", "")));
-     * }</pre>
-     *
      * @param firstInnerName the unqualified name of the first level of inner class
      * @param moreInnerNames the unqualified name(s) of the remaining levels of
      *                       inner class
@@ -232,10 +201,6 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes an array type.
      *
-     * @implSpec
-     * The default implementation returns {@code true} if the descriptor
-     * starts with: {@code '['}
-     *
      * @return whether this {@linkplain ClassDesc} describes an array type
      */
     default boolean isArray() {
@@ -245,10 +210,6 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes a primitive type.
      *
-     * @implSpec
-     * The default implementation returns {@code true} if the length of the
-     * descriptor is equal to 1
-     *
      * @return whether this {@linkplain ClassDesc} describes a primitive type
      */
     default boolean isPrimitive() {
@@ -258,10 +219,6 @@
     /**
      * Returns whether this {@linkplain ClassDesc} describes a class or interface type.
      *
-     * @implSpec
-     * The default implementation returns {@code true} if the descriptor starts with:
-     * {@code 'L'}
-     *
      * @return whether this {@linkplain ClassDesc} describes a class or interface type
      */
     default boolean isClassOrInterface() {
@@ -272,12 +229,6 @@
      * Returns the component type of this {@linkplain ClassDesc}, if it describes
      * an array type, or {@code null} otherwise.
      *
-     * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     return isArray() ? ClassDesc.ofDescriptor(descriptorString().substring(1)) : null;
-     * }</pre>
-     *
      * @return a {@linkplain ClassDesc} describing the component type, or {@code null}
      * if this descriptor does not describe an array type
      */
@@ -289,16 +240,6 @@
      * Returns the package name of this {@linkplain ClassDesc}, if it describes
      * a class or interface type.
      *
-     * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     if (!isClassOrInterface())
-     *         return "";
-     *     String className = internalToBinary(ConstantUtils.dropFirstAndLastChar(descriptorString()));
-     *     int index = className.lastIndexOf('.');
-     *     return (index == -1) ? "" : className.substring(0, index);
-     * }</pre>
-     *
      * @return the package name, or the empty string if the class is in the
      * default package, or this {@linkplain ClassDesc} does not describe a class or interface type
      */
@@ -314,24 +255,10 @@
      * Returns a human-readable name for the type described by this descriptor.
      *
      * @implSpec
-     * <p>The default implementation is equivalent to:
-     * <pre>{@code
-     *     if (isPrimitive())
-     *         return Wrapper.forBasicType(descriptorString().charAt(0)).primitiveSimpleName();
-     *     else if (isClassOrInterface()) {
-     *         return descriptorString().substring(Math.max(1, descriptorString().lastIndexOf('/') + 1),
-     *                                             descriptorString().length() - 1);
-     *     }
-     *     else if (isArray()) {
-     *         int depth = ConstantUtils.arrayDepth(descriptorString());
-     *         ClassDesc c = this;
-     *         for (int i=0; i<depth; i++)
-     *             c = c.componentType();
-     *         return c.displayName() + "[]".repeat(depth);
-     *     }
-     *     else
-     *         throw new IllegalStateException(descriptorString());
-     * }</pre>
+     * <p>The default implementation returns the simple name
+     * (e.g., {@code int}) for primitive types, the unqualified class name
+     * for class or interface types, or the display name of the component type
+     * suffixed with the appropriate number of {@code []} pairs for array types.
      *
      * @return the human-readable name
      */
--- a/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDesc.java	Tue Nov 27 14:56:13 2018 -0500
@@ -46,9 +46,6 @@
  * {@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/DirectMethodHandleDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DirectMethodHandleDescImpl.java	Tue Nov 27 14:56:13 2018 -0500
@@ -156,9 +156,11 @@
     }
 
     /**
-     * Returns {@code true} if the two direct method handle descriptors are equal.
-     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
-     * @param o the {@code DirectMethodHandleDescImpl} to compare to this
+     * Returns {@code true} if this {@linkplain DirectMethodHandleDescImpl} is
+     * equal to another {@linkplain DirectMethodHandleDescImpl}.  Equality is
+     * determined by the two descriptors having equal kind, owner, name, and type
+     * descriptor.
+     * @param o a {@code DirectMethodHandleDescImpl} to compare to this
      *       {@code DirectMethodHandleDescImpl}
      * @return {@code true} if the specified {@code DirectMethodHandleDescImpl} is
      *      equals to this {@code DirectMethodHandleDescImpl}.
@@ -174,11 +176,6 @@
                Objects.equals(type, desc.type);
     }
 
-    /**
-     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
-     *
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         return Objects.hash(kind, owner, name, type);
--- a/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicCallSiteDesc.java	Tue Nov 27 14:56:13 2018 -0500
@@ -239,8 +239,12 @@
     }
 
     /**
-     * Returns {@code true} if the two dynamic call site descriptors are equal.
-     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * Compares the specified object with this descriptor for equality.  Returns
+     * {@code true} if and only if the specified object is also a
+     * {@linkplain DynamicCallSiteDesc}, and both descriptors have equal
+     * bootstrap methods, bootstrap argument lists, invocation name, and
+     * invocation type.
+     *
      * @param o the {@code DynamicCallSiteDesc} to compare to this
      *       {@code DynamicCallSiteDesc}
      * @return {@code true} if the specified {@code DynamicCallSiteDesc} is
@@ -257,11 +261,6 @@
                Objects.equals(invocationType, specifier.invocationType);
     }
 
-    /**
-     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
-     *
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         int result = Objects.hash(bootstrapMethod, invocationName, invocationType);
--- a/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/DynamicConstantDesc.java	Tue Nov 27 14:56:13 2018 -0500
@@ -214,7 +214,7 @@
 
     /**
      * Returns the name that would appear in the {@code NameAndType} operand
-     *             of the {@code LDC} for this constant
+     * of the {@code LDC} for this constant
      *
      * @return the constant name
      */
@@ -347,8 +347,12 @@
     // @@@ To eventually support in canonicalization: DCR with BSM=MHR_METHODHANDLEDESC_ASTYPE becomes AsTypeMHDesc
 
     /**
-     * Returns {@code true} if the two dynamic constant descriptors are equal.
-     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * Compares the specified object with this descriptor for equality.  Returns
+     * {@code true} if and only if the specified object is also a
+     * {@linkplain DynamicConstantDesc}, and both descriptors have equal
+     * bootstrap methods, bootstrap argument lists, constant name, and
+     * constant type.
+     *
      * @param o the {@code DynamicConstantDesc} to compare to this
      *       {@code DynamicConstantDesc}
      * @return {@code true} if the specified {@code DynamicConstantDesc} is
@@ -366,11 +370,6 @@
                Objects.equals(constantType, desc.constantType);
     }
 
-    /**
-     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
-     *
-     * @see #equals
-     */
     @Override
     public final int hashCode() {
         int result = Objects.hash(bootstrapMethod, constantName, constantType);
--- a/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/MethodTypeDescImpl.java	Tue Nov 27 14:56:13 2018 -0500
@@ -138,8 +138,11 @@
     }
 
     /**
-     * Returns {@code true} if the two method type descriptors are equal.
-     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * Returns {@code true} if this {@linkplain MethodTypeDescImpl} is
+     * equal to another {@linkplain MethodTypeDescImpl}.  Equality is
+     * determined by the two descriptors having equal return types and argument
+     * types.
+     *
      * @param o the {@code MethodTypeDescImpl} to compare to this
      *       {@code MethodTypeDescImpl}
      * @return {@code true} if the specified {@code MethodTypeDescImpl} is
@@ -156,11 +159,6 @@
                && Arrays.equals(argTypes, constant.argTypes);
     }
 
-    /**
-     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
-     *
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         int result = returnType.hashCode();
--- a/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/constant/ReferenceClassDescImpl.java	Tue Nov 27 14:56:13 2018 -0500
@@ -80,8 +80,11 @@
     }
 
     /**
-     * Returns {@code true} if the two class descriptors are equal.
-     * Obeys the general contract of {@link java.lang.Object equals(Object)}.
+     * Returns {@code true} if this {@linkplain ReferenceClassDescImpl} is
+     * equal to another {@linkplain ReferenceClassDescImpl}.  Equality is
+     * determined by the two class descriptors having equal class descriptor
+     * strings.
+     *
      * @param o the {@code ClassDesc} to compare to this
      *       {@code ClassDesc}
      * @return {@code true} if the specified {@code ClassDesc} is
@@ -96,11 +99,6 @@
         return descriptor.equals(constant.descriptorString());
     }
 
-    /**
-     * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
-     *
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         return descriptor.hashCode();
--- a/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	Wed Nov 21 15:24:03 2018 -0500
+++ b/src/java.base/share/classes/java/lang/invoke/TypeDescriptor.java	Tue Nov 27 14:56:13 2018 -0500
@@ -28,6 +28,7 @@
 
 /**
  * An entity that has a field or method type descriptor
+ *
  * @jvms 4.3.2 Field Descriptors
  * @jvms 4.3.3 Method Descriptors
  *
@@ -35,14 +36,18 @@
  */
 public interface TypeDescriptor {
     /**
-     * Return the type descriptor for this instance, which may be a field or method type descriptor.
+     * Return the type descriptor string for this instance, which must be either
+     * a field type descriptor (JVMS 4.3.2) or method type descriptor (JVMS 4.3.3).
+     *
      * @return the type descriptor
+     * @jvms 4.3.2 Field Descriptors
+     * @jvms 4.3.3 Method Descriptors
      */
     String descriptorString();
 
 
     /**
-     * Represents a field type descriptor
+     * An entity that has a field type descriptor
      *
      * @param <F> the class implementing {@linkplain TypeDescriptor.OfField}
      * @jvms 4.3.2 Field Descriptors
@@ -79,10 +84,11 @@
 
 
     /**
-     * Represents a method type descriptor
+     * An entity that has a method type descriptor
      *
      * @param <F> the type representing field type descriptors
      * @param <M> the class implementing {@linkplain TypeDescriptor.OfMethod}
+     * @jvms 4.3.2 Field Descriptors
      * @jvms 4.3.3 Method Descriptors
      * @since 12
      */