Peter has posted 3 posts at DZone. You can read more from them at their website. View Full User Profile

Is It Just Me: Fear Of Over-Annotation

12.20.2008
| 5462 views |
  • submit to reddit

I was reading the new Java Servlet Specification (3.0), especially the "inevitable" sections dealing with annotations.

There have been quite a few blogs and articles around showing different opinions about pros and cons of the actual annotations in the spec.

But I have a feeling about annotations that's getting stronger over time: is the use of annotations as proposed by the various specs always leading to the desired result? Is it the only solution to the addressed problem? Is there possibly some overuse?

Another example I remember is the WebBeans spec that introduced Meta-Annotations. When will we start getting Meta-Meta-Annotations? This is somehow fun: it reminds me of the UML introduction of another level of meta and ot smalltalks meta-object-class. I really like meta but, anyway, back to the servlet spec.

Right after the section about annotations is the section dealing with web.xml and web-fragment.xml and the various rules which control the use of annotations and/or web.xml and/or web-fragment.xml.

Excuse me! What?! Maybe I'm a bit old fashined but I guess that set of rules introduces a bit of unnecessary complexity. Think of real-world software-projects... more options means more discussion means more... However, let me state this here: I'm not completely against annotations. I rather like them, if they're used in a sound manner.

For example, take the ServletFilter-Annotation. It requires the developer to provide a Path-Mapping Parameter. That means the Filters path is fixed at development time. Hmmm, is it just me to whom this sounds strange? Where are the good old times of the clean separation of concerns that Sun defined when coming up with J2EE: development vs. deployment. Yes I know: annotations are a great help to developers that want to do some rapid typing. But what I see here is that this annotation of ServletFiler is JUST a simple workaround for...

a.) ...developers who refuse to edit two seperate files (the filter.java and the web.xml) and/or

b.) ...tool-vendors who have not come up with the idea to have cleverly linked source code editors which really would make life easier.

I think especially point b needs some clarification. Think of a clever, context-sensitive IDE toolset, especially editors which allow to link two files (the filter.java and the web.xml) together in ONE editor-view.

Say you just typed "extends ServletFilter": I have an editor in mind which automatically links a view of the web.xml into the java source code. No need anymore to switch between files but still the best of both worlds: ease of development through directly typing in meta-infomarion and still seperate source and deployment artefacts.

Source Editor with web.xml section Such an intelligent editor could look like the picture above, yes of course it has to look a lot prettier, but I'm an developer, not an artist ;-)

So how does this look to you? It's pretty much like annotations but without annotations. The develper is not forced to switch to another file or view like in pre-annotation times: whether it be the web.xml itself or the web-wizard. The developer is able to type in stuff and in the background the intelligent editor routes the various pieces of information into the file where they belong. By the way: I would very much prefer to see the notion of "deployment environment" that I'ver tried to sketch with the tabs "Development Config" to "Productiv config". Those environments must somehow be configurable, that would have been a big points addressed in servlet spec.

So this is may case against annotation-overuse in favor of intelligent development tools.

What do you think?

Published at DZone with permission of its author, Peter Huber.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Johannes Brodwall replied on Sat, 2008/12/20 - 3:33pm

The path of changing the configuration (especially to the degree of changing the filters used during development) has been a path that has led to poor quality, stupid complexity and has excused frameworks that are too clunky to test fully in development. Things should be as similar as possible in all environments. After giving up the mirage of "development vs. deployment" my life is simpler (ref. a - not having to deal with as many files) and less error prone. Win-win.

John O'Hanley replied on Sat, 2008/12/20 - 6:58pm

I think you have a valid point. And I share your unease with annotations.

Annotations make me think of these questions :

Do they really simplify, or do they make things more complex? Do they really represent a long-term improvement to the language, or are they an experiment of limited success? Are they a fad?

What bothered me at first with annotations is that they don't seem to have a very clear reason for existing in the first place. They apparently were inspired by XDoclet, for generating 'side files'. However, they are used for a lot more than simply generating 'side files'. They are all over the map. 

 They were not created to solve a specific, clear problem. Compared with other techniques (for example interfaces, or abstract methods), annotations don't have a clear, simple reason for being. And that makes me very suspicious of them.

Daniele Gariboldi replied on Sun, 2008/12/21 - 2:33am

