1<html><head> 2 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 3 <title>Chapter 10. Annotations</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="FindBugs™ Manual"><link rel="up" href="index.html" title="FindBugs™ Manual"><link rel="prev" href="analysisprops.html" title="Chapter 9. Analysis Properties"><link rel="next" href="rejarForAnalysis.html" title="Chapter 11. Using rejarForAnalysis"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. Annotations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="analysisprops.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="rejarForAnalysis.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 10. Annotations"><div class="titlepage"><div><div><h2 class="title"><a name="annotations"></a>Chapter 10. Annotations</h2></div></div></div><p> 4<span class="application">FindBugs</span> supports several annotations to express the developer's intent 5so that FindBugs can issue warnings more appropriately. You need to use 6Java 5 to use annotations, and must place the annotations.jar and jsr305.jar 7files in the classpath while compiling your program. 8</p><div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.CheckForNull</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter 9 <p> 10The annotated element might be null, and uses of the element should check for null. 11When this annotation is applied to a method it applies to the method return value. 12 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.CheckReturnValue</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Method, Constructor 13 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 14 <span class="command"><strong>priority:</strong></span>The priority of the warning (HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 15 </p><p> 16 <span class="command"><strong>explanation:</strong></span>A textual explaination of why the return value should be checked. Default value:"". 17 </p></dd></dl></div><p> 18This annotation is used to denote a method whose return value should always be checked after invoking the method. 19 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotation</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package 20 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 21 <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. 22 </p><p> 23 <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 24 </p></dd></dl></div><p> 25Indicates that all members of the class or package should be annotated with the default 26value of the supplied annotation classes. This would be used for behavior annotations 27such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use 28@DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only 29on those parameters, methods or fields that you want to allow to be null. 30 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package 31 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 32 <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. 33 </p><p> 34 <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 35 </p></dd></dl></div><p> 36This is same as the DefaultAnnotation except it only applys to fields. 37 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package 38 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 39 <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. 40 </p><p> 41 <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 42 </p></dd></dl></div><p> 43This is same as the DefaultAnnotation except it only applys to methods. 44 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Package 45 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 46 <span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified. 47 </p><p> 48 <span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM. 49 </p></dd></dl></div><p> 50This is same as the DefaultAnnotation except it only applys to method parameters. 51 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.NonNull</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter 52 <p> 53The annotated element must not be null. 54Annotated fields must not be null after construction has completed. Annotated methods must have non-null return values. 55 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.Nullable</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter 56 <p> 57The annotated element could be null under some circumstances. In general, this means 58developers will have to read the documentation to determine when a null value is 59acceptable and whether it is neccessary to check for a null value. FindBugs will 60treat the annotated items as though they had no annotation. 61 </p><p> 62In pratice this annotation is useful only for overriding an overarching NonNull 63annotation. 64 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Method 65 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 66 <span class="command"><strong>value:</strong></span>Specify when the super invocation should be 67 performed (FIRST, ANYTIME, LAST). Default value:ANYTIME. 68 </p></dd></dl></div><p> 69Used to annotate a method that, if overridden, must (or should) be invoke super 70in the overriding method. Examples of such methods include finalize() and clone(). 71The argument to the method indicates when the super invocation should occur: 72at any time, at the beginning of the overriding method, or at the end of the overriding method. 73(This anotation is not implmemented in FindBugs as of September 8, 2006). 74 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.PossiblyNull</strong></span></span></dt><dd><p> 75This annotation is deprecated. Use CheckForNull instead. 76 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.SuppressWarnings</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Type, Field, Method, Parameter, Constructor, Package 77 <div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p> 78 <span class="command"><strong>value:</strong></span>The name of the warning. More than one name can be specified. 79 </p><p> 80 <span class="command"><strong>justification:</strong></span>Reason why the warning should be ignored. Default value:"". 81 </p></dd></dl></div><p> 82The set of warnings that are to be suppressed by the compiler in the annotated element. 83Duplicate names are permitted. The second and successive occurrences of a name are ignored. 84The presence of unrecognized warning names is <span class="emphasis"><em>not</em></span> an error: Compilers 85must ignore any warning names they do not recognize. They are, however, free to emit a 86warning if an annotation contains an unrecognized warning name. Compiler vendors should 87document the warning names they support in conjunction with this annotation type. They 88are encouraged to cooperate to ensure that the same names work across multiple compilers. 89 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.UnknownNullness</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter 90 <p> 91Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. 92 </p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.UnknownNullness</strong></span></span></dt><dd><span class="command"><strong>[Target]</strong></span> Field, Method, Parameter 93 <p> 94Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. 95 </p></dd></dl></div><p> 96 <span class="application">FindBugs</span> also supports the following annotations: 97</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">net.jcip.annotations.GuardedBy</li><li class="listitem">net.jcip.annotations.Immutable</li><li class="listitem">net.jcip.annotations.NotThreadSafe</li><li class="listitem">net.jcip.annotations.ThreadSafe</li></ul></div><p> 98</p><p> 99You can refer the JCIP annotation <a class="ulink" href="http://jcip.net/annotations/doc/index.html" target="_top"> 100API documentation</a> at <a class="ulink" href="http://jcip.net/" target="_top">Java Concurrency in Practice</a>. 101</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analysisprops.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="rejarForAnalysis.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. Analysis Properties </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. Using rejarForAnalysis</td></tr></table></div></body></html>