| ## Java 1.1 Unleashed # - 18 - The Reflection Package by Corey Klaasmeyer IN THIS CHAPTER The Class Class The Member Interface The Field Class The Method Class The Constructor Class The Array Class The Modifier Class The reflection package (`java.lang.reflect`) allows you to peer into the Java virtual machine and gather information about classes and objects. JavaBeans application builder tools make use of these classes as do compilers and debuggers that need access to class-level information. Object serialization classes must also inspect objects to pack and unpack objects. This chapter describes the major classes of the reflection package and their uses. Java 1.1 added new methods to the `Class` class to support reflection. Although the `Class` class should really be a member of the `java.lang.reflect` package, it remains a member of `java.lang` for backwards compatibility. For this reason, a portion of the `Class` methods are covered in Chapter 10, "The Language Package," as part of the `java.lang` package; the rest of the methods of `Class` are covered in this chapter. This chapter focuses on methods relevant to the `java.lang.reflect` subpackage. The `Exception` classes defined in this package are covered in Chapter 7, "Exception Handling." ## The Class Class The `Class` class plays a central role in the reflection package by providing runtime access to classes and interfaces through `Class` objects. Instances of these `Class` objects are created by calling the static method `forName()` of class `Class`. These `Class` objects are representations, or reflections, of their respective classes and interfaces. Methods of the `Class` class return instances of `Field`, `Method`, `Constructor`, `Array`, and `Modifier` classes, which you can then use to access and modify members of the reflected classes and interfaces. NOTE: The `Class`, `Field`, `Method`, `Constructor`, and `Array` classes all have private constructors. Only the Java virtual machine can create new instances of these classes. The following methods play important roles in the `java.lang.reflect` classes: `boolean isInstance(Object` obj`)` `boolean isInterface(` `boolean isArray()` `boolean isPrimitive()` `int getModifiers()` `Field[] getFields()` `Field getField(String` name`)` `Method[] getMethods()` `Method getMethod(String` name`, Class[]` parameterTypes`)` `Constructor[] getConstructors()` `Constructor getConstructor(Class[]` parameterTypes`)` `Class[] getDeclaredClasses()` `Field[] getDeclaredFields()` `Method[] getDeclaredMethods()` ### The isInstance() Method
    boolean isInstance(Object obj)
The `isInstance()` method works like the `instanceof` operator. If the `Object` argument is not `null` and can be cast to the type of the `Class` object without throwing an exception, the method returns `true`.
    Object o = new Object();
    Class instance = Class.forName("java.lang.StringBuffer");
    System.out.println( instance.isInstance( o ) );
This code segment prints `false` because a reference of type `Object` cannot be cast to a `StringBuffer` type. ### The isInterface() Method
    boolean isInterface()
The `isInterface()` method returns `true` if the `Class` object represents an `interface` type. The `isInterface()` method can be used in the following way:
    Class instance = Class.forName("java.lang.image.ImageObserver");
    System.out.println( instance.isInterface() );
This code prints `true` because `ImageObserver` is an interface. ### The isArray() Method
    boolean isArray()
The `isArray()` method returns `true` if the `Class` object represents an array type; it returns `false` if not. This method can be used as follows:
    Class instance = Class.forName("java.awt.image.ImageObserver");
    System.out.println( instance.isArray() );
This example outputs `false` because the `ImageObserver` class is not an array type. ### The isPrimitive() Method
    boolean isPrimitive()
The `isPrimitive()` method returns `true` if the `Class` object represents a primitive type; it returns `false` if not. The following is an example of its use:
    System.out.println( Integer.TYPE.isPrimitive() );
This example prints `true` because the `final` `static` class variable `Integer.TYPE` is an object representing the primitive type `int`. This `TYPE` class variable is a member of all the type wrapper classes, including the new class `Void`. In fact, `Void` contains nothing but the `TYPE` class variable. ### The getModifiers() Method
    int getModifiers()
Although you may guess that the `getModifiers()` method returns an array of modifiers, it actually returns an `int`. The static method `toString()` of the `Modifier` class can then be used to return the set of modifiers represented by this `int` value. The following example illustrates this process:
    Class instance = Class.forName("java.lang.StringBuffer");
    int modifiers = instance.getModifiers();
    System.out.println(Modifier.toString(modifiers));
This code segment prints all the modifiers found in the definition of the `StringBuffer` class:
    public final synchronized
### The getFields() Method
    Field[] getFields()
