Class is a generic class, declared as Class<T>. Each Class object for a reference type is of a parameterized type corresponding to the class it represents. For example, the type of String.class is Class<String>, the type of Integer.class is Class<Integer>, and so forth. The type of the Class object for a primitive type is the same type as that of its corresponding wrapper class. For example, the type of int.class is Class<Integer>, but note that int.class and Integer.class are two different instances of the same type of class. Parameterized types all share the Class object of their raw type—for example, the Class object for List<Integer> is the same as that for List<String> and the same as that for List.class, and its type is Class<List>.

A parameterized Class type is known as the type token for a given class. The easiest way to obtain a type token is to use a class literal, such as String.class, since this provides you with the exact type token. In contrast, Class.forName is declared to return a wildcard, Class<?>, that represents an unidentified type token—to use this type token effectively you need to establish its actual type, as you'll soon see. The Object method getClass returns the type token for the type of object it is invoked on, and its return type is also Class<?>, another wildcard. However, getClass receives special treatment by the compiler: If getClass is invoked on a reference with static type T, then the compiler treats the return type of getClass as being Class<?extends T>.^[1] So this works:

String str = "Hello";
Class<String> c1 = String.class;  // exact type token
Class<? extends String> c2 =
    str.getClass();               // compiler magic

but this won't compile:

Class<? extends String> c3 =
    Class.forName("java.lang.String");  // INVALID

Taking an unknown type token Class<?> and turning it into a type token of a known type is a common action when working with reflection. What you need is something that acts like a cast, but as you already know, you can't perform casts involving parameterized types. The solution to this is another piece of “magic” in the shape of the asSubclass method of class Class:

The asSubclass method doesn't change the Class object at all; it simply changes the type of the expression it is invoked on, so we can use the additional type information—just as a cast does. For example, here's how you can use asSubclass with forName to fix the previous problem:

Class<? extends String> c3 =
    Class.forName("java.lang.String").
        asSubclass(String.class);       // OK

Note that you can't convert the unknown type token to be exactly Class<String>, but having Class<?extends String> should be sufficient. Of course, String is not a practical example for using reflection. A more typical example would be when you are loading an unknown class that implements a known interface and you want to create an instance of that class; you'll see an example of this in the Game class on page 436.

The Class class provides a number of methods for obtaining information about a particular class. Some of these provide information on the type of the class—the interfaces it implements, the class it extends—and others return information on the members of the class, including nested classes and interfaces. You can ask if a class represents an interface or an array, or whether a particular object is an instance of that class. We look at these different methods over the next few pages.

The most basic Class methods are those that walk the type hierarchy, displaying information about the interfaces implemented and the classes extended. As an example, this program prints the complete type hierarchy of the type represented by a string passed as an argument:

import java.lang.reflect.*;

public class TypeDesc {
    public static void main(String[] args) {
        TypeDesc desc = new TypeDesc();
        for (String name : args) {
            try {
                Class<?> startClass = Class.forName(name);
                desc.printType(startClass, 0, basic);
            } catch (ClassNotFoundException e) {
                System.err.println(e);  // report the error
        }
    }
}

// by default print on standard output
private java.io.PrintStream out = System.out;

// used in printType() for labeling type names
private static String[]
    basic   = { "class",   "interface",
                "enum",    "annotation"  },
    supercl = { "extends", "implements" },
    iFace   = { null,       "extends"  };

private void printType(
    Type type, int depth, String[] labels)
{
    if (type == null) // stop recursion -- no supertype
        return;

    // turn the Type into a Class object
    Class<?> cls = null;
    if (type instanceof Class<?>)
        cls = (Class<?>) type;
    else if (type instanceof ParameterizedType)
        cls = (Class<?>)
            ((ParameterizedType)type).getRawType();
    else
        throw new Error("Unexpected non-class type");

    // print this type
    for (int i = 0; i < depth; i++)
        out.print("  ");
    int kind = cls.isAnnotation() ? 3 :
        cls.isEnum() ? 2 :
        cls.isInterface() ? 1 : 0;
    out.print(labels[kind] + " ");
    out.print(cls.getCanonicalName());

    // print generic type parameters if present
    TypeVariable<?>[] params = cls.getTypeParameters();
        if (params.length > 0) {
            out.print('<'),
            for (TypeVariable<?> param : params) {
                out.print(param.getName());
                out.print(", ");
            }
            out.println(">");
        }
        else
            out.println();

        // print out all interfaces this class implements
        Type[] interfaces = cls.getGenericInterfaces();
        for (Type iface : interfaces) {
            printType(iface, depth + 1,
                      cls.isInterface() ? iFace : supercl);
        }
        // recurse on the superclass
        printType(cls.getGenericSuperclass(),
                  depth + 1, supercl);
    }
}

