Java Reflection Tutorial, Part 2: Annotations

Welcome to Part 2 of the Java reflection tutorial. This part will focus on annotations, which allow arbitrary data to be attached to a class, method, field, or any other symbol.

If you have not yet read Part 1, please go read it. It explains some basic concepts.

Now, without further ado…

Getting Started

This tutorial assumes that you have Basic.java from part 1. If not (I don’t), here it is:

import java.lang.reflect.*;
import java.lang.annotation.*;

public class Basic {
    public static void main(String[] args) {
        // SETUP //
        System.out.println("Hello Java Reflection");

        // GETTING THE NAME OF A CLASS //
        Class<?> cls = Basic.class;
        System.out.println("The class's name is " + cls.getName());
        
        // GETTING THE NAME OF A METHOD //
        Basic basic = new Basic();
        basic.doSomething("whatever");
        try {
            Method doSomething = cls.getMethod("doSomething", String.class);
            System.out.println("The method's name is " + doSomething.getName());
        } catch(NoSuchMethodException e) {
            System.out.println("A whatsit happened: " + e.toString());
        }
    }
    public void doSomething(String whatever) {
        System.out.println("Doing something very interesting...");
        System.out.println("Whatever is " + whatever);
    }
}

Now, let’s take a look at annotations.

Built-In Annotations

Java has several built-in annotations, including @Override, @Deprecated, and others. Let’s take a look at @Override first.

@Override allows you to override previously defined methods. For instance, if you had a class called Class1 (very creative name, isn’t it?):

public class Class1 {
    public void doSomething() {
        System.out.println("Hello world, Class1 style!");
    }
}

Then, say that you had a class called Class2, which extended Class1, and you wanted to define anew the doSomething method. You might take a gander at it like this:

public class Class2 extends Class1 {
    public void doSomething() {
        System.out.println("Hello world, Class2 style!");
    }
}

However, you would be gandering at hot air, and the compiler would scream loudly at you for it. Don’t do that. In Java, you need to annotate any overridden method with @Override, like so:

public class Class2 extends Class1 {
    @Override
    public void doSomething() {
        System.out.println("Hello world, Class2 style!");
    }
}

As you can see, using an annotation is very easy: Just smack it down in front of the thing you want to annotate, and you’re off to the races.

And now, you can go and enjoy your polymorphic “Hello, World” in peace. But don’t go away just yet, because there’s more coming. Unless, of course, you’re bored out of your mind, in which case you would probably prefer some of the other content on this site.

An important note: @Override is not needed when overriding methods defined in interfaces or abstract classes. Those are meant to be overridden, and so the all-knowing Oracle realized that it was redundant to mandate that people specifically denote that they’re overriding something which cannot be used in any way except being overridden.

Anyhoo, now we move on to @Deprecated.

(looks up what @Deprecated actually does)

@Deprecated marks a program element (e.g. package, class, field, method, etc.) as deprecated. If you try to use a deprecated field, the compiler will give you a warning.

To use it, just put it in front of just about anything, like @Override:

@Deprecated
public class DontUseMe {
    @Deprecated
    public void blowUpTheWorld() {}
    
    @Deprecated
    public String goodbyeWorld = "Goodbye, World";
}

Just in case it wasn’t obvious, now people know not to use that class.

This is just a small sample of the built-in annotations that Java provides. To see the full list (as of Java 8), see https://docs.oracle.com/javase/tutorial/java/annotations/predefined.html.

Creating Your Own Annotations

To create your own annotations, use an @interface block. Not an interface, an @interface. Each parameter for the annotation is defined as a method in the @interface. For example, to create an annotation like the Author annotation in the official tutorial:

@interface Author {
    String name();
    String date();
}

And there you have it, a simple annotation. To use it, make sure it’s imported, and:

@Author(name = "Marty", date = "The Future")
// declare something here

Tip
If an annotation has only one method named value, you can pass it as an unnamed argument. For example, if @Author didn’t have date, and you renamed name to value, you could use:
@Author("Nobody In Particular")

Of course, you would probably want to make date into a Date, so that you don’t trip over unexpected time-traveling DeLoreans, but this suffices for a demonstration.

Now, this annotation can be used on everything at the moment — even the type of an argument. Since it’s kind of silly to put an @Author annotation on the type String, let’s fix that.

