org.checkerframework.checker.nullness.qual.EnsuresNonNullIf Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of checker Show documentation

The Checker Framework enhances Java's type system to make it more powerful and useful. This lets software developers detect and prevent errors in their Java programs. The Checker Framework includes compiler plug-ins ("checkers") that find bugs or verify their absence. It also permits you to write your own compiler plug-ins.

The newest version!

package org.checkerframework.checker.nullness.qual;

import org.checkerframework.framework.qual.ConditionalPostconditionAnnotation;
import org.checkerframework.framework.qual.InheritedAnnotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

// TODO: In a fix for https://tinyurl.com/cfissue/1917, add the text:  Every prefix expression is
// also non-null; for example, {@code @EnsuresNonNullIf(expression="a.b.c", results=true)} implies
// that both {@code a.b} and {@code a.b.c} are non-null if the method returns {@code true}.
/**
 * Indicates that the given expressions are non-null, if the method returns the given result (either
 * true or false).
 *
 * Here are ways this conditional postcondition annotation can be used:
 *
 * 
Method parameters: A common example is that the {@code equals} method is annotated as
 * follows:
 *
 * 
{@code   @EnsuresNonNullIf(expression="#1", result=true)
 *   public boolean equals(@Nullable Object obj) { ... }}
 *
 * because, if {@code equals} returns true, then the first (#1) argument to {@code equals} was not
 * null.
 *
 * Fields: The value expressions can refer to fields, even private ones. For example:
 *
 * 
{@code   @EnsuresNonNullIf(expression="this.derived", result=true)
 *   public boolean isDerived() {
 *     return (this.derived != null);
 *   }}
 *
 * As another example, an {@code Iterator} may cache the next value that will be returned, in which
 * case its {@code hasNext} method could be annotated as:
 *
 * {@code   @EnsuresNonNullIf(expression="next_cache", result=true)
 *   public boolean hasNext() {
 *     if (next_cache == null) {
 *       return false;
 *     }
 *     ...
 *   }}
 *
 * An {@code EnsuresNonNullIf} annotation that refers to a private field is useful for verifying
 * that a method establishes a property, even though client code cannot directly affect the field.
 *
 * Method calls: If {@link Class#isArray()} returns true, then {@link
 * Class#getComponentType()} returns non-null. You can express this relationship as:
 *
 * 
{@code   @EnsuresNonNullIf(expression="getComponentType()", result=true)
 *   public native @Pure boolean isArray();}
 *
 * You can write two {@code @EnsuresNonNullIf} annotations on a single method:
 *
 * 
 *     @EnsuresNonNullIf(expression="outputFile", result=true)
 *     @EnsuresNonNullIf(expression="memoryOutputStream", result=false)
 *     public boolean isThresholdExceeded() { ... }
 * 
 *
 * @see NonNull
 * @see EnsuresNonNull
 * @see org.checkerframework.checker.nullness.NullnessChecker
 * @checker_framework.manual #nullness-checker Nullness Checker
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@ConditionalPostconditionAnnotation(qualifier = NonNull.class)
@InheritedAnnotation
@Repeatable(EnsuresNonNullIf.List.class)
public @interface EnsuresNonNullIf {
    /**
     * Returns the return value of the method under which the postcondition holds.
     *
     * @return the return value of the method under which the postcondition holds
     */
    boolean result();

    /**
     * Returns Java expression(s) that are non-null after the method returns the given result.
     *
     * @return Java expression(s) that are non-null after the method returns the given result
     * @checker_framework.manual #java-expressions-as-arguments Syntax of Java expressions
     */
    String[] expression();

    /**
     * * A wrapper annotation that makes the {@link EnsuresNonNullIf} annotation repeatable.
     *
     * Programmers generally do not need to write this. It is created by Java when a programmer
     * writes more than one {@link EnsuresNonNullIf} annotation at the same location.
     */
    @Documented
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
    @ConditionalPostconditionAnnotation(qualifier = NonNull.class)
    @InheritedAnnotation
    public static @interface List {
        /**
         * Returns the repeatable annotations.
         *
         * @return the repeatable annotations
         */
        EnsuresNonNullIf[] value();
    }
}