I've been writing in Java and C# for a while, but I'm having a hard time identifying places where using a custom annotation would be advantageous.
I can see that JUnit uses annotations in test classes to identify the order it should run the methods in the test classes, which obviates the need for a configuration of some sort.
What are other examples of problems that annotations solve elegantly?
As others pointed out, annotations are metadata about classes / properties / methods. In general, I find them most useful when data needs to be transformed between the Java domain and another domain or format, such as
The latter two are real examples from the project I am working on.
Another, related task is data validation. We use the annotations of Hibernate Validator (which is an implementation of JSR 303 - Bean Validation) to validate critical pieces of the data received from the above mentioned mainframe, before letting it enter our domain.
As others noted, all the information represented by annotations could in theory be represented in other forms, e.g. in distinct config files (in XML or other format). However, often it is just so much more convenient to have the annotations right there in the code, next to the entity it refers to. Typically (like in the above examples) the metadata represented by annotations is tightly tied to the code. So - once created - it very rarely changes independently of the corresponding code itself. So keeping it physically together with the code makes it cleaner and more maintainable.
Depending on the annotations you use and how you run JUnit, JUnit scans the classpath and runs everything with the proper annotations (or, in the old school versions, that implemented a certain interface)
You're right in the sense that annotations are mostly useful for configuration - they're essentially metadata about the method/class. Here's an example from my work - for some reason I can't remember, we needed to dump objects to a log, but we wanted to filter some of attributes. We made a Loggable annotation that could be applied to individual getters or a class, we then used reflection to determine what to dump and what not to.
I would venture a guess that anything you can do with an annotation you could do with some sort of configuration file. Some annotations are basically formalized comments (e.g., @Deprecated). So the fact you can't come up with common cases isn't really surprising.
You can also add them as hints for static and run time code analysis tools. e.g. @ThreadSafe, @Immutable and so on. These give hints to the developer as to how the object should be treated/behave and the tooling can often give some level of confidence on that.
I've been experimenting with using annotations to give executable specifications to code and generating unit tests for my algebra project. For example, I have an interface with a method to add two objects together, and the properties you would expect from additions are marked as annotations:
interface Group<E> extends Set<E> {
@Commutative @Associative @Identity("zero") @Inverse("neg")
E plus (E, E);
E zero ();
E neg (E e);
}
I have a (partially implemented) annotation processor that generates tests for these properties for any class that claims to implement this interface.
This is an example of "user" annotations: @Commutative, @Associative, etc. are implemented as part of the algebra library, not as part of the annotation processing tool; generating new properties with tests is a simple matter of adding a new annotation type with a special method that checks the property.
Annotations have been moderately well-suited to this task, although there are a number of shortcomings. For example, java annotations do not have a notion of inheritance, so my processor has to explicitly search for annotations on all superinterfaces of a class. Also, Java doesn't support marking a method with multiple copies of the same annotation, so I can't write @DistributesOver("foo") and @DistributesOver("bar") on the same method.
Annotations are just metadata, personally I prefer annotations to xml configurations, but don't completely right xml off. My advice use annotations whenthat wouuld make metadata usage more clear and transparent. As an example take a look at JPA annotations, isn't it better to say that your class is an Entity than it is to right an xml file about it and how it relates to other @entities. Annother example Spring MVC @Controllers and @RequestMapping , it's so much easier to find out what the class is and what it does by simply looking at it, not having to go through a pletora of xml files. It is important to note however that too many annotations make the code difficult to read and should be avoided when possible. My advice, go with your gut but always try to make your code readable.
Hope that helps,
Peter
P.S. I don't know what Junit does, I have never looked at it's code, but I assume there is some sort of a classpath scanner
