JetBrains Java Annotations 24.1.0 · org.intellij.lang.annotations.MagicConstant

This annotation intended to help IntelliJ IDEA and other IDEs to detect and auto-complete int and String constants used as an enumeration. For example, in the java.awt.Label#Label(String, int) constructor the alignment parameter can be one of the following int constants: java.awt.Label#LEFT, java.awt.Label#CENTER or java.awt.Label#RIGHT

So, if @MagicConstant annotation applied to this constructor, the IDE will check the constructor usages for the allowed values.

E.g.

new Label("text", 0); // 0 is not allowed
new Label("text", Label.LEFT); // OK

@MagicConstant can be applied to:

Field, local variable, parameter.
E.g.

@MagicConstant(intValues = {TOP, CENTER, BOTTOM})
int textPosition;

The IDE will check expressions assigned to the variable for allowed values:

textPosition = 0; // not allowed
 textPosition = TOP; // OK

Method
E.g.

@MagicConstant(flagsFromClass = java.lang.reflect.Modifier.class)
 public native int getModifiers();

The IDE will analyse getModifiers() method calls and check if its return value is used with allowed values:

if (aClass.getModifiers() == 3) // not allowed
 if (aClass.getModifiers() == Modifier.PUBLIC) // OK

Annotation class
Annotation class annotated with @MagicConstant created alias you can use to annotate everything as if it was annotated with @MagicConstant itself.
E.g.
```
@MagicConstant(flags = {Font.PLAIN, Font.BOLD, Font.ITALIC}) 
```
```
@interface FontStyle {} 
```
The IDE will check constructs annotated with @FontStyle for allowed values:
@FontStyle int myStyle = 3; // not allowed @FontStyle int myStyle = Font.BOLD | Font.ITALIC; // OK

The @MagicConstant annotation has SOURCE retention, i.e. it is removed upon compilation and does not create any runtime overhead.

Method Summary

Modifier and Type	Method and Description
public long[]	Returns: allowed int flags (i.e. values (typically named constants) which can be combined with bitwise OR operator (\|). The difference from the `intValues()` is that flags are allowed to be combined (via plus:+ or bitwise OR: \|) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g. `@MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED}) int hFlags; hFlags = 3; // not allowed; should be "magic" constant. if (hFlags & (HierarchyEvent.PARENT_CHANGED \| HierarchyEvent.SHOWING_CHANGED) != 0); // OK: combined several constants via bitwise OR` flags()
public Class<?>	Returns: allowed int flags which are defined in the specified class static final constants. The difference from the `valuesFromClass()` is that flags are allowed to be combined (via plus:+ or bitwise OR: \|) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g. `@MagicConstant(flagsFromClass = java.awt.InputEvent.class) int eventMask; eventMask = 10; // not allowed; should be "magic" constant. eventMask = InputEvent.CTRL_MASK \| InputEvent.ALT_MASK; // OK: combined several constants via bitwise OR` flagsFromClass()
public long[]	Returns: int values (typically named constants) which are allowed here. E.g. `void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW}) int confirmOpenNewProject);` intValues()
public @NonNls String[]	Returns: String values (typically named constants) which are allowed here. stringValues()
public Class<?>	Returns: allowed values which are defined in the specified class static final constants. E.g. `@MagicConstant(valuesFromClass = Cursor.class) int cursorType; cursorType = 11; // not allowed; should be "magic" constant. cursorType = Cursor.E_RESIZE_CURSOR; // OK: "magic" constant used.` valuesFromClass()

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

flags back to summary

flags	back to summary
public long[] flags() Returns:long[] allowed int flags (i.e. values (typically named constants) which can be combined with bitwise OR operator (\|). The difference from the `intValues()` is that flags are allowed to be combined (via plus:+ or bitwise OR: \|) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g. `@MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED}) int hFlags; hFlags = 3; // not allowed; should be "magic" constant. if (hFlags & (HierarchyEvent.PARENT_CHANGED \| HierarchyEvent.SHOWING_CHANGED) != 0); // OK: combined several constants via bitwise OR`

public long[] flags()

Returns:long[]

allowed int flags (i.e. values (typically named constants) which can be combined with bitwise OR operator (|). The difference from the intValues() is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g.

@MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED})
int hFlags;

hFlags = 3; // not allowed; should be "magic" constant.
if (hFlags & (HierarchyEvent.PARENT_CHANGED | HierarchyEvent.SHOWING_CHANGED) != 0); // OK: combined several constants via bitwise OR

flagsFromClass back to summary

flagsFromClass	back to summary
public Class<?> flagsFromClass() Returns:Class<?> allowed int flags which are defined in the specified class static final constants. The difference from the `valuesFromClass()` is that flags are allowed to be combined (via plus:+ or bitwise OR: \|) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g. `@MagicConstant(flagsFromClass = java.awt.InputEvent.class) int eventMask; eventMask = 10; // not allowed; should be "magic" constant. eventMask = InputEvent.CTRL_MASK \| InputEvent.ALT_MASK; // OK: combined several constants via bitwise OR`

public Class<?> flagsFromClass()

Returns:Class<?>

allowed int flags which are defined in the specified class static final constants. The difference from the valuesFromClass() is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g.

@MagicConstant(flagsFromClass = java.awt.InputEvent.class)
int eventMask;

eventMask = 10; // not allowed; should be "magic" constant.
eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK: combined several constants via bitwise OR

intValues	back to summary
public long[] intValues() Returns:long[] int values (typically named constants) which are allowed here. E.g. `void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW}) int confirmOpenNewProject);`

stringValues	back to summary
public @NonNls String[] stringValues() Returns:@NonNls String[] String values (typically named constants) which are allowed here. Annotations @NonNls

valuesFromClass	back to summary
public Class<?> valuesFromClass() Returns:Class<?> allowed values which are defined in the specified class static final constants. E.g. `@MagicConstant(valuesFromClass = Cursor.class) int cursorType; cursorType = 11; // not allowed; should be "magic" constant. cursorType = Cursor.E_RESIZE_CURSOR; // OK: "magic" constant used.`

public @Interface MagicConstant

Method Summary

Method Detail