This program loops through the names provided on the command line, obtains the Class object for each named type and invokes printType on each of them. It must do this inside a try block in case there is no class of the specified name. Here is its output when invoked on the utility class java.util.HashMap:

class java.util.HashMap<K, V>
  implements java.util.Map<K, V>
  implements java.lang.Cloneable
  implements java.io.Serializable
  extends java.util.AbstractMap<K, V>
    implements java.util.Map<K, V>
    extends java.lang.Object

After the main method is the declaration of the output stream to use, by default System.out. The String arrays are described shortly.

The printType method prints its own type parameter's description and then invokes itself recursively to print the description of type's supertypes. Because we initially have general Type objects, we first have to convert them to Class objects. The depth parameter keeps track of how far up the type hierarchy it has climbed, indenting each description line according to its depth. The depth is incremented at each recursion level. The labels array specifies how to label the class—labels[0] is the label if the type is a class; labels[1] is for interfaces; labels[2] for enums; and labels[3] for annotation types. Note the order in which we check what kind of type we have—an enum type is a class, and an annotation type is an interface, so we have to check for these more specific kinds of type first.

Three arrays are defined for these labels: basic is used at the top level, supercl is used for superclasses, and iFace is used for superinterfaces of interfaces, which extend, not implement, each other. After we print the right prefix, we use getCanonicalName to print the full name of the type. The Class class provides a toString method, but it already adds “class” or “interface” in front. We want to control the prefix, so we must create our own implementation. We look more at class names a little later.

Next, the type is examined to see if it is a generic type. All classes implement GenericDeclaration, which defines the single method getTypeParameters that returns an array of TypeVariable objects. If we have one or more type parameters then we print each of their names between angle brackets, just as they would appear in your source code.

After printing the type description, printType invokes itself recursively, first on all the interfaces that the original type implements and then on the superclass this type extends (if any), passing the appropriate label array to each. Eventually, it reaches the Class object for Object, which implements no interfaces and whose getGenericSuperclass method returns null, and the recursion ends.

Some simple query methods, a few of which you saw in the example, examine the kind of Class object that you are dealing with:

You can also ask whether you have a top-level type or a nested type, and if nested, some information about which kind of nested type:

Note that there is no way to determine if a member class is a static nested class or an inner class.

The example showed the two methods you can use to find out where a type fits in the type hierarchy:

The legacy methods getInterfaces and getSuperclass are similar to the above except they return Class objects instead of Type objects. Any parameterized type is returned as the Class object for the corresponding raw type.

Given all the different kinds of types there are, some methods only apply to a subset of those different kinds:

Exercise 16.1: Modify TypeDesc to skip printing anything for the Object class. It is redundant because everything ultimately extends it. Use the reference for the Class object for the Object type.

Exercise 16.2: Modify TypeDesc to show whether the named type is a nested type, and if so, what other type it is nested within.

The Class class contains a set of methods you can use to examine the class's components: its fields, methods, constructors, and nested types. Special types are defined to represent each of these, which you will learn about in detail in later sections: Field objects for fields, Method objects for methods, Constructor objects for constructors, and for nested types, the Class objects you have already seen.

These methods come in four variants depending on whether you want all members or a particular member, only public members or any members, only members declared in the current class or inherited members as well.

You can request all the public members of a specific kind that are either declared in the class (interface) or inherited, by using one of the following:^[2]

public Constructor[] getConstructors()
public Field[] getFields()
public Method[] getMethods()
public Class[] getClasses()

Because constructors are not inherited, getConstructors returns Constructor objects only for public constructors declared in the current class.

