org.checkerframework.dataflow.qual.AssertMethod Maven / Gradle / Ivy

Go to download

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-eisop4

Show newest version

package org.checkerframework.dataflow.qual;

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;

/**
 * {@code AssertMethod} is a method annotation that indicates that a method throws an exception if
 * the value of a boolean argument is false. This can be used to annotate methods such as JUnit's
 * {@code Assertions.assertTrue(...)}.
 *
 * The annotation enables flow-sensitive type refinement to be more precise. For example, if
 * {@code Assertions.assertTrue} is annotated as follows:
 *
 * 
@AssertMethod(value = AssertionFailedError.class)
 * public static void assertFalse(boolean condition);
 * 
 *
 * Then, in the code below, the Optional Checker can determine that {@code optional} has a value and
 * the call to {@code Optional#get} will not throw an exception.
 *
 *  * Assertions.assertTrue(optional.isPresent());
 * Object o = optional.get();
 * 
 *
 * This annotation is a trusted annotation, meaning that the Checker Framework does not
 * check whether the annotated method really does throw an exception depending on the boolean
 * expression.
 *
 * @checker_framework.manual #type-refinement Automatic type refinement (flow-sensitive type
 *     qualifier inference)
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface AssertMethod {

    /**
     * The class of the exception thrown by this method. The default is {@link AssertionError}.
     *
     * @return class of the exception thrown by this method
     */
    Class value() default AssertionError.class;

    /**
     * The one-based index of the boolean parameter that is tested.
     *
     * @return the one-based index of the boolean parameter that is tested
     */
    int parameter() default 1;

    /**
     * Returns whether this method asserts that the boolean expression is false.
     *
     * 
For example, JUnit's Assertions.assertFalse(...)
     * throws an exception if the first argument is false. So it is annotated as follows:
     *
     * 
@AssertMethod(value = AssertionFailedError.class, isAssertFalse = true)
     * public static void assertFalse(boolean condition);
     * 
     *
     * @return the value for {@link #parameter} on which the method throws an exception
     */
    boolean isAssertFalse() default false;
}