To restrict where your annotation can be used, you can annotate it (yes, you can put annotations on annotations) with a @Target annotation, in java.lang.annotation. @Target takes one argument, an ElementType or an array of ElementTypes. ElementType is an enum with the following options (mostly copy-pasted from https://docs.oracle.com/javase/tutorial/java/annotations/predefined.html):

  • ElementType.ANNOTATION_TYPE can be applied to an annotation type.
  • ElementType.CONSTRUCTOR can be applied to a constructor.
  • ElementType.FIELD can be applied to a field or property.
  • ElementType.LOCAL_VARIABLE can be applied to a local variable.
  • ElementType.METHOD can be applied to a method-level annotation.
  • ElementType.PACKAGE can be applied to a package declaration.
  • ElementType.PARAMETER can be applied to the parameters of a method.
  • ElementType.TYPE can be applied to any type declaration.

For example, to restrict @Author to types, annotations, constructors, fields, packages, and methods (the sensible items), you would define it like so:

import java.lang.annotation.*;
// ...
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.PACKAGE, ElementType.METHOD})
@interface Author {
    String name();
    String date();
}

Now, if you try to, say, take undo credit for the creation of java.lang.String, the compiler will yell at you.

Using Annotations for Reflection

Now, we get to the part that justifies this post’s inclusion in a series entitled “Java Reflection Tutorial”. To use annotations for reflection, you need to use the Annotation interface (in the java.lang.annotation package, which should already be imported from Basic.java). To get started, let’s put Author into its own file. Call it Author.java, and put it in the same package as Basic.java:

import java.lang.annotation.*;

@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.PACKAGE, ElementType.METHOD})
public @interface Author {
    String name();
    String date();
}

If it’s in a named package, be sure to put a package declaration!

Now, let’s put an @Author annotation on Basic, to let the world know who wrote it. Put this on a line before the class declaration in Basic.java:

@Author(name = "Fozzie Bear", date = "Somewhere around 2021")

Now that the humans know, let’s make sure that the computers know as well. To get the Annotation instance for the annotation, we can use the Class.getDeclaredAnnotationsByType method. Since we know that we can only have one instance of the annotation on any given element (to repeat annotations, annotate the annotation declaration with @Repeatable), we can just take the first element of the returned list and cast it to Author: (put this at the end of main)

Author author = cls.getDeclaredAnnotationsByType(Author.class)[0];

However, if you try to run this (I did), you’ll find that the annotation doesn’t exist! This is because of retention policies.

Somewhat Unplanned Interlude: Retention Policies

Retention policies (defined using the @Retention annotation) tell the compiler how long to keep the annotation around for. A value of RetentionPolicy.CLASS (the default) tells the compiler to keep the annotation around during compilation, but ignore it at runtime. A value of RetentionPolicy.SOURCE tells the compiler to ignore the annotation altogether, and makes the annotation behave, for all intents and purposes, like a comment. A value of RetentionPolicy.RUNTIME, which is what we want, tells the compiler to keep the annotation around during both compile and runtime, for reflection purposes. To make @Author available for reflection, add a retention policy in Author.java:

// ...
@Retention(RetentionPolicy.RUNTIME)
// ...

And Now, We Return To Our Regularly Scheduled Programming

At this point, we’re retrieving the annotation class, but we’re not actually doing with it. To finish up, let’s print out the author and date from the annotation:

System.out.println("This class was written by " + author.name());
System.out.println("Date: " + author.date());

Now, if you run it, along with the output it previously gave, it will also print out the following:

This class was written by Fozzie Bear
Date: Somewhere around 2021

And we’re done! This tutorial just scratches the surface of what’s possible with annotations, though, so be sure to check out the official tutorial at https://docs.oracle.com/javase/tutorial/java/annotations/index.html.

An Exercise

Try making Author able to be used multiple times, and modify Basic.java to print out all of the occurrences. For instance:

@Author(name = "Fozzie Bear", date = "2021-09-08")
@Author(name = "Kermit", date = "2021-12-21")

And the output would be:

This class was written by Fozzie Bear
Date: 2021-09-08
This class was written by Kermit
Date: 2021-12-21

Java Reflection Tutorial, Part 1

This is a repost from our previous blog platform.

Jun 2, 2021 • Aleks Rutins

Java Reflection Tutorial, Part 1

First of all, this is the first time I’ve ever written a blog post. My apologies if the organization makes no sense.

Reflection in programming is the act of using code to write or read itself. For example, in Java, getting the name of a class or method at runtime is reflection.

In Java, most of the reflection classes and methods are in the java.lang.reflect package, and tools for dealing with annotations are in java.lang.annotation.

To get started, create a directory to hold files for this tutorial. Create a new basic Java file, and call it Basic.java:

import java.lang.reflect.*;
import java.lang.annotation.*;

public class Basic {
    public static void main(String[] args) {
        System.out.println("Hello Java Reflection");
    }
}

If you don’t know what that does, a comprehensive tutorial is here.

Run it with java Basic.java. You should see the output:

$ java Basic.java
Hello Java Reflection

Great! Your Java installation works. If it doesn’t, go ask the Oracle. Or ask OpenJDK, if you’re on Linux.