You can also ask for the members of a specific kind that are actually declared in the class (interface), as opposed to being inherited. Such members need not be public:

public Constructor[] getDeclaredConstructors()
public Field[] getDeclaredFields()
public Method[] getDeclaredMethods()
public Class[] getDeclaredClasses()

In each case, if there is no member of that kind, you will get an empty array. The getClasses and getDeclaredClasses methods return both nested classes and nested interfaces.

Requesting a particular member requires you to supply further information. For nested types this is simply the name of the nested type and, in fact, there are no special methods to do this because Class.forName can be used for this purpose. Particular fields are requested using their name:

public Field getField(String name)
public Field getDeclaredField(String name)

The first form finds a public field that is either declared or inherited, while the second finds only a declared field that need not be public. If the named field does not exist, a NoSuchFieldException is thrown. Note that the implicit length field of an array is not returned when these methods are invoked on an array type.

Particular methods are identified by their signature—their name and a sequence of Class objects representing the number and type of their parameters. Remember that for a varargs method the last parameter will actually be an array.

public Method 
    getMethod(String name, Class... parameterTypes)
public Method 
    getDeclaredMethod(String name, Class... parameterTypes)

Similarly, constructors are identified by their parameter number and types:

public Constructor<T> 
     getConstructor(Class... parameterTypes)
public Constructor<T>
     getDeclaredConstructor(Class... parameterTypes)

In both cases, if the specified method or constructor does not exist, you will get a NoSuchMethodException.

Note that when you ask for a single constructor you get a parameterized constructor type, Constructor<T>, that matches the type of the Class object, while the array returned for a group of constructors is not parameterized by T. This is because you can't create a generic array. Any constructor extracted from the array is essentially of an unknown kind, but this only affects use of the invoke method, which we discuss a little later.

All the above methods require a security check before they can proceed and so will interact with any installed security manager—see “Security” on page 677. If no security manager is installed then all these methods will be allowed. Typically, security managers will allow any code to invoke methods that request information on the public members of a type—this enforces the normal language level access rules. However, access to non-public member information will usually be restricted to privileged code within the system. Note that the only distinction made is between public and non-public members—security managers do not have enough information to enforce protected or package-level access. If access is not allowed, a SecurityException is thrown.

The following program lists the public fields, methods, and constructors of a given class:

import java.lang.reflect.*;

  public class ClassContents {
     public static void main(String[] args) {
         try {
             Class<?> c = Class.forName(args[0]);
             System.out.println(c);
             printMembers(c.getFields());
             printMembers(c.getConstructors());
             printMembers(c.getMethods());
         } catch (ClassNotFoundException e) {
             System.out.println("unknown class: " + args[0]);
         }
     }

     private static void printMembers(Member[] mems) {
         for (Member m : mems) {
             if (m.getDeclaringClass() == Object.class)
                 continue;
             String decl = m.toString();
             System.out.print("    ");
             System.out.println(strip(decl, "java.lang."));
         }
     }

     // ... definition of strip ... 
}

We first get the Class object for the named class. We then get and print the arrays of member objects that represent all the public fields, constructors, and methods of the class. The printMembers method uses the Member object's toString method to get a string that describes the member, skipping members that are inherited from Object (using getDeclaringClass to see which class the member belongs to) since these are present in all classes and so are not very useful to repeat each time (strip removes any leading "java.lang." from the name). Here is the output when the program is run on the Attr class from page 76:

class Attr
    public Attr(String)
    public Attr(String, Object)
    public String Attr.toString()
    public String Attr.getName()
    public Object Attr.getValue()
    public Object Attr.setValue(Object)

Exercise 16.3: Modify ClassContents to show information for all declared and all public inherited members. Make sure you don't list anything twice.

The Class objects in the TypeDesc program are obtained using the static method Class.forName, which takes a string argument and returns a Class object for the type with that name. The name must be the binary name of a class or interface, or else be a specially named array type—these are defined below.

