Bill Burke has written up four simple rules for when to use annotations instead of XML, based on his experience with JBoss’ EJB3 implementation. They are:

• Use an annotation if the metadata you are applying changes the design of your class.
• Use an annotation if the metadata changes the design of code interacting with your class.
• If your application needs to be portable between app-servers or databases, don't use an annotation that will not allow you to be portable.
• Use XML when you want to configure on a per-deployment basis.

He also walks through each of the rules, explaining some of the thought behind them.

What do you think of his four rules? Are they complete? Would you add to them?

Well, this is quite interesting article and I suppose these rules are just result of common sense.

However, while author is concentrated on usage of annotations with EJB, I suppose that since annotations now are built-in feature of Java, the entire question may be wide - When not to use annotation?

In some cases, annotations are positioned by replacement of configuration files (for example - mapping to database etc). The main drawback of such approach is significant reducing of code portability and reuse.

Another thing - runtime annotations processed by APT. Potentially, one may create annotations that just will twist behavior of the code and therefore reduce readability and transparency of plain Java code (actually, similar problem occur with AOP - you could not say for sure which code will be executed and which actions will be performed, for example during call of particular method just by inspecting plain Java class listing).

In general, it seems that it is possible to discover more annotations use cases that looks attractive from the first glance but may result bad design.

Therefore, I suppose it could be great to collect opinions when NOT to use annotation.

Best regards,
Andrew Sazonov
http://www.softamis.biz
SoftAMIS - you source of high quality Java and Web solutions!

Any studies or observations on the .NET side of the best practices regarding annotations (that .NET has had for some time now)?

Aren't annotations overidden by XML descriptor files? If AOP framework in use provides such feature, then it wouldn't matter most of the time if you use annotation or not, since annotations would just provide "default" values which could be overriden by XML files in case they needed to be changed. I am not sure though if and how this would work in every situation.

Regards,
Henrique Steckelberg

Aren't annotations overidden by XML descriptor files? If AOP framework in use provides such feature, then it wouldn't matter most of the time if you use annotation or not, since annotations would just provide "default" values which could be overriden by XML files in case they needed to be changed. I am not sure though if and how this would work in every situation.Regards,Henrique Steckelberg

Although I agree that using AOP or some other annotation override facility allows you to change the behavior as you like, one thing to worry about is how can you get a concise picture of your metadata if only some parts of it are described as annotations and certain fragments are described in XML?

Annotation overriding is something that still needs to be nailed down in EJB 3 and J2EE 5 in general and there's still a lot of debate going on about it. It would be cool to hear some constructive feedback on it.

Bill

It would be cool to hear some constructive feedback on it.Bill

If a class is annotated, is there a defined mechanism for overriding that annotation? If not, won't the very concept of overriding, necessarily through some application specific means, provide a false result when the classes are inspected for their annotation type and data?

It would be cool to hear some constructive feedback on it.Bill

If a class is annotated, is there a defined mechanism for overriding that annotation? If not, won't the very concept of overriding, necessarily through some application specific means, provide a false result when the classes are inspected for their annotation type and data?

The inspection mechanism should be aware of the external definition files and return the overriden values instead of the annotated ones, through a well defined overriding mechanism, so one can not just change some annotated values, but add new ones and remove existing ones.

The inspection mechanism should be aware of the external definition files and return the overriden values instead of the annotated ones, through a well defined overriding mechanism, so one can not just change some annotated values, but add new ones and remove existing ones.

Unless this is defined by the spec, it cannot be done generically, and hence, IMO, should be avoided.
Leave annotations for annotating, not configuring, code.

Unless this is defined by the spec, it cannot be done generically, and hence, IMO, should be avoided.Leave annotations for annotating, not configuring, code.

But then we would miss a chance of having proper defaults and avoid descriptor file hell. This subject really needs to be properly addressed in the specs.

The inspection mechanism should be aware of the external definition files and return the overriden values instead of the annotated ones, through a well defined overriding mechanism, so one can not just change some annotated values, but add new ones and remove existing ones.

I'm not so sure about being able to *remove* existing annotations... Would that still be considered overriding?

The article is intriguing, as are the comments from Andrew Sazonov.

I have believed for a while that there is a dearth of "patterns of etiquette" regarding all the meta-programming facilities available to us today: MOF, AOP and now Annotations. I'm sure that there is some work going on in this arena of which I'm ignorant. (Maybe generous TSS readers can highlight some such work.) However, I do believe that in general the patterns' movement needs to catch up with all the un-restrained meta-programming going on. Gone are the times when I could read a section of code from curly-brace to curly-brace and know exactly what's going on; what with all the "what-ifs" injected by these meta-programming facilities.

Thoughts, anyone?

Gone are the times when I could read a section of code from curly-brace to curly-brace and know exactly what's going on; what with all the "what-ifs" injected by these meta-programming facilities.Thoughts, anyone?

