checker.src.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.

There is a newer version: 3.42.0

Show 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.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 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 equals method is annotated as follows:
 * 
   @EnsuresNonNullIf(expression="#1", result=true)
 *   public boolean equals(@Nullable Object obj) { ... }
 * because, if equals returns true, then the first (#1) argument to
 * equals was not null.
 * 
 *
 * Fields:
 * The value expressions can refer to fields, even private ones.  For example:
 * 
   @EnsuresNonNullIf(expression="this.derived", result=true)
 *   public boolean isDerived() {
 *     return (this.derived != null);
 *   }
 * As another example, an Iterator may cache the next value that
 * will be returned, in which case its hasNext method could be
 * annotated as:
 *    @EnsuresNonNullIf(expression="next_cache", result=true)
 *   public boolean hasNext() {
 *     if (next_cache == null) return false;
 *     ...
 *   }
 * An EnsuresNonNullIf annotation that refers to a private field is
 * useful for verifying that client code performs needed checks in the right
 * order, even if the 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:
 * 
   @EnsuresNonNullIf(expression="getComponentType()", result=true)
 *   public native @Pure boolean isArray();
 *
 * @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
public @interface EnsuresNonNullIf {
    /**
     * 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();

    /**
     * The return value of the method that needs to hold for the postcondition
     * to hold.
     */
    boolean result();
}