Add additional way to exclude code parts using annotations

[GoogleCodeExporter]

This issue will implement a new mechanism to exclude specific classes or (this 
is new!) specific methods or parts of methods from being checked with 
ForbiddenAPIs.

The idea here is to use an annotation, that must have at least 
RetentionPolicy.CLASS or RetentionPolicy.RUNTIME. ForbiddenAPIs will not 
provide such an annotation, it can simply configured to look for any annotation 
type(s), configured as a list of Class parameters.

This allows to run forbidden-apis with ant like:

<forbiddenapis supressAnnotations="org.foo.bar.SuppressForbidden" .../>

(same in maven as a list of class properties).

You have to define the custom annotation (or multiples) as part of your own 
project, so we get no external dependencies. You can also misuse another 
annotation (LOL). The annotation must just be of RetentionPolicy.CLASS or 
RetentionPolicy.RUNTIME. It does not need to be documented. Just SOURCE-only 
annotations won't work (because no longer visible in class files).

You can then annotate classes with this annotation (which does the same like 
excluding the class file using the excludes="...." Ant/Maven config settings) 
or go down to methods or code lines. In fact depending on the type of your 
annotation, you can use it like SuppressWarnings. So annotate any method, code 
line, or parameter [not yet decided if this makes sense] you want t exclude 
from checking (or in Java 8 also types).

Forbidden-APIs will add an "example/default annotation" in its own JAR file, 
but you are not required to use it (especially if you don't want to have a 
compile-time dependency to forbiddenapis).

Original issue reported on code.google.com by uwe.h.schindler on 14 Sep 2014 at 5:08

[GoogleCodeExporter]

In addition, the custom annotation may not even public, can be package private 
anyways. The checker will just look for the class name name when visiting an 
annotation in the ClassVisitor, not even validate or resolve it!

Original comment by uwe.h.schindler on 14 Sep 2014 at 5:12

[GoogleCodeExporter]

Issue 44 has been merged into this issue.

Original comment by uwe.h.schindler on 8 Dec 2014 at 7:06

[GoogleCodeExporter]

Issue 44 has been merged into this issue.

Original comment by uwe.h.schindler on 24 Dec 2014 at 12:19

[GoogleCodeExporter]

Issue 44 has been merged into this issue.

Original comment by uwe.h.schindler on 24 Dec 2014 at 12:24

[GoogleCodeExporter]

One thing: As the suppressing annotation may be reported later in the ASM 
visitor, the errors need to be buffered first and onlyprinted to output one the 
class/method/field was processed.

Issue #12 will handle this, as buffering of messages needs to be done to sort 
them by line number (needed for correct Java 8 behaviour), where synthetic 
methods are listed in class file out of order.

Original comment by uwe.h.schindler on 25 Dec 2014 at 12:31

[uschindler]

I added support for a default (shipped-with) annotation in afce079

[uschindler]

This should work now for Ant, Maven, CLI. Documentation was also updated.