LOGIN | REGISTER NOW | SUBSCRIBE
 
 
News on Monday
more>>
SharePoint Tech Report
more>>


   

 
 
Download Current Issue
ISSUE 2/1/2010 PDF

Need Back Issues?
DOWNLOAD HERE

Receive the print Edition?


 
blogs tab
Visual Studio 2010 Release Candidate Available Today
A Visual Studio 2010 release candidate is available on MSDN.
02/09/2010 09:45 AM EST

Is Microsoft eyeing Office subscription pricing?
Microsoft may be preparing to offer a new Office pricing option called "union," which charges the same for cloud as on-premises.
02/01/2010 09:38 AM EST

Facebook rewrites PHP runtime
Facebook is about to open source its own PHP runtime, written from scratch for speed.
01/30/2010 08:53 PM EST

 

Events calendar tab
Macworld 2010
2/9/2010 to 2/13/2010
San Francisco
IDG World Expo

SPTechCon 2010
2/10/2010 to 2/12/2010
San Francisco
BZ Media

PyCon 2010 (Python Conf.)
2/17/2010 to 2/25/2010
Atlanta
Python Software Foundation

Southern Calif. Linux Expo
2/19/2010 to 2/20/2010
Los Angeles
SCALE

IBM Pulse
2/21/2010 to 2/24/2010
Las Vegas
IBM


 
print Printable version 
Most Read Latest News Blog Resources
Facebook brings HipHop to PHP
HipHop compiles PHP to speed up the Web layer at world's most popular social networking si...

Adobe moves LiveCycle application platform to the cloud
Release gives developers just what they need to create targeted business process-oriented ...

Oracle acquires AmberPoint
Today's merger will probably affect most of AmberPoint's existing partnerships with other ...

Digg!  Digg
Reddit  Reddit
Slashdot  Slashdot
Share on facebook  Facebook
Share on Twitter  Twitter

Java Annotations


By Allen Holub
April 1, 2005 — 
Java 5’s “annotation” feature is a welcome addition to the language. Unfortunately, the implementation is worse than it needs to be, largely, I believe, because of a lack of openness in the Java Community Process.

Annotations replace dubious tagging idioms in your code. The classic example of this problem is the get/set idiom required originally by the JavaBeans spec and now endemic. Nobody ever intended for these getters and setters to be called by anything other than a UI-building tool. They were just a way of annotating the fact that an object exposed a property to an outside tool (which, in this case, uses the information to build a “property sheet”).

These particular getter/setter methods exist solely to provide information for the external tool. They should not be called from normal code. Another example of a flawed tagging mechanism is the Serializable interface, which tells the compiler (and JVM) to treat the annotated object specially. Serializable has no methods, so implementing it is nonsensical on its face.

An official annotation mechanism lets you leave notes for the compiler or runtime system without resorting to dubious idioms. For example, you could use private @property Color backgroundColor; to indicate that a layout tool should put a Background Color property into its property sheet. No getters and setters are required. By the same token, a persistence framework could tag a field with @persistent instead of using get/set. Other applications abound: You could precede a class definition with an @remote annotation to indicate that it would be used remotely via RMI. No need for a Remote interface or magic exceptions; the compiler provides the infrastructure for you. @precondition and @postcondition annotations can tell a compiler to automatically build regression tests for you. You get the idea.

Though annotations are wonderful, the mechanisms used to implement them in Java are not. For example, the syntax used to describe an annotation derives, inappropriately, from that of an interface definition. You might define an annotation that documents a known bug as follows: @Bug{id=1234, synopsis=“description of behavior”}

The associated declaration actually uses the interface keyword, and specifies the id and synopsis arguments as if they were methods of an interface named Bug, which is just plain weird. This syntax renders the definition too abstruse, and discourages people from using the feature.

Though the syntax is annoying, the hoops you have to jump through to figure out how to use an annotation are unacceptable. There’s one exception: It’s easy to get a list of annotated fields and methods using introspection APIs of the Class class. Annotations are most useful when handled by the compiler, however, and the mechanism for doing that (the “apt” tool and associated interfaces that you have to implement) is overcomplicated and underdocumented.

The Java Community Process is the main culprit. The JCP doesn’t require an open process, and the Annotations (JSR 250) group was tightly shuttered, not letting outsiders see the proposed spec until it was too late to make any suggestions or changes that might make the technology workable.

Even worse, closed specifications encourage bad (or nonexistent) documentation. Tight groups working in isolation don’t write much down. The group members know the material, and they don’t have to explain things to outsiders.

In the current case, this lack of written documentation was never corrected. The actual specification is scattered throughout the Java Language Specification, and is nowhere presented in a coherent form. Of the two documents provided in the installed Java documentation, one is barely adequate for describing how to use annotations in a simplistic way, and the other is an inadequate explanation of the apt tool required to process annotations.

It’s just not possible to understand how to create your own annotations (and the associated processors) simply by reading. A lot of trial-and-error experimentation is required as well. Learning a new feature that’s integral to the language shouldn’t be this hard. The complete source code for even one nontrivial example would help, but there’s nothing. The lack of a comprehensive example also sets off warning bells. How can you judge the quality of an API if you’ve never created an application using that API?

Annotations not only clean up your code, but also make it easier to write and maintain. They eliminate unnecessary complexity and hide details that shouldn’t be visible. They’re difficult to learn, but you should learn them anyway.

Allen Holub is an architect, consultant and instructor in C/C++, Java and OO Design. Reach him at www.holub.com.


Share this link: http://www.sdtimes.com/link/28514
 

Add comment


Name*
Email*  
Country     


  • Comment
  • Preview
Loading