Java Annotations: A [Somewhat] Brief Introduction

So in my last post where I described a messaging system we implemented, I also mentioned our use of annotations. I thought it would be appropriate to write a follow-up post with a brief introduction to them, so here it is. I'm going to talk about annotations in the Java sense, but a lot of this propagates to other [reflective] languages too.

Annotations are often defined as "notes of explanation or comments added to text". In Java, one can regard an annotation as metadata attached to code, a piece of code describing code. Well, the first question that one might ask is "Why do I need this when I can just use comments?" and indeed, this question makes for an excellent starting point when writing an introduction. Well, probably the main reason to have annotations over comments is that annotations are part of the language, with a specific syntax, which in turn allows parsers to easily understand them. Comments, on the other hand, could be in any form and would be a huge mess to understand by a compiler, unless a certain standard was specified.

"So what good are they for?" you might ask next. Well, they can let you do some pretty neat stuff. First I should describe the three flavors of annotations in Java:

source code

Present at the source code level only and will be discarded by the compiler during compilation. These guys are useful to give hints to compilers and programs as to the nature of the code itself. For example, one may have seen @Override or @Deprecated annotations when using Eclipse or other code. The former specifies that an error should be produced if the method doesn't override one in a super class, and the latter indicates a class, method, etc. as deprecated.

class

This is the default flavor. Compilers will produce bytecode containing these annotations, but you probably won't be able to access these during runtime. Useful if you are doing bytecode analysis of code.

runtime

To me, possibly one of the more useful flavors of annotations for developers. These annotations can be requested at runtime, which allows you to do neat tricks. The reason this is possible is due to the reflective nature of Java. You can access this through the Class.getAnnotations() method


So how do we create an annotation? Well, it's pretty straightforward. Note that I'll be using the messaging system from my previous post as an example. Here's what the Message annotation looks like:

@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = {ElementType.FIELD})
public @interface Message {
Class<?>[] signature() default {};
}

So the first line says we want to be able to retrieve this annotation at runtime. Note the use of the @ symbol here. This is the notation used for annotations. The second line says what type of things this annotation can be applied to. In the above example, it can only be applied to a field in a class, but not methods, or classes themselves. Note the @ symbol before the interface keyword in the third line. This is how we define an annotation. Finally, the fourth line specifies the one and only property in our annotation, and that's an array of classes that specify the signature of the message (i.e., the types for the data that will accompany a message). We specify the default signature to be an empty array. What's interesting in this example is that we used annotations to describe an annotation itself (@Retention and @Target describe @Message).

For our messaging system, the field itself is a static member that is a String, and that string defines the name of the message. For example,

@Message(signature = {String.class})
public final static String MYMESSAGE = "myMessageName";

describes a message with the name "myMessageName" which sends a String argument to all receiving functions. If we wanted to, we could have defined a second property in the annotation for the message name. In our message delivery class, we can then loop through all the fields in a class to register messages like this:

public void registerSender(Class<? extends MessageSender> sender) {
MessageData msgData = getData(sender);
for(Field field : sender.getDeclaredFields()) {
if(field.isAnnotationPresent(Message.class)) {
if((field.getModifiers() & Modifier.STATIC) == 0)
continue;

Message msg = field.getAnnotation(Message.class);
msgData.addMessage(field.get(null).toString(), msg.signature());
}
}
}

Note that, for simplicity, I excluded the try/catch blocks and log messages in the above. A fairly straightforward piece of code: for each field in the class, if the field is static and has the Message annotation, we add the message to the set of messages we understand. This is far more convenient than having to register each individual message. For message receivers we have a ReceiverMethod annotation that I won't explain, but it looks something like this:

@Retention(RetentionPolicy.RUNTIME)
@Target(value = { ElementType.METHOD })
public @interface ReceiverMethod {
// Special message name which allows catching all messages from a sender
public static final String CATCHALL = "<<all>>";

// Properties
public Class senderClass();
public String message();
}

We can then do something similar to the registerSender method above to register our receiver. So that's my quick introduction to annotations. Maybe you can find other interesting ways to make use of these little critters in your own programs.

6 comments:

Shawn said...

Do you know of any way to add annotations to a class/method/field/etc through reflection at runtime?

Jason G said...

Hey Shawn. If you mean adding annotations through code itself, and not writing them by hand, I don't know of a way. The only thing I can think of would be writing your own class loader to dynamically inject annotations, but that seems like overkill.

I would have to ask why you would want to do this anyways, because it would defeat the purpose of annotations. Annotations describe code, and code generally doesn't change at runtime.

I have a feeling that maybe, what you want to do should be done in a different way. Maybe you have an interesting use case that I'm not aware of though?

Shawn said...

It IS a bit of an odd case, and annotations might not be the way to do it.

What I'm trying to do is to run a JUnit test suite from a JAR. I need to find a way to selectively exclude certain tests. I don't have the ability to alter the test code myself, just the code that runs it. There is an @Ignore annotation that seems to do what I need, but it needs to be added to the source and I can't do that.

Jason G said...

Hmm, yes. I can see a potential use for it in your case. Like I said, the only way I can think of doing this is by manually modifying the byte code using some library (e.g., http://jakarta.apache.org/bcel/).

Another solution is to extend the JUnit4 testing classes and filter out the methods/classes you don't want to test. I think this is a far better solution to this problem, but maybe it isn't applicable in your context.

If you do happen to find a way to deal with the annotations, let me know because I'd love to hear about your solution!

Saran said...

Hi iam Saran...

I need the main purpose of annotation.please help me.

Jason G said...

Hi Saran. There really isn't a "main" purpose to annotations. As I said in my post, an annotation is simply a piece of code that describes another piece of code. What you use them for is very application-dependent.

Take a look at my own example given in the post. I used annotations to describe two things: 1) messages that could be sent by one class and 2) functions that acted as receivers for these messages. They can also be used to mark code as deprecated, incomplete, or in need of upgrade.

What I'm saying is that there is not a whole lot of understanding of what annotations are for, but rather mostly knowing when they're useful. Note that in my messaging example, I *could* have done everything without annotations, but they simplified my problem. Best of luck!