Initial @nullable annoations

Author: Clint Checketts

pom.xml

@@ -73,6 +73,14 @@
       <scope>provided</scope>
       <optional>true</optional>
     </dependency>
+    <dependency>
+      <!--JSR-305 only used for non-required meta-annotations-->
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+      <version>3.0.2</version>
+      <scope>provided</scope>
+      <optional>true</optional>
+    </dependency>
     <dependency>
       <groupId>org.hamcrest</groupId>
       <artifactId>hamcrest-core</artifactId>

src/main/java/org/assertj/core/annotations/NonNull.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * Copyright 2012-2019 the original author or authors.
+ */
+package org.assertj.core.annotations;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierNickname;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A common annotation to declare that annotated elements cannot be {@code null}.
+ * Leverages JSR 305 meta-annotations to indicate nullability in Java to common tools with
+ * JSR 305 support and used by Kotlin to infer nullability of the API.
+ * <p>
+ * <p>Should be used at parameter, return value, and field level. Method overrides should
+ * repeat parent {@code @NonNull} annotations unless they behave differently.
+ * <p>
+ * <p>Use {@code @NonNullApi} (scope = parameters + return values) and/or {@code @NonNullFields}
+ * (scope = fields) to set the default behavior to non-nullable in order to avoid annotating
+ * your whole codebase with {@code @NonNull}.
+ *
+ * @see NonNullApi
+ * @see NonNullFields
+ * @see Nullable
+ */
+@Target({ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull
+@TypeQualifierNickname
+public @interface NonNull {
+}

src/main/java/org/assertj/core/annotations/NonNullApi.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * Copyright 2012-2019 the original author or authors.
+ */
+package org.assertj.core.annotations;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierDefault;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A common annotation to declare that parameters and return values
+ * are to be considered as non-nullable by default for a given package.
+ * <p>
+ * <p>Leverages JSR-305 meta-annotations to indicate nullability in Java to common
+ * tools with JSR-305 support and used by Kotlin to infer nullability of the API.
+ * <p>
+ * <p>Should be used at package level in association with {@link Nullable}
+ * annotations at parameter and return value level.
+ *
+ * @see NonNullFields
+ * @see Nullable
+ * @see NonNull
+ */
+@Target({ElementType.PACKAGE, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull
+@TypeQualifierDefault({ElementType.METHOD, ElementType.PARAMETER})
+public @interface NonNullApi {
+}

src/main/java/org/assertj/core/annotations/NonNullFields.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * Copyright 2012-2019 the original author or authors.
+ */
+package org.assertj.core.annotations;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierDefault;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A common annotation to declare that fields are to be considered as
+ * non-nullable by default for a given package.
+ *
+ * <p>Leverages JSR-305 meta-annotations to indicate nullability in Java to common
+ * tools with JSR-305 support and used by Kotlin to infer nullability of the API.
+ *
+ * <p>Should be used at package level in association with {@link Nullable}
+ * annotations at field level.
+ *
+ * @see NonNullFields
+ * @see Nullable
+ * @see NonNull
+ */
+@Target({ElementType.PACKAGE, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull
+@TypeQualifierDefault(ElementType.FIELD)
+public @interface NonNullFields {
+}

src/main/java/org/assertj/core/annotations/Nullable.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * Copyright 2012-2019 the original author or authors.
+ */
+package org.assertj.core.annotations;
+
+import javax.annotation.Nonnull;
+import javax.annotation.meta.TypeQualifierNickname;
+import javax.annotation.meta.When;
+import java.lang.annotation.*;
+
+/**
+ * A common annotation to declare that annotated elements can be {@code null} under
+ * some circumstance. Leverages JSR 305 meta-annotations to indicate nullability in Java
+ * to common tools with JSR 305 support and used by Kotlin to infer nullability of the API.
+ * <p>
+ * <p>Should be used at parameter, return value, and field level. Methods override should
+ * repeat parent {@code @Nullable} annotations unless they behave differently.
+ * <p>
+ * <p>Can be used in association with {@code NonNullApi} or {@code @NonNullFields} to
+ * override the default non-nullable semantic to nullable.
+ *
+ * @see NonNullApi
+ * @see NonNullFields
+ * @see NonNull
+ */
+@Target({ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Nonnull(when = When.MAYBE)
+@TypeQualifierNickname
+public @interface Nullable {
+}

src/main/java/org/assertj/core/api/exception/PathsException.java

@@ -12,10 +12,12 @@
  */
 package org.assertj.core.api.exception;
 
+import org.assertj.core.annotations.Nullable;
+
 public final class PathsException extends RuntimeException {
   private static final long serialVersionUID = 1L;
 
-  public PathsException(final String message, final Throwable cause) {
+  public PathsException(final String message, @Nullable final Throwable cause) {
     super(message, cause);
   }
 }

src/main/java/org/assertj/core/api/exception/package-info.java

@@ -0,0 +1,18 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * Copyright 2012-2019 the original author or authors.
+ */
+@NonNullApi
+@NonNullFields
+package org.assertj.core.api.exception;
+
+import org.assertj.core.annotations.NonNullApi;
+import org.assertj.core.annotations.NonNullFields;