I agree with you.

I'm in a one-developer project which started using jsf 1.1 then jsf 1.2 and now SEAM. In SEAM you can use attributes to specify back beans names and it makes your life easier, at first.

But the time I need to find the class called by a EL expression, I have to issue a global search to find it out.

And it was only me  who wrote the code !

One xml with all the configuration for a specific purpose is still the best way to "index" and document the borders between two worlds: java code and facelets/jsp/url/.. text pages.

And I agree with you about tools: I like your idea and it doesn't seem difficult to implement. The problem to solve is to avoid xml verbosity,it's not to avoid a central point of configuration, and integrated tools can do a lot more about this than today tools do.

For the same reason I don't like  web-fragment.xml, so that if I have a jar in my webapp something magic happens and a url is taken by a filter without my knowledge, perhaps overriding my own filter.

I see that we are going toward a OSGi world, with modularization as the next cool thing, but this adds complexity, and it must pay for itself in power/easy of use/easy to manage products.

I would prefer something like a warning and a wizard at development time: you put wicket.jar at development time in your classpath, a tool-plugin parses it's META-INF and displays you it's  web-fragment.xml. You edit it and accept the fragment into your web.xml.

If you change the jar with the new version, the plugin warns you and show a diff to let you decide.

If you remove the jar,  the plugin warns you and let you delete the fragment from your web.xml.

At deployment time, you still have only one point to check (and edit) for url mappings etc..

Today developers use (advanced) developer tools, deployers operating system tools (command line tools, batch scripts and text editors mainly).

Just to summarize: tools have to easy the life of  the developer, config files  have to easy the life of  the deployer, and they both can be happy.

 

 

Gavin King replied on Sun, 2008/12/21 - 4:00am in response to: Daniele Gariboldi

Daniele Gariboldi replied on Sun, 2008/12/21 - 3:33am

I'm in a one-developer project which started using jsf 1.1 then jsf 1.2 and now SEAM. In SEAM you can use attributes to specify back beans names and it makes your life easier, at first.

But the time I need to find the class called by a EL expression, I have to issue a global search to find it out.

 

You should try JBoss Tools. In JBoss Tools I can just click on any EL expression and be taken directly to the attribute that the expression refers to.

That's much, much better than searching for an intermediate XML declaration.

Michael Duffy replied on Sun, 2008/12/21 - 10:28am

First people complained about embedding dependencies in code.  Hence inversion of control was born.

Then they complained about "too much XML configuration".  So annotations became the rage.

 Now we read rants about over-annotation?

 Gotta say it someplace. 

Sometimes it feels to me like all this is just fodder for bloggers and vendors.

%

 

Alex(JAlexoid) ... replied on Sun, 2008/12/21 - 6:51pm

It's just you.

Annotations were a result of the fact that we had too much XML. That started to become a real issue and annotations are the result of fixing that.
There is no issue with "over annotation", till we hit one. And I guess until we have not hit that problem, we don't get to think of a way to solve.

We solve this one, and we got another top issue. That is always true about everything, since nothing is perfect.

And really, tools are good, but overeliance on them is as much a bad thing as it is over reliance on anniotations.

Jeroen Wenting replied on Mon, 2008/12/22 - 1:10am

I'm with you. Annotations go back to the Bad Old Days (tm) of mixing configuration information with program code.
I've always considered them (or rather that capability of them) to be a bad idea.

The "too much XML" argument is moot. Instead of having a few lines of configuration code, we now have a few lines of annotations (as all those annotations replace exactly one line of XML code, and sometimes not even that).
Effectively then, we've replaced something like <xmlParam attr1="a" attr2="b" attr3="c"/> with something like  @AnnotationParam {attr1="a", attr2="b", attr3="c"} and lost the ability to change that parameter without recompiling the application.

Expect a few years from now (Java8 anyone?) to see a capability to read the attributes of annotations from an XML configuration file, and the people who now state that annotations are good because they reduce the amount of XML configuration will hail that as good because it reduces the amount of configuration hardcoded into the application.

J Szy replied on Mon, 2008/12/22 - 3:34am in response to: Alex(JAlexoid) Panzin

[quote=jalexoid]Annotations were a result of the fact that we had too much XML. That started to become a real issue and annotations are the result of fixing that.[/quote]