The `getFields()` method returns an array of `Field` objects representing all the member fields of the reflected interface or class. All the `public` fields of the superclass or superinterface are included in this array. Each of the `Field` objects in the array represents a single class (`static`) variable or instance variable. If no `public` fields are found in the reflected class, an array of length zero is returned. The following example uses the `getFields()` method to gather information about the `Event` class; the method returns an array of 74 `public` instance and class variables:
    Class instance = Class.forName( "java.awt.Event" );
    Field[] result = null;
    result = instance.getFields();

    for( int i = 0 ; i < Array.getLength( result ) ; i++ ) {
    System.out.println( result[i].toString() ); }
See the discussion of the `toString()` method, in the section "The `Field` Class," later in this chapter for information about what the output from this code snippet looks like. ### The getField() Method
    Field getField(String name)
The `getField()` method returns a single `Field` object with a name matching the `String` argument. To find the field with the specified name, the `getField()` method searches all the `public` instance fields or `static` fields of the reflected class or object and all the `public` fields of the superclass or superinterface. If no fields matching that name are found, a `NoSuchFieldException` exception is thrown. The following example shows how to find the `id` variable in the `Event` object:
    Class instance = Class.forName( "java.awt.Event" );
    Field result = instance.getField( "id" );
    System.out.println( result.toString() );
In this example, the `getField()` method searches for the instance variable `"id"` within the reflected `Event` class. It finds the field and prints the following information about the field:
    public int java.awt.Event.id
### The getMethods() Method
    Method[] getMethods()
The `getMethods()` method can be used in the same way as the `getFields()` method just described. Instead of returning `Field` objects, however, the `getMethods()` method returns all the `public` methods of the reflected interface or class and the `public` methods of any superclasses or superinterfaces. If no `public` methods are found, the method returns an array of length zero. Here is an example showing how this method is called on a `Class` object representing the `String` class:
    Class instance = Class.forName( "java.lang.String" );
    Method[] result = instance.getMethods();

    for( int i = 0 ; i < result.length ; i++ ) {
    System.out.println( result[i].toString() ); }
This example prints out all the `public` methods in the `String` class as well as all the `public` methods of the `Object` class. The `toString()` method of the `Method` class describes more fully how the output from this example is formatted. ### The getMethod() Method
    Method getMethod(String name, Class[] parameterTypes)
The `getMethod()` method returns a `Method` object representing a method with the same name as the `String` argument. An array of `Class` objects is sent as the second argument to the method to distinguish between overridden and overloaded methods with the same names. Because a method signature is defined by number of parameters, types of parameters, as well as order of parameters, the order of the `Class` objects in the `Class[]` array parameter is important. If no method by that signature is found, the method throws a `NoSuchMethodException` exception. The `getMethod()` method can be used as in the following example:
    Class instance = Class.forName("java.lang.String");
    Class[] array = new Class[2];
    array[0] = Class.forName("java.lang.String");
    array[1] = Integer.TYPE;
    System.out.println(instance.getMethod("indexOf",array).toString());
The fourth line in this code segment is interesting because it uses the new `static` `final` class variable `TYPE`, which is a member of the `Integer` class. The variable contains a reference to an object of class `Class`, which in this case represents the `int` type. The new primitive `Class` objects are discussed in the example code of the `isPrimitive()` method, presented earlier in this chapter. ### The getConstructors() Method
    Constructor[] getConstuctors()
The `getConstructors()` method returns an array containing `Constructor` objects. If the reflected class represents an interface or a primitive type or there are no public constructors, an array of length zero is returned. The following example enumerates all the constructors of the `String` class:
    Class instance = Class.forName( "java.lang.String" );
    Constructor[] result = instance.getConstructors();

    for( int i = 0 ; i < result.length ; i++ ) {
    System.out.println( result[i].toString() ); }
This example prints the 11 constructors defined in the `String` class. See the description of the `toString()` method in "The `Constructor` Class," later in this chapter, for details about the formatting of this output. ### The getConstructor() Method
    Constructor getConstructor(Class[] parameterTypes)
The `getConstructor()` method returns a single `Constructor` object that represents the constructor member of the reflected class with a matching signature. The name of the constructor is not specified because this name is always the same as the name of the constructor's class. Only the number, types, and order of the parameters determine which constructor is returned. If a zero-length array of `Class` objects is sent as a parameter, the default constructor is returned. If no constructor is found within the reflected class, a `NoSuchMethodException` exception is returned. Interfaces and classes with no `public` constructors also throw this exception. The following example uses this method to find a specific constructor in the `String` class:
    Class instance = Class.forName("java.lang.String");
    Class[] array = new Class[1];
    array[0] = Class.forName("java.lang.String");
    System.out.println(instance.getConstructor(array).toString());
This program outputs the following line:
    public java.langString(java.lang.String)
### The getDeclaredClasses() Method
    Class[] getDeclaredClasses()