Getting the Name of a Class

Now, let’s do some reflection! Add some lines to main:

import java.lang.reflect.*;
import java.lang.annotation.*;

public class Basic {
    public static void main(String[] args) {
        System.out.println("Hello Java Reflection");
        Class<?> cls = Basic.class;
        System.out.println("The class's name is " + cls.getName());
    }
}

Run it again, and you should see this:

$ java Basic.java
Hello Java Reflection
The class's name is Basic

Whoa! How’d it know that? Let’s see.

First, take a look at this line:

Class<?> cls = Basic.class;

First of all, the ? in Class<?> tells the Java compiler to auto-detect the type argument. In this case, it could also have been written as Class<Basic>, but that would be more typing. I could also use var, which tells it to completely auto-detect the type:

var cls = Basic.class;

However, var is not supported in JDK 7, which is what FTC uses. If you have JDK 9 or higher, you can use var, though.

Next, Basic.class tells it to get the Class<T> (T is a type argument) instance for BasicClass<T> is core for reflection. So essential, in fact, that it is included in java.lang.

On to the next line:

System.out.println("The class's name is " + cls.getName());

Everybody should be familiar with System.out.println. If not, I urge you once again to check out this tutorial. However, cls.getName() should be new. If not, I urge you to skip to the next heading, wait for part 2 (annotations), or seek out a more advanced tutorial.

getName is a method on Class<T> that gets the qualified name. For example, if Basic were in the com.not.a.domain package, cls.getName() would return "com.not.a.domain.Basic". Since Basic is not in a package, it just returns "Basic". If you need an unqualified name, without the package, use Class.getSimpleName.

Getting the Name of a Method

To access methods, we use the Method type, which is in java.lang.reflect. Methods can be accessed using Class.getMethod or Class.getMethods, which return a specific method or a list of all methods in the class, respectively.

Add a method to Basic:

public void doSomething(String whatever) {
    System.out.println("Doing something very interesting...");
    System.out.println("Whatever is " + whatever);
}

Now, just to make sure it exists, create an instance in main and try it:

Basic basic = new Basic();
basic.doSomething("whatever");

Run it, and the whole output should be:

$ java Basic.java
Hello Java Reflection
The class's name is Basic
Doing something very interesting...
Whatever is whatever

It works! Now, let’s get a Method instance for that method. Remember, cls is Basic.class. The try block is necessary because getMethod can throw a NoSuchMethodException if the method was not found.

try {
    Method doSomething = cls.getMethod("doSomething", String.class);
} catch(NoSuchMethodException e) {
    System.out.println("A whatsit happened: " + e.toString());
}

Now, let’s look at the interesting line:

Method doSomething = cls.getMethod("doSomething", String.class);

If you look at the description for Class.getMethod, you can see that the first argument is the name of the method, and any remaining arguments are parameter types, as Class<T> instances. In this case, since the method is called doSomething and it takes one String argument, the first argument is "doSomething" and the second argument is String.class.

Now that we have the Method instance, it’s easy enough to get the name (inside the try block):

System.out.println("The method's name is " + doSomething.getName());

Now, the output should be:

$ java Basic.java
Hello Java Reflection
The class's name is Basic
Doing something very interesting...
Whatever is whatever
The method's name is doSomething

It worked!

If something went wrong, here’s the full code of Basic.java (organized into sections):

import java.lang.reflect.*;
import java.lang.annotation.*;

public class Basic {
    public static void main(String[] args) {
        // SETUP //
        System.out.println("Hello Java Reflection");

        // GETTING THE NAME OF A CLASS //
        Class<?> cls = Basic.class;
        System.out.println("The class's name is " + cls.getName());
        
        // GETTING THE NAME OF A METHOD //
        Basic basic = new Basic();
        basic.doSomething("whatever");
        try {
            Method doSomething = cls.getMethod("doSomething", String.class);
            System.out.println("The method's name is " + doSomething.getName());
        } catch(NoSuchMethodException e) {
            System.out.println("A whatsit happened: " + e.toString());
        }
    }
    public void doSomething(String whatever) {
        System.out.println("Doing something very interesting...");
        System.out.println("Whatever is " + whatever);
    }
}

See you in Part 2, which will go over annotations!

Other Notes & Exercises

  1. Try putting Basic in a package, and see what getName returns. Then, try to get the name without the package name.
  2. If you aren’t sure how to set up your IDE, I use Visual Studio Code with the Java Extension Pack.
  3. The java command-line tool, as used above, can also compile files on-the-fly. If you experience problems, you can use the longer version:
    $ javac Basic.java
    $ java Basic ...
  4. Use the documentation for Method to figure out how to get the name of the class that declared the method.