madbean

A few months ago, Sun made available an early access compiler for JSR 14. JSR 14 adds Generics to the Java language, and will be available in full in JDK1.5.

The early-access compiler works by “wrapping” around the existing JDK1.4 compiler, and comes with helper .sh and .bat files. They work fine, but using those wrapper scripts from within Ant wasn’t the easiest thing in the world.

So I hacked together my own Ant compiler-adapter for this early access compiler, which you can download below.

(Make sure you read the caveats below.)

What is JSR 14 and Generics?

Generics allow parameterised types, or what are called templates in C++. You know what a type is; in Java it is a class. A parameterised type (or class) has one (or more) parameters; these parameters can modify the meaning of the type.

Take java.util.List for example; it stores a list of Objects. Well, in a real program it rarely stores actual instances of java.lang.Object; you usually fill it with a more useful subclass, like Strings.

And this is where a parameterised type comes in; it allows you to add more information to you code, telling the compiler and other coders what is actually inside your List.

Time for a code example. I’m sure you’ve seen something like this before:

List someList  = new LinkedList();
someList.add("item 1");
someList.add("item 2");

...

for (Iterator i = someList.iterator(); i.hasNext();) {
    String str = (String) i.next();
    System.out.println(str);
}

The “problem” with the above code is… how can you be sure it’s a String when you cast the return value of i.next()? The answer is you can’t; you just have to trust the program has been coded right.

This changes under JDK1.5 and Generics:

List someList  = new LinkedList();
someList.add(”item 1″);
someList.add(”item 2″);

…

for (Iterator i = someList.iterator(); i.hasNext();) {
    String str = i.next();
    System.out.println(str);
}

As you can see by the emphasised parts, we declare what type of List it is using “angle bracket” notation, and we don’t need to do the cast. There are many more benefits to Generics, maybe I’ll talk about them another day.

Quick-starting Generics with my Ant compiler-adapter

Here are simple, step-by-step instructions for Generics-enabling your code with the JSR 14 early-access prototype and my Ant compiler adapter (see downloads below).

1. Extract the JSR 14 early-access .zip to your hard drive somewhere.
2. Copy jsr14adapter-1.x.jar to your ANT_HOME/lib directory.
   • Alternatively, you can put jsr14adapter-1.x.jar in you CLASSPATH before running Ant.
3. Add a jsr14.home property to your Ant file.
4. Set either of these two values to com.madbean.Jsr14CompilerAdapter:
   • the global build.compiler property; or
   • the compiler attribute of the Ant task.
5. Set source="1.5" on your Ant task.

A more detailed example

Suppose you have a run-of-the-mill Ant build file like this: cea513ff1e419375b8b33b4d7166838b

To Generics-enable your compilation, drop jsr14adapter-1.x.jar into your ANT_HOME/lib directory, and make the following changes to your Ant build file:

    

    
      
      source=”1.5″
             compiler=”com.madbean.Jsr14CompilerAdapter”
             />
    

    
      
    

* You need to replace d:/opt/java/jsr14_adding_generics-1_3-ea with the directory where you extracted the JSR early-access download.

Caveats

As always, your mileage may vary:

• This only works under JDK1.4.1 or later.
• I have tested this with Ant 1.5 on Windows2000; but it should work with Ant 1.5.1 or later, and on Linux.
• When you compile Ant may issue the following warning, which you can ignore (sorry, I couldn’t really work out how to make Ant shut-up about it):
  Since compiler setting isn't classic or modern,ignoring fork setting.
• This comes with absolutely NO WARRANTY.

Downloads/Resources

My Ant compiler-adapter:

• The compiler adapter (place this in ANT_HOME/lib):
  jsr14adapter-1.2.jar (1.75KB)
• If you are interested, here is the source:
  jsr14adapter-1.2-src.zip (1.58KB)

JSR 14/Generics

• “Early Access Index Prototype for JSR014: Adding Generics to the Java Programming Language v. 1.3″
  http://developer.java.sun.com/developer/earlyAccess/adding_generics/
• Article: “Preparing for Generics: An Introduction” by Paul Mingardi
  http://developer.java.sun.com/developer/technicalArticles/releases/generics/