The `getDeclaredClasses()` method can be used to find the public, private, or protected member classes declared within the reflected class or interface. Inherited member classes are not returned by this method. If the `Class` object represents a primitive type, or the class declares no classes or interfaces as members, this method returns an array of length zero. The following code is an example of the usage of the `getDeclaredClasses()` method:
    Class instance = Class.forName( "java.net.URLConnection" );
    Class[] result = instance.getDeclaredClasses();
### The getDeclaredFields() Method
    Field[] getDeclaredFields()
Like the `getDeclaredClasses()` method, the `getDeclaredFields()` method returns all the private, protected, or public fields declared by the reflected class or interface (excluding inherited methods). If the `Class` object represents a primitive type or the class declares no fields, this method returns an array of length zero. The following example lists all the declared fields of the `URLConnection` class:
    Class instance = Class.forName( "java.net.URLConnection" );
    Field[] result = instance.getDeclaredFields();
    for( int i = 0 ; i < result.length ; i++ ) {
    System.out.println( result[i].toString() ); }
### The getDeclaredMethods() Method
    Method[] getDeclaredMethods()
The `getDeclaredMethods()` method returns all the private, protected, or public methods of the reflected class or interface (excluding inherited methods). If the `Class` object represents a primitive type or the class declares no fields, this method returns an array of length zero. The following example lists all the declared methods within the `URLConnection` class:
    Class instance = Class.forName( "java.net.URLConnection" );
    Field[] result = instance.getDeclaredFields();
    for( int i = 0 ; i < result.length ; i++ ) {
    System.out.println( result[i].toString() ); }
## The Member Interface The `Member` interface defines a number of methods implemented by the `Field`, `Method`, and `Constructor` classes. Because all these classes are members of classes or interfaces, it is logical that they share some functionality. A detailed explanation of the functionality of these methods is included in this section rather than in each of the classes that implement these member interfaces. Examples of the use of these methods and brief descriptions of their functionality are included in each of the classes that implement the `Member` interface. Following is a list of the methods defined by the `Member` interface: `Class getDeclaringClass()` `String getName()` `int getModifiers()` ### The getDeclaringClass() Method
    Class getDeclaringClass()
The `getDeclaringClass()` method returns a `Class` object that represents the class or interface that declared this member. This method is typically used after the `getFields()`, `getMethods()`, or `getConstructors()` method has returned an array of one of the `Field`, `Method`, or `Constructor` classes. Because these methods return member types from superclasses or superinterfaces, `getDeclaringClass()` is required to determine the class to which a member field, method, or constructor belongs. ### The getName() Method
    String getName()
The `getName()` method returns a `String` indicating the name of this member or constructor. ### The getModifiers() Method
    int getModifiers()
The `getModifiers()` method returns the modifiers for the reflected member or constructor. The `int` returned is an encoded representation of some combination of modifiers in a standard order. The Java virtual machine stores modifiers internally in the same format (that is, as encoded `int`s). The `static` `toString()` method of the `Modifier` class can be used to translate an encoded `int` into a string of modifiers. ## The Field class The `Field` class provides access to the fields of a class or object. The term field refers to both instance and class variables. The `Field` object is typically used to get a field or set a field. This list shows the member methods of the `Field` class: `Class getDeclaringClass()` `String getName()` `int getModifiers()` `Class getType()` `boolean equals(Object` obj`)` `String toString()` `Object get(Object` obj`)` `boolean getBoolean(Object` obj`)` `byte getByte(Object` obj`)` `char getChar(Object` obj`)` `short getShort(Object` obj`)` `int getInt(Object` obj`)` `long getLong(Object` obj`)` `float getFloat(Object` obj`)` `double getDouble(Object` obj`)` `int hashCode()` `void set(Object` obj`, Object` value`)` `void setBoolean(Object` obj`, boolean` z`)` `void setByte(Object` obj`, byte` b`)` `void setChar(Object` obj`, char` c`)` `void setShort(Object` obj`, short` s`)` `void setInt(Object` obj`, int` i`)` `void setLong(Object` obj`, long` l`)` `void setFloat(Object` obj`, float` f`)` `void setDouble(Object` obj`, double` d`)` ### The getDeclaringClass() Method
    Class getDeclaringClass()
The `getDeclaringClass()` method returns an instance of `Class` to which the instance or class variable represented by the `Field` object belongs. If an array of `Field` objects is received in response to a call to the `getFields()` method of the `Class` class, the `getDeclaringClass()` method can be used to find the declaring class for a particular `Field` object. For example, if you want to find the `Class` of the third element of an array of `Field` objects defined within the `Panel` class and its superclasses, you can use the `getDeclaringClass()` method in this way:
    Class instance = Class.forName( "java.awt.Panel" );
    Field[] result = instance.getFields();
    System.out.println( result[2].getDeclaringClass().toString() );
