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

2021 End of Year Wrap Up Newsletter

Happy New Year from the Manchester Machine Makers! Below is what the team has been working on:

Grants

  • The Manchester Machine Makers also received a matching grant up to $500. Consider making a tax deductible donation to the Manchester Machine Makers 4-H Club. All gifts will be matched up until January 31, 2022! Donate here or scan the QR code. 

Hardware

  • We have completed our drivebase! With the drivebase fully constructed and operational the team has met its deadline of November 23, 2021.
Above: Our robot’s first test drive on the field. \Right: The drivebase!
Above: Our robot’s first test drive on the field.
Right: The drivebase!

The intake and the delivery system

  • The intake system is critical to picking up pieces of freight. Currently we are in the process of building our intake system. We started the process by drawing a few rough sketches. We then started trying to put the intake together using the rough idea and eye-balling the process. Learning how to disconnect the metal chains only to realize we couldn’t reattach the chain. The plastic chain seems to be working very well and it is much easier to adjust the size. As a team, after getting a SolidWorks representation of the intake, we decided to change the sprockets to all one size. We learned the hard way that the sonic hubs should be fit onto the axle before putting them into the gecko wheel.
Isaac and Takoda present
the finished slide mechanism.
  • The delivery system is how the freight is moved from the robot to the delivery hub. All of the inserts have been successfully 3d printed (thank you Amy Wright at BBA) and issues with length of the inserts revealed that super gluing them together was unnecessary- the screws are sufficient. In addition, there was no system to drive the final stage of extension, so a bearing was added to the back of each of the lower slides. The slide assemblies were built and mounted to the custom angle brackets, and standoffs were mounted to that bracket. There was some horizontal expansion in the slides, so some small spacers may be needed along with the standoffs. Once the final bearing is attached to the back of the slides, they will be able to have four stages of extension, meaning the greatest remaining challenge is wiring the pulley system.

Outreach

  • This fall, the team has taken part in the beta test of the FTC Machine Learning Tool. Part of this year’s challenge involves training a TensorFlow model to allow the robot to recognize a custom-designed object on the field. The FTC leadership has designed this tool to make machine learning more accessible to teams and make it simpler to construct the large datasets needed to properly train a model. Our team gained access to the tool early in order to provide feedback, improving the experience of other teams as it is opened to the whole FTC community.
  • In January the Manchester Machine Makers will be mentoring the Lego Team, the Fiery Froggies! Isaac Vernon and Charlotte Ruley will meet with the team to support them as they get ready for their competition.
  • The Manchester Machine Makers held a virtual open house on December 22. See the recorded session below to hear about our progress from the team!

Happy New Year!

2021 VASE HOST Grant

This fall we applied for the Vermont Academy of Science and Engineering (VASE) Hands-On Science and Technology (HOST) Grants program. The VASE HOST grants are given yearly and are primarily intended for science, technology, and robotic clubs/teams in Vermont. Typically about 10 grants are awarded ranging from $500-1,000.

This year the Manchester Machine Makers has been awarded a grant of $1,000 to create two Programming Boards. In the past we borrowed school programming boards so it will be helpful to finally have our own. For those who don’t know what a Programming Board is, it’s basically the necessary hardware needed for a programmer to test and develop code (see photo below). Interested? Check out our programming board page to see how to make your own!

November 2021 Newsletter

Jacob, Takoda, Piper, Amos, Isaac, and Charlotte 
during a photoshoot at the Manchester Machine Makers’ new headquarters.
Jacob, Takoda, Piper, Amos, Isaac, and Charlotte 
during a photoshoot at the Manchester Machine Makers’ new headquarters. 

We have gotten to work on our robot! Here is what the team has been doing this fall:

  • We have been cleaning out and organizing our new space donated by TPW Real Estate that we are sharing with two local First Lego League teams: the Fiery Froggies and the Explore team. 
  • Also, along with the new space, we have welcomed some new members this fall: Amos, Jake, Zach, and Takoda. See their full profiles on the Team page. 
  • After finalizing our strategy and plans for our robot, we have documented our goals and deadlines for the season. Currently, our drive base is scheduled to be fully built by November 23, 2021.
  • On October 24th, Randy Marsh, our engineering mentor, who has helped the Manchester Machine Makers before, attended one of our virtual meetings, giving a demonstration on different aspects and features of the 3D modeling software, Solidworks, which the team uses often to model its builds and custom parts. Helping the team further, he provided the team with valuable feedback and advice on our custom field element. 
  • On October 29 we met with our founding mentor Mike Cole to brainstorm ideas about our delivery system
  • We fully constructed our half playing field for the competition. Additionally, we catalogued the parts we already had and ordered more for the robot. 
  • We received a donation and an internship opportunity for team members from EPS, Engineered Printing Solutions in East Dorset VT (see blog post, EPS Supports Manchester Machine Makers). 
  • We also have been working on the design of our robot’s intake mechanism, since it will be vital in Freight Frenzy. We can’t score points without being able to accurately and efficiently pick up freight!
  • As of mid-November, we have finalized our custom field element, and it will be 3D printed as soon as possible (most likely in December). We have also fully finished creating a 3D model of our drive base.

However, this is just what we have done so far!

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.

EPS Supports Manchester Machine Makers

Isaac Vernon and Charlotte Ruley receive check from EPS’ Julie Glover. 

FTC Team #16221, The Manchester Machine Makers 4-H Club, is pleased to announce that Engineered Printing Solutions in East Dorset VT has joined us in a partnership of support and mentoring.  Additionally, they will offer an internship program to team members for the 2021-2022 FIRST Tech Challenge Season. EPS is committed to inspiring our young roboticists, building a community of scientists and engineers here in Northshire.

The competition theme this year is “Freight Frenzy” and the team is busy designing and building a robot to accomplish the tasks outlined by the FIRST organization (www.firstinspires.org).  FIRST was founded in 1987 by innovator and inventor Dean Kamen to promote STEM advancement for young people, and is continued and supported by thousands of volunteers and mentors around the world. 

The Manchester Machine Makers is a 4-H Club with members in grades 7-12 from all over Bennington County. For more information about the team and Engineered Printing Solutions visit www.manchestermachinemakers.org and www.epsvt.com. Additionally, see EPS’ blog post on the topic at https://epsvt.com/eps-donates-manchester-machine-makers/.

We are getting ready for the upcoming season!

The Manchester Machine Makers are gearing up for the upcoming season. The team currently has nine members who are students at Burr and Burton Academy, Long Trail, Dorset, and Arlington Memorial Middle School. That includes the team’s four new members that have joined this spring: David, Piper, Finn, and Katie.

We are all excited for the FIRST Tech Challenge announcement this fall, on the 18th of September, revealing this year’s robotics challenge. In the meantime, the Manchester Machine Makers are preparing the best we can for the upcoming season.

Since the team frequently uses MATLAB and Solidworks as we build and design robots, new members have been learning and practicing how to use this software over the summer.

As time draws nearer to the FIRST Tech Challenge kick off, we are working hard to prepare for the upcoming season so we can hit the ground running!