org.checkerframework.checker.nullness.qual.EnsuresKeyForIf 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.44.0

Show newest version

package org.checkerframework.checker.nullness.qual;

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;
import org.checkerframework.framework.qual.ConditionalPostconditionAnnotation;
import org.checkerframework.framework.qual.InheritedAnnotation;
import org.checkerframework.framework.qual.JavaExpression;
import org.checkerframework.framework.qual.QualifierArgument;

/**
 * Indicates that the given expressions evaluate to a value that is a key in all the given maps, if
 * the method returns the given result (either true or false).
 *
 * As an example, consider the following method in {@code java.util.Map}:
 *
 * 
 *   @EnsuresKeyForIf(result=true, expression="key", map="this")
 *   public boolean containsKey(String key) { ... }
 * 
 *
 * If an invocation {@code m.containsKey(k)} returns true, then the type of {@code k} can be
 * inferred to be {@code @KeyFor("m")}.
 *
 * @see KeyFor
 * @see EnsuresKeyFor
 * @checker_framework.manual #map-key-checker Map Key Checker
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@ConditionalPostconditionAnnotation(qualifier = KeyFor.class)
@InheritedAnnotation
@Repeatable(EnsuresKeyForIf.List.class)
public @interface EnsuresKeyForIf {
  /** The value the method must return, in order for the postcondition to hold. */
  boolean result();

  /**
   * Java expressions that are keys in the given maps after the method returns the given result.
   *
   * @checker_framework.manual #java-expressions-as-arguments Syntax of Java expressions
   */
  String[] expression();

  /**
   * Returns Java expressions whose values are maps, each of which contains each expression value as
   * a key (after the method returns the given result).
   *
   * @return Java expressions whose values are maps, each of which contains each expression value as
   *     a key (after the method returns the given result)
   * @checker_framework.manual #java-expressions-as-arguments Syntax of Java expressions
   */
  @JavaExpression
  @QualifierArgument("value")
  String[] map();

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