The output from this example is as follows:
    interface java.awt.image.ImageObserver
The method did not return a `Class` object representing the `Panel` class as you may have expected. Instead, it returned an `interface`-type class called `ImageObserver` from the image subpackage of `java.awt` because the `getFields()` method also returns public fields from the superclass of the reflected class. ### The getName() Method
    String getName()
The `getName()` method returns the name of the instance or class variable represented by this `Field` object. This example demonstrates the use of `getName()`:
    System.out.println( result[2].getName() );
If we add this line to the example from the description of `getDeclaringClass()` in the preceding section, the output includes a second line: `PROPERTIES`. `PROPERTIES` is the name of the `public` instance variable contained in the third element of the array of `Field` objects. ### The getModifiers() Method
    int getModifiers()
The `getModifiers()` method returns an `int` value that represents the set of modifiers found in the definition of the field represented by the `Field` object. This example demonstrates the use of the `getModifiers()` method:
    Class instance = Class.forName("java.awt.Event");
    Field field = instance.getField("id");
    System.out.println(Modifier.toString(field.getModifiers()));
Because the instance variable of class `java.awt.Event` is `public`, this example results in the following output: public ### The getType() Method
    Class getType()
The `getType()` method returns the type of field represented by the `Field` object as a `Class` object. The following example demonstrates the use of this method on a `Field` object:
    Class instance = Class.forName("java.awt.Event");
    Field field = instance.getField("id");
    System.out.println( field.getType().toString() );
In this example, the `Field` object represents the instance variable `"id"` of class `java.awt.Event`. Because its type is `int`, this code outputs the string `"int"`. ### The hashCode() Method
    int hashCode()
The `hashCode()` method returns an integer representation of the class created by taking the exclusive`-OR` of the hashcode of the declaring class and the name of the field represented by this `Field` object. The following example returns the hashcode for the `id` field in the `Event` class:
    Class class = Class.forName("java.awt.Event");
    Field field = class.getField("id");
    System.out.println( field.hashCode() );
### The equals() Method
    boolean equals(Object obj)
The `equals()` method compares two `Field` objects for equality. The two objects are equal and the method returns `true` if they both have the same declaring class and the same name. The following example shows a case in which two `Field` objects are defined within the class `Event`. Because they both exist in the same class, they cannot be equal.
    Class instance = Class.forName( "java.awt.Event" );
    Field[] result = instance.getFields();
    System.out.println( result[2].equals( result[3]  ) );
This code outputs `false` because these two modifiers do not have the same name. ### The toString() Method
    String toString()
The `toString()` method overrides the `Object` class `toString()` method. The string returned from this method includes all the modifiers that describe the field represented by the `Field` object. The modifiers are followed by the return type, package name, and class. The name of the instance variable or class variable is then appended to the end of the class. In this example, the `toString()` method is called on the second element of the array of `Field` objects from the `Event` class:
    Class instance = Class.forName( "java.awt.Event" );
    Field[] result = instance.getFields();
    System.out.println( result[2].toString()  );
The following output is printed:
    public final static int java.awt.image.ImageObserver.PROPERTIES
In general, this method first outputs the modifier `public`, `protected`, or `private`, then outputs `static`, `final`, `transient`, or `volatile`, and finally outputs the type. The modifiers are followed by the fully qualified class name, a period (.), and the name of the field represented by the `Field` object. ### The get(), getBoolean(), getByte(), getChar(), getShort(), getInt(), getLong(), getFloat(), and getDouble() Methods
    Object get(Object obj)
    boolean getBoolean(Object obj)
    byte getByte(Object obj)
    char getChar(Object obj)
    short getShort(Object obj)
    int getInt(Object obj)
    long getLong(Object obj)
    float getFloat(Object obj)
    double getDouble(Object obj)
You can use the `get()` method to get the value of the instance or class variable represented by a `Field` object. The `Object` argument of this method specifies the object from which the value should be taken. The first method always returns a reference to an `Object`. If the field value contains a primitive type, that type is turned into a reference using an appropriate type wrapper class. The remaining get methods return specific primitive types without wrapping the primitive type. For this reason, they operate more efficiently than the `get()` method when returning a primitive type. Java access rules still control access to instance variables. Private variables remain private to an object. If an attempt to access a nonaccessible instance or class variable is made, the `get()` method throws an `IllegalAccessException` exception. In the following example, a value is retrieved from an object of class `Button`:
    Class instance = Class.forName( "java.awt.Button" );
    Field result = instance.getField("label");
    Button button = new Button("This is a label.");
    System.out.println( result.get( button ) );
