Reflection on Tiger Blog

Version 2



    New Kids on the Hierarchy
       Reflections on Metadata
       Working with Generics
    Changes to the "Old" API

    Much has been written about the new language features in J2SE 1.5, Tiger. Many, such as the introduction of enums, generics, and metadata, involve changing bytecode. These additions to the language require modifications to existing APIs. One of the APIs most radically affected by these changes is the Reflection API. Reflection has existed since JDK 1.1, and many frameworks, libraries, and utilities have been built upon it. This article examines the modifications to the Reflection API that are now available to the public as part of JDK 1.5 beta 1, and shows how you can take advantage of them in your code.

    New Kids on the Hierarchy

    A few interfaces and exceptions have been added tojava.lang.reflect, as well as tojava.lang. Some "old classes" -- such asClass, Method, Constructor, and others -- have been retrofitted to implement them. In this section we will look at these added interfaces.

    Reflections on Metadata

    The AnnotatedElement interface is implemented by any class that represents an element that may contain annotations (also known as metadata), as specified by JSR-175. TheClass, Constructor, Field,Method, and Package each have been modified to implement AnnotatedElement. The interface specifies methods to retrieve all annotations, annotations by type, annotations declared only in a particular class (i.e., not including superclasses), and also a method to query whether or not a class contains an annotation of a specific type. The following code snippets demonstrate the use of these methods. Note that you must have some knowledge about how annotations work to fully understand this example.

    First, create a custom annotation that we will later examine with reflection.

    package; import java.lang.annotation.Retention; import static java.lang.annotation.RetentionPolicy.*; @Retention(RUNTIME) public @interface SampleAnnotation { public String value(); }

    Next, create a class AnnotatedElementTest and mark it and an instance method aMethod() as being annotated with the SampleAnnotation class you just created:

    @SampleAnnotation("AnnotatedElementTest") public class AnnotatedElementTest { @SampleAnnotation("aMethod") @Deprecated public void aMethod() { } //... }

    You can detect and get a handle to the Classannotations by creating a Class object and invoking the methods is AnnotationPresent() andgetAnnotations(). You can repeat the process for the annotated method. The getAnnotations() method is used to retrieve all of the annotations this method has that are retained until runtime. When you compile and runAnnotatedElementTest, you will notice that@Deprecated is not shown. That is because it's only part of the source code and it's not present, even in the class file. Here's the listing for AnnotatedElementTest.

    package; import java.lang.annotation.Annotation; import java.lang.reflect.Method; @SampleAnnotation("AnnotatedElementTest") public class AnnotatedElementTest { @SampleAnnotation("aMethod") @Deprecated public void aMethod() { } public static void main(String[] args) throws Exception { Class<AnnotatedElementTest> clazz = AnnotatedElementTest.class; System.out.println(clazz.isAnnotationPresent(SampleAnnotation.class)); System.out.println(clazz.getAnnotation(SampleAnnotation.class)); Method method = clazz.getMethod("aMethod"); for (Annotation a : method.getAnnotations()) { System.out.println(a); } } }
    Working with Generics

    The following additions to the Reflection APIs allow you to obtain information about generics.

    • Type: This new marker interface was introduced in order to represent all of the types that can be used in Java. These include raw types; i.e., Classes, parameterized types, array types, type variables, and primitive types. java.lang.Class, for example, has been retrofitted to implement this new interface.

    • TypeVariable: This interface represents type variables of all kinds. For example, inClass<T>, T is a type variable. There are methods for obtaining the name of the variable, its bounds (superclasses) and its GenericDeclaration -- the last one is explained below.

    • GenericDeclaration: This interface, implemented by Class, Constructor andMethod, indicates they might declareTypeVariables. It defines a sole method,getTypeParameters(), returning an array containing all of the TypeVariables in the order in which they were originally declared.

    • ParameterizedType: Represents a parameter type with a generic type, such as Class<T>. It has methods that allow retrieval of the actual type arguments (T, in the previous example), to get the enclosing class of this type, if any, and to retrieve the raw type declared (Class, in this case).

    • GenericArrayType: Represents an array of a generic type, such as T[]. It has a method that allows one to retrieve the component type of the array (in this case,T).

    • WildcardType: Represents a type that uses wildcards, such as ? or ? extends T. The methods provided return the lower bounds of the type (in T super Integer, Integer would be a lower bound) and the upper bounds (for ?, Object is the upper bound).

    • MalformedParameterizedTypeException: This exception is thrown if the parameterized type cannot be instantiated at runtime for some reason. It is aRuntimeException.

    • GenericSignatureFormatError: This exception indicates a low-level bytecode error and it should be rare. However, using JDK 1.5 beta 1, is possible to get this error when you try to call getTypeParameters() in an instance of a system class that defines a non-trivial type variable, such as<T extends Class<T>>. An example of such a class instance is TypeVariable.class.

    • TypeNotPresentException: This exception can occur when some code tries to access a type using its name, but it cannot be found. It is the only new exception related to reflection that is not defined in the expected package, but injava.lang.

    Here is an example of how to use some of these classes and interfaces related to generics.

    package; import java.lang.reflect.GenericArrayType; import java.lang.reflect.Method; import java.lang.reflect.ParameterizedType; import java.lang.reflect.Type; import java.lang.reflect.TypeVariable; import java.lang.reflect.WildcardType; import java.util.Map; // This class declaration defines a type variable T public class GenericsTest<T extends Thread> { // This method is used in the reflection example below public void aMethod(Class<? extends T> clazz1, Class<T> clazz2, T[] ts) { } // Prints information about a type variable private static void print(TypeVariable v) { System.out.println("Type variable"); System.out.println("Name: " + v.getName()); System.out.println("Declaration: " + v.getGenericDeclaration()); System.out.println("Bounds:"); for (Type t : v.getBounds()) { print(t); } } // Prints information about a wildcard type private static void print(WildcardType wt) { System.out.println("Wildcard type"); System.out.println("Lower bounds:"); for (Type b : wt.getLowerBounds()) { print(b); } System.out.println("Upper bounds:"); for (Type b : wt.getUpperBounds()) { print(b); } } // Prints information about a parameterized type private static void print(ParameterizedType pt) { System.out.println("Parameterized type"); System.out.println("Owner: " + pt.getOwnerType()); System.out.println("Raw type: " + pt.getRawType()); for (Type actualType : pt.getActualTypeArguments()) { print(actualType); } } // Prints information about a generic array type private static void print(GenericArrayType gat) { System.out.println("Generic array type"); System.out.println("Type of array: "); print(gat.getGenericComponentType()); } /** * Prints information about a type. The nested * if/else-if chain calls the * appropriate overloaded print method for the * type. If t is just a Class, * we print it directly. */ private static void print(Type t) { if (t instanceof TypeVariable) { print((TypeVariable)t); } else if (t instanceof WildcardType) { print((WildcardType)t); } else if (t instanceof ParameterizedType) { print((ParameterizedType)t); } else if (t instanceof GenericArrayType) { print((GenericArrayType)t); } else { System.out.println(t); } } public static void main(String[] args) throws Exception { // Some classes we are going to play with Class[] classes = new Class[] {Class.class, Map.class, GenericsTest.class}; // Iterate the array for each class instance... for (Class clazz : classes) { // Prints its name and ... System.out.println("Class: " + clazz); // Iterate for each type variable defined by this class for (TypeVariable v : clazz.getTypeParameters()) { print(v); } System.out.println(); } System.out.println("Reflective information " + "about the parameters of aMethod"); // Iterate for each method... for (Method method : GenericsTest.class.getDeclaredMethods()) { // Until we find aMethod if (method.getName().equals("aMethod")) { // Then, go over all parameters ... for (Type t : method.getGenericParameterTypes()) { System.out.println("Parameter:"); // And print reflexive information about them print(t); System.out.println(); } break; } } } }

    Changes to the "Old" API

    One thing most people erroneously assume is that they will be able to extract information about the actual binding of a type variable once they have a variable of a parameterized type. For example, if there is a method that accepts as a parameter that is declared as Collection<E>, inside of the method it is impossible to know what type actually is being used forE. That happens because generics are implemented in Java using erasure, which means that the actual type information is lost. There is no way to find what type was actually used to represent a type variable, even if you think that intentionally adding a method with this information would be possible. An example is shown below:

    public class GenericClass<E> { // some code public Class<E> getElementType() { return E.class; } //more code }

    This code doesn't compile, since information aboutE is defined in runtime and erasured, while a reference to .class is statically resolved. That said, let's consider which changes have been made to the "old classes" that have been part of the API before Tiger:

    • Member: This interface, which is implemented by Class, Field and Method, now defines a new method, isSynthetic(). According to its Javadoc, it "Returns true if this member was introduced by the compiler and returns false otherwise&quot.

    • Proxy: getProxyClass() had its signature changed to accept a varargsClass parameter for interfaces instead of the original array one.

    • Class: java.lang.Class now looks scarier than ever if you don't have a clue about generics. Even its declaration has changed to include a type variable,T, for the actual class it represents. This allows some interesting reflexive constructions and methods to appear, such as the new cast(Object) method. This method takes an object and returns an instance of T. In code, it works like this:

      Class<Serializable> cs = Serializable.class; // more code ... Object o = ...; Serializable s = cs.cast(o);

      Several methods that accepted arrays of Class have been retrofitted to support varargs, such asgetConstructor, getDeclaredConstructor,getDeclaredMethod, and getMethod. This makes it easier to call these methods, as shown below:

      // This now works for no-args methods: // It is equivalent to getMethod("aMethod", new Class[] {}); Method m1 = clazz.getMethod("aMethod"); // And this for methods that takes many arguments. // It is equivalent to //getMethod("aMethod", new Class[] {String.class, Object.class}); Method m2 = clazz.getMethod("aMethod", String.class, Object.class);

      Also, getEnclosingConstructor() andgetEnclosingMethod() are useful for retrieving the instance of the constructor or method where a local class or an anonymous inner class have been defined inside. They only return meaningful values if called in Class instances representing these two types of classes; otherwise, they returnnull.

      The getEnumConstants() method returns a generic array type -- T[] -- with all of the declared enum instances, given that this instance represents an Enum(i.e., returns true for the also newisEnum() method).

      The getGenericInterfaces() andgetGenericSuperclass() methods are useful if you implement or extend a parameterized type, such asList<E>. These methods return arrays ofType and Type, respectively, allowing access to the generic declaration of a superclass or superinterface. However, as the example inGenericsTest shows, dealing with different subclasses of Type requires some ugly code, since it is only a marker interface (i.e., it does not define any methods).

      A minor change has been made to getSuperclass(). Now it returns Class<? super T> instead of the raw type. Most developers will not find it particularly useful, but it is an example of better type safety added by generics.

      The newInstance() method now returns a type variable, T. This eliminates the need for a cast in some common uses, such as in:

      // Supposing E represents an interface ... // If we get an instance of an implementation class such as: Class<E> clazz; // We now can simply do: E e = clazz.newInstance();
    • Field: Trivial changes have been made to this class. A new getter method has been added --isEnumConstant() -- as well asgetGenericType(), which is useful if the field's type is a type variable or a parameterized type.

    • Constructor and Method:Constructor's changes are a subset of the ones made toMethod, so they are grouped for brevity.getGenericExceptionTypes() andgetGenericParameterTypes() return arrays ofType, allowing access to parameterized types that might be part of the method/constructor signature.

      The getParameterAnnotations() method return a bi-dimensional array of Annotations present in each parameter type. The first dimension represents each parameter, and the second one its annotations.

      The isVarArgs() method indicates if this constructor/method takes a varargs parameter. These are the methods both have in common.

      One method in Constructor,newInstance, has been changed to acceptvarargs as its parameter type. Again, this change is intended to make easier to call this method.

      Changes exclusive to Method include the addition ofgetGenericReturnType(), for return types involving generics, and a isBridge() method, which has this puzzling Javadoc description: "Returns true if and only if this method is a bridge method as defined by the Java Language Specification." A new version of invoke that takes its args parameter as varargsinstead of an array of Object is also provided in order to make the API simpler.


    Significant changes have been made to Java in order to make it more powerful and expressive. However, the side effect is the increased difficulty in using some Java APIs, especially Reflection, which must provide support for nearly all enhancements that require changes to bytecode. Luckily, as developers use the new API and have more resources available about the changes, such as this article, there will be more pros than cons.