Every type is represented by a number of different names. The actual class or interface name is the simple name of the type. This is the shortest name you could write in your program to represent a given type. For example, the simple name of java.lang.Object is Object, the simple name of the nested Entry interface in the java.util.Map interface is Entry, the simple name of the type representing an array of Object instances is Object[], and the simple name of an array of int is int[]. All types except for anonymous inner classes have simple names. You can get the simple name of a type from the Class method getSimpleName.

The canonical name of a type is its full name, as you would write it in your programs, including, if applicable, the package and enclosing type in which the type was declared. For example, the canonical name of Object is java.lang.Object; for the nested Entry interface it is java.util.Map.Entry; for an array of Object instances it is java.lang.Object[]; and for an array of int is int[]. In more specific terms, the canonical name of a top-level class or interface is its package name followed by dot, followed by its simple name. The canonical name of a nested type is the canonical name of the type in which it is declared, followed by dot, followed by its simple name. The canonical name of an array type is the canonical name of its element type followed by []. Local inner classes and anonymous inner classes do not have canonical names. You can get the canonical name of a type from the Class method getCanonicalName.

The canonical name is an example of a fully qualified name—the simple name qualified by the package and enclosing type, if applicable. While simple names might be ambiguous in a given context, a fully qualified name uniquely determines a type. Each type has only one canonical name, but nested types (and so arrays of nested types) can have multiple fully qualified names. For example, the java.util.SortedMap interface extends java.util.Map and inherits the nested Entry interface. Consequently, you can identify the Entry type by the fully qualified name java.util.SortedMap.Entry.

The binary name of a class or interface (not array) is a name used to communicate with the virtual machine, such as by passing it to Class.forName to ask the virtual machine for a specific Class object. The binary name of a top-level class or interface is its canonical name. For nested types there is a special naming convention, as you learned in “Implementation of Nested Types” on page 149. Static nested types and inner classes (excluding local and anonymous inner classes) have a binary name that consists of the binary name of their immediately enclosing type, followed by $ and the simple name of the nested or inner type. For example, the binary name of the Entry interface is java.util.Map$Entry. For local inner classes, the binary name is the binary name of the enclosing class, followed by $, then a number, and then its simple name. For an anonymous inner class, the binary name is the binary name of the enclosing class, followed by $ and a number.^[3] You get the binary name of a type from the Class method getName. This binary name is what forName expects as a class or interface name.

