richie
6 years ago
10 changed files with 395 additions and 0 deletions
@ -0,0 +1,3 @@
|
||||
# jetbrains annotations |
||||
|
||||
作为注解事实上的标准,不能更改包名,半身也不存在什么冲突,直接放进来 |
@ -0,0 +1,33 @@
|
||||
// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
|
||||
package org.jetbrains.annotations; |
||||
|
||||
import java.lang.annotation.ElementType; |
||||
import java.lang.annotation.Retention; |
||||
import java.lang.annotation.RetentionPolicy; |
||||
import java.lang.annotation.Target; |
||||
|
||||
/** |
||||
* Helper annotations for asynchronous computation. |
||||
* Used for example in IDEA debugger for async stacktraces feature. |
||||
* |
||||
* @author egor |
||||
*/ |
||||
public interface Async { |
||||
|
||||
/** |
||||
* Indicates that the marked method schedules async computation. |
||||
* Scheduled object is either {@code this}, or the annotated parameter value. |
||||
*/ |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PARAMETER}) |
||||
@interface Schedule {} |
||||
|
||||
/** |
||||
* Indicates that the marked method executes async computation. |
||||
* Executed object is either {@code this}, or the annotated parameter value. |
||||
* This object needs to match with the one annotated with {@link Schedule} |
||||
*/ |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PARAMETER}) |
||||
@interface Execute {} |
||||
} |
@ -0,0 +1,93 @@
|
||||
/* |
||||
* Copyright 2000-2016 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.*; |
||||
import java.util.concurrent.atomic.AtomicBoolean; |
||||
|
||||
/** |
||||
* 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.<p> |
||||
* |
||||
* Method contract has the following syntax:<br> |
||||
* contract ::= (clause ';')* clause<br> |
||||
* clause ::= args '->' effect<br> |
||||
* args ::= ((arg ',')* arg )?<br> |
||||
* arg ::= value-constraint<br> |
||||
* value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'<br> |
||||
* effect ::= value-constraint | 'fail' <p> |
||||
* |
||||
* The constraints denote the following:<br> |
||||
* <ul> |
||||
* <li> _ - any value |
||||
* <li> null - null value |
||||
* <li> !null - a value statically proved to be not-null |
||||
* <li> true - true boolean value |
||||
* <li> false - false boolean value |
||||
* <li> fail - the method throws an exception, if the arguments satisfy argument constraints |
||||
* </ul> |
||||
* Examples:<p> |
||||
* {@code @Contract("_, null -> null")} - method returns null if its second argument is null<br> |
||||
* {@code @Contract("_, null -> null; _, !null -> !null")} - method returns null if its second argument is null and not-null otherwise<br> |
||||
* {@code @Contract("true -> fail")} - a typical assertFalse method which throws an exception if {@code true} is passed to it<br> |
||||
* |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) |
||||
public @interface Contract { |
||||
/** |
||||
* Contains the contract clauses describing causal relations between call arguments and the returned value |
||||
*/ |
||||
String value() default ""; |
||||
|
||||
/** |
||||
* Specifies that the annotated method has no visible side effects. |
||||
* If its return value is not used, removing its invocation won't |
||||
* affect program state and change the semantics, unless method call throws an exception. |
||||
* Exception throwing is not considered to be a side effect. |
||||
* <p> |
||||
* Method should not be marked as pure if it does not produce a side-effect by itself, |
||||
* but it could be used to establish a happens-before relation between an event in |
||||
* another thread, so changes performed in another thread might become visible in current thread |
||||
* after this method invocation. Examples of such methods are {@link Object#wait()}, {@link Thread#join()} |
||||
* or {@link AtomicBoolean#get()}. On the other hand, some synchronized methods like {@link java.util.Vector#get(int)} |
||||
* could be marked as pure, because the purpose of synchronization here is to keep the collection internal integrity |
||||
* rather than to wait for an event in another thread. |
||||
* <p> |
||||
* "Invisible" side effects (such as logging) that don't affect the "important" program semantics are allowed.<br><br> |
||||
* <p> |
||||
* This annotation 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; |
||||
|
||||
/** |
||||
* Contains a specifier which describes which method parameters can be mutated during the method call. |
||||
* <p> |
||||
* The following values are possible: |
||||
* <table summary=""> |
||||
* <tr><td>"this"</td><td>Method mutates the receiver object, and doesn't mutates any objects passed as arguments (cannot be applied for static method or constructor)</td></tr> |
||||
* <tr><td>"arg"</td><td>Method mutates the sole argument and doesn't mutate the receiver object (if applicable)</td></tr> |
||||
* <tr><td>"arg1", "arg2", ...</td><td>Method mutates the N-th argument</td></tr> |
||||
* <tr><td>"this,arg1"</td><td>Method mutates the receiver and first argument and doesn't mutate any other arguments</td></tr> |
||||
* </table> |
||||
* |
||||
* @return a mutation specifier string |
||||
* Warning: This annotation parameter is experimental and may be changed or removed without further notice! |
||||
*/ |
||||
String mutates() default ""; |
||||
} |
@ -0,0 +1,48 @@
|
||||
/* |
||||
* Copyright 2000-2015 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 that an element of the program is an user-visible string which needs to be localized. |
||||
* This annotation is intended to be used by localization tools for |
||||
* detecting strings which should be reported as requiring localization. |
||||
* |
||||
* @author mike |
||||
* @see NonNls |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE, ElementType.PACKAGE}) |
||||
public @interface Nls { |
||||
|
||||
enum Capitalization { |
||||
|
||||
NotSpecified, |
||||
/** |
||||
* e.g. This Is a Title |
||||
*/ |
||||
Title, |
||||
/** |
||||
* e.g. This is a sentence |
||||
*/ |
||||
Sentence |
||||
} |
||||
|
||||
Capitalization capitalization() default Capitalization.NotSpecified; |
||||
} |
@ -0,0 +1,56 @@
|
||||
/* |
||||
* Copyright 2000-2009 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 that an element of the program is not an user-visible string which needs to be localized, |
||||
* or does not contain such strings. This annotation is intended to be used by localization tools for |
||||
* detecting strings which should not be reported as requiring localization. |
||||
* <ul> |
||||
* <li>If a method parameter is annotated with {@code NonNls}, the strings passed |
||||
* as values of this parameter are not reported as requiring localization. |
||||
* Also, if the parameter of a property setter method is annotated with {@code NonNls}, values |
||||
* of that property in UI Designer forms are never highlighted as hard-coded strings.</li> |
||||
* <li>If a field is annotated with {@code NonNls}, all string literals found in the |
||||
* initializer of the field are not reported as requiring localization.</li> |
||||
* <li>If a method is called on a field, parameter or local variable annotated with {@code NonNls}, |
||||
* string literals passed as parameters to the method are not reported as requiring localization. |
||||
* <li>If a field, parameter or local variable annotated with {@code NonNls} is passed as a |
||||
* parameter to the {@code equals()} method invoked on a string literal, the literal is not |
||||
* reported as requiring localization.</li> |
||||
* <li>If a field, parameter or local variable annotated with {@code NonNls} is found at |
||||
* the left side of an assignment expression, all string literals in the right side |
||||
* of the expression are not reported as requiring localization.</li> |
||||
* <li>If a method is annotated with {@code NonNls}, string literals returned from the method |
||||
* are not reported as requiring localization.</li> |
||||
* <li>If a class is annotated with {@code NonNls}, all string literals in |
||||
* the class and all its subclasses are not reported as requiring localization.</li> |
||||
* <li>If a package is annotated with {@code NonNls}, all string literals in |
||||
* the package and all its subpackages are not reported as requiring localization.</li> |
||||
* </ul> |
||||
* |
||||
* @author max |
||||
* @see Nls |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE, ElementType.PACKAGE}) |
||||
public @interface NonNls { |
||||
|
||||
} |
@ -0,0 +1,46 @@
|
||||
/* |
||||
* Copyright 2000-2012 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.*; |
||||
|
||||
/** |
||||
* An element annotated with NotNull claims {@code null} value is <em>forbidden</em> |
||||
* to return (for methods), pass to (parameters) and hold (local variables and fields). |
||||
* Apart from documentation purposes this annotation is intended to be used by static analysis tools |
||||
* to validate against probable runtime errors and element contract violations. |
||||
* |
||||
* @author max |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE}) |
||||
public @interface NotNull { |
||||
/** |
||||
* @return Custom exception message |
||||
*/ |
||||
String value() default ""; |
||||
|
||||
/** |
||||
* @return Custom exception type that should be thrown when not-nullity contract is violated. |
||||
* The exception class should have a constructor with one String argument (message). |
||||
* |
||||
* By default, {@link IllegalArgumentException} is thrown on null method arguments and |
||||
* {@link IllegalStateException} — on null return value. |
||||
*/ |
||||
Class<? extends Exception> exception() default Exception.class; |
||||
} |
@ -0,0 +1,44 @@
|
||||
/* |
||||
* Copyright 2000-2014 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.*; |
||||
|
||||
/** |
||||
* An element annotated with {@link Nullable} claims {@code null} value is perfectly <em>valid</em> |
||||
* to return (for methods), pass to (parameters) or hold in (local variables and fields). |
||||
* Apart from documentation purposes this annotation is intended to be used by static analysis tools |
||||
* to validate against probable runtime errors or element contract violations. |
||||
* <br> |
||||
* By convention, this annotation applied only when the value should <em>always</em> be checked against {@code null} |
||||
* because the developer could do nothing to prevent null from happening. |
||||
* Otherwise, too eager {@link Nullable} usage could lead to too many false positives from static analysis tools. |
||||
* <br> |
||||
* For example, {@link java.util.Map#get(Object key)} should <em>not</em> be annotated {@link Nullable} because |
||||
* someone may have put not-null value in the map by this key and is expecting to find this value there ever since. |
||||
* <br> |
||||
* On the other hand, the {@link java.lang.ref.Reference#get()} should be annotated {@link Nullable} because |
||||
* it returns {@code null} if object got collected which can happen at any time completely unexpectedly. |
||||
* |
||||
* @author max |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE}) |
||||
public @interface Nullable { |
||||
String value() default ""; |
||||
} |
@ -0,0 +1,41 @@
|
||||
/* |
||||
* Copyright 2000-2009 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 that a method parameter accepts arguments which must be valid property |
||||
* keys in a specific resource bundle. When a string literal which is not a property |
||||
* key in the specified bundle is passed as a parameter, IntelliJ IDEA highlights |
||||
* it as an error. The annotation is also used to provide completion in string literals |
||||
* passed as parameters. |
||||
* |
||||
* @author max |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.CLASS) |
||||
@Target({ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.FIELD}) |
||||
public @interface PropertyKey { |
||||
/** |
||||
* The full-qualified name of the resource bundle in which the property keys must |
||||
* be present. Consists of a full-qualified name of the package corresponding to the |
||||
* directory where the resource bundle is located and the base name of the resource |
||||
* bundle (with no locale specifier or extension), separated with a dot. |
||||
*/ |
||||
String resourceBundle(); |
||||
} |
@ -0,0 +1,29 @@
|
||||
/* |
||||
* Copyright 2000-2015 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.*; |
||||
|
||||
/** |
||||
* A method/constructor annotated with TestOnly claims that it should be called from testing code only. |
||||
* <p> |
||||
* Apart from documentation purposes this annotation is intended to be used by static analysis tools |
||||
* to validate against element contract violations. |
||||
*/ |
||||
@Documented |
||||
@Retention(RetentionPolicy.SOURCE) |
||||
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.TYPE}) |
||||
public @interface TestOnly { } |
Loading…
Reference in new issue