The answer to your question is: tools.
Only tools can show you attached code that will run before/after your procedure. Using plain text editor will not be an option anymore.
With AOP and annotations we are entering the era of code that is not readable outside specificly designed IDEs.

With AOP and annotations we are entering the era of code that is not readable outside specificly designed IDEs.

ù

Then please bring back the Dark Ages of comprehensible code.

With AOP and annotations we are entering the era of code that is not readable outside specificly designed IDEs.

ùThen please bring back the Dark Ages of comprehensible code.

I don't see either of your points. How does an annotation require specific IDE tools? Pure AOP, would require IDE integration, but it really depends how you're using it. If you use annotations+AOP you have explicitness (the annotation) and a nice way to define the annotation's behavior (AOP).

J2EE and Spring hide a lot of things from plain Java code as you have to look at XML deployment descriptors. Annotations actually make things explicit in code which is why XDoclet has been so popular over the years.

My feeling is that if you find that you have to continually override an annotation with XML, then you probably shouldn't be using that annotation. I also believe that XML should only have metadata that you might change from deployment to deployment. Metadata in general usually changes the design of the class or the code interacting with the class so an explicit annotation helps a person to figure out exactly what a piece of code does just be looking at the source file.

Bill

Pure AOP, would require IDE integration, but it really depends how you're using it.

That's my point. Code with AspectJ aspects for example is absolutely unreadable without IDE support.

And using annotations with AOP is just 1 particular case.
Not most powerfull i must say.

So if you want to gain full advantage of AOP you have to have tools to help you with your code.

So if you want to gain full advantage of AOP you have to have tools to help you with your code.

I concurr.

The answer to your question is: tools.Only tools can show you attached code that will run before/after your procedure. Using plain text editor will not be an option anymore.With AOP and annotations we are entering the era of code that is not readable outside specificly designed IDEs.

Well given that stuff like LISP etc. is around for some time and used in plain text editors, I don't quite buy the tool thing.

Also, tools will still often not tell you "what is exactly happening" because they are using or in fact they are a product of some vendor who does not want to expose the exact functionality of what is going on in the first place (e.g. tools like WebLogic WorkShop
etc.).

No tool in the world will help you, if the tool is unaware of what the code that targets the annotation is, what it is actually doing etc.

Metaprogramming in fact elimates some very important advantage you had up til recently as a customer of say a Java library or an Application Server. You could go about decompiling the damned or brillant thing and trace the errors down for good rather easily. With metaprogramming, that won't work nowhere near that easily. The hope of course is that the programs you buy are less bug ridden in the first place but I would rather assume they will be more feature loaden...

@Remote, @Local
At first glance, I thought that this possibly triggered Rule 4. Then I thought that it is important to know the semantics of the interface you are invoking on. Going through a @Remote interface forces call-by-value semantics. @Local forces call-by-reference. You'll probably want your application code to realize this just by navigating to the definition of the interface.

Better watch out or someone will start another pedantic argument about call-by-value VS call-by-reference. :)

If annotations are not to earn the name as "litter" or "geek-ware" I think some more guidance from JavaSoft is needed. I don't gt the feeling JavaSoft put as much care or thought into Annotations as they did generics, and I'm concerned that when best-practice is established they will allow freedoms and restrictions in the wrong places.

I difficulty with Annotations changing the "design" (I presume compile time) of the code, if design mean interface. I don't think its good practice to change interfaces without you knowing it?

The 2nd rule "changes the design of code interacting with your class" sounds like a "hint" rule. If the hint can be varied (otherwise what's the point) and I have 2 encapsulating code bases which way am I supposed set the Annotation. Does code reuse not mean that hint annotations are deployment annotations?

Finally, I agree with the 3rd and 4th rules that you shouldn't place vendor or deployment specific code in Annotations. But doesn't this sound like the more general hardcoding bad rule. Is he saying hardcoding in other respects is OK - such as validation or internationalisation?




if I object to rule

If annotations are not to earn the name as "litter" or "geek-ware" I think some more guidance from JavaSoft is needed. I don't gt the feeling JavaSoft put as much care or thought into Annotations as they did generics, and I'm concerned that when best-practice is established they will allow freedoms and restrictions in the wrong places.

This idea that annotations are "litter"/"geek-ware" is incorrect. Annotations have been around for a long time now. XDoclet has been extrememly popular and .Net has had annotations for some time. I think the JSR-175 EG did a fine job defining annotations they just screwed up in two areas:

1) overriding methods don't inherit annotations from superclass

2) They defined no annotation override facility. Now every framework/app server/container on the planet is going to have to implement one.

I difficulty with Annotations changing the "design" (I presume compile time) of the code, if design mean interface.

By design, I meant the actual implementation. For instance, let's say you had a FetchType.LAZY for a particular association. If your business logic is interested in this association, then it really should fetch this association when it loads the given entity in a EJBQL query for performance reasons.

Bill