For their names, array types have a special notation, known as internal format because it is the format used inside the virtual machine. But for some reason this notation is not considered a binary name. This notation consists of a code representing the component type of the array, preceded by the character [. The component types are encoded as follows:

For example, an array of int is named [I, while an array of Object is named [Ljava.lang.Object; (note the trailing semicolon). A multidimensional array is just an array whose component type is an array, so, for example, a type declared as int[][] is named [[I—an array whose component type is named [I. These internal format names can be passed to forName to obtain the class objects for array types, and it is this name that getName returns for array types.

For primitive types and void, the simple name, canonical name, and binary name are all the same—the keyword that presents that type, such as int, float, or void—and all the name methods return the same name. For these types, Class objects cannot be obtained from forName. You must use the class literals, such as int.class, or the TYPE field of the appropriate wrapper class, such as Void.TYPE. If a name representing one of these types is used with forName, it is assumed to be a user-defined class or interface and is unlikely to be found.

The forName method we have been using is a simpler form of the more general forName method:

As this method description indicates, obtaining the Class object for a class can involve loading, linking, and initializing the class—a fairly complex process that is described further in Section 16.13 on page 435. The simple Class.forName method uses the current class loader—the one that loaded the current class in which the forName invocation appears—and initializes the class if needed. If the class cannot be found then the checked exception ClassNotFoundException is thrown. The exception can contain a nested exception that describes the problem, which you can get from invoking getCause on the exception object. This will be either the nested exception or null. Because of the complexities of loading, linking, and initializing a class, these methods can also throw the unchecked exceptions LinkageError and ExceptionInInitializerError.

When writing your programs you can check the type of an object by using instanceof or change the type of an expression with a cast. In both cases you need to know the name of the type involved so you can write it in the code. When working with reflection, you have only Class objects to work with, so operators like instanceof and casts can't be used. The class Class provides several methods that provide functionality analogous to the language level operators:

Under normal circumstances attempting to set the value of a field declared as final will result in IllegalAccessException being thrown. This is what you would expect: Final fields should never have their value changed. There are special circumstances—such as during custom deserialization (see page 554)—where it makes sense to change the value of a final field. You can do this via reflection only on instance fields, and only if setAccessible(true) has been invoked on the Field object. Note that it is not enough that setAccessible(true) would succeed, it must actually be called.

This capability is provided for highly specialized contexts and is not intended for general use—we mention it only for completeness. Changing a final field can have unexpected, possibly tragic consequences unless performed in specific contexts, such as custom deserialization. Outside those contexts, changes to a final field are not guaranteed to be visible. Even in such contexts, code using this technique must be guaranteed that security will not thwart its work. Changing a final field that is a constant variable (see page 46) will never result in the change being seen, except through the use of reflection—don't do it!

Exercise 16.6: Create an Interpret program that creates an object of a requested type and allows the user to examine and modify fields of that object.

An inner class (excluding local and anonymous inner classes) never has a no-arg constructor, since the compiler transforms all inner class constructors to take a first parameter that is a reference to the enclosing object. This means that you can never use Class.newInstance to create an inner class object, so you must use Constructor objects. The Constructor objects for an inner class reflect the transformed code, not the code written by the programmer. For example, consider the BankAccount class and its associated inner Action class from page 136. The Action class had a single constructor that took a String parameter, representing the action that had occurred (withdraw, deposit, and so on), and a long value, representing the amount involved. If you use getDeclaredConstructors to obtain that Constructor object and print its signature using toString, you will get the following:

BankAccount$Action(BankAccount,java.lang.String,long)

Here you can see both the use of the $ naming convention for inner classes and the implicitly added constructor argument that refers to the enclosing object. You can retrieve this constructor as follows:

Class<Action> actionClass = Action.class;
Constructor<Action> con =
    actionClass.getDeclaredConstructor(BankAccount.class,
            String.class, long.class);

If you want to construct an Action object you must supply an appropriate enclosing object reference as in

BankAccount acct = new BankAccount();
// ...
Action a = con.newInstance(acct, "Embezzle", 10000L);

The GenericDeclaration interface, which is implemented by Class, Method, and Constructor, has the single method getTypeParameters, which returns an array of TypeVariable objects. The TypeVariable interface is itself a generic interface, declared as

interface TypeVariable<D extends GenericDeclaration>

So, for example, the TypeVariable objects Method.getTypeParameters returns would be of type TypeVariable<Method>.

Each type variable has a name returned by getName. It also has one or more upper bounds, obtained as a Type[] from getBounds. Recall that if there is no explicit upper bound then the upper bound is Object.

The getGenericDeclaration method returns the Type object for the GenericDeclaration in which the TypeVariable was declared. For example, the expression TypeVariable.class.getTypeParameters()[0] would yield a TypeVariable object that represents D in the declaration above. If you invoked getGenericDeclaration on this object, it would return the Class object for the TypeVariable interface. More generally, for any GenericDeclaration object g with at least one type parameter,

g.getTypeParameters()[i].getGenericDeclaration() == g

is always true (assuming i is a valid index of course).

Type variable objects are created on demand by the reflection methods that return them, and there is no requirement that you receive the same TypeVariable object each time you ask for the same type variable. However, the objects returned for a given type variable must be equivalent according to the equals method. The bounds for a type variable are not created until getBounds is invoked, so getBounds can throw TypeNotPresentException if a type used in the bounds cannot be found. It can also throw MalformedParameterizedTypeException if any of the bounds refers to a ParameterizedType instance that cannot be created for some reason.

Parameterized types, such as List<String>, are represented by objects that implement the ParameterizedType interface. You can obtain the actual type arguments for the parameterized type from getActualTypeArguments, which returns an array of Type objects. For example, getActualTypeArguments invoked on the parameterized type List<String> would yield an array of length one, containing String.class as its only element.

The getOwnerType method (which perhaps would have been better called getDeclaringType) returns the Type object for the type in which this ParameterizedType object is a member. If this is not a member of another type then null is returned. This is analogous to the Class.getDeclaringClass method except that a Type object is returned.

Like TypeVariable objects, ParameterizedType objects are created on demand and are not always the same object, so you should use equals not == to check for equivalent parameterized type objects. Also, when a parameterized type is created, all its type arguments are also created, and this applies recursively. Both of the above methods will sometimes throw either TypeNotFoundException or MalformedParameterizedTypeException.

Finally, ParameterizedType also has the method getRawType, which returns the Class object for the raw type of the parameterized type. For example, if getRawType were invoked on the parameterized type List<String> it would return List.class. Even though a raw type is by definition a non-generic class or interface, getRawType returns a Type instance rather than a Class<?>, so a cast must be applied, as you saw in the TypeDesc program.

A wildcard type parameter is represented by an instance that implements the WildcardType interface. For example, given a parameterized type for List<?extends Number>, getActualTypeArguments will give an array of length one containing a WildcardType object representing “?extends Number”.

WildcardType has two methods: getUpperBounds and getLowerBounds, which return Type arrays representing the upper and lower bounds of the wildcard, respectively. If no upper bound was specified, the upper bound is Object. If a wildcard has no lower bound, getLowerBounds returns an empty array.

As with TypeVariable, the type objects for bounds are created on demand, so TypeNotPresentException or MalformedParameterizedTypeException may be thrown.

The last of the type related interfaces is GenericArrayType. This represents array types in which the component type is a parameterized type or a type variable.^[4] GenericArrayType has a single method, getGenericComponentType, which returns the Type for the component type of the array, which will be either a ParameterizedType or a TypeVariable. For example, for a List<String>[] field, getGenericType would return a GenericArrayType object whose getComponentType would return a ParameterizedType for List<String>.

The component type object gets created when getGenericComponentType is invoked, so as you might expect, you may get a TypeNotPresentException or MalformedParameterizedTypeException.

None of the interfaces described above define the toString method, or any other general way to obtain a string representation of a type—with the exception of TypeVariable, which has the getName method. However, all the type objects will have a toString method defined. With no specification of what toString should return for Type objects, you cannot rely on toString to give a reasonable representation of the type. If you want a string representation of a type, you will need to assemble it yourself from the information available. For example, if a WildcardType object has no lower bound and an upper bound of X, then the wildcard is “?extends X”. For a ParameterizedType you can construct the string representation using the raw type and the actual type parameter types.

Exercise 16.9: Use reflection to write a program that will print a full declaration of a named class, including everything except the import statements, comments, and code for initializers, constructors, and methods. The member declarations should appear just as you would write them. You will need to use all the reflection classes you have seen. Also note that the toString methods of many of the reflection objects will not provide the information you want in the correct format, so you will need to piece together the individual pieces of information.

Recall the toArray method of the SingleLinkQueue class from Chapter 11. We promised back then that we'd show you how to create the array directly (instead of having it passed in) by having the type token for the actual type argument of the queue passed in. Here's a first attempt:

public E[] toArray_v1(Class<E> type) {
    int size = size();
    E[] arr = (E[]) Array.newInstance(type, size);
    int i = 0;
    for (Cell<E> c = head;
         c != null && i < size;
         c = c.getNext())
        arr[i++] = c.getElement();
    return arr;
}

This code works, but is less desirable than the generic version that took in the array to fill. The main problem is that the above causes an “unchecked” warning from the compiler. As you may have already noticed, the cast to E[] is a cast involving a type parameter and such casts have a different meaning at runtime—the actual cast will be to Object, which is the erasure of E. Despite this, it is apparent that the code above is type-safe: We ask for an array that has a component type of E and we try to use the returned object as such an array. The existence of the “unchecked” warning is a consequence of a limitation in the Array API and can't be avoided.

The second problem with the above is that it suffers from the same limitation as the original non-generic version of toArray—it will only allow an array of the exact element type to be created, not an array of any supertype. We can address this latter problem by turning the current version into a generic method, as we did previously:

public <T> T[] toArray(Class<T> type) {
    int size = size();
    T[] arr = (T[]) Array.newInstance(type, size);
    int i = 0;
    Object[] tmp = arr;
    for (Cell<E> c = head;
         c != null && i < size;
         c = c.getNext())
        tmp[i++] = c.getElement();
    return arr;
}

This version still has the “unchecked” warning—that can't be avoided—but it allows any Class object to passed in and tries to return an array with that component type. As with the generic version that takes the array as an argument, this version relies on the runtime checking of array stores to ensure that the component type passed is actually compatible with the element type of the current queue.

So you're left with two approaches for dealing with the toArray requirement: have the caller pass in the array and avoid warnings, but be forced to deal with an array of the wrong size, or have the caller pass in the type token for the element type and create an array of the right size, but be subjected to the “unchecked” warning. Or you could do as the collection classes do and combine both: Take in an array, but if it is the wrong size dynamically create another one, and get the warning. While we normally advise that you avoid “unchecked” warnings at all costs, the case of Array.newInstance is an exception.^[5]

Exercise 16.10: Modify Interpret further to allow users to specify a type and size of array to create; set and get the elements of that array; and access fields and invoke methods on specific elements of the array.

A class loader can delegate responsibility for loading a class to its parent class loader. The parent class loader can be specified as a constructor argument to ClassLoader:

A generic class loader, intended for use by others, should provide both forms of constructor to allow an explicit parent to be set.

The system class loader is typically the class loader used by the virtual machine to load the initial application class. You can get a reference to it from the static method getSystemClassLoader.

The bootstrap class loader is the class loader used to load those classes belonging to the virtual machine (classes like Object, String, List, and so forth). These classes are often referred to as system classes, a term which can lead to some confusion since the system classes are loaded by the bootstrap loader, whereas application classes are loaded by the system class loader. The bootstrap loader may or may not be represented by an actual ClassLoader object, so invoking getClassLoader on an instance of one of the system classes will typically return null, indicating it was loaded by the bootstrap loader.

You can get the parent class loader from the method getParent. If the class loader's parent is the bootstrap class loader, getParent may return null.

Class loaders are an integral part of the security architecture—see “Security” on page 677—so creating a class loader and asking for the parent class loader are checked operations that may throw a SecurityException.

The primary method of ClassLoader is loadClass:

The default implementation of loadClass, which is not usually overridden, attempts to load a class as follows:

Note that the parent class loader is always given the chance to load the class first; only if the bootstrap loader and the system class loader fail to load a given class will your custom class loader be given the opportunity to do so. The implication is that your custom class loader must search for classes in places that are different from those searched by the system or bootstrap class loaders.

The PlayerLoader class extends ClassLoader to override findClass:

class PlayerLoader extends ClassLoader {
    public Class<?> findClass(String name)
        throws ClassNotFoundException
    {
        try {
            byte[] buf = bytesForClass(name);
            return defineClass(name, buf, 0, buf.length);
        } catch (IOException e) {
            throw new ClassNotFoundException(e.toString());
        }
    }

    // ... bytesForClass, and any other methods ...
}

The findClass method generally has to perform two actions. First, it has to locate the bytecodes for the specified class and load them into a byte array—the job of bytesForClass in our example. Second, it uses the utility method defineClass to actually load the class defined by those bytes into the virtual machine and return a Class object for that class.

An overloaded form of defineClass takes an additional ProtectionDomain argument, while the above form uses a default protection domain. Protection domains define the security permissions for objects in that domain—again see “Security” on page 677 for further details. Both forms of defineClass may throw SecurityException.

Before you can define a class you have to read the bytes for the class, and that is the purpose of bytesForClass:

protected byte[] bytesForClass(String name)
    throws IOException, ClassNotFoundException
{
    FileInputStream in = null;
    try {
        in = streamFor(name + ".class");
        int length = in.available(); // get byte count
        if (length == 0)
            throw new ClassNotFoundException(name);
        byte[] buf = new byte[length];
        in.read(buf);                // read the bytes
        return buf;
    } finally {
        if (in != null)
            in.close();
    }
}

This method uses streamFor (not shown) to get a FileInputStream to the class's bytecodes, assuming that the bytecodes are in a file named by the class name with a ".class" appended—streamFor knows where to search for the class files to be loaded. We then create a buffer for the bytes, read them all, and return the buffer.

When the class has been successfully loaded, findClass returns the new Class object returned by defineClass. There is no way to explicitly unload a class when it is no longer needed. You simply stop using it, allowing it to be garbage-collected when its ClassLoader is unreachable.

Exercise 16.11: Expand on Game and Player to implement a simple game, such as tic-tac-toe. Score some Player implementations over several runs each.

The class loader assists in only the first stage of making a class available. There are three steps in all:

The Class object returned by defineClass only represents a loaded class—it has not yet been linked. You can explicitly link by invoking the (misnamed) resolveClass method:

The loadClass method we described does not resolve the class that is loaded. A protected, overloaded form of loadClass takes an additional boolean flag indicating whether or not to resolve the class before returning. The virtual machine will ensure that a class is resolved (linked) before it is initialized.

A class must be initialized immediately before the first occurrence of: an instance of the class being created; a static method of the class being invoked; or a non-final static field of the class being accessed. This includes the use of reflection methods to perform those actions. Additionally, before an assert statement is executed inside a nested type, the enclosing top-level class (if there is one) must be initialized. Using reflection to directly load a class may also trigger initialization—such as use of Class.forName(name)—but note that simple use of a class literal does not trigger initialization.

Classes are the primary resources a program needs, but some classes need other associated resources, such as text, images, or sounds. Class loaders have ways to find class resources, and they can use the same mechanisms to get arbitrary resources stored with the class. In our game example, a particular playing strategy might have an associated “book” that tells it how to respond to particular situations. The following code, in a BoldPlayer class, would get an InputStream for such a book:

String book = "BoldPlayer.book";
InputStream in;
ClassLoader loader = this.getClass().getClassLoader();
if (loader != null)
    in = loader.getResourceAsStream(book);
else
    in = ClassLoader.getSystemResourceAsStream(book);

System resources are associated with system classes (the classes that may have no associated class loader instance). The static ClassLoader method getSystemResourceAsStream returns an InputStream for a named resource. The preceding code checks to see whether it has a class loader. If it does not, the class has been loaded by the bootstrap class loader; otherwise, it uses the class loader's getResourceAsStream method to turn its resource name into a byte input stream. The resource methods return null if the resource is not found.

The Class class provides a getResourceAsStream method to simplify getting resources from a class's class loader. The preceding code could be written more simply as

String book = "BoldPlayer.book";
InputStream in = BoldPlayer.class.getResourceAsStream(book);

Resource names must be made up of one or more valid identifiers separated by / characters, specifying a path to the resource. Typically, a class loader will search for resources in the same places it will search for class files.

Two other resource methods—getResource and getSystemResource—return URL objects that name the resources. The class java.net.URL is covered briefly on page 725; it provides methods to use uniform resource locators to access resources. You can invoke the getContents method on the URL objects returned by the class loader methods to get an object that represents the contents of that URL.

The getResources method returns a java.util.Enumeration object (an older variant of the Iterator you've seen before) that can step through URL objects for all the resources stored under a given name. The static method getSystemResources does the same for system resources.

The resource-getting methods first ask the parent class loader for the resource, or they ask the bootstrap class loader if there is no parent. If the resource cannot be found, then findResource or findResources is invoked. Just as loadClass is built on top of a findClass that you provide when you subclass ClassLoader, so the resource methods are built on top of two methods that you can override to find resources:

Here is a findResource for PlayerLoader:

public java.net.URL findResource(String name) {
    File f = fileFor(name);
    if (!f.exists())
        return null;
    try {
        return f.toURL();
    } catch (java.net.MalformedURLException e) {
        return null;        // shouldn't happen
    }
}

The fileFor method is analogous to the streamFor method of PlayerLoader. It returns a java.io.File object that corresponds to the named resource in the file system. If the named file actually exists, then the URL for the resource is created from the path. (The File class represents a pathname in the file system—see “The File Class” on page 543.)

The BoldPlayer class might come with a BoldPlayer.book that can be found in the same place as the class file. You can replace this version with your own by simply placing yours in a location where it will be found first by the system class loader or the bootstrap loader.

Exercise 16.12: Modify your results for Exercise 16.11 to allow player strategies to use attached resources by implementing findResource and findResources.