Author: kwin
Date: Fri Jun 30 15:12:38 2017
New Revision: 1800431
URL: http://svn.apache.org/viewvc?rev=1800431&view=rev
Log:
clarify where to use which JSR305 annotation
Modified:
sling/site/trunk/content/documentation/development/jsr-305.mdtext
Modified: sling/site/trunk/content/documentation/development/jsr-305.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/jsr-305.mdtext?rev=1800431&r1=1800430&r2=1800431&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/jsr-305.mdtext (original)
+++ sling/site/trunk/content/documentation/development/jsr-305.mdtext Fri Jun
30 15:12:38 2017
@@ -10,11 +10,13 @@ The annotations used within Sling are ba
Due to the fact that Eclipse and FindBugs are interpreting annotations
differently ([Findbugs-1355](https://sourceforge.net/p/findbugs/bugs/1355/)).
Sling only uses the following two different annotations which are supported by
both tools:
-1. `javax.annotation.CheckForNull`
-1. `javax.annotation.Nonnull`
+1. `javax.annotation.CheckForNull` (only on return values which may be `null`)
+1. `javax.annotation.Nonnull` (on return values and arguments which are never
supposed to be `null`)
Annotations which support setting the default null semantics of return values
and or parameters on a package level cannot be leveraged for that reason.
+In case no annotations have been set on method arguments those accept `null`
as a value. Return values should always be explicitly annotated, as from both
cases checks can be derived.
+
The annotations have a retention policy of `runtime`, therefore bundles using
these automatically have a `Import-Package` header listing `javax.annotation`.
That package is by default exported by the system bundle (as this package is
also part of the
[JRE](https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html)).
To be able to resolve the bundle through this exported package from the system
bundle you should use the `com.google.code.findbugs:jsr305` artifact in version
3.0.0 as that exports the package `javax.annotation` in no specific version.
Newer versions use version directives which automatically restrict the version
range for the generated `Import-Package` header to `[3,4)` [which usually
cannot be resolved at run time](https://github.com/amaembo/jsr-305/issues/31).
# Use With Eclipse
