Category Archives: Javac

Installing Java 7 on Debian Squeeze

For all of my servers I use Debian, however that distribution has a few problems, mainly the packages can be a bit behind the cutting edge.

Now this is usually a good thing if you are looking for stability – cutting edge software can have issues, especially from new features etc, so for a live environment you want something thats stable.

However, there does come a time when this can bite back. You either need a feature thats not in the standard repositories or in this case the version is now unsupported.

In Debian Squeeze it has Java 6 – but that was EOL’d a couple of months ago so is no longer supported by Oracle. The current version is Java 7 update 17.

So how do we get Java 7 installed?

Well it’s pretty easy to do, we just need to add another repository into apt and install it.

First the repository:

sudo su -
echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu precise main" | tee -a /etc/apt/sources.list
echo "deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu precise main" | tee -a /etc/apt/sources.list
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys EEA14886
apt-get update
exit

What that does is to install the ubuntu ppa repository into apt, setup the public keys and then load the package lists.

Next we need to install it:

sudo apt-get install oracle-java7-installer

This will now download Oracle Java 7 and present you with a couple of screens about licensing. Just ok and accept it and it will now install.

That’s it. You now have Java 7 installed – but it’s not the default JDK (if you already had Java 6 installed). If you want it to be the default then there’s just one more thing to do:

sudo apt-get install oracle-java7-set-default

That’s a dummy package but it will make Java 7 the default on that machine. If you want to check then you can check:

peter@titan ~ $ java -version
java version "1.7.0_17"
Java(TM) SE Runtime Environment (build 1.7.0_17-b02)
Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)
Tagged , , , , , , ,

Validating source with Annotation Processors

The release of retepTools 9.2 this week introduces a new annotation processor which validates the use of some of the annotations provided by the library generating either compilation warnings or errors dependent upon the errors found. This article describes how that processor works and the reasons behind it’s creation.

In the previous article I wrote about problems in reading values from Annotations in super types. That issue had cropped up due to some of the rules required for this processor.

Now this processor is still in it’s early stages of development but it works and is therefore useable. The rules that follow are those it will enforce and those will not change – although I will almost certainly add more over time.

The rules

Each rule defined below follows this template:

package.Annotation

Action when violated: Compile time error/warning

Mutually excludes: package.AnotherAnnotation…

Related: package.RelatedAnnotation

The Action when violated indicates if an error or warning wouild be produced if that rule is violated.

If the Mutually excludes line is present, then a compile time error will be generated if the annotation is present on an element with any of the listed annotations.

If the Related line is present, it lists annotations that are related and can affect the outcome of this rule.

1 Concurrency RULES

The main set of rules are for concurrency. In previous versions there’s a set of annotations which inject code into the methods they annotate ensuring those methods run within a specific lock – either a standard java.util.concurrent.locks.ReentrantLock or a java.util.concurrent.locks.RentrantReadWriteLock. The problem was that without compile time checking it would be possible to mark a method in one class as being a ReadLock, but then override that method in a subclass and annotate it with WriteLock. Now this would cause an immediate deadlock.

So here are the rules enforced for concurrency:

net.jcip.annotations.NotThreadSafe

Action when violated: Compile time error

Mutually excludes: net.jcip.annotations.ThreadSafe

This annotation is still optional, however it should be declared on a class that may be used in a concurrent context to indicate that it does not use any concurrency. For example an implementation of List should be marked @NotThreadSafe, but a ConcurrentList implementation with @ThreadSafe.

When it is present, this rule will generate a compile time error if any of the concurrency annotations are used in that class. Also subclasses cannot be ThreadSafe due to this class being NotThreadSafe.

For obvious reasons this annotation is mutually exclusive with NotThreadSafe

net.jcip.annotations.ThreadSafe

Action when violated: Compile time error

Mutually excludes: net.jcip.annotations.NotThreadSafe

For all classes that use any of the concurrency annotations must now be marked as ThreadSafe. The reason behind this is to ensure that documentation indicates that the class is ThreadSafe, but also to ensure that subclasses are also ThreadSafe as they can affect the concurrency of the super class. Because of this, a subclass of a class annotated with ThreadSafe must also be marked as ThreadSafe.

For obvious reasons this annotation is mutually exclusive with NotThreadSafe

uk.org.retep.annotations.Lock

Action when violated: Compile time error or warning

Mutually excludes: uk.org.retep.annotations.ReadLock, uk.org.retep.annotations.WriteLock

Related: uk.org.retep.annotations.Contract

This annotation indicates that the method runs within a shared lock. As defined by the annotations javadoc, it injects code into the method to gain the lock, run the method body and then release the lock.

