101 lines
11 KiB
HTML
101 lines
11 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<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>
|
|
<span class="application">FindBugs</span> supports several annotations to express the developer's intent
|
|
so that FindBugs can issue warnings more appropriately. You need to use
|
|
Java 5 to use annotations, and must place the annotations.jar and jsr305.jar
|
|
files in the classpath while compiling your program.
|
|
</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
|
|
<p>
|
|
The annotated element might be null, and uses of the element should check for null.
|
|
When this annotation is applied to a method it applies to the method return value.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>priority:</strong></span>The priority of the warning (HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
|
|
</p><p>
|
|
<span class="command"><strong>explanation:</strong></span>A textual explaination of why the return value should be checked. Default value:"".
|
|
</p></dd></dl></div><p>
|
|
This annotation is used to denote a method whose return value should always be checked after invoking the method.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified.
|
|
</p><p>
|
|
<span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
|
|
</p></dd></dl></div><p>
|
|
Indicates that all members of the class or package should be annotated with the default
|
|
value of the supplied annotation classes. This would be used for behavior annotations
|
|
such as @NonNull, @CheckForNull, or @CheckReturnValue. In particular, you can use
|
|
@DefaultAnnotation(NonNull.class) on a class or package, and then use @Nullable only
|
|
on those parameters, methods or fields that you want to allow to be null.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified.
|
|
</p><p>
|
|
<span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
|
|
</p></dd></dl></div><p>
|
|
This is same as the DefaultAnnotation except it only applys to fields.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified.
|
|
</p><p>
|
|
<span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
|
|
</p></dd></dl></div><p>
|
|
This is same as the DefaultAnnotation except it only applys to methods.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>Annotation class objects. More than one class can be specified.
|
|
</p><p>
|
|
<span class="command"><strong>priority:</strong></span>Default priority(HIGH, MEDIUM, LOW, IGNORE). Default value:MEDIUM.
|
|
</p></dd></dl></div><p>
|
|
This is same as the DefaultAnnotation except it only applys to method parameters.
|
|
</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
|
|
<p>
|
|
The annotated element must not be null.
|
|
Annotated fields must not be null after construction has completed. Annotated methods must have non-null return values.
|
|
</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
|
|
<p>
|
|
The annotated element could be null under some circumstances. In general, this means
|
|
developers will have to read the documentation to determine when a null value is
|
|
acceptable and whether it is neccessary to check for a null value. FindBugs will
|
|
treat the annotated items as though they had no annotation.
|
|
</p><p>
|
|
In pratice this annotation is useful only for overriding an overarching NonNull
|
|
annotation.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>Specify when the super invocation should be
|
|
performed (FIRST, ANYTIME, LAST). Default value:ANYTIME.
|
|
</p></dd></dl></div><p>
|
|
Used to annotate a method that, if overridden, must (or should) be invoke super
|
|
in the overriding method. Examples of such methods include finalize() and clone().
|
|
The argument to the method indicates when the super invocation should occur:
|
|
at any time, at the beginning of the overriding method, or at the end of the overriding method.
|
|
(This anotation is not implmemented in FindBugs as of September 8, 2006).
|
|
</p></dd><dt><span class="term"><span class="command"><strong>edu.umd.cs.findbugs.annotations.PossiblyNull</strong></span></span></dt><dd><p>
|
|
This annotation is deprecated. Use CheckForNull instead.
|
|
</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
|
|
<div class="variablelist"><dl><dt><span class="term"><span class="command"><strong>[Parameter]</strong></span></span></dt><dd><p>
|
|
<span class="command"><strong>value:</strong></span>The name of the warning. More than one name can be specified.
|
|
</p><p>
|
|
<span class="command"><strong>justification:</strong></span>Reason why the warning should be ignored. Default value:"".
|
|
</p></dd></dl></div><p>
|
|
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 <span class="emphasis"><em>not</em></span> 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.
|
|
</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
|
|
<p>
|
|
Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
|
|
</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
|
|
<p>
|
|
Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses.
|
|
</p></dd></dl></div><p>
|
|
<span class="application">FindBugs</span> also supports the following annotations:
|
|
</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>
|
|
</p><p>
|
|
You can refer the JCIP annotation <a class="ulink" href="http://jcip.net/annotations/doc/index.html" target="_top">
|
|
API documentation</a> at <a class="ulink" href="http://jcip.net/" target="_top">Java Concurrency in Practice</a>.
|
|
</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> |