Common Annotations
Stable
Overview of Common Annotations module
The Common Annotations module provides the
CommonAnnotationsAPI
that contains annotations usable across the IDE sources. One such type
of annotations can guard (together with FindBugs)
your code against null related defects.
In case your module is using projectized.xml you can simply run
ant findbugs to check your module. In such case the result is
available in nbbuild/build/findbugs/your-module-name.xml.
What is New (see all changes)?
-
Apr 1 '21 Exposing necessary javax.annotation elements
In order to enable
-Werrorto treat warnings as errors, we need to get rid of annotation errors caused by missingWhenconstants as PR-2835 explains. This is done by exposing transitively needed, but previously missingjavax.annotationelements. Javadoc for thejavaxisn't generated and they aren't recommended to be used directly. -
Feb 1 '13 Added justification attribute to
SuppressWarningsIntroduced justification attribute to specify why it is ok to suppress a warning.
-
Nov 28 '11 Added
StaticResourceIntroduced an annotation for validating the existence of static resources.
- Jan 22 '09 Initial version released First initial release of the Common Annotations API.
Use Cases
CheckReturnValue annotated method
When the method return value is important value to check (or the only effect the method has) the method can be annotated with CheckReturnValue. Annotation serves as documentation as well as a hint for static code analysis.
CheckForNull annotated method
Method annotated with
CheckForNull
may return null value. Annotation serves as documentation
as well as a hint for static code analysis.
NonNull annotated element
When the field, parameter, local variable or return value of the method
must not be null the
NonNull
annotation can be used to clearly express this. It serves as documentation
as well as a hint for static code analysis.
NullAllowed annotated element
Field, parameter or local variable annotated with
NullAllowed
can contain null value so null check should
occur before any dereference. Annotation serves as documentation
as well as a hint for static code analysis.
NullUnknown annotated element
Annotation
NullUnknown
complementing other nullness annotations serves for cases where
the element may or may not be null under certain
defined circumstances (usage).
SuppressWarnings annotated element
When the analysis tool report false warning it is possible to use SuppressWarning annotation to suppress the warning.
Exported Interfaces
This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...Group of java interfaces
| Interface Name | In/Out | Stability | Specified in What Document? |
|---|---|---|---|
| CommonAnnotationsAPI | Exported | Stable | .../annotations/common/package-summary.html |
Implementation Details
Where are the sources for the module?
The sources for the module are in the Apache Git repositories or in the GitHub repositories
What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?
Nothing.
Read more about the implementation in the answers to architecture questions.