This rule ensures that:

  • The method cannot be annotated with a ReadLock or WriteLock as those annotations are mutually exclusive with this one – generates an error.
  • If the method is overridden then a warning is issued that the overridden method code will be running outside of the lock.
  • As there’s a contract defined in the javadoc for a method called lock() to be defined then that method should be annotated with @Contract( Lock.class ) to document that it’s bound by that Contract. If it is not then a warning is generated.
  • The Contract for the support lock() method that is enforced is that the method has one of the following signatures. If it does not have these signatures then an error is generated: private java.util.concurrent.locks.Lock lock(); or protected final java.util.concurrent.locks.Lock lock();
  • The class is annotated with @ThreadSafe.

uk.org.retep.annotations.ReadLock

Action when violated: Compile time error or warning

Mutually excludes: uk.org.retep.annotations.Lock, uk.org.retep.annotations.WriteLock

Related: uk.org.retep.annotations.Contract

This annotation indicates that the method runs within a shared read lock. As defined by the annotations javadoc, it injects code into the method to gain the lock, run the method body and then release the lock.

This rule ensures that:

  • The method cannot be annotated with a Lock or WriteLock as those annotations are mutually exclusive with this one – generates an error.
  • If the method is overridden then a warning is issued that the overridden method code will be running outside of the lock.
  • As there’s a contract defined in the javadoc for a method called readLock() to be defined then that method should be annotated with @Contract( ReadLock.class ) to document that it’s bound by that Contract. If it is not then a warning is generated.
  • The Contract for the support readLock() method that is enforced is that the method has one of the following signatures. If it does not have these signatures then an error is generated: private java.util.concurrent.locks.Lock readLock(); or protected final java.util.concurrent.locks.Lock readLock();
  • The class is annotated with @ThreadSafe.

uk.org.retep.annotations.WriteLock

Action when violated: Compile time error or warning

Mutually excludes: uk.org.retep.annotations.Lock, uk.org.retep.annotations.ReadLock

Related: uk.org.retep.annotations.Contract

This annotation indicates that the method runs within a shared lock. As defined by the annotations javadoc, it injects code into the method to gain the lock, run the method body and then release the lock.

This rule ensures that:

  • The method cannot be annotated with a Lock or ReadLock as those annotations are mutually exclusive with this one – generates an error.
  • If the method is overridden then a warning is issued that the overridden method code will be running outside of the lock.
  • As there’s a contract defined in the javadoc for a method called writeLock() to be defined then that method should be annotated with @Contract( WriteLock.class ) to document that it’s bound by that Contract. If it is not then a warning is generated.
  • The Contract for the support writeLock() method that is enforced is that the method has one of the following signatures. If it does not have these signatures then an error is generated: private java.util.concurrent.locks.Lock writeLock(); or protected final java.util.concurrent.locks.Lock writeLock();
  • The class is annotated with @ThreadSafe.

2 Singletons

There are two annotations provided for supporting singletons:

uk.org.retep.annotations.NoInstance

Action when violated: Compile time error

Mutually excludes: uk.org.retep.annotations.Singleton

A class marked with NoInstance implies that there can be no instance of this class – i.e. a class with just static fields or methods.

This rule will generate an error if the class violates any of the following:

  • The class is not declared final as it cannot have subclasses
  • The class has a non private default constructor
  • The class has a non default constructor
  • The class has any instance methods or fields
  • The class has a field referencing itself – i.e. private static Class instance;
  • The class has a method who’s return type is that of the class
  • The class is annotated with Singleton as its mutually exclusive with NoInstance

uk.org.retep.annotations.Singleton

Action when violated: Compile time error

Mutually excludes: uk.org.retep.annotations.NoInstance

A class marked with Singleton implies that there is only a single instance of this class .

This rule will generate an error if the class violates any of the following:

  • The class is not declared final as it cannot have subclasses
  • The class has a non private default constructor
  • The class has a non default constructor
  • The class has no instance methods or fields
  • The class does not have a private static field referencing itself – i.e. private static Class instance;
  • The class does not have a public static method who’s return type is that of the class
  • The class is annotated with NoInstance as its mutually exclusive with Singleton

3 Miscellaneous

This set of rules are not associated with any annotations but enforce certain optional rules.

3.1 hashCode and Equals

When enabled ensures that if a class overrides either of the hashCode() or equals() methods then a compiler error is issued if the class does not override both of them. This is because there is a contract between those two methods where equals() can return true only if the hashCode of both object are also equal (read the docs for java.lang.Object if you disagree).

This rule came about because recently I had a class that was misbehaving in a map and it was because it had not defined both methods.

