Discovering Class Members
There are two categories of methods provided in Class for accessing fields, methods, and constructors: methods which enumerate these members and methods which search for particular members. Also there are distinct methods for accessing members declared directly on the class versus methods which search the superinterfaces and superclasses for inherited members. The following tables provide a summary of all the member-locating methods and their characteristics.
| Class API | List of members? | Inherited members? | Private members? |
|---|---|---|---|
| getDeclaredField() | no | no | yes |
| getField() | no | yes | no |
| getDeclaredFields() | yes | no | yes |
| getFields() | yes | yes | no |
| Class API | List of members? | Inherited members? | Private members? |
|---|---|---|---|
| getDeclaredMethod() | no | no | yes |
| getMethod() | no | yes | no |
| getDeclaredMethods() | yes | no | yes |
| getMethods() | yes | yes | no |
| Class API | List of members? | Inherited members? | Private members? |
|---|---|---|---|
| getDeclaredConstructor() | no | N/A 1 | yes |
| getConstructor() | no | N/A 1 | no |
| getDeclaredConstructors() | yes | N/A 1 | yes |
| getConstructors() | yes | N/A 1 | no |
1 Constructors are not inherited.
Given a class name and an indication of which members are of interest, the ClassSpy example uses the get*s() methods to determine the list of all public elements, including any which are inherited.
import java.lang.reflect.Constructor; import java.lang.reflect.Field; import java.lang.reflect.Method; import java.lang.reflect.Member; import static java.lang.System.out; enum ClassMember < CONSTRUCTOR, FIELD, METHOD, CLASS, ALL >public class ClassSpy < public static void main(String. args) < try < Classc = Class.forName(args[0]); out.format("Class:%n %s%n%n", c.getCanonicalName()); Package p = c.getPackage(); out.format("Package:%n %s%n%n", (p != null ? p.getName() : "-- No Package --")); for (int i = 1; i < args.length; i++) < switch (ClassMember.valueOf(args[i])) < case CONSTRUCTOR: printMembers(c.getConstructors(), "Constructor"); break; case FIELD: printMembers(c.getFields(), "Fields"); break; case METHOD: printMembers(c.getMethods(), "Methods"); break; case CLASS: printClasses(c); break; case ALL: printMembers(c.getConstructors(), "Constuctors"); printMembers(c.getFields(), "Fields"); printMembers(c.getMethods(), "Methods"); printClasses(c); break; default: assert false; >> // production code should handle these exceptions more gracefully > catch (ClassNotFoundException x) < x.printStackTrace(); >> private static void printMembers(Member[] mbrs, String s) < out.format("%s:%n", s); for (Member mbr : mbrs) < if (mbr instanceof Field) out.format(" %s%n", ((Field)mbr).toGenericString()); else if (mbr instanceof Constructor) out.format(" %s%n", ((Constructor)mbr).toGenericString()); else if (mbr instanceof Method) out.format(" %s%n", ((Method)mbr).toGenericString()); >if (mbrs.length == 0) out.format(" -- No %s --%n", s); out.format("%n"); > private static void printClasses(Class c) < out.format("Classes:%n"); Class[] clss = c.getClasses(); for (Class cls : clss) out.format(" %s%n", cls.getCanonicalName()); if (clss.length == 0) out.format(" -- No member interfaces, classes, or enums --%n"); out.format("%n"); > > This example is relatively compact; however the printMembers() method is slightly awkward due to the fact that the java.lang.reflect.Member interface has existed since the earliest implementations of reflection and it could not be modified to include the more useful getGenericString() method when generics were introduced. The only alternatives are to test and cast as shown, replace this method with printConstructors() , printFields() , and printMethods() , or to be satisfied with the relatively spare results of Member.getName() .
Samples of the output and their interpretation follows. User input is in italics.
$ java ClassSpy java.lang.ClassCastException CONSTRUCTOR Class: java.lang.ClassCastException Package: java.lang Constructor: public java.lang.ClassCastException() public java.lang.ClassCastException(java.lang.String)
Since constructors are not inherited, the exception chaining mechanism constructors (those with a Throwable parameter) which are defined in the immediate super class RuntimeException and other super classes are not found.
$ java ClassSpy java.nio.channels.ReadableByteChannel METHOD Class: java.nio.channels.ReadableByteChannel Package: java.nio.channels Methods: public abstract int java.nio.channels.ReadableByteChannel.read (java.nio.ByteBuffer) throws java.io.IOException public abstract void java.nio.channels.Channel.close() throws java.io.IOException public abstract boolean java.nio.channels.Channel.isOpen()
The interface java.nio.channels.ReadableByteChannel defines read() . The remaining methods are inherited from a super interface. This code could easily be modified to list only those methods that are actually declared in the class by replacing get*s() with getDeclared*s() .
$ java ClassSpy ClassMember FIELD METHOD Class: ClassMember Package: -- No Package -- Fields: public static final ClassMember ClassMember.CONSTRUCTOR public static final ClassMember ClassMember.FIELD public static final ClassMember ClassMember.METHOD public static final ClassMember ClassMember.CLASS public static final ClassMember ClassMember.ALL Methods: public static ClassMember ClassMember.valueOf(java.lang.String) public static ClassMember[] ClassMember.values() public final int java.lang.Enum.hashCode() public final int java.lang.Enum.compareTo(E) public int java.lang.Enum.compareTo(java.lang.Object) public final java.lang.String java.lang.Enum.name() public final boolean java.lang.Enum.equals(java.lang.Object) public java.lang.String java.lang.Enum.toString() public static T java.lang.Enum.valueOf (java.lang.Class,java.lang.String) public final java.lang.Class java.lang.Enum.getDeclaringClass() public final int java.lang.Enum.ordinal() public final native java.lang.Class java.lang.Object.getClass() public final native void java.lang.Object.wait(long) throws java.lang.InterruptedException public final void java.lang.Object.wait(long,int) throws java.lang.InterruptedException public final void java.lang.Object.wait() hrows java.lang.InterruptedException public final native void java.lang.Object.notify() public final native void java.lang.Object.notifyAll()
In the fields portion of these results, enum constants are listed. While these are technically fields, it might be useful to distinguish them from other fields. This example could be modified to use java.lang.reflect.Field.isEnumConstant() for this purpose. The EnumSpy example in a later section of this trail, Examining Enums, contains a possible implementation.
In the methods section of the output, observe that the method name includes the name of the declaring class. Thus, the toString() method is implemented by Enum , not inherited from Object . The code could be amended to make this more obvious by using Field.getDeclaringClass() . The following fragment illustrates part of a potential solution.
Trail: The Reflection API
Reflection is commonly used by programs which require the ability to examine or modify the runtime behavior of applications running in the Java virtual machine. This is a relatively advanced feature and should be used only by developers who have a strong grasp of the fundamentals of the language. With that caveat in mind, reflection is a powerful technique and can enable applications to perform operations which would otherwise be impossible.
Extensibility Features An application may make use of external, user-defined classes by creating instances of extensibility objects using their fully-qualified names. Class Browsers and Visual Development Environments A class browser needs to be able to enumerate the members of classes. Visual development environments can benefit from making use of type information available in reflection to aid the developer in writing correct code. Debuggers and Test Tools Debuggers need to be able to examine private members on classes. Test harnesses can make use of reflection to systematically call a discoverable set APIs defined on a class, to insure a high level of code coverage in a test suite.
Drawbacks of Reflection
Reflection is powerful, but should not be used indiscriminately. If it is possible to perform an operation without using reflection, then it is preferable to avoid using it. The following concerns should be kept in mind when accessing code via reflection.
Performance Overhead Because reflection involves types that are dynamically resolved, certain Java virtual machine optimizations can not be performed. Consequently, reflective operations have slower performance than their non-reflective counterparts, and should be avoided in sections of code which are called frequently in performance-sensitive applications. Security Restrictions Reflection requires a runtime permission which may not be present when running under a security manager. This is in an important consideration for code which has to run in a restricted security context, such as in an Applet. Exposure of Internals Since reflection allows code to perform operations that would be illegal in non-reflective code, such as accessing private fields and methods, the use of reflection can result in unexpected side-effects, which may render code dysfunctional and may destroy portability. Reflective code breaks abstractions and therefore may change behavior with upgrades of the platform.
Trail Lessons
This trail covers common uses of reflection for accessing and manipulating classes, fields, methods, and constructors. Each lesson contains code examples, tips, and troubleshooting information.
Classes This lesson shows the various ways to obtain a Class object and use it to examine properties of a class, including its declaration and contents. Members This lesson describes how to use the Reflection APIs to find the fields, methods, and constructors of a class. Examples are provided for setting and getting field values, invoking methods, and creating new instances of objects using specific constructors. Arrays and Enumerated Types This lesson introduces two special types of classes: arrays, which are generated at runtime, and enum types, which define unique named object instances. Sample code shows how to retrieve the component type for an array and how to set and get fields with array or enum types.
The examples in this trail are designed for experimenting with the Reflection APIs. The handling of exceptions therefore is not the same as would be used in production code. In particular, in production code it is not recommended to dump stack traces that are visible to the user.
Package java.lang.reflect
Provides classes and interfaces for obtaining reflective information about classes and objects. Reflection allows programmatic access to information about the fields, methods, and constructors of loaded classes, and the use of reflected fields, methods, and constructors to operate on their underlying counterparts, within encapsulation and security restrictions.
Classes in this package, along with java.lang.Class accommodate applications such as debuggers, interpreters, object inspectors, class browsers, and services such as Object Serialization and JavaBeans that need access to either the public members of a target object (based on its runtime class) or the members declared by a given class.
AccessibleObject allows suppression of access checks if the necessary ReflectPermission is available.
Array provides static methods to dynamically create and access arrays.
Java programming language and JVM modeling in core reflection
The components of core reflection, which include types in this package as well as Class , Package , and Module , fundamentally present a JVM model of the entities in question rather than a Java programming language model. A Java compiler, such as javac , translates Java source code into executable output that can be run on a JVM, primarily class files. Compilers for source languages other than Java can and do target the JVM as well.
The translation process, including from Java language sources, to executable output for the JVM is not a one-to-one mapping. Structures present in the source language may have no representation in the output and structures not present in the source language may be present in the output. The latter are called synthetic structures. Synthetic structures can include methods, fields, parameters, classes and interfaces. One particular kind of synthetic method is a bridge method. It is possible a synthetic structure may not be marked as such. In particular, not all class file versions support marking a parameter as synthetic. A source language compiler generally has multiple ways to translate a source program into a class file representation. The translation may also depend on the version of the class file format being targeted as different class file versions have different capabilities and features. In some cases the modifiers present in the class file representation may differ from the modifiers on the originating element in the source language, including final on a parameter and protected , private , and static on classes and interfaces.
Besides differences in structural representation between the source language and the JVM representation, core reflection also exposes runtime specific information. For example, the class loaders and protection domains of a Class are runtime concepts without a direct analogue in source code.