This example prints the following output:
    This is a label
Because the `label` field of the `Button` class is `protected`, the preceding code has to be declared as part of the `java.awt` package to avoid throwing an `IllegalAccessException`. If the field is `public` rather than `protected`, this is not a concern. ### The set(), setBoolean(), setByte(), setChar(), setShort(), setInt(), setLong(), setFloat(), and setDouble() Methods
    Object set(Object obj, Object value)
    void setBoolean(Object obj, boolean z)
    void setByte(Object obj, byte b)
    void setChar(Object obj, char c)
    void setShort(Object obj, short s)
    void setInt(Object obj, int i)
    void setLong(Object obj, long l)
    void setFloat(Object obj, float f)
    void setDouble(Object obj, double d)
The `set()` method can be used to set the value of an instance variable or class variable represented by the `Field` object. A value is set within the object specified by the `Object` argument. The `set()` method takes a reference to an object as its second parameter; the remaining methods take one of the primitive types as their second parameter. As is true with the get methods, the set methods that return a specific primitive type operate more efficiently than the `set()` method itself because they do not take the extra step of unwrapping the value to be set when dealing with primitive types. The following example shows how the `label` field of the `Button` class can be set within an instance of that class:
    Class instance = Class.forName( "java.awt.Button" );
    Field result = instance.getDeclaredField("label");
    Button button = new Button("This is a label.");
    result.set(button,"This is a set label");
    System.out.println( result.get( button ) );
In this example, a `Field` object representing the field `label` is returned using the `getDeclaredField()` method. The `getField()` method would not work in this case because the instance variable is protected. In addition, to gain access to the `label` field, this code segment must declare itself as part of the `java.awt` package. After the `Field` object is created, a new instance of `Button` is created. The `set()` method sets the `label` field of this object to a new value by passing a reference to the `Button` object as the first parameter and the new value as the second parameter. In a call to the `set()` method, if the second value happens to be an object of some primitive type, the object is automatically unwrapped. The new value in the `label` field is then printed by accessing the `Field` object with the `get()` method. The example prints the following line:
    This is a set label
## The Method Class The `Method` class provides access to a method of a class or interface. The method represented by the `Method` object can be an `abstract`, `static`, or `instance` method. As with the `Field` and `Class` classes, instances of the `Method` class can be created only by the Java virtual machine; these instances are always `final`. The `Method` object can be used to get information about the reflected method; the `Method` object can also be used to invoke that method on an instance of the declaring class. All the methods of the `Method` class are listed here: `Class getDeclaringClass()` `String getName()` `int getModifiers()` `Class getReturnType()` `Class[] getParameterTypes()` `Class[] getExceptionTypes()` `boolean equals(Object` obj`)` `int hashCode()` `String toString()` `Object invoke(Object` obj`, Object[]` args`)` ### The getDeclaringClass() Method
    Class getDeclaringClass()
The `getDeclaringClass()` method returns a `Class` object that represents the class in which the reflected method is declared. This method can be used as in this example:
    Class instance = Class.forName("java.lang.String");
    Class[] array = new Class[2];
    array[0] = Class.forName("java.lang.String");
    array[1] = Integer.TYPE;
    Method method = instance.getMethod("indexOf",array);
    System.out.println(method.getDeclaringClass().getName());
In this example, `getDeclaringClass()` returns a `Class` object representing the declaring class for the `indexOf(String, int)` method of the `String` class. The name of the class is printed as output: java.lang.String NOTE: The first four lines of code in the preceding example are used in the descriptions of the rest of the methods of the `Method` class. ### The getName() Method
    String getName()
The `getName()` method returns the name of the reflected method as a string. The `getName()` method can be used as follows:
    System.out.println( method.getName() );
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints the name of the method: indexOf ### The getModifiers() Method
    int getModifiers()
The `getModifiers()` method returns an `int` representing the set of modifiers that belongs to the reflected method. This method can be used in the following way:
    System.out.println(Modifier.toString(method.getModifiers()));
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints the modifiers of this method: public ### The getReturnType() Method
    Class getReturnType()
The `getReturnType()` method returns a `Class` object representing the return type for the reflected method. The following example demonstrates how this method can be used:
    System.out.println(method.getReturnType().toString());
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints the return type of this method: int ### The getParameterTypes() Method
    Class[] getParameterTypes()
The `getParameterTypes()` method returns an array of `Class` objects that represent the order and types of the parameters in the reflected method. The method is used as follows:
    Class[] params = method.getParameterTypes();
    for(int c=0;c<params.length;c++)
    {System.out.println(params[c].toString());}
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints the parameter types of this method in the correct order:
    class java.lang.String

    int