This rule is enabled by default and can be turned off by passing a configuration parameter to javac.

3.2 Missing javadoc comments

When enabled this rule will generate either a compiler warning or error if a non-private method has no documentation. This option is disabled by default but can be enabled by passing a configuration parameter to javac. The type of action when the rule is violated is itself configurable for this rule.

4 Configuration

The processor has some level of configurability, enabling certain rules to be enabled or disabled depending on user requirements.

4.1 Javac

When using the javac command you can pass any of the following options on the command line, prefixing them with -A. They then take a single value, either true or false to turn that option on or off. For example to turn on the missing javadoc rule, then you would pass -AwarnMissingJavadocs=true to javac.

4.2 Maven

When using the maven compiler plugin you are supposed to be able to add the javac options to the pom by using the compilerArgument attribute:

<compilerArgument>-AfailHashCodeEquals=true -AwarnMissingJavadocs=true</compilerArgument>

The problem is that although this is shown in the plugins documentation, it doesn’t work as it gets passed to javac as a single argument and not as a set of arguments.

To get around this the processor also supports a special option called mavenOpts who’s value is a comma separated list of the required features – if the feature is in the string then it is enabled. To disable a feature then simply prefix the feature with either ! or ^ – there’s two options to negate as some shells use ! so it’s not always possible to use on the command line:

<compilerArgument>-AmavenOpts=failHashCodeEquals,^warnMissingJavadocs</compilerArgument>

4.3 Currently supported options

failHashCodeEquals

Should an error occur if one of hashCode or equals is overridden but not the other? Enabled by default

warnMissingJavadocs

If enabled a compiler warning is generated for each non private method or field that has no documentation.

failMissingJavaDocs

This overrides warnMissingJavadocs if enabled. This will cause a compiler error to be issued if a non private method or field has no documentation.

Getting Class values from Annotations in an AnnotationProcessor

In annotation processors one common use case is to read the values contained within an Annotation. In most cases this works fine, however there are some caveats when it comes to accessing values within Annotations that are either Class or a Class array. It’s even worse if you are trying to access an annotation on a method within a super type of the class you are processing. Here I’ll go through how to access those Class values and how to get those values when they are in a super type – specifically when a method has been overridden.

First why?

Well inside retepTools we have an AnnotationProcessor that checks to ensure that certain annotations are used correctly, specifically the @ReadLock and @WriteLock annotations. It’s invalid for those annotations to be used together on the same method. It’s also invalid for a method to be annotated with one and then overridden in another class but annotated with the other, so the processor checks the overridden method and generates an error if the rules have been violated.

Now this caused be a big headache in reading the overridden annotations, because although the annotations were present, the values (and specific the Class ones) were null. Although @ReadLock and @WriteLock do not use values, another related annotation @Contract does, so here’s how I finally solved the problem.

The usual way of reading annotation values

In most cases, when you have an javax.lang.model.element.Element you can use the getAnnotation() method to return your annotation and then you have access to the values contained within it. For example say we have an annotation called Action which holds a single String value:

@Documented
@Retention( RetentionPolicy.RUNTIME )

@Target(ElementType.METHOD)

public @interface Action

{

    String value();

}

We annotate a class with that annotation against the run method:

public class A {

    @Action( “do something” )

    public void run() {

    }

}

Now within your AnnotationProcessor, you can obviously get the value easily by calling getAnnotation( Action.class ) and if it returns an instance call the value() method:

@SupportedAnnotationTypes( “*” )

@SupportedSourceVersion( SourceVersion.RELEASE_6 )

@ProhibitAnnotationProcessing

public class Processor

        extends AbstractProcessor

{

    @Override

    public boolean process( final Set<? extends TypeElement> annotations,

                            final RoundEnvironment env )

    {

        if( !env.processingOver() )

        {

            for( Element e : env.getRootElements() )

            {

                TypeElement te = findEnclosingTypeElement( e );

                System.out.printf( “\nScanning Type %s\n\n”,

                                   te.getQualifiedName() );

                for( ExecutableElement ee : ElementFilter.methodsIn(

                        te.getEnclosedElements() ) )

                {

                    Action action = ee.getAnnotation( Action.class );

                    

                    System.out.printf(

                            “%s Action value = %s\n”,

                            ee.getSimpleName(),

                            action == null ? null : action.value() );

                }

            }

        }

        return false;

    }

    public static TypeElement findEnclosingTypeElement( Element e )

    {

        while( e != null && !(e instanceof TypeElement) )

        {

            e = e.getEnclosingElement();

        }

        return TypeElement.class.cast( e );

    }

}

This generates the following output when run:

————————————————————————

