Key Classes of the Reflection API

To accomplish the task of introspection, the Java API provides java.lang.Class and several classes in the java.lang.reflect package, including Constructor, Method, and Field. These classes are used to obtain information about their respective characteristics from an object. The following sections introduce you to the three key classes in the java.lang.reflect package. This discussion covers the major methods of each class (refer to the Java API documentation for a complete listing). Examples later in the chapter build on this introduction to the Reflection API to demonstrate how you use these classes in conjunction with java.lang.Class to support runtime discovery in your programs.

The Constructor Class

A Constructor instance provides information about a particular class constructor and allows you to call that constructor to instantiate an object. If you know the name of a class and the parameter lists of its constructors prior to runtime, you don't need to use Constructor to create an instance. As you've seen starting in Chapter 7, "Classes," you only need to use the new operator and specify the constructor name and arguments in that case. However, if you are writing a program that is required to load a class that is not known prior to runtime and create instances of it using constructors that accept arguments, it is Constructor that makes this possible.

Note

You can access no-argument constructors to create an object using the newInstance method of Class instead of using Constructor. This approach is discussed later in the chapter.

You'll see later how to obtain a Constructor instance for a class, but for now, look at the methods that are available to you once you have a reference to such an instance. First, a Constructor object allows you to query it for the associated constructor's class and the constructor name.

 public Class getDeclaringClass() public String getName() 

Beyond its name, you can learn more about a constructor's signature using methods that report the modifiers and exceptions included in its declaration.

 public int getModifiers() public Class[] getExceptionTypes() 

The integer value returned by getModifiers can be decoded by calling static methods, such as isPublic, provided by java.lang.reflect.Modifier. The Class array returned by getExceptionTypes includes an entry for each exception listed in the throws clause of the constructor you are inspecting.

The more interesting Constructor methods are those that allow you to instantiate an object. First, you can discover the parameter types, in their declared order, found in the constructor's parameter list.

 public Class[] getParameterTypes() 

Using this knowledge, you can create an object using Constructor by calling its newInstance method.

 public Object newInstance( Object[] initargs )   throws InstantiationException, IllegalAccessException,          IllegalArgumentException, InvocationTargetException 

This method accepts an array of parameters and passes them to the associated constructor to perform the instantiation. The exceptions declared as thrown represent the possible problems that might occur, such as an attempt to call a constructor without having the required access, a mismatch of passed parameters with the parameter list, or an attempt to instantiate an abstract class. You'll see the newInstance method used in the later examples.

The Method Class

A Method instance provides information about a particular method declared by a class or interface. Similar to Constructor, Method is useful when you need to call a method that is not known to your program until runtime. Given that methods and constructors have much in common, the set of methods declared by Method is nearly the same as the set declared by Constructor. The first difference results from the fact that methods, unlike constructors, can return a value. Reflection allows you to determine a method's return type using getReturnType declared in Method.

 public Class getReturnType() 

The other difference addressed by Method is that you call a method on a particular instance (or its class if it's static), where a constructor is instead used to create an instance. In place of newInstance, Method declares invoke to support method calls using Reflection.

 public Object invoke( Object targetObj, Object[] args )   throws IllegalAccessException, IllegalArgumentException,          InvocationTargetException 

When you call invoke, you pass the instance on which to invoke the method and an array of method arguments. If the method you want to invoke is static, you can pass null for the target object.

The Field Class

A Field instance provides information about a class or instance field declared by an interface or class. Field allows you to dynamically discover the characteristics of a field, query its value, and even change its value. Similar to the other classes you've seen so far, Field supports getDeclaringClass, getModifiers, and getName methods to provide access to basic information. Somewhat like the getReturnType method of the Method class, Field allows you to determine the declared type of an associated field.

 public Class getType() 

The remaining methods of Field are mostly related to retrieving and setting a field's value. This can be done in a manner that is either general or specific with respect to type. First, look at the general methods.

 public Object get( Object targetObj )   throws IllegalArgumentException, IllegalAccessException public void set( Object targetObj, Object newValue )   throws IllegalArgumentException, IllegalAccessException 

In these methods, the targetObj parameter is the object whose field is to be accessed. This parameter is ignored for static fields, so you can pass null in that situation. As implied by the signatures, get returns the value of the field for the target object and set assigns the value of the argument newValue to the corresponding field. These methods treat the field type generically as Object, but you can also use methods that work with a field using a more specific type. These methods take the following form, where Type is one of Boolean, Byte, Char, Double, Float, Int, Long, or Short and primitiveType is the primitive type corresponding to Type.

 public  primitiveType  get  Type  ( Object targetObj )   throws IllegalArgumentException, IllegalAccessException public void set  Type  ( Object targetObj, primitiveType newValue )   throws IllegalArgumentException, IllegalAccessException