1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
/*
* 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.intellij.lang.annotations;
import java.lang.annotation.*;
/**
* <p>This annotation intended to help IDEA to detect and auto-complete int and String constants used as an enumeration.
* For example, in the {@link java.awt.Label#Label(String, int)} constructor the <tt><b>alignment</b></tt> parameter can be one of the following
* int constants: {@link java.awt.Label#LEFT}, {@link java.awt.Label#CENTER} or {@link java.awt.Label#RIGHT}
*
* <p>So, if <tt>@MagicConstant</tt> annotation applied to this constructor, IDEA will check the constructor usages for the allowed values.
* <p>E.g.<br>
* <pre>{@code
* new Label("text", 0); // 0 is not allowed
* new Label("text", Label.LEFT); // OK
* }</pre>
*
* <p>
* <tt>@MagicConstant</tt> can be applied to:
* <ul>
* <li> Field, local variable, parameter.
*
* <br>E.g. <br>
* <pre>{@code @MagicConstant(intValues = {TOP, CENTER, BOTTOM})
* int textPosition;
* }</pre>
* IDEA will check expressions assigned to the variable for allowed values:
* <pre>{@code
* textPosition = 0; // not allowed
* textPosition = TOP; // OK
* }</pre>
*
* <li> Method
*
* <br>E.g.<br>
* <pre>{@code @MagicConstant(flagsFromClass = java.lang.reflect.Modifier.class)
* public native int getModifiers();
* }</pre>
*
* IDEA will analyse getModifiers() method calls and check if its return value is used with allowed values:<br>
* <pre>{@code
* if (aClass.getModifiers() == 3) // not allowed
* if (aClass.getModifiers() == Modifier.PUBLIC) // OK
* }</pre>
*
* <li>Annotation class<br>
* Annotation class annotated with <tt>@MagicConstant</tt> created alias you can use to annotate
* everything as if it was annotated with <tt>@MagicConstant</tt> itself.
*
* <br>E.g.<br>
* <pre>{@code @MagicConstant(flags = {Font.PLAIN, Font.BOLD, Font.ITALIC}) }</pre>
* <pre>{@code @interface FontStyle {} }</pre>
*
* IDEA will check constructs annotated with @FontStyle for allowed values:<br>
* <tt>@FontStyle int myStyle = 3; // not allowed<br></tt>
* <tt>@FontStyle int myStyle = Font.BOLD | Font.ITALIC; // OK</tt><br>
* </tt>
*
* </ul>
*
* The <tt>@MagicConstant</tt> annotation has SOURCE retention, i.e. it is removed upon compilation and does not create any runtime overhead.
*/
@Retention(RetentionPolicy.SOURCE)
@Target({
ElementType.FIELD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE,
ElementType.ANNOTATION_TYPE,
ElementType.METHOD
})
public @interface MagicConstant {
/**
* @return int values (typically named constants) which are allowed here.
* E.g.
* <tt><pre>
* {@code
* void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW})
* int confirmOpenNewProject);
* }</pre></tt>
*/
long[] intValues() default {};
/**
* @return String values (typically named constants) which are allowed here.
*/
String[] stringValues() default {};
/**
* @return allowed int flags (i.e. values (typically named constants) which can be combined with bitwise or operator (|).
* Also 0 and -1 are considered allowed.
* E.g.
* <tt><pre>
* {@code @MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED})
* int hFlags;
*
* hFlags = 3; // not allowed
* if (hFlags & (HierarchyEvent.PARENT_CHANGED | HierarchyEvent.SHOWING_CHANGED) != 0); // OK
* }</pre></tt>
*/
long[] flags() default {};
/**
* @return allowed values which are defined in the specified class public static final constants.
*
* E.g.
* <tt><pre>
* {@code @MagicConstant(valuesFromClass = Cursor.class)
* int cursorType;
*
* cursorType = 11; // not allowed;
* cursorType = Cursor.E_RESIZE_CURSOR; // OK
* }</pre></tt>
*/
Class valuesFromClass() default void.class;
/**
* @return allowed int flags which are defined in the specified class public static final constants.
*
* E.g.
* <tt><pre>
* {@code @MagicConstant(flagsFromClass = java.awt.InputEvent.class)
* int eventMask;
*
* eventMask = 10; // not allowed;
* eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK
* }</pre></tt>
*/
Class flagsFromClass() default void.class;
}
|
