Standing in the Field @ Valley Forge

Standing in the Field

Notes from SJS Application Server Field Engineering

« Annotations Preso... | Main | Getting Things Done »
Sunday November 28, 2004
Annotations (Part 1)

I said several weeks ago that I would like to post my presentation on metadata that I originally gave to the Harrisburg Java Users Group. I'm not completely sure that I'm going to be able to post all of the code, but I'd like to get what I can posted. Because, as I said, I don't think there are many good resources on annotations that go past the basics.

I'm still working on converting the presentation into a bloggable format. (Without my commentary, I'm not sure the slides could stand on their own.) But here is the first section. It's more flushed out than the original presentation, but still has the conversational tone of a presentation rather than a paper. If you spot any errors or ambiguities, please feel free to contact me.

Metadata (JSR 175) in Java 5.0, Part One

Why Metadata?

Metadata is one of the major features of Java 5.0 in the "developer ease of use" theme. It is valuable both in its direct ability to make life easier for developers and also indirectly by enabling future technologies, such as EJB 3.0. By making the Java language more "declarative", developers can implement functionality in fewer lines of code and with more maintainability and readability.

Metadata is a generic term for this type of declarative functionality: literally meaning data about the data (and therefore code about the code). Annotations refers to the specific implementation of metadata chosen by JSR 175: special interface-like markers in the Java code that have declarative behaviors.

Declarative programming is not new to Java. There are a number of existing Java features that are declarative: marker interfaces, JMX naming conventions, and JavaBean properties are just some examples of declarative behavior in Java. Annotations, however, introduces a complete framework for expanding the languages with declarative metadata instead of just ad hoc, case by case naming conventions. This adds both consistency and the ability for tools and compilers to spot errors. (I know that I've personally spent a lot of time chasing down typos in JavaBean getter/setter names.)

Tool support for metadata was one of the design goals for metadata. The goal being to enable tools to understand the declarative meaning associated with metadata and also to enable tools to use annotations for their own functionity. (Imagine annotations that mark tool generated code. A tool that was aware of these annotations could freeze those sections of code and regenerate them as necessary based on the annotation parameters.)

Although EJB 3.0 is still in early draft stage, I'd suggest downloading the EJB 3.0 specification and taking a look at how annotations are used in that specification. Simplifying J2EE was one of the original reasons for metadata and the EJB 3.0 specification is a glimpse into the plans for annotations going forward.

Annotation Basics

This post is not meant to be a syntax guide for annotations. There are plenty of introductions to the annotation syntax available on the web. I'd recommend starting with the language documentation on java.sun.com. However, as a quick refresher, basic annotations look like JavaDoc comments (including the fact that they begin with @ symbols, except that they exist directly in the code outside of comment delimeters.

Simple examples of annotations built into the Java language include:

More complicated annotations can have name/value arguments.

[I'd like to expand this section in the future. I admittedly handwaved over this in the original presentation due to time constraints and the fact that many in the audience had already experimented with the basics of annotations.]

Built in annotations

Java 5.0 includes several built in annotation types that are defined directly in the language.

@Override is annotation that is used to mark methods that are meant to override methods in the super class. This declaration enables the compiler to catch bugs where you meant to override a method but the method signature doesn't match properly.

@Override
public int getValue() { return someValue() }

This annotation is of limited value, at least in my opinion, since it depends on the user manually adding an annotation in order to detect a relatively obscure typo. The ratio between effort required to potential payoff doesn't seem worth it to me. But it is a good illustration of one of the key pieces of annotation functionality: the ability to affect the compiler.

@Deprecated is the new way to declare methods as deprecated. Like the old JavaDoc way, this will cause the compiler to generate compile time warnings when the deprecated method is used.

@Deprecated public int getValue() { return someValue(); }

I never liked the fact that JavaDoc could affect the compiler with deprecated flags. It was a very useful feature, but I was philosophically opposed to comments affecting the compiler. Moving the deprecated flag to an annotation is a more elegant solution: this is exactly the kind of declarative functionality that annotations are meant to address.

@SuppressWarnings allows you to turn off compiler warnings for a specific piece of code. Useful because of how touchy the compiler can be with warnings regarding collections now that generics have been implemented. [I have had some problems getting @SuppressWarnings. I'm not sure if this is a bug yet.]

@SuppressWarnings(“unchecked”);
public void nonGenericList(List myList) { myList.add(“new value”) ; }

There are also built-in meta annotations that are used to annotate annotations. @Retention indicates whether annotations should be compiled into .class files and retained in memory. @Target indicates the types of objects that can be annotated. @Documented indicates whether an annotation should appear in JavaDoc. @Inherited indicates whether annotating a class also affects subclasses.

Continued later this week in part two where I will talk about creating custom annotations and the apt tool.

(2004-11-28 23:16:13.0) Permalink


Comments:

Post a Comment:

Comments are closed for this entry.