changeset 50924:4ead060db982 jep-334

adding @jvms tags
author vromero
date Fri, 01 Jun 2018 07:30:11 -0700
parents 33e5cd5815b7
children d853e7821dcb
files src/java.base/share/classes/java/lang/Class.java src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/Constable.java src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java src/java.base/share/classes/java/lang/invoke/constant/package-info.java
diffstat 14 files changed, 38 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.base/share/classes/java/lang/Class.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/Class.java	Fri Jun 01 07:30:11 2018 -0700
@@ -3864,6 +3864,7 @@
      * will have identical descriptor strings.
      *
      * @return the type descriptor representation
+     * @jvms 4.3.2 Field Descriptors
      */
     @Override
     public String descriptorString() {
--- a/src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ClassDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -103,6 +103,7 @@
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the name string is not in the
      * correct format
+     * @jvms 4.3.2 Field Descriptors
      */
     static ClassDesc ofDescriptor(String descriptor) {
         requireNonNull(descriptor);
@@ -254,6 +255,7 @@
      * Return a field type descriptor string for this type, as per JVMS 4.3.2
      *
      * @return the descriptor string
+     * @jvms 4.3.2 Field Descriptors
      */
     String descriptorString();
 }
--- a/src/java.base/share/classes/java/lang/invoke/constant/Constable.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/Constable.java	Fri Jun 01 07:30:11 2018 -0700
@@ -58,6 +58,8 @@
  * (For example, {@link MethodHandle} will produce nominal descriptors for direct
  * method handles, but not necessarily those produced by method handles
  * combinators.)
+ * @jvms 4.4 The Constant Pool
+ * @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure
  *
  * @param <T> the type of the constant value
  */
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantClassDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -51,6 +51,7 @@
      *                   as per JVMS 4.3.2
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * field descriptor string, or does not describe a class or interface type
+     * @jvms 4.3.2 Field Descriptors
      */
     ConstantClassDesc(String descriptor) {
         requireNonNull(descriptor);
@@ -99,6 +100,7 @@
      * @param clazz ignored
      * @param descriptor a field descriptor string for the class, as per JVMS 4.3.2
      * @return the {@linkplain ClassDesc}
+     * @jvms 4.3.2 Field Descriptors
      */
     public static ClassDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
                                               String descriptor) {
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -80,6 +80,7 @@
  * @see Constable
  * @see ConstantDescs
  *
+ * @jvms 4.4 The Constant Pool
  */
 public interface ConstantDesc<T> {
     /**
@@ -93,6 +94,8 @@
      * @return the resolved constant value
      * @throws ReflectiveOperationException if a class, method, or field
      * could not be reflectively resolved in the course of resolution
+     * @jvms 5.4.3 Resolution
+     * @jvms 5.4.4 Access Control
      */
     T resolveConstantDesc(MethodHandles.Lookup lookup) throws ReflectiveOperationException;
 }
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantDescs.java	Fri Jun 01 07:30:11 2018 -0700
@@ -338,6 +338,7 @@
      * @param paramTypes the types of the static bootstrap arguments, if any
      * @return the {@link MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
+     * @jvms 4.2.2 Unqualified Names
      */
     public static ConstantMethodHandleDesc ofCallsiteBootstrap(ClassDesc clazz,
                                                                String name,
@@ -357,6 +358,7 @@
      * @param paramTypes the types of the static bootstrap arguments, if any
      * @return the {@link MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
+     * @jvms 4.2.2 Unqualified Names
      */
     public static ConstantMethodHandleDesc ofConstantBootstrap(ClassDesc clazz,
                                                                String name,
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodHandleDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -64,6 +64,7 @@
      * and {@code type} is not consistent with that kind of field accessor, or if
      * {@code kind} describes a constructor, and the return type of {@code type}
      * is not {@code void}
+     * @jvms 4.2.2 Unqualified Names
      */
     ConstantMethodHandleDesc(Kind kind, ClassDesc owner, String name, MethodTypeDesc type) {
         if (kind == CONSTRUCTOR)
@@ -198,6 +199,9 @@
      * @param memberType A method type descriptor for the method handle being
      *                described, as per JVMS 4.3.3
      * @return the {@linkplain MethodHandleDesc}
+     * @jvms 4.2.2 Unqualified Names
+     * @jvms 4.3.2 Field Descriptors
+     * @jvms 4.3.3 Method Descriptors
      */
     public static ConstantMethodHandleDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
                                                      String bsmKindName, String memberOwner, String memberName, String memberType) {
--- a/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/ConstantMethodTypeDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -66,6 +66,7 @@
      * @return a {@linkplain ConstantMethodTypeDesc} describing the desired method type
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * method descriptor
+     * @jvms 4.3.3 Method Descriptors
      */
     static ConstantMethodTypeDesc ofDescriptor(String descriptor) {
         requireNonNull(descriptor);
@@ -154,6 +155,7 @@
      * @param clazz ignored
      * @param descriptor a method descriptor string for the method type, as per JVMS 4.3.3
      * @return the {@linkplain MethodTypeDesc}
+     * @jvms 4.3.3 Method Descriptors
      */
     public static ConstantMethodTypeDesc constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
                                                    String descriptor) {
--- a/src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/DynamicCallSiteDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -68,6 +68,7 @@
      * @throws NullPointerException if any parameter is null
      * @throws IllegalArgumentException if the invocation name has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     private DynamicCallSiteDesc(ConstantMethodHandleDesc bootstrapMethod,
                                 String invocationName,
@@ -99,6 +100,7 @@
      * @throws NullPointerException if any parameter is null
      * @throws IllegalArgumentException if the invocation name has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public static DynamicCallSiteDesc of(ConstantMethodHandleDesc bootstrapMethod,
                                          String invocationName,
@@ -175,6 +177,7 @@
      * @throws NullPointerException if any parameter is null
      * @throws IllegalArgumentException if the invocation name has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public DynamicCallSiteDesc withNameAndType(String invocationName,
                                                MethodTypeDesc invocationType) {
--- a/src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/DynamicConstantDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -89,6 +89,7 @@
      * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     protected DynamicConstantDesc(ConstantMethodHandleDesc bootstrapMethod,
                                   String constantName,
@@ -150,6 +151,7 @@
      * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public static<T> ConstantDesc<T> ofCanonical(ConstantMethodHandleDesc bootstrapMethod,
                                                  String constantName,
@@ -178,6 +180,7 @@
      * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
                                                String constantName,
@@ -203,6 +206,7 @@
      * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
                                                String constantName,
@@ -244,6 +248,7 @@
      * @throws NullPointerException if any argument is null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     public static<T> DynamicConstantDesc<T> of(ConstantMethodHandleDesc bootstrapMethod,
                                                String constantName) {
@@ -394,6 +399,9 @@
      *                     of the {@code LDC} for this constant, as per JVMS 4.3.2
      * @param args The static arguments to the bootstrap method
      * @return the {@linkplain DynamicConstantDesc}
+     * @jvms 4.2.2 Unqualified Names
+     * @jvms 4.3.2 Field Descriptors
+     * @jvms 4.3.3 Method Descriptors
      */
     public static DynamicConstantDesc<?> constantBootstrap(MethodHandles.Lookup lookup, String name, Class<ClassDesc> clazz,
                                                            String bsmOwner, String bsmName, String bsmDesc,
--- a/src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/MethodHandleDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -105,6 +105,7 @@
      * @throws NullPointerException if any non-ignored arguments are null
      * @throws IllegalArgumentException if the {@code name} has the incorrect
      * format
+     * @jvms 4.2.2 Unqualified Names
      */
     static ConstantMethodHandleDesc of(Kind kind,
                                        ClassDesc clazz,
@@ -135,6 +136,8 @@
      * of the method handle, as per JVMS 4.3.3
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the non-ignored arguments are null
+     * @jvms 4.2.2 Unqualified Names
+     * @jvms 4.3.3 Method Descriptors
      */
     static ConstantMethodHandleDesc of(Kind kind,
                                        ClassDesc clazz,
@@ -167,6 +170,7 @@
      *                                    the method handle
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the non-ignored arguments are null
+     * @jvms 4.2.2 Unqualified Names
      */
     static ConstantMethodHandleDesc of(Kind kind,
                                        ClassDesc clazz,
@@ -188,6 +192,7 @@
      * @param fieldType a {@link ClassDesc} describing the type of the field
      * @return the {@linkplain MethodHandleDesc}
      * @throws NullPointerException if any of the arguments are null
+     * @jvms 4.2.2 Unqualified Names
      */
     static ConstantMethodHandleDesc ofField(Kind kind,
                                             ClassDesc clazz,
--- a/src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/MethodTypeDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -48,6 +48,7 @@
      * @throws NullPointerException if any argument is {@code null}
      * @throws IllegalArgumentException if the descriptor string is not a valid
      * method descriptor
+     * @jvms 4.3.3 Method Descriptors
      */
     static MethodTypeDesc ofDescriptor(String descriptor) {
         return ConstantMethodTypeDesc.ofDescriptor(descriptor);
@@ -159,6 +160,7 @@
      * Return the method type descriptor string, as per JVMS 4.3.3.
      *
      * @return the method type descriptor string
+     * @jvms 4.3.3 Method Descriptors
      */
     default String descriptorString() {
         return String.format("(%s)%s",
--- a/src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/PrimitiveClassDesc.java	Fri Jun 01 07:30:11 2018 -0700
@@ -48,6 +48,7 @@
      * string corresponding to one of the nine base types as per JVMS 4.3
      * @throws IllegalArgumentException if the descriptor string does not
      * describe a valid primitive type
+     * @jvms 4.3 Descriptors
      */
     PrimitiveClassDesc(String descriptor) {
         super(ConstantDescs.BSM_PRIMITIVE_CLASS, requireNonNull(descriptor), ConstantDescs.CR_Class);
--- a/src/java.base/share/classes/java/lang/invoke/constant/package-info.java	Thu May 31 13:03:59 2018 -0700
+++ b/src/java.base/share/classes/java/lang/invoke/constant/package-info.java	Fri Jun 01 07:30:11 2018 -0700
@@ -90,7 +90,7 @@
  * reading and writing APIs, and and is used by the
  * {@link java.lang.invoke.Intrinsics#invokedynamic(DynamicCallSiteDesc, java.lang.Object...)}
  * API for expressing {@code invokedynamic} call sites in Java source files.
- *
+ * @jvms 4.4 The Constant Pool
  */
 package java.lang.invoke.constant;