I wouldn't call this "fixing". It turns that a minor problem of XML files was turned into a major problem of mixing up deployment and development times, breaking the separation of concerns and introducing unneeded dependencies into the code.Many hard learned lessons now seem thrown away.

[quote]There is no issue with "over annotation", till we hit one. And I guess until we have not hit that problem, we don't get to think of a way to solve.[/quote]

Maybe not "overannotation" but there certainly is a major problem with separation of concerns.

My, to change some path now it's needed to bloody recompile the app. If it isn't wrong then I don't know what is.

Alex(JAlexoid) ... replied on Mon, 2008/12/22 - 9:07am in response to: J Szy

[quote]My, to change some path now it's needed to bloody recompile the app.[/quote]

Hm... Never seen an application that didn't need compile/package/deploy* cycle to have the changes activated...
(But that is probably architects'/developers' fault.)

Most of the times XML config will override the annotation based config.(All the time for Java EE)
So I think, that annotations are the best place for putting the default config.

And really, you probably have never hit "XML hell"(try 3-4 1MB .xml files) issue, that is really alive and well today.

* - at least 2 of those

Peter Huber replied on Mon, 2008/12/22 - 11:56am in response to: Alex(JAlexoid) Panzin

1st of all: Thanks guys for your participation! And 2nd: Wish you all a very pleasent christmas and a successful new year!

Well, I think I have to repeat or clarify what my point is: My point is NOT against ALL Annotations. They are mostly good an usefull tools.

But on the other hand - with respect to ServletFilter Annotations as an example - there are places I would rather see other solutions that would better suite the problem. maybe good tool support? Maybe completly other ways?

I like the intelligent-editor-idea I had proposed in the article that avoids xml-hell because it chooses the part of the xml file that is suitable for the context AND shows it alongside with java-code in just ONE editor. 

Editing in such a convenient Editor is pretty much comparable to editing annotations - the user experience is just "one editor"... 

[quote]

Hm... Never seen an application that didn't need compile/package/deploy* cycle to have the changes activated...
(But that is probably architects'/developers' fault.)

[/quote]

Maybe ServletFilter is a good example here - You might want to publish to open source some standard Filters (zip-Filter, reduce-unnecessary-blank-line-when-working-with-jstl-Filter) that other people might want to use in their projects. If such a others-people-project has also got some project-specific annotated filters then what? Do they have to configure your open source filters coming in a jar in web.xml whereas their own filters are configured by annotations. I don't know. Tell me - is this a good idea or maybe that is not a point in the discussion about annotations at all. What do you think?

Alex(JAlexoid) ... replied on Mon, 2008/12/22 - 12:37pm in response to: Peter Huber

[quote]Maybe ServletFilter is a good example here - You might want to publish to open source some standard Filters (zip-Filter, reduce-unnecessary-blank-line-when-working-with-jstl-Filter) that other people might want to use in their projects. If such a others-people-project has also got some project-specific annotated filters then what? Do they have to configure your open source filters coming in a jar in web.xml whereas their own filters are configured by annotations. I don't know. Tell me - is this a good idea or maybe that is not a point in the discussion about annotations at all. What do you think?[/quote]

As I said, annotations are the best fit for defaults(in your particular example) and that external components need to be wired via XML sounds logical. And since we mostly use stuff in it's default mode, we have less XML.

In your case, defaults would be used.
(Example: zip-Filter: applied to result of content types: text/* and selected application/. So filter can be applied to all URL patterns (*), by default)

Probably someone else can tell you how the web container has to handle annotated servlerts and servlet filters in JARs, because I don't know. And that is another issue. But if you would need only to add the jar name to that xml file it wouldn't sound so bad.

All above stated is IMHO.

J Szy replied on Mon, 2008/12/22 - 4:06pm in response to: Alex(JAlexoid) Panzin

[quote](But that is probably architects'/developers' fault.)[/quote]

Most things are, annotations' abuse among. 

[quote]And really, you probably have never hit "XML hell"(try 3-4 1MB .xml files) issue, that is really alive and well today.[/quote]

I never said it's not a problem. I said that using annotations as a solution to this is doing more harm than good.

XML hell could be dealt with using better XML tools, maybe such as the original author described or reducing the amount of XML needed some way that would not require to pollute the source. Or both.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.