org.jetbrains.annotations.Contract Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of kotlin-compiler-embeddable Show documentation
Show all versions of kotlin-compiler-embeddable Show documentation
the Kotlin compiler embeddable
/*
* Copyright 2000-2013 JetBrains s.r.o.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jetbrains.annotations;
import java.lang.annotation.*;
/**
* Specifies some aspects of the method behavior depending on the arguments. Can be used by tools for advanced data flow analysis.
* Note that this annotation just describes how the code works and doesn't add any functionality by means of code generation.
*
* Method contract has the following syntax:
* contract ::= (clause ';')* clause
* clause ::= args '->' effect
* args ::= ((arg ',')* arg )?
* arg ::= value-constraint
* value-constraint ::= 'any' | 'null' | '!null' | 'false' | 'true'
* effect ::= value-constraint | 'fail'
*
* The constraints denote the following:
*
* - _ - any value
*
- null - null value
*
- !null - a value statically proved to be not-null
*
- true - true boolean value
*
- false - false boolean value
*
- fail - the method throws an exception, if the arguments satisfy argument constraints
*
* Examples:
* @Contract("_, null -> null")
- method returns null if its second argument is null
* @Contract("_, null -> null; _, !null -> !null")
- method returns null if its second argument is null and not-null otherwise
* @Contract("true -> fail")
- a typical assertFalse method which throws an exception if true
is passed to it
*
*/
@Documented
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
public @interface Contract {
/**
* Contains the contract clauses describing causal relations between call arguments and the returned value
*/
String value() default "";
/**
* Specifies if this method is pure, i.e. has no visible side effects. This may be used for more precise data flow analysis, and
* to check that the method's return value is actually used in the call place.
*/
boolean pure() default false;
}