### The getExceptionTypes() Method
    Class[] getExceptionTypes()
The `getExceptionTypes()` method returns an array of `Class` objects that represent the exceptions thrown by the reflected method. This method can be used as follows:
    Class[] params = method.getExceptionTypes();
    for(int c=0;c<params.length;c++)
    {System.out.println(params[c].toString());}
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints nothing because the reflected method throws no exceptions and an array of length zero is returned from the `getParameterTypes()` method. ### The equals() Method
    boolean equals(Object obj)
The `equals()` method tests two `Method` objects for equality. Two `Method` objects are equal if they have the same declaring class, name, and formal parameter types. ### The hashCode() Method
    int hashCode()
The `hashCode()` method returns a hashcode for the reflected method. The hashcode is an exclusive`-OR` of the hashcodes of the reflected method's declaring class and the reflected method's name. The following example demonstrates how this method can be used:
    System.out.println( method.hashCode() );
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints the following:
    74190650
### The toString() Method
    String toString()
The `toString()` method returns a string representation of the reflected field with modifiers, return type, package name, method name, and parameters. In general, this method first outputs the modifier `public`, `protected`, or `private`, then outputs `static`, `final`, `transient`, or `volatile`, and finally outputs the return type. The modifiers are followed by a fully qualified class name, a period (`.`), and the name of the method represented by this `Method` object. A set of parentheses at the end encloses a list of fully qualified type names representing the methods parameter list. Finally, the word `throws` is tacked on to the end with a comma-separated list of all the exceptions thrown by this method. The following example shows how the `toString()` method can be used:
    System.out.println( method.toString() );
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints this line:
    public int java.lang.String.indexOf(java.lang.String, int)
### The invoke() Method
    Object invoke(Object obj, Object[] args)
The `invoke()` method is used to call a method on an object. The object name is passed as the first parameter to the method. The second parameter is an array with the arguments to be sent to the method. The following example shows how this method is used:
    String string = new String("The day's soma ration");
    Object[] arguments = { "soma", new Integer(0) };
    System.out.println(method.invoke(string,arguments));
If the variable `method` reflects the `indexOf(String, int)` method of the `String` class (refer back to the `getDeclaringClass()` example), this code segment prints `10` because the word `soma` is found at position 10 in the string `The day's soma ration`. ## The Constructor Class The `Constructor` class provides access to a constructor of a class. Instances of the `Constructor` class can be created only by the Java virtual machine; these instances are always `final`. The `Constructor` object can be used to get information about the reflected constructor or to create new instances of the declaring class. All the methods of the `Constructor` class are listed here: `Class getDeclaringClass()` `String getName()` `int getModifiers()` `Class[] getParameterTypes()` `Class[] getExceptionTypes()` `boolean equals(Object` obj`)` `int hashCode()` `String toString()` `Object newInstance(Object` initargs`[])` ### The getDeclaringClass() Method
    Class getDeclaringClass()
The `getDeclaringClass()` method returns a `Clas`s object representing the class in which the reflected constructor is declared. This method can be used as follows:
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    System.out.println(constructors[0].getDeclaringClass().getName());
In this example, the `getDeclaringClass()` method is called on the first `Constructor` object in the array. The `getName()` method of the `Class` object name returns `java.lang.String`. NOTE: The first two lines of code in this example are used in the descriptions of the rest of the methods of the `Constructor` class. ### The getName() Method
    String getName()
The `getName()` method returns the name of the constructor reflected by the `Constructor` object. This is the same name as the declaring class. The `getName()` method in the following example returns the string `java.lang.String`:
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    System.out.println(constructors[0].getName());
### The getModifiers() Method
    int getModifiers()
The `getModifiers()` method returns an `int` that represents the modifiers for the constructor reflected by this `Constructor` object. The following example prints `public` as the modifier for the first constructor from the `java.lang.String` class:
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    System.out.println(Modifier.toString(constructors[0].getModifiers()));
### The getParameterTypes() Method
    Class[] getParameterTypes()
The `getParameterTypes()` method returns an ordered list of all the parameters of a constructor in an array of `Class` objects. The following example shows how the `getParameterTypes()` method is used:
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    Class[] parameters = constructors[1].getParameterTypes();
    System.out.println(parameters[0].getName());
The only parameter in the second constructor in the `String` class is a `String` parameter type. This method prints the following output:
    java.lang.String
### The getExceptionTypes() Method
    Class[] getExceptionTypes()
