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