Table of Contents
A language that is capable of reflection, like Java is, allows developers to inspect types, methods, fields, annotations, etc. at run time and to defer the decision on how to use them from compile time to run time. To that end, Java’s reflection API offers types like Class
, Field
, Constructor
, Method
, Annotation
, and others. With them it is possible to interact with types that were not known at compile time, for example to create instances of an unknown class and call methods on them.
This quick tip is intended to give you a high-level understanding of what reflection is, what it looks like in Java, and what it could be used for. After it you will be ready to get started or work through longer tutorials. To get the most out of it you should have a good understanding of how Java is structured, specifically what classes and methods are and how they relate. Knowing about annotations unlocks a separate section.
Reflection API
Instead of building from the ground up I want to start with a simple example. First as plain Java code:
URL url = new URL("https://sitepoint.com/java");
String urlString = url.toExternalForm();
System.out.println(urlString);
I decided at compile time (meaning, when I was writing the code) that I wanted to create an URL
object, and call some method in it. Here’s how I would do the same with Java’s reflection API:
// the gateway to reflection is the `Class` instance
// for the class you want to operate on
Class<?> type = Class.forName("java.net.URL");
// fetches the constructor that takes a `String` argument
// and uses it to create a new instance for the given string
Constructor<?> constructor = type.getConstructor(String.class);
Object instance = constructor.newInstance("https://sitepoint.com/java");
// fetches the `toExternalForm` method and invokes it on
// the instance that was just created
Method method = type.getMethod("toExternalForm");
Object methodCallResult = method.invoke(instance);
System.out.println(methodCallResult);
Using the reflection API is of course more cumbersome than writing the code directly. But this way, details that used to be baked into the code (like that I use URL
or which method I call) becomes just a parameter. As a consequence, instead of having to settle on URL
and toExternalForm
at compile time, they could be decided upon later when the program is already running.
Most use cases for this occur in “frameworky” environments. Think about JUnit, for example, that wants to execute all methods that are annotated with @Test
. Once it found them with a class path scan it uses getMethod
and invoke
to call them. Spring and other web frameworks act similarly when looking for controllers and request mappings. Extensible applications that want to load user-provided plugins at run time are another use case.
Fundamental Types and Methods
The gateway into the reflection API is Class::forName
. In its simple form this static method just takes a fully qualified class name and returns a Class
instance for it. That instance can be used to get fields, methods, constructors, and more.
To get a specific constructor, the getConstructor
method can be called with the types of the constructor arguments as I have done above. Similarly, specific methods can be accessed by calling getMethod
and passing its name as well as the parameter types. The getMethod("toExternalForm")
call above did not specify any types because the method has no arguments.
Here’s a method that does:
Class<?> type = Class.forName("java.net.URL");
// `URL::openConnection` has an overload that accepts a java.net.Proxy
Method openConnection = type.getMethod("openConnection", Proxy.class);
The instances returned by these calls are of type Constructor
and Method
, respectively. To call the underlying member they offer methods like Constructor::newInstance
and Method::invoke
. An interesting detail of the latter is that the instance on which the method is to be called needs to be passed to it as the first argument. The other arguments will be passed on to the called method.
Continuing the openConnection
example:
openConnection.invoke(instance, someProxy);
If a static method is to be called, the instance argument will be ignored and can hence be null
.
Annotations
Annotations are an important part of reflection. In fact, annotations are primarily targeted towards reflection. They are meant to provide meta information that can be accessed at run time and then used to shape the behavior of the program. (As mentioned, JUnit’s @Test
and Spring’s @Controller
and @RequestMapping
are great examples.)
All important reflection related types like Class
, Field
, Constructor
, Method
, and Parameter
implement the AnnotatedElement
interface. The linked Javadoc contains a thorough explanation of how annotations can relate to these elements (directly present, indirectly present, or associated) but it’s simplest form is this: The getAnnotations
method returns the annotations present on that element in form of an array of Annotation
instances, whose members can then be accessed.
Summary
Java’s reflection API allows the introspection of types, methods, annotations, etc. at run time and the invocation of constructors and methods that were not known at compile time. To get started, call Class.forName("fully.qualified.class.Name")
and then getConstructors
, getMethods
, getAnnotations
, or similar methods. Invocation happens with newInstance
for constructors and invoke
for methods.
You can also use reflection to break into code and mutate non-public fields or call non-public methods – this is a risky practice, though, and gets even tougher to pull off in Java 9. If you’re curious and would like to know all the API’s ins and outs, give the reflection trail in Java’s official documentation a go. By now, the API is a little dated and has some downsides but newer alternatives exist, check out method handles (since Java 7) and variable handles (since Java 9).