The `getExceptionTypes()` method returns an array of `Class` objects that represent the exceptions thrown by the reflected constructor. This method is used as follows: `System.out.println(constructor.getExceptionTypes());` ### The equals() Method
    boolean equals(Object obj)
The `equals()` method returns `true` if the `Constructor` objects are equal; that is, if they have the same declaring class and the same parameter types, order, and number. The method is used as follows:
    System.out.println(constructor1.equals(constructor2));
This example outputs `true` if `constructor1` and `constructor2` meet the conditions for equality. If not, the method outputs `false`. ### The hashCode() Method
    int hashCode()
The `hashCode()` method overrides the `hashCode()` method defined in class `Object` and returns a hashcode. The returned hashcode is the same as the hashcode of the declaring class. This method is used as shown here:
    System.out.println(constructor1.hashCode());
This example prints the hashcode representing the `constructor1` `Constructor` object. ### The toString() Method
    String toString()
The `toString()` method returns a string representation of the constructor reflected by this `Constructor` object. An example of the use and format of the output string is shown here:
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    System.out.println(constructors[0].toString());
This example sends the following output:
    public java.lang.String()
In general, this method first outputs the modifier `public`, `protected`, or `private`, and then outputs `static`, `final`, `transient`, or `volatile`. The modifiers are followed by a fully qualified class name, a period (`.`), and the name of the method represented by this `Method` object. A set of parentheses at the end encloses a list of fully qualified type names representing the method's parameter list. Finally, the word `throws` is tacked on to the end with a comma-separated list of all the exceptions thrown by this method. ### The newInstance() Method
    public Object newInstance(Object initargs[]))
The `newInstance()` method can be used to create a new instance of the `Constructor` object's declaring class. The method cannot instantiate instances of abstract classes or create a new instance with a constructor that has been declared `private`. The new object is returned if the number of the arguments match.
    Class instance = Class.forName("java.lang.String");
    Constructor[] constructors = instance.getConstructors();
    Object[] arguments = { "We made a new object!" };
    String newObject = (String)constructors[1].newInstance(arguments);
    System.out.println( newObject );
In the preceding example, all the constructors that belong to class `String` are stored in the array `constructors`. The second array element (at index `1`) contains the `String` constructor that takes a string argument. To instantiate the new object, the arguments must be specified in an array of type `Object[]`. The first element of this array is set to the string that is used to construct the new `String` class. Finally, the new instance is created by calling the `newInstance()` method of the appropriate constructor object; the result is stored in the identifier `newObject`. This is a convoluted way to send the following output:
    We made a new object!
## The Array Class The `Array` class provides access to array objects and classes. The following methods can be used to instantiate new array objects and to access or modify elements within arrays: `Object newInstance(Class` componentType`, int` length`)` `int getLength(Object` array`)` `int get(Object` array`, int` index`)` `boolean getBoolean(Object` array`, int` index`)` `byte getByte(Object` array`, int` index`)` `char getChar(Object` array`, int` index`)` `short getShort(Object` array`, int` index`)` `int getInt(Object` array`, int` index`)` `long getLong(Object` array`, int` index`)` `float getFloat(Object` array`, int` index`)` `double getDouble(Object` array`, int` index`)` `void set(Object` array`, int` index`, Object` value`)` `void setBoolean(Object` array`, int` index`, boolean` z`)` `void setByte(Object` array`, int` index`, byte` b`)` `void setChar(Object` array`, int` index`, char` c`)` `void setShort(Object` array`, int` index`, short` s`)` `void setInt(Object` array`, int` index`, int` i`)` `void setLong(Object` array`, int` index`, long` l`)` `void setFloat(Object` array`, int` index`, float` f`)` `void setDouble(Object` array`, int` index`, double` d`)` ### The newInstance() Methods `Object newInstance(Class` componentType, int length) `Object newInstance(Class` componentType, int[] dimensions) The `newInstance()` methods return arrays with the specified component type and dimensions. The first version of the method returns a single dimensional array whose length is specified by the second argument. The second version of the method returns a multidimensional array whose dimensions are specified by the second array argument. Both methods return an array just as if it had been created in the standard way:
    new int[dimensions]
    new int[dimensions][dimensions]
In the following example, a new four-element array of type `String[]` is created using the `Array` class's `newInstance()` method. The elements of the array are then initialized and concatenated in a print statement:
    String[] strings = (String[])Array.newInstance(Class.forName("java.lang.String"),4);
    strings[0] = "I ";
    strings[1] = "am ";
    strings[2] = "human ";
    strings[3] = "not an array! ";
    System.out.println( strings[0] + strings[1] + strings[2] + strings[3] );
