Alternate names: ResultOfMethodCallIgnored, ReturnValueIgnored
The @CheckReturnValue
annotation (available in JSR-3051 or in
Error Prone) marks methods whose return values should be checked. This
error is triggered when one of these methods is called but the result is not
used.
@CheckReturnValue
may be applied to a class or package 2 to
indicate that all methods in that class or package must have their return values
checked.
For convenience, we provide an annotation, @CanIgnoreReturnValue
, to
exempt specific methods or classes from this behavior. @CanIgnoreReturnValue
is available from the Error Prone annotations package,
com.google.errorprone.annotations
.
If you really want to ignore the return value of a method annotated with
@CheckReturnValue
, a cleaner alternative to @SuppressWarnings
is to assign
the result to a variable that starts with unused
:
public void setNameFormat(String nameFormat) {
String unused = format(nameFormat, 0); // fail fast if the format is bad or null
this.nameFormat = nameFormat;
}
@CheckReturnValue
is ignored under the following conditions (which saves users
from having to use either an unused
variable or @SuppressWarnings
):
Calls from Mockito.verify()
or Stubber.when()
; e.g.,
Mockito.verify(t).foo()
or doReturn(val).when(t).foo()
(where foo()
is
annotated with @CheckReturnValue
). Here, the method calls are just used to
program the mock object, not to be consumed directly.
Code that does exception testing with JUnit, where the intent is that the method call should throw an exception:
Uses of JUnit 4.13 or JUnit5’s assertThrows
methods:
assertThrows(IndexOutOfBoundsException.class, () -> list.get(-1));
The try/execute/fail/catch
pattern
try {
list.get(-1);
fail("Expected a IndexOutOfBoundsException to be thrown on a negative index");
} catch (IndexOutOfBoundsException expected) {
}
JUnit’s ExpectedException
expectedException.expect(IndexOutOfBoundsException.class);
list.get(-1); // If this throws IOOBE, the test passes.
Suppress false positives by adding the suppression annotation @SuppressWarnings("CheckReturnValue")
to the enclosing element.
Of note, the JSR-305 project was never fully approved, so the JSR-305 version of the annotation is not actually official and causes issues with Java 9 and the Module System. Prefer to use the Error Prone version. ↩
To annotate a package, create a
package-info.java
file in the package directory, add a package statement,
and annotate the package statement. ↩