< prev index next >
src/java.base/share/classes/java/lang/Class.java
Print this page
@@ -97,20 +97,47 @@
* ({@code boolean}, {@code byte}, {@code char}, {@code short}, {@code
* int}, {@code long}, {@code float}, and {@code double}), and the
* keyword {@code void} are also represented as {@code Class} objects.
*
* <p> {@code Class} has no public constructor. Instead a {@code Class}
- * object is constructed automatically by the Java Virtual Machine
- * when a class loader invokes one of the
- * {@link ClassLoader#defineClass(String,byte[], int,int) defineClass} methods
- * and passes the bytes of a {@code class} file.
+ * object is constructed automatically by the Java Virtual Machine when
+ * a class is derived from the bytes of a {@code class} file through
+ * the invocation of one of the following methods:
+ * <ul>
+ * <li> {@link ClassLoader#defineClass(String, byte[], int, int) ClassLoader::defineClass}
+ * <li> {@link java.lang.invoke.MethodHandles.Lookup#defineClass(byte[])
+ * java.lang.invoke.MethodHandles.Lookup::defineClass}
+ * <li> {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
+ * java.lang.invoke.MethodHandles.Lookup::defineHiddenClass}
+ * </ul>
*
* <p> The methods of class {@code Class} expose many characteristics of a
* class or interface. Most characteristics are derived from the {@code class}
- * file that the class loader passed to the Java Virtual Machine. A few
- * characteristics are determined by the class loading environment at run time,
- * such as the module returned by {@link #getModule() getModule()}.
+ * file that the class loader passed to the Java Virtual Machine or
+ * from the {@code class} file passed to {@code Lookup::defineClass}
+ * or {@code Lookup::defineHiddenClass}.
+ * A few characteristics are determined by the class loading environment
+ * at run time, such as the module returned by {@link #getModule() getModule()}.
+ *
+ * <p> The following example uses a {@code Class} object to print the
+ * class name of an object:
+ *
+ * <blockquote><pre>
+ * void printClassName(Object obj) {
+ * System.out.println("The class of " + obj +
+ * " is " + obj.getClass().getName());
+ * }
+ * </pre></blockquote>
+ *
+ * It is also possible to get the {@code Class} object for a named
+ * type (or for void) using a class literal. See Section 15.8.2 of
+ * <cite>The Java™ Language Specification</cite>.
+ * For example:
+ *
+ * <blockquote>
+ * {@code System.out.println("The name of class Foo is: "+Foo.class.getName());}
+ * </blockquote>
*
* <p> Some methods of class {@code Class} expose whether the declaration of
* a class or interface in Java source code was <em>enclosed</em> within
* another declaration. Other methods describe how a class or interface
* is situated in a <em>nest</em>. A <a id="nest">nest</a> is a set of
@@ -125,33 +152,28 @@
* {@code class} files are generated, for example, a Java compiler
* will typically record a top-level class as the host of a nest where the
* other members are the classes and interfaces whose declarations are
* enclosed within the top-level class declaration.
*
- * <p> Some methods of class {@code Class} expose some characteristics of
- * <em>hidden classes</em>. Hidden classes are created by calling
+ * <p> A class or interface created by the invocation of
* {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
- * Lookup::defineHiddenClass}.
- *
- * <p> The following example uses a {@code Class} object to print the
- * class name of an object:
- *
- * <blockquote><pre>
- * void printClassName(Object obj) {
- * System.out.println("The class of " + obj +
- * " is " + obj.getClass().getName());
- * }
- * </pre></blockquote>
- *
- * <p> It is also possible to get the {@code Class} object for a named
- * type (or for void) using a class literal. See Section 15.8.2 of
- * <cite>The Java™ Language Specification</cite>.
- * For example:
- *
- * <blockquote>
- * {@code System.out.println("The name of class Foo is: "+Foo.class.getName());}
- * </blockquote>
+ * Lookup::defineHiddenClass} is a {@linkplain Class#isHidden() <em>hidden</em>}
+ * class or interface.
+ * All kinds of class, including enum types and record types, may be
+ * hidden classes; all kinds of interface, including annotation types,
+ * may be hidden interfaces.
+ *
+ * The {@linkplain #getName() name of a hidden class or interface} is not a
+ * binary name, which means that a hidden class or interface cannot be
+ * resolved by linkage of constant pool entries and cannot be discovered by
+ * {@link #forName Class::forName} or {@link ClassLoader#loadClass(String, boolean)
+ * ClassLoader::loadClass}.
+ *
+ * A hidden class or interface is never an array class, but may be
+ * the element type of an array. In all other respects, the fact that
+ * a class or interface is hidden has no bearing on the characteristics
+ * exposed by the methods of class {@code Class}.
*
* @param <T> the type of the class modeled by this {@code Class}
* object. For example, the type of {@code String.class} is {@code
* Class<String>}. Use {@code Class<?>} if the class being modeled is
* unknown.
@@ -188,13 +210,13 @@
}
/**
* Converts the object to a string. The string representation is the
* string "class" or "interface", followed by a space, and then by the
- * fully qualified name of the class in the format returned by
- * {@code getName}. If this {@code Class} object represents a
- * primitive type, this method returns the name of the primitive type. If
+ * name of the class in the format returned by {@code getName}.
+ * If this {@code Class} object represents a primitive type,
+ * this method returns the name of the primitive type. If
* this {@code Class} object represents void this method returns
* "void". If this {@code Class} object represents an array type,
* this method returns "class " followed by {@code getName}.
*
* @return a string representation of this class object.
@@ -744,15 +766,16 @@
public boolean isAnnotation() {
return (getModifiers() & ANNOTATION) != 0;
}
/**
- * Returns {@code true} if this class is a synthetic class;
- * returns {@code false} otherwise.
- * @return {@code true} if and only if this class is a synthetic class as
- * defined by the Java Language Specification.
+ * Returns {@code true} if and only if this class has the synthetic modifier
+ * bit set.
+ *
+ * @return {@code true} if and only if this class has the synthetic modifier bit set
* @jls 13.1 The Form of a Binary
+ * @jvms 4.1 The {@code ClassFile} Structure
* @since 1.5
*/
public boolean isSynthetic() {
return (getModifiers() & SYNTHETIC) != 0;
}
@@ -760,21 +783,29 @@
/**
* Returns the name of the entity (class, interface, array class,
* primitive type, or void) represented by this {@code Class} object,
* as a {@code String}.
*
- * <p> If this class object represents a reference type that is not an
- * array type then the binary name of the class is returned, as specified
- * by
+ * <p> If this {@code Class} object represents a class or interface,
+ * 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>
+ * of the class is returned, as specified by
* <cite>The Java™ Language Specification</cite>.
+ * <li> If the class or interface is hidden, then the result is a string
+ * of the format: {@code N + '/' + <suffix>}
+ * where {@code N} is the binary name indicated by the {@code class}
+ * file passed to
+ * {@link java.lang.invoke.MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
+ * java.lang.invoke.MethodHandles.Lookup::defineHiddenClass} and
+ * {@code <suffix>} is an unqualified name that is guaranteed to be
+ * unique during this execution of the JVM.
+ * </ul>
*
- * <p> If this class object represents a primitive type or void, then the
- * name returned is a {@code String} equal to the Java language
- * keyword corresponding to the primitive type or void.
- *
- * <p> If this class object represents a class of arrays, then the internal
- * form of the name consists of the name of the element type preceded by
+ * <p> If this {@code Class} object represents an array class, then
+ * the name consists of the encoded element type (see below) preceded by
* one or more '{@code [}' characters representing the depth of the array
* nesting. The encoding of element type names is as follows:
*
* <blockquote><table class="striped">
* <caption style="display:none">Element types and encodings</caption>
@@ -793,10 +824,14 @@
* <tr><th scope="row"> long <td style="text-align:center"> J
* <tr><th scope="row"> short <td style="text-align:center"> S
* </tbody>
* </table></blockquote>
*
+ * <p> If this {@code Class} object represents a primitive type or {@code void},
+ * then the result is a {@code String} equal to the Java language
+ * keyword corresponding to the primitive type or {@code void}.
+ *
* <p> The class or interface name <i>classname</i> is the binary name of
* the class specified above.
*
* <p> Examples:
* <blockquote><pre>
@@ -808,16 +843,12 @@
* returns "[Ljava.lang.Object;"
* (new int[3][4][5][6][7][8][9]).getClass().getName()
* returns "[[[[[[[I"
* </pre></blockquote>
*
- * <p> If this class object represents a {@linkplain #isHidden() hidden class},
- * then the name of a hidden class is not a binary name and contains
- * a ASCII {@code '/'} character.
- *
* @return the name of the class or interface
- * represented by this object.
+ * represented by this {@code Class} object.
*/
public String getName() {
String name = this.name;
return name != null ? name : initClassName();
}
@@ -1625,14 +1656,20 @@
return getName();
}
/**
* Returns the canonical name of the underlying class as
- * defined by the Java Language Specification. Returns null if
- * the underlying class does not have a canonical name (i.e., if
- * it is a local or anonymous class or an array whose component
- * type does not have a canonical name).
+ * defined by <cite>The Java™ Language Specification</cite>.
+ * Returns {@code null} if the underlying class does not have a canonical
+ * name. Classes without canonical names include:
+ * <ul>
+ * <li>a {@linkplain #isLocalClass() local class}
+ * <li>a {@linkplain #isAnonymousClass() anonymous class}
+ * <li>a {@linkplain #isHidden() hidden class}
+ * <li>an array whose component type does not have a canonical name</li>
+ * </ul>
+ *
* @return the canonical name of the underlying class if it exists, and
* {@code null} otherwise.
* @since 1.5
*/
public String getCanonicalName() {
@@ -1665,12 +1702,14 @@
}
}
/**
* Returns {@code true} if and only if the underlying class
- * is an anonymous class. An anonymous class is not a
- * {@linkplain #isHidden() hidden class}.
+ * is an anonymous class.
+ *
+ * @apiNote
+ * An anonymous class is not a {@linkplain #isHidden() hidden class}.
*
* @return {@code true} if and only if this class is an anonymous class.
* @since 1.5
*/
public boolean isAnonymousClass() {
@@ -4235,16 +4274,10 @@
}
/**
* Returns {@code true} if and only if the underlying class is a hidden class.
*
- * <p> A <em>hidden class</em> is created by calling
- * {@link MethodHandles.Lookup#defineHiddenClass(byte[], boolean, MethodHandles.Lookup.ClassOption...)
- * Lookup::defineHiddenClass}. A hidden class is non-discoverable
- * by name via {@link Class#forName(String) Class::forName},
- * {@link ClassLoader#loadClass(String) ClassLoader::loadClass}, and bytecode linkage.
- *
* @return {@code true} if and only if this class is a hidden class.
*
* @since 15
* @see MethodHandles.Lookup#defineHiddenClass
*/
< prev index next >