Building scratch

   task-segment: [clean, install]

————————————————————————

[clean:clean]

Deleting directory /Users/peter/dev/retep/scratch/target

[compiler:compile {execution: compileAnnotations}]

Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes

[resources:resources]

Using default encoding to copy filtered resources.

[compiler:compile]

Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes

Scanning Type scratch.A

run Action value = do something

Reading annotation values from an overridden method

Now this is fine, but what happens if you are looking at an annotation thats in an overridden class?

Say we have class B which extends A and overrides run():

public class B extends A {

    @Override

    public void run() {

    }

}

Now when we run the processor, for each ExecutableElement we’ll first look for an annotation and then if not found we’ll look for an overridden method and check there. 

    @Override

    public boolean process( final Set<? extends TypeElement> annotations,

                            final RoundEnvironment env )

    {

        if( !env.processingOver() )

        {

            for( Element e : env.getRootElements() )

            {

                TypeElement te = findEnclosingTypeElement( e );

                System.out.printf( “\nScanning Type %s\n\n”,

                                   te.getQualifiedName() );

                for( ExecutableElement ee : ElementFilter.methodsIn(

                        te.getEnclosedElements() ) )

                {

                    Action action = ee.getAnnotation( Action.class );

                    if( action == null )

                    {

                        // Look for the overridden method

                        ExecutableElement oe = getExecutableElement( te,

                                                                     ee.getSimpleName() );

                        if( oe != null )

                        {

                            action = oe.getAnnotation( Action.class );

                        }

                    }

                    System.out.printf(

                            “%s Action value = %s\n”,

                            ee.getSimpleName(),

                            action == null ? null : action.value() );

                }

            }

        }

        return false;

    }

    public ExecutableElement getExecutableElement( final TypeElement typeElement,

                                                   final Name name )

    {

        TypeElement te = typeElement;

        do

        {

            te = (TypeElement) processingEnv.getTypeUtils().asElement(

                    te.getSuperclass() );

            if( te != null )

            {

                for( ExecutableElement ee : ElementFilter.methodsIn(

                        te.getEnclosedElements() ) )

                {

                    if( name.equals( ee.getSimpleName() ) && ee.getParameters().isEmpty() )

                    {

                        return ee;

                    }

                }

            }

        } while( te != null );

        return null;

    }

Now when we run we get the annotated value on A.run() when we are processing B.run():

[compiler:compile]

Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes

Scanning Type scratch.A

run Action value = do something

Scanning Type scratch.B

run Action value = do something

The problem with Class

Now this is fine, but what happens if the annotation’s value is Class instead of String? Well the problem here is that Javac does not load classes in the normal manner. In fact it doesn’t at all for classes that are in the source – it’s all contained within a model.

Now say our Action annotation had value defined as Class instead of String. In that case when we call action.value() it would fail:

[compiler:compile]

Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes

Scanning Type scratch.A

javax.lang.model.type.MirroredTypeException: Attempt to access Class object for TypeMirror java.lang.Runnable

So we have to find another way to get the value, and there are two available to us. The first is not to use getAnnotation() but getAnnotationMirrors(), and the second is a neat trick with MirroredTypeException.

Solution 1 use getAnnotationMirrors()

This solution is a little long winded but is the most reliable. When getAnnotationMirrors() is used, it returns a set of AnnotationMirror instances, one for each annotation on that Element, so the first step is to locate the correct AnnotationMirror for the annotation you require. The next step is to extract the AnnotationValue’s from that mirror which represents the values stored in the annotation. This is held in a map keyed by an ExecutableElement.

Why ExecutableElement? Well it’s because the annotation values are actually defined as methods – hence why in our Action value is defined as value().

So in the next example we run through the AnnotationMirrors on a method until we find the one for our annotation then run through until we find the required value.

Once we have the AnnotationValue we simply print it to System.out but normally you would use the getValue() method which returns the value as an Object. If the value is an array it returns a java.util.List containing the values. Oh and if the values are of type Class then it returns a TypeMirror or a List of TypeMirrors.

Element actionElement = processingEnv.getElementUtils().getTypeElement(

        Action.class.getName() );

TypeMirror actionType = actionElement.asType();

for( ExecutableElement ee : ElementFilter.methodsIn(

        te.getEnclosedElements() ) )