The output from this example is shown here: `I am human not an array!` Notice that the returned type had to be cast as type `String[]` because the method returns an array of type `Object`. If the array has to be multidimensional, you can send an array of `int`s as the second argument to the `newInstance()` method. ### The getLength() Method `int getLength(Object` array) The `getLength()` method returns the length of the array argument. If `getLength()` is called on the `strings` object created in the example in the preceding section, the method would return `4` as the length of the array. The following example shows this usage: `strings.getLength``()` ### The get(), getBoolean(), getByte() , getChar(), getShort(), getInt(), getLong(), getFloat(), and getDouble() Methods
    Object get(Object array, int index)
    boolean getBoolean(Object array, int index)
    byte getByte(Object array, int index)
    char getChar(Object array, int index)
    short getShort(Object array, int index)
    int getInt(Object array, int index)
    long getLong(Object array, int index)
    float getFloat(Object array, int index)
    double getDouble(Object array, int index)
The get methods return a value of the array object argument at the index specified by the `int` argument. If the type returned is a primitive type, it is wrapped in its corresponding type wrapper class. Because the methods that get a primitive type do not have to wrap the returned primitive type in a type wrapper, they operate more efficiently. The following example gets the `String` value from the second element of the `strings` array created in the example for the `newInstance()` method, earlier in this section:
    System.out.println( (String)Array.get(strings,1) );
The string `"am"` is printed as the output for this example. ### The set(), setBoolean(), setByte(), setChar(), setShort(), setInt(), setLong(), setFloat(), and setDouble() Methods
    void set(Object array, int index, Object value)
    void setBoolean(Object array, int index, boolean z)
    void setByte(Object array, int index, byte b)
    void setChar(Object array, int index, char c)
    void setShort(Object array, int index, short s)
    void setInt(Object array, int index, int i)
    void setLong(Object array, int index, long l)
    void setFloat(Object array, int index, float f)
    void setDouble(Object array, int index, double d)
These methods set a value of the array object argument at the index specified by the `int` argument. If the value to set is a primitive type, the value sent in must be wrapped in the appropriate type wrapper class. Because the methods that set a primitive type do not have to unwrap the value to be set, they operate more efficiently than the more general `set()` method. The following example resets the second element of the `strings` object created in the example for the `newInstance()` method, earlier in this section:
    Array.set(strings,1,"am not ");
    Array.set(strings,3,"but an array! ");
    System.out.println( strings[0] + strings[1] + strings[2] + strings[3] );
## The Modifier Class The `Modifier` class provides a number of static methods that take an integer as their argument. This integer represents an encoded set of variable or method modifiers. The integer is returned from one of the `getModifier()` methods described earlier in this chapter. The Java virtual machine stores modifiers internally as encoded integers. The `Modifier` class methods return a `boolean` or `String`. Typically, the modifier is being tested to determine whether it contains a specific modifier, or it is being decoded and returned as a string representation. The following list includes all the member methods of the `Modifier` class: `boolean isPublic(int` mod`)` `boolean isPrivate(int` mod`)` `boolean isProtected(int` mod`)` `boolean isStatic(int` mod`)` `boolean isFinal(int` mod`)` `boolean isSynchronized(int` mod`)` `boolean isVolatile(int` mod`)` `boolean isTransient(int` mod`)` `boolean isNative(int` mod`)` `boolean isInterface(int` mod`)` `boolean isAbstract(int` mod`)` `String toString(int` mod`)` These methods test the integer for a modifier of a particular type. For example, the `isPublic()` method tests the integer argument and returns `true` if the integer represents a set of modifiers that contains the `public` modifier. The `toString()` method returns a string of the set of modifiers contained by the integer. This method can be used as follows:
    Modifier.toString( method.getModifiers() );
In this example, `method` is an instance of the `Method` class, and the `getModifiers()` method returns an `int` representing the modifiers declared for the reflected method. The method `toString()` decodes the `int` representation; it first outputs a string with the modifier `public`, `protected`, or `private`, and then outputs `static`, `final`, `transient`, or `volatile`. For example, if the `method` object in the preceding example is declared as `private`, `final`, and `static`, the following string is output: `private static final` ## Summary This chapter described the reflection package new to the Java Development Kit version 1.1. If you are using object serialization or are developing JavaBeans components, you will use this package indirectly. If you happen to be developing debuggers or other applications that require runtime information about, and access to, classes and objects, you may use this package directly. The `Field`, `Method`, `Constructor`, and `Array` classes provide the core functionality for inspection and modification of classes and objects. These classes can be created only by the Java virtual machine. The `Modifier` class contains a number of utility methods that allow you to decode the integer representation of a set of modifiers belonging to a field, method, or class.
| ©Copyright, Macmillan Computer Publishing. All rights reserved.