stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8309819: Clarify API note in Class::getName and MethodType::toMethodDescriptorString

Browse Source 
Reviewed-by: mchung
This commit is contained in:
Chen Liang 2023-06-30 23:37:53 +00:00 committed by Mandy Chung
parent 140b70fb29
commit 8c8e9d911d
2 changed files with 37 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/java.base/share/classes/java/lang/Class.java
View File

@ -170,7 +170,7 @@ import sun.reflect.misc.ReflectUtil;
* may be hidden interfaces.
*
* The {@linkplain #getName() name of a hidden class or interface} is
* not a <a href="ClassLoader.html#binary-name">binary name</a>,
* not a {@linkplain ClassLoader##binary-name binary name},
* which means the following:
* <ul>
* <li>A hidden class or interface cannot be referenced by the constant pools
@ -542,8 +542,8 @@ public final class Class<T> implements java.io.Serializable,
/**
* Returns the {@code Class} with the given <a href="ClassLoader.html#binary-name">
* binary name</a> in the given module.
* Returns the {@code Class} with the given {@linkplain ClassLoader##binary-name
* binary name} in the given module.
*
* <p> This method attempts to locate and load the class or interface.
* It does not link the class, and does not run the class initializer.
@ -566,7 +566,7 @@ public final class Class<T> implements java.io.Serializable,
* loads a class in another module.
*
* @param module A module
* @param name The <a href="ClassLoader.html#binary-name">binary name</a>
* @param name The {@linkplain ClassLoader##binary-name binary name}
* of the class
* @return {@code Class} object of the given name defined in the given module;
* {@code null} if not found.
@ -894,11 +894,11 @@ public final class Class<T> implements java.io.Serializable,
* not an array class, then:
* <ul>
* <li> If the class or interface is not {@linkplain #isHidden() hidden},
* then the <a href="ClassLoader.html#binary-name">binary name</a>
* then the {@linkplain ClassLoader##binary-name binary name}
* of the class or interface is returned.
* <li> If the class or interface is hidden, then the result is a string
* of the form: {@code N + '/' + <suffix>}
* where {@code N} is the <a href="ClassLoader.html#binary-name">binary name</a>
* where {@code N} is the {@linkplain ClassLoader##binary-name binary name}
* indicated by the {@code class} file passed to
* {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
* Lookup::defineHiddenClass}, and {@code <suffix>} is an unqualified name.
@ -918,7 +918,7 @@ public final class Class<T> implements java.io.Serializable,
* <tr><th scope="row"> {@code boolean} <td style="text-align:center"> {@code Z}
* <tr><th scope="row"> {@code byte} <td style="text-align:center"> {@code B}
* <tr><th scope="row"> {@code char} <td style="text-align:center"> {@code C}
* <tr><th scope="row"> class or interface with <a href="ClassLoader.html#binary-name">binary name</a> <i>N</i>
* <tr><th scope="row"> class or interface with {@linkplain ClassLoader##binary-name binary name} <i>N</i>
* <td style="text-align:center"> {@code L}<em>N</em>{@code ;}
* <tr><th scope="row"> {@code double} <td style="text-align:center"> {@code D}
* <tr><th scope="row"> {@code float} <td style="text-align:center"> {@code F}
@ -946,6 +946,9 @@ public final class Class<T> implements java.io.Serializable,
* returns "[[[[[[[I"
* </pre></blockquote>
*
* @apiNote
* Distinct class objects can have the same name but different class loaders.
*
* @return the name of the class, interface, or other entity
* represented by this {@code Class} object.
* @jls 13.1 The Form of a Binary
@ -4534,7 +4537,7 @@ public final class Class<T> implements java.io.Serializable,
* <blockquote>
* {@code "L" +} <em>N</em> {@code + "." + <suffix> + ";"}
* </blockquote>
* where <em>N</em> is the <a href="ClassLoader.html#binary-name">binary name</a>
* where <em>N</em> is the {@linkplain ClassLoader##binary-name binary name}
* encoded in internal form indicated by the {@code class} file passed to
* {@link MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
* Lookup::defineHiddenClass}, and {@code <suffix>} is an unqualified name.
@ -4562,11 +4565,6 @@ public final class Class<T> implements java.io.Serializable,
* is a one-letter code corresponding to a primitive type or {@code void}
* ({@code "B", "C", "D", "F", "I", "J", "S", "Z", "V"}) (JVMS {@jvms 4.3.2}).
*
* @apiNote
* This is not a strict inverse of {@link #forName};
* distinct classes which share a common name but have different class loaders
* will have identical descriptor strings.
*
* @return the descriptor string for this {@code Class} object
* @jvms 4.3.2 Field Descriptors
* @since 12

50
src/java.base/share/classes/java/lang/invoke/MethodType.java
View File

@ -51,7 +51,6 @@ import sun.security.util.SecurityConstants;
import static java.lang.invoke.MethodHandleStatics.UNSAFE;
import static java.lang.invoke.MethodHandleStatics.newIllegalArgumentException;
import static java.lang.invoke.MethodType.fromDescriptor;
/**
* A method type represents the arguments and return type accepted and
@ -1159,26 +1158,29 @@ class MethodType
}
/**
* Finds or creates an instance of a method type, given the spelling of its bytecode descriptor.
* Convenience method for {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* Finds or creates an instance of a method type of the given method descriptor
* (JVMS {@jvms 4.3.3}). This method is a convenience method for
* {@link #methodType(java.lang.Class, java.lang.Class[]) methodType}.
* Any class or interface name embedded in the descriptor string will be
* resolved by the given loader (or if it is null, on the system class loader).
* <p>
* Note that it is possible to encounter method types which cannot be
* constructed by this method, because their component types are
* not all reachable from a common class loader.
* resolved by the given loader (or if it is {@code null}, on the system class loader).
*
* @apiNote
* It is possible to encounter method types that have valid descriptors but
* cannot be constructed by this method, because their component types are
* not visible from a common class loader.
* <p>
* This method is included for the benefit of applications that must
* generate bytecodes that process method handles and {@code invokedynamic}.
* @param descriptor a bytecode-level type descriptor string "(T...)T"
* @param descriptor a method descriptor string
* @param loader the class loader in which to look up the types
* @return a method type matching the bytecode-level type descriptor
* @throws NullPointerException if the string is null
* @throws IllegalArgumentException if the string is not well-formed
* @return a method type of the given method descriptor
* @throws NullPointerException if the string is {@code null}
* @throws IllegalArgumentException if the string is not a method descriptor
* @throws TypeNotPresentException if a named type cannot be found
* @throws SecurityException if the security manager is present and
* {@code loader} is {@code null} and the caller does not have the
* {@link RuntimePermission}{@code ("getClassLoader")}
* @jvms 4.3.3 Method Descriptors
*/
public static MethodType fromMethodDescriptorString(String descriptor, ClassLoader loader)
throws IllegalArgumentException, TypeNotPresentException
@ -1218,19 +1220,20 @@ class MethodType
}
/**
* Returns a descriptor string for the method type. This method
* {@return the descriptor string for this method type} This method
* is equivalent to calling {@link #descriptorString() MethodType::descriptorString}.
*
* <p>
* Note that this is not a strict inverse of {@link #fromMethodDescriptorString fromMethodDescriptorString}.
* Two distinct classes which share a common name but have different class loaders
* will appear identical when viewed within descriptor strings.
* @apiNote
* This is not a strict inverse of {@link #fromMethodDescriptorString
* fromMethodDescriptorString} which requires a method type descriptor
* (JVMS {@jvms 4.3.3}) and a suitable class loader argument.
* Two distinct {@code MethodType} objects can have an identical
* descriptor string as distinct classes can have the same name
* but different class loaders.
*
* <p>
* This method is included for the benefit of applications that must
* generate bytecodes that process method handles and {@code invokedynamic}.
* {@link #fromMethodDescriptorString(java.lang.String, java.lang.ClassLoader) fromMethodDescriptorString},
* because the latter requires a suitable class loader argument.
* @return the descriptor string for this method type
* @jvms 4.3.3 Method Descriptors
* @see <a href="#descriptor">Nominal Descriptor for {@code MethodType}</a>
*/
@ -1244,16 +1247,16 @@ class MethodType
}
/**
* Returns a descriptor string for this method type.
* {@return the descriptor string for this method type}
*
* <p>
* If this method type can be <a href="#descriptor">described nominally</a>,
* If this method type can be {@linkplain ##descriptor described nominally},
* then the result is a method type descriptor (JVMS {@jvms 4.3.3}).
* {@link MethodTypeDesc MethodTypeDesc} for this method type
* can be produced by calling {@link MethodTypeDesc#ofDescriptor(String)
* MethodTypeDesc::ofDescriptor} with the result descriptor string.
* <p>
* If this method type cannot be <a href="#descriptor">described nominally</a>
* If this method type cannot be {@linkplain ##descriptor described nominally}
* and the result is a string of the form:
* <blockquote>{@code "(<parameter-descriptors>)<return-descriptor>"}</blockquote>
* where {@code <parameter-descriptors>} is the concatenation of the
@ -1262,7 +1265,6 @@ class MethodType
* of the return type. No {@link java.lang.constant.MethodTypeDesc MethodTypeDesc}
* can be produced from the result string.
*
* @return the descriptor string for this method type
* @since 12
* @jvms 4.3.3 Method Descriptors
* @see <a href="#descriptor">Nominal Descriptor for {@code MethodType}</a>