{

    ExecutableElement oe = ee;

    AnnotationValue action = null;

    while( action == null && oe != null )

    {

        for( AnnotationMirror am : oe.getAnnotationMirrors() )

        {

            if( am.getAnnotationType().equals( actionType ) )

            {

                for( Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : am.getElementValues().entrySet() )

                {

                    if( “value”.equals(

                            entry.getKey().getSimpleName().toString() ) )

                    {

                        action = entry.getValue();

                        break;

                    }

                }

            }

        }

        // Look for the overridden method

        oe = getExecutableElement(

                findEnclosingTypeElement( oe ),

                ee.getSimpleName() );

    }

    System.out.printf(

            “%s Action value = %s\n”,

            ee.getSimpleName(),

            action == null ? null : action );

}

Now at first that appears to work, and in most use cases it does – if we have a method thats overridden then we get the annotation values from the overridden method.

However, although its not obvious, if the super type is not part of the same CompilationUnit – i.e. it’s in a third party jar or from a previous call to javac then it will not find anything outside of that CompilationUnit.

The trouble with TypeMirrors

Now the cause on why the solution above fails isn’t obvious. The problem here is actually down to the TypeMirror’s. In the above example we get a TypeMirror for the annotation called actionType then search the AnnotationMirror set of each element using that TypeMirror.

Now TypeMirror acts in a similar way to how Class works at runtime. At run time Class is equal if it’s in the same ClassLoader, so here TypeMirror is equal if it’s in the same CompilationUnit. So the example above fails because they are different instances.


So the solution here is not to use TypeMirror.equals() but to convert the TypeMirror into a String representing the fully qualified class name and use equals() on that String. Now, no matter what  source the super type comes from, it will always match.

Here’s the new version:

final String actionName = Contract.class.getName();

for( ExecutableElement ee : ElementFilter.methodsIn(

        te.getEnclosedElements() ) )

{

    ExecutableElement oe = ee;

    AnnotationValue action = null;

    while( action == null && oe != null )

    {

        for( AnnotationMirror am : oe.getAnnotationMirrors() )

        {

            if( actionName.equals(

                    am.getAnnotationType().toString() ) )

            {

                for( Map.Entry<? extends ExecutableElement, ? extends AnnotationValue> entry : am.getElementValues().entrySet() )

                {

                    if( “value”.equals(

                            entry.getKey().getSimpleName().toString() ) )

                    {

                        action = entry.getValue();

                        break;

                    }

                }

            }

        }

        // Look for the overridden method

        oe = getExecutableElement(

                findEnclosingTypeElement( oe ),

                ee.getSimpleName() );

    }

    System.out.printf(

            “%s Action value = %s\n”,

            ee.getSimpleName(),

            action == null ? null : action );

}

Now that one works. The lesson here is to use the String version of TypeElement when searching as two TypeElement’s representing the same class are not always equal.

Solution 2 – Single Class values

Now if your value contains just one Class (i.e. not Class[] ) then there’s a much simpler solution. This one isn’t that obvious, but I found that someone had a similar problem in the sun forums[1]. There the trick is to actually use getAnnotation() and catch the MirroredTypeException. Surprisingly the exception then provides the TypeMirror of the required class:

for( ExecutableElement ee : ElementFilter.methodsIn(

        te.getEnclosedElements() ) )

{

    Action action = ee.getAnnotation( Action.class );

    if( action == null )

    {

        // Look for the overridden method

        ExecutableElement oe = getExecutableElement( te,

                                                     ee.getSimpleName() );

        if( oe != null )

        {

            action = oe.getAnnotation( Action.class );

        }

    }

    TypeMirror value = null;

    if( action != null )

    {

        try

        {

            action.value();

        }

        catch( MirroredTypeException mte )

        {

            value = mte.getTypeMirror();

        }

    }

    System.out.printf(

            “%s Action value = %s\n”,

            ee.getSimpleName(),

            value );

}

Notice getTypeMirror() method call? Here’s the output of the above loop:

[compiler:compile]

Compiling 2 source files to /Users/peter/dev/retep/scratch/target/classes

Scanning Type scratch.A

run Action value = java.lang.Runnable

Scanning Type scratch.B

run Action value = java.lang.Runnable

This trick works fine for individual classes, but sadly it does not work for Class[] arrays. According to the javadocs it should work for Class[] as it should then throw the MirroredTypesException instead and that exception contains an alternate method that returns a List of TypeMirrors.

However it doesn’t – it simply throws MirroredTypeException for the first element in the array. I think it’s where it’s running through the array to populate it and the first element is then throwing MirroredTypeException before it gets chance to throw MirroredTypesException.

Conclusion

Well, hopefully this article will save someone hours of trouble when they hit the same problem. I’ve spent about 20 hours of time searching the net and dabbling for these solutions – and at least these solutions use just the documented public APIs.

References

  1. http://forums.sun.com/thread.jspa?threadID=791053
Follow

Get every new post delivered to your Inbox.

Join 1,770 other followers