< prev index next >
src/java.base/share/classes/java/lang/ClassLoader.java
Print this page
8199947: Rename HTML element id in ClassLoader javadoc to avoid name conflict with private elements
Summary: rename "name" anchor to "binary-name"
Reviewed-by: jjg, alanb, mchung, martin
Contributed-by: David Lloyd <david.lloyd@redhat.com>
*** 71,81 ****
import sun.security.util.SecurityConstants;
/**
* A class loader is an object that is responsible for loading classes. The
* class {@code ClassLoader} is an abstract class. Given the <a
! * href="#name">binary name</a> of a class, a class loader should attempt to
* locate or generate data that constitutes a definition for the class. A
* typical strategy is to transform the name into a file name and then read a
* "class file" of that name from a file system.
*
* <p> Every {@link java.lang.Class Class} object contains a {@link
--- 71,81 ----
import sun.security.util.SecurityConstants;
/**
* A class loader is an object that is responsible for loading classes. The
* class {@code ClassLoader} is an abstract class. Given the <a
! * href="#binary-name">binary name</a> of a class, a class loader should attempt to
* locate or generate data that constitutes a definition for the class. A
* typical strategy is to transform the name into a file name and then read a
* "class file" of that name from a file system.
*
* <p> Every {@link java.lang.Class Class} object contains a {@link
*** 200,210 ****
* . . .
* }
* }
* </pre></blockquote>
*
! * <h3> <a id="name">Binary names</a> </h3>
*
* <p> Any class name provided as a {@code String} parameter to methods in
* {@code ClassLoader} must be a binary name as defined by
* <cite>The Java™ Language Specification</cite>.
*
--- 200,210 ----
* . . .
* }
* }
* </pre></blockquote>
*
! * <h3> <a id="binary-name">Binary names</a> </h3>
*
* <p> Any class name provided as a {@code String} parameter to methods in
* {@code ClassLoader} must be a binary name as defined by
* <cite>The Java™ Language Specification</cite>.
*
*** 478,496 ****
}
// -- Class --
/**
! * Loads the class with the specified <a href="#name">binary name</a>.
* This method searches for classes in the same manner as the {@link
* #loadClass(String, boolean)} method. It is invoked by the Java virtual
* machine to resolve class references. Invoking this method is equivalent
* to invoking {@link #loadClass(String, boolean) loadClass(name,
* false)}.
*
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The resulting {@code Class} object
*
* @throws ClassNotFoundException
* If the class was not found
--- 478,496 ----
}
// -- Class --
/**
! * Loads the class with the specified <a href="#binary-name">binary name</a>.
* This method searches for classes in the same manner as the {@link
* #loadClass(String, boolean)} method. It is invoked by the Java virtual
* machine to resolve class references. Invoking this method is equivalent
* to invoking {@link #loadClass(String, boolean) loadClass(name,
* false)}.
*
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The resulting {@code Class} object
*
* @throws ClassNotFoundException
* If the class was not found
*** 498,508 ****
public Class<?> loadClass(String name) throws ClassNotFoundException {
return loadClass(name, false);
}
/**
! * Loads the class with the specified <a href="#name">binary name</a>. The
* default implementation of this method searches for classes in the
* following order:
*
* <ol>
*
--- 498,508 ----
public Class<?> loadClass(String name) throws ClassNotFoundException {
return loadClass(name, false);
}
/**
! * Loads the class with the specified <a href="#binary-name">binary name</a>. The
* default implementation of this method searches for classes in the
* following order:
*
* <ol>
*
*** 528,538 ****
* <p> Unless overridden, this method synchronizes on the result of
* {@link #getClassLoadingLock getClassLoadingLock} method
* during the entire class loading process.
*
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @param resolve
* If {@code true} then resolve the class
*
* @return The resulting {@code Class} object
--- 528,538 ----
* <p> Unless overridden, this method synchronizes on the result of
* {@link #getClassLoadingLock getClassLoadingLock} method
* during the entire class loading process.
*
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @param resolve
* If {@code true} then resolve the class
*
* @return The resulting {@code Class} object
*** 577,587 ****
return c;
}
}
/**
! * Loads the class with the specified <a href="#name">binary name</a>
* in a module defined to this class loader. This method returns {@code null}
* if the class could not be found.
*
* @apiNote This method does not delegate to the parent class loader.
*
--- 577,587 ----
return c;
}
}
/**
! * Loads the class with the specified <a href="#binary-name">binary name</a>
* in a module defined to this class loader. This method returns {@code null}
* if the class could not be found.
*
* @apiNote This method does not delegate to the parent class loader.
*
*** 596,606 ****
* </ol>
*
* @param module
* The module
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The resulting {@code Class} object in a module defined by
* this class loader, or {@code null} if the class could not be found.
*/
final Class<?> loadClass(Module module, String name) {
--- 596,606 ----
* </ol>
*
* @param module
* The module
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The resulting {@code Class} object in a module defined by
* this class loader, or {@code null} if the class could not be found.
*/
final Class<?> loadClass(Module module, String name) {
*** 672,691 ****
}
}
}
/**
! * Finds the class with the specified <a href="#name">binary name</a>.
* This method should be overridden by class loader implementations that
* follow the delegation model for loading classes, and will be invoked by
* the {@link #loadClass loadClass} method after checking the
* parent class loader for the requested class.
*
* @implSpec The default implementation throws {@code ClassNotFoundException}.
*
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The resulting {@code Class} object
*
* @throws ClassNotFoundException
* If the class could not be found
--- 672,691 ----
}
}
}
/**
! * Finds the class with the specified <a href="#binary-name">binary name</a>.
* This method should be overridden by class loader implementations that
* follow the delegation model for loading classes, and will be invoked by
* the {@link #loadClass loadClass} method after checking the
* parent class loader for the requested class.
*
* @implSpec The default implementation throws {@code ClassNotFoundException}.
*
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The resulting {@code Class} object
*
* @throws ClassNotFoundException
* If the class could not be found
*** 695,705 ****
protected Class<?> findClass(String name) throws ClassNotFoundException {
throw new ClassNotFoundException(name);
}
/**
! * Finds the class with the given <a href="#name">binary name</a>
* in a module defined to this class loader.
* Class loader implementations that support the loading from modules
* should override this method.
*
* @apiNote This method returns {@code null} rather than throwing
--- 695,705 ----
protected Class<?> findClass(String name) throws ClassNotFoundException {
throw new ClassNotFoundException(name);
}
/**
! * Finds the class with the given <a href="#binary-name">binary name</a>
* in a module defined to this class loader.
* Class loader implementations that support the loading from modules
* should override this method.
*
* @apiNote This method returns {@code null} rather than throwing
*** 713,723 ****
* The module name; or {@code null} to find the class in the
* {@linkplain #getUnnamedModule() unnamed module} for this
* class loader
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The resulting {@code Class} object, or {@code null}
* if the class could not be found.
*
* @since 9
--- 713,723 ----
* The module name; or {@code null} to find the class in the
* {@linkplain #getUnnamedModule() unnamed module} for this
* class loader
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The resulting {@code Class} object, or {@code null}
* if the class could not be found.
*
* @since 9
*** 735,745 ****
/**
* Converts an array of bytes into an instance of class {@code Class}.
* Before the {@code Class} can be used it must be resolved. This method
* is deprecated in favor of the version that takes a <a
! * href="#name">binary name</a> as its first argument, and is more secure.
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
* of a valid class file as defined by
--- 735,745 ----
/**
* Converts an array of bytes into an instance of class {@code Class}.
* Before the {@code Class} can be used it must be resolved. This method
* is deprecated in favor of the version that takes a <a
! * href="#binary-name">binary name</a> as its first argument, and is more secure.
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
* of a valid class file as defined by
*** 802,817 ****
*
* <p>
* This method defines a package in this class loader corresponding to the
* package of the {@code Class} (if such a package has not already been defined
* in this class loader). The name of the defined package is derived from
! * the <a href="#name">binary name</a> of the class specified by
* the byte array {@code b}.
* Other properties of the defined package are as specified by {@link Package}.
*
* @param name
! * The expected <a href="#name">binary name</a> of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
--- 802,817 ----
*
* <p>
* This method defines a package in this class loader corresponding to the
* package of the {@code Class} (if such a package has not already been defined
* in this class loader). The name of the defined package is derived from
! * the <a href="#binary-name">binary name</a> of the class specified by
* the byte array {@code b}.
* Other properties of the defined package are as specified by {@link Package}.
*
* @param name
! * The expected <a href="#binary-name">binary name</a> of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
*** 921,951 ****
* {@link java.security.CodeSource CodeSource} within the
* {@code ProtectionDomain} of the class. Any classes added to that
* package must contain the same set of certificates or a
* {@code SecurityException} will be thrown. Note that if
* {@code name} is {@code null}, this check is not performed.
! * You should always pass in the <a href="#name">binary name</a> of the
* class you are defining as well as the bytes. This ensures that the
* class you are defining is indeed the class you think it is.
*
* <p> If the specified {@code name} begins with "{@code java.}", it can
* only be defined by the {@linkplain #getPlatformClassLoader()
* platform class loader} or its ancestors; otherwise {@code SecurityException}
* will be thrown. If {@code name} is not {@code null}, it must be equal to
! * the <a href="#name">binary name</a> of the class
* specified by the byte array {@code b}, otherwise a {@link
* NoClassDefFoundError NoClassDefFoundError} will be thrown.
*
* <p> This method defines a package in this class loader corresponding to the
* package of the {@code Class} (if such a package has not already been defined
* in this class loader). The name of the defined package is derived from
! * the <a href="#name">binary name</a> of the class specified by
* the byte array {@code b}.
* Other properties of the defined package are as specified by {@link Package}.
*
* @param name
! * The expected <a href="#name">binary name</a> of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
--- 921,951 ----
* {@link java.security.CodeSource CodeSource} within the
* {@code ProtectionDomain} of the class. Any classes added to that
* package must contain the same set of certificates or a
* {@code SecurityException} will be thrown. Note that if
* {@code name} is {@code null}, this check is not performed.
! * You should always pass in the <a href="#binary-name">binary name</a> of the
* class you are defining as well as the bytes. This ensures that the
* class you are defining is indeed the class you think it is.
*
* <p> If the specified {@code name} begins with "{@code java.}", it can
* only be defined by the {@linkplain #getPlatformClassLoader()
* platform class loader} or its ancestors; otherwise {@code SecurityException}
* will be thrown. If {@code name} is not {@code null}, it must be equal to
! * the <a href="#binary-name">binary name</a> of the class
* specified by the byte array {@code b}, otherwise a {@link
* NoClassDefFoundError NoClassDefFoundError} will be thrown.
*
* <p> This method defines a package in this class loader corresponding to the
* package of the {@code Class} (if such a package has not already been defined
* in this class loader). The name of the defined package is derived from
! * the <a href="#binary-name">binary name</a> of the class specified by
* the byte array {@code b}.
* Other properties of the defined package are as specified by {@link Package}.
*
* @param name
! * The expected <a href="#binary-name">binary name</a> of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes in positions
* {@code off} through {@code off+len-1} should have the format
*** 967,977 ****
* @throws ClassFormatError
* If the data did not contain a valid class
*
* @throws NoClassDefFoundError
* If {@code name} is not {@code null} and not equal to the
! * <a href="#name">binary name</a> of the class specified by {@code b}
*
* @throws IndexOutOfBoundsException
* If either {@code off} or {@code len} is negative, or if
* {@code off+len} is greater than {@code b.length}.
*
--- 967,977 ----
* @throws ClassFormatError
* If the data did not contain a valid class
*
* @throws NoClassDefFoundError
* If {@code name} is not {@code null} and not equal to the
! * <a href="#binary-name">binary name</a> of the class specified by {@code b}
*
* @throws IndexOutOfBoundsException
* If either {@code off} or {@code len} is negative, or if
* {@code off+len} is greater than {@code b.length}.
*
*** 1025,1035 ****
* cl.defineClass}(name, temp, 0,
* temp.length, pd);<br>
* </code></p>
*
* @param name
! * The expected <a href="#name">binary name</a>. of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes from positions
* {@code b.position()} through {@code b.position() + b.limit() -1
--- 1025,1035 ----
* cl.defineClass}(name, temp, 0,
* temp.length, pd);<br>
* </code></p>
*
* @param name
! * The expected <a href="#binary-name">binary name</a>. of the class, or
* {@code null} if not known
*
* @param b
* The bytes that make up the class data. The bytes from positions
* {@code b.position()} through {@code b.position() + b.limit() -1
*** 1045,1055 ****
* @throws ClassFormatError
* If the data did not contain a valid class.
*
* @throws NoClassDefFoundError
* If {@code name} is not {@code null} and not equal to the
! * <a href="#name">binary name</a> of the class specified by {@code b}
*
* @throws SecurityException
* If an attempt is made to add this class to a package that
* contains classes that were signed by a different set of
* certificates than this class, or if {@code name} begins with
--- 1045,1055 ----
* @throws ClassFormatError
* If the data did not contain a valid class.
*
* @throws NoClassDefFoundError
* If {@code name} is not {@code null} and not equal to the
! * <a href="#binary-name">binary name</a> of the class specified by {@code b}
*
* @throws SecurityException
* If an attempt is made to add this class to a package that
* contains classes that were signed by a different set of
* certificates than this class, or if {@code name} begins with
*** 1196,1217 ****
throw new NullPointerException();
}
}
/**
! * Finds a class with the specified <a href="#name">binary name</a>,
* loading it if necessary.
*
* <p> This method loads the class through the system class loader (see
* {@link #getSystemClassLoader()}). The {@code Class} object returned
* might have more than one {@code ClassLoader} associated with it.
* Subclasses of {@code ClassLoader} need not usually invoke this method,
* because most class loaders need to override just {@link
* #findClass(String)}. </p>
*
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The {@code Class} object for the specified {@code name}
*
* @throws ClassNotFoundException
* If the class could not be found
--- 1196,1217 ----
throw new NullPointerException();
}
}
/**
! * Finds a class with the specified <a href="#binary-name">binary name</a>,
* loading it if necessary.
*
* <p> This method loads the class through the system class loader (see
* {@link #getSystemClassLoader()}). The {@code Class} object returned
* might have more than one {@code ClassLoader} associated with it.
* Subclasses of {@code ClassLoader} need not usually invoke this method,
* because most class loaders need to override just {@link
* #findClass(String)}. </p>
*
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The {@code Class} object for the specified {@code name}
*
* @throws ClassNotFoundException
* If the class could not be found
*** 1237,1253 ****
// return null if not found
private native Class<?> findBootstrapClass(String name);
/**
! * Returns the class with the given <a href="#name">binary name</a> if this
* loader has been recorded by the Java virtual machine as an initiating
! * loader of a class with that <a href="#name">binary name</a>. Otherwise
* {@code null} is returned.
*
* @param name
! * The <a href="#name">binary name</a> of the class
*
* @return The {@code Class} object, or {@code null} if the class has
* not been loaded
*
* @since 1.1
--- 1237,1253 ----
// return null if not found
private native Class<?> findBootstrapClass(String name);
/**
! * Returns the class with the given <a href="#binary-name">binary name</a> if this
* loader has been recorded by the Java virtual machine as an initiating
! * loader of a class with that <a href="#binary-name">binary name</a>. Otherwise
* {@code null} is returned.
*
* @param name
! * The <a href="#binary-name">binary name</a> of the class
*
* @return The {@code Class} object, or {@code null} if the class has
* not been loaded
*
* @since 1.1
*** 2085,2097 ****
return NamedPackage.toPackage(p.packageName(), p.module());
}
/**
! * Defines a package by <a href="#name">name</a> in this {@code ClassLoader}.
* <p>
! * <a href="#name">Package names</a> must be unique within a class loader and
* cannot be redefined or changed once created.
* <p>
* If a class loader wishes to define a package with specific properties,
* such as version information, then the class loader should call this
* {@code definePackage} method before calling {@code defineClass}.
--- 2085,2097 ----
return NamedPackage.toPackage(p.packageName(), p.module());
}
/**
! * Defines a package by <a href="#binary-name">name</a> in this {@code ClassLoader}.
* <p>
! * <a href="#binary-name">Package names</a> must be unique within a class loader and
* cannot be redefined or changed once created.
* <p>
* If a class loader wishes to define a package with specific properties,
* such as version information, then the class loader should call this
* {@code definePackage} method before calling {@code defineClass}.
*** 2121,2131 ****
* that all packages in a named module are defined with the properties
* specified by {@link Package}. Otherwise, some {@code Package} objects
* in a named module may be for example sealed with different seal base.
*
* @param name
! * The <a href="#name">package name</a>
*
* @param specTitle
* The specification title
*
* @param specVersion
--- 2121,2131 ----
* that all packages in a named module are defined with the properties
* specified by {@link Package}. Otherwise, some {@code Package} objects
* in a named module may be for example sealed with different seal base.
*
* @param name
! * The <a href="#binary-name">package name</a>
*
* @param specTitle
* The specification title
*
* @param specVersion
*** 2183,2196 ****
return p;
}
/**
! * Returns a {@code Package} of the given <a href="#name">name</a> that
* has been defined by this class loader.
*
! * @param name The <a href="#name">package name</a>
*
* @return The {@code Package} of the given name that has been defined
* by this class loader, or {@code null} if not found
*
* @throws NullPointerException
--- 2183,2196 ----
return p;
}
/**
! * Returns a {@code Package} of the given <a href="#binary-name">name</a> that
* has been defined by this class loader.
*
! * @param name The <a href="#binary-name">package name</a>
*
* @return The {@code Package} of the given name that has been defined
* by this class loader, or {@code null} if not found
*
* @throws NullPointerException
*** 2231,2241 ****
public final Package[] getDefinedPackages() {
return packages().toArray(Package[]::new);
}
/**
! * Finds a package by <a href="#name">name</a> in this class loader and its ancestors.
* <p>
* If this class loader defines a {@code Package} of the given name,
* the {@code Package} is returned. Otherwise, the ancestors of
* this class loader are searched recursively (parent by parent)
* for a {@code Package} of the given name.
--- 2231,2241 ----
public final Package[] getDefinedPackages() {
return packages().toArray(Package[]::new);
}
/**
! * Finds a package by <a href="#binary-name">name</a> in this class loader and its ancestors.
* <p>
* If this class loader defines a {@code Package} of the given name,
* the {@code Package} is returned. Otherwise, the ancestors of
* this class loader are searched recursively (parent by parent)
* for a {@code Package} of the given name.
*** 2245,2255 ****
* loader is not its ancestor. When invoked on the platform class loader,
* this method will not find packages defined to the application
* class loader.
*
* @param name
! * The <a href="#name">package name</a>
*
* @return The {@code Package} of the given name that has been defined by
* this class loader or its ancestors, or {@code null} if not found.
*
* @throws NullPointerException
--- 2245,2255 ----
* loader is not its ancestor. When invoked on the platform class loader,
* this method will not find packages defined to the application
* class loader.
*
* @param name
! * The <a href="#binary-name">package name</a>
*
* @return The {@code Package} of the given name that has been defined by
* this class loader or its ancestors, or {@code null} if not found.
*
* @throws NullPointerException
< prev index next >