Reply

Clean Up Warnings with the 'restriction' Suppression Flag

At 12:04 AM on Feb 20, 2006, R.J. Lorimer wrote:

Eclipse 3.2 M5 brings the addition of a new supported SuppressWarnings annotation parameter: 'restriction'. This new annotation allows you to tell the Eclipse JDT compiler to stop nagging you about something naughty you are doing in your code, such as referencing an 'internal' package in your Eclipse plug-in, or perhaps your project has access rules defined, as I described previously here . These access rules and definitions exist for a reason; to warn you if you are breaking rules. That being said, sometimes breaking rules is neccessary; and in those cases it's nice to be able to tell Eclipse to keep it's mouth shut .

The Eclipse JDT compiler will happily process this annotation at any level - at a type, a field, a method, a method parameter, a constructor, or even a local variable or statement - something which the Javac compiler doesn't currently support for any annotations as far as I know.

As an example, say we are trying to avoid any AWT usage whatsoever in our application due to some valid reason, or perhaps just due to an extreme distaste for the long-toothed windowing toolkit. Maybe we want to ensure we use Swing instead, so we have some simple rules set up, such as this one:

java/awt/** - discouraged

(Follow the instructions in the tip referenced above to try this out).

Now, we all know that in some cases it might be beneficial to reference AWT code even when coding in Swing - so when those cases arise we can use this new annotation to keep the compiler happy. We could use the annotation in this way:

package com.javalobby.tnt.misc;
 
import java.awt.*;
 
public class RestrictedWarningTest {
	public static void main(String[] args) {
		@SuppressWarnings("restriction")
		Frame f = new Frame();
	}
}	

In this case, even though we are referencing the AWT frame class, Eclipse won't mark the frame usage as bad because we are suppressing that warning with the annotation. Now, let's say that we had more lines that were breaking rules.

package com.javalobby.tnt.misc;
 
import java.awt.*;
 
public class RestrictedWarningTest {
	public static void main(String[] args) {
		@SuppressWarnings("restriction")
		Frame f = new Frame();
		f.setVisible(true);
	}
}

What happens? Well, long story short, the first line that instantiates the frame is quietly accepted, but the line that sets the visibility is flagged as being a no-no. One way to ensure that Eclipse accepts all of these lines as a neccessary evil is to naturally group them in a method, and assign the annotation to the method rather than the statement:

public class RestrictedWarningTest {
	public static void main(String[] args) {
		doNaughtyAWTStuff();
	}
	
	@SuppressWarnings("restriction")
	private static void doNaughtyAWTStuff() {
		Frame f = new Frame();
		f.setVisible(true);
	}
}

This parameter is something that the Eclipse JDT compiler exclusively will recognize; the Java compiler will not at this time, even in Mustang (aka Java 6). Java 5 (Tiger) won't even process the SuppressWarnings annotation at all.

That's not to say that it's a problem; the SuppressWarnings annotation explicitly states that compilers must accept parameters they don't recognize, and compile accordingly. It does leave the option for the compiler to throw a warning (How ironic, the compiler can emit a warning when we are trying to suppress them).

Here is more from the annotation documentation:

The set of warnings that are to be suppressed by the compiler in the annotated element. Duplicate names are permitted. The second and successive occurrences of a name are ignored. The presence of unrecognized warning names is not an error: Compilers must ignore any warning names they do not recognize. They are, however, free to emit a warning if an annotation contains an unrecognized warning name.

Compiler vendors should document the warning names they support in conjunction with this annotation type. They are encouraged to cooperate to ensure that the same names work across multiple compilers.

Until next time,

R.J. Lorimer
Contributing Editor - rj -at- javalobby.org
Author              - http://www.coffee-bytes.com
Software Consultant - http://www.numbersix.com

8 replies so far ( Post your own)