    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class java.lang.ClassLoader

    java.lang.Object
       |
       +----java.lang.ClassLoader

public abstract class ClassLoader
extends Object

The class `ClassLoader` is an abstract class. Applications implement subclasses of `ClassLoader` in order to extend the manner in which the Java Virtual Machine dynamically loads classes.

Normally, the Java Virtual Machine loads classes from the local file system in a platform-dependent manner. For example, on UNIX systems, the Virtual Machine loads classes from the directory defined by the `CLASSPATH` environment variable.

However, some classes may not originate from a file; they may originate from other sources, such as the network, or they could be constructed by an application. The method `defineClass` converts an array of bytes into an instance of class `Class`. Instances of this newly defined class can be created using the `newInstance` method in class `Class`.

The methods and constructors of objects created by a class loader may reference other classes. To determine the class(es) referred to, the Java Virtual Machine calls the `loadClass` method of the class loader that originally created the class. If the Java Virtual Machine only needs to determine if the class exists and if it does exist to know its superclass, the `resolve` flag is set to `false`. However, if an instance of the class is being created or any of its methods are being called, the class must also be resolved. In this case the `resolve` flag is set to `true`, and the `resolveClass` method should be called.

For example, an application could create a network class loader to download class files from a server. Sample code might look like:

`ClassLoader loader = new NetworkClassLoader(host, port);
Object main = loader.loadClass("Main", true).newInstance();
. . .`

The network class loader subclass must define the method `loadClass` to load a class from the network. Once it has downloaded the bytes that make up the class, it should use the method `defineClass` to create a class instance. A sample implementation is:

>          class NetworkClassLoader {
>              String host;
>              int port;
>              Hashtable cache = new Hashtable();
>              private byte loadClassData(String name)[] {
>              // load the class data from the connection
>               . . .
>              }
>              public synchronized Class loadClass(String name,
>                                                  boolean resolve) {
>                  Class c = cache.get(name);
>                  if (c == null) {
>                      byte data[] = loadClassData(name);
>                      c = defineClass(data, 0, data.length);
>                      cache.put(name, c);
>                  }
>                  if (resolve)
>                      resolveClass(c);
>                  return c;
>              }
>          }

See Also:
  Class, newInstance, defineClass, loadClass, resolveClass

##

ClassLoader()
  Constructs a new class loader and initializes it.

##

defineClass(byte[], int, int)
  Converts an array of bytes into an instance of class `Class`. Deprecated.
defineClass(String, byte[], int, int)
  Converts an array of bytes to an instance of class Class.
findLoadedClass(String)
findSystemClass(String)
  Finds the system class with the specified name, loading it in if necessary.
getResource(String)
  Find a resource with a given name.
getResourceAsStream(String)
  Get an InputStream on a given resource.
getSystemResource(String)
  Find a resource with a given name.
getSystemResourceAsStream(String)
  Get an InputStream on a given resource..
loadClass(String)
  Requests the class loader to load and resolve a class with the specified name.
loadClass(String, boolean)
  Resolves the specified name to a Class.
resolveClass(Class)
  Resolves the class so that an instance of the class can be created, or so that one of its methods can be called.
setSigners(Class, Object[])
  Sets the signers of a class.

##

ClassLoader

     protected ClassLoader()

  Constructs a new class loader and initializes it.

  If there is a security manager, its `checkCreateClassLoader` method is called. This may result in a security exception.

  Throws: SecurityException
    if the current thread does not have permission to create a new class loader.
  See Also:
    SecurityException, checkCreateClassLoader

##

loadClass

     public Class loadClass(String name) throws ClassNotFoundException

  Requests the class loader to load and resolve a class with the specified name. The `loadClass` method is called by the Java Virtual Machine when a class loaded by a class loader first references another class. Every subclass of class `ClassLoader` must define this method.

  Class loaders should use a hashtable or other cache to avoid defining classes with the same name multiple times.

  Parameters:
    name - the name of the desired `Class`.
  Returns:
    the resulting `Class`, or `null` if it was not found.
  Throws: ClassNotFoundException
    if the class loader cannot find a definition for the class.

loadClass

     protected abstract Class loadClass(String name,
                                        boolean resolve) throws ClassNotFoundException

  Resolves the specified name to a Class. The method loadClass() is called by the virtual machine.

  If the `resolve` flag is true, the method should call the `resolveClass` method on the resulting class object.

  As an abstract method, loadClass() must be defined in a subclass of ClassLoader. By using a Hashtable, you can avoid loading the same Class more than once.

  Parameters:
    name - the name of the desired Class.
    resolve - true if the Class needs to be resolved.
  Returns:
    the resulting Class, or null if it was not found.
  Throws: ClassNotFoundException
    if the class loader cannot find a definition for the class.
  See Also:
    Hashtable

defineClass

     protected final Class defineClass(byte data[],
                                       int offset,
                                       int length)

  Note: defineClass() is deprecated. Replaced by defineClass(java.lang.String, byte[], int, int).

  Converts an array of bytes into an instance of class `Class`. Before the Class can be used it must be resolved. This method is deprecated in favor of the version that takes a "name" as a first argument, and is more secure.

  Parameters:
    data - the bytes that make up the `Class`.
    offset - the start offset of the `Class` data.
    length - the length of the `Class` data.
  Returns:
    the `Class` object that was created from the data.
  Throws: ClassFormatError
    if the data does not contain a valid Class.
  See Also:
    loadClass, resolveClass

defineClass

     protected final Class defineClass(String name,
                                       byte data[],
                                       int offset,
                                       int length)

  Converts an array of bytes to an instance of class Class. Before the Class can be used it must be resolved.

  Parameters:
    name - the expected name of the class; null if unknown; using '.' and not '/' as separator, and without a trailing ".class" suffix.
    data - the bytes that make up the `Class`.
    offset - the start offset of the `Class` data.
    length - the length of the `Class` data.
  Returns:
    the `Class` object that was created from the data.
  Throws: ClassFormatError
    if the data does not contain a valid Class.
  See Also:
    loadClass, resolveClass

resolveClass

     protected final void resolveClass(Class c)

  Resolves the class so that an instance of the class can be created, or so that one of its methods can be called. This method should be called by `loadClass` if the resolve flag is `true`.

  Parameters:
    c - the `Class` instance to be resolved.
  See Also:
    defineClass

findSystemClass

     protected final Class findSystemClass(String name) throws ClassNotFoundException

  Finds the system class with the specified name, loading it in if necessary.

  A system class is a class loaded from the local file system in a platform- dependent way. It has no class loader.

  Parameters:
    name - the name of the system `class`.
  Returns:
    a system class with the given name.
  Throws: ClassNotFoundException
    if it could not find a definition for the class.
  Throws: NoClassDefFoundError
    if the class is not found.

setSigners

     protected final void setSigners(Class cl,
                                     Object signers[])

  Sets the signers of a class. This is called after defining a class, by signature-aware class loading code.

findLoadedClass

     protected final Class findLoadedClass(String name)

getSystemResourceAsStream

     public static final InputStream getSystemResourceAsStream(String name)

  Get an InputStream on a given resource.. Will return null if no resource with this name is found.

  The resource name may be any system resource (e.g. follows CLASSPATH order).

  Parameters:
    name - the name of the resource, to be used as is.
  Returns:
    an InputStream on the resource, or null if not found.

getSystemResource

     public static final URL getSystemResource(String name)

  Find a resource with a given name. The return is a URL to the resource Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream.

  The resource name may be any system resource (e.g. follows CLASSPATH order).

  Parameters:
    name - the name of the resource, to be used as is.
  Returns:
    the URL on the resource, or null if not found.

getResourceAsStream

     public InputStream getResourceAsStream(String name)

  Get an InputStream on a given resource. Will return null if no resource with this name is found.

  The class loader can choose what to do to locate the resource.

  Parameters:
    name - the name of the resource, to be used as is.
  Returns:
    an InputStream on the resource, or null if not found.

getResource

     public URL getResource(String name)

  Find a resource with a given name. The return is a URL to the resource. Doing a getContent() on the URL may return an Image, an AudioClip, or an InputStream.

  The class loader can choose what to do to locate the resource.

  Parameters:
    name - the name of the resource, to be used as is.
  Returns:
    an InputStream on the resource, or null if not found.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature - Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.