Java Annotation Attribute Value Restrictions

1. Overview

These days, it's hard to imagine Java without annotations, a powerful tool in the Java language.

Java provides a set of built-in annotations. Additionally, there are plenty of annotations from different libraries. We can even define and process our own annotations. We can tune these annotations with attribute values, however, these attribute values have limitations. Particularly, an annotation attribute value must be a constant expression.

In this tutorial, we're going to learn some reasons for that limitation and look under the hood of the JVM to explain it better. We'll also take a look at some examples of problems and solutions involving annotation attribute values.

2. Java Annotation Attributes Under the Hood

Let's consider how Java class files store annotation attributes. Java has a special structure for it called element_value. This structure stores a particular annotation attribute.

The structure element_value can store values of four different types:

• a constant from the pool of constants
• a class literal
• a nested annotation
• an array of values

So, a constant from an annotation attribute is a compile-time constant. Otherwise, the compiler wouldn't know what value it should put into the constant pool and use as an annotation attribute.

The Java specification defines operations producing constant expressions. If we apply these operations to compile-time constants, we'll get compile-time constants.

Let's assume we have an annotation @Marker that has an attribute value:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Marker {
    String value();
}

For example, this code compiles without errors:

@Marker(Example.ATTRIBUTE_FOO + Example.ATTRIBUTE_BAR)
public class Example {
    static final String ATTRIBUTE_FOO = "foo";
    static final String ATTRIBUTE_BAR = "bar";
    // ...
}

Here, we define an annotation attribute as a concatenation of two strings. A concatenation operator produces a constant expression.

3. Using Static Initializer

Let's consider a constant initialized in a static block:

@Marker(Example.ATTRIBUTE_FOO)
public class Example {
    static final String[] ATTRIBUTES = {"foo", "Bar"};
    static final String ATTRIBUTE_FOO;
    static {
        ATTRIBUTE_FOO = ATTRIBUTES[0];
    }
    
    // ...
}

It initializes the field in the static block and tries to use that field as an annotation attribute. This approach leads to a compilation error.

First, the variable ATTRIBUTE_FOO has static and final modifiers, but the compiler can't compute that field. The application computes it at runtime.

Second, annotation attributes must have an exact value before the JVM loads the class. However, when the static initializer runs, the class is already loaded. So, this limitation makes sense.

The same error shows up when in the field initialization. This code is incorrect for the same reason:

@Marker(Example.ATTRIBUTE_FOO)
public class Example {
    static final String[] ATTRIBUTES = {"foo", "Bar"};
    static final String ATTRIBUTE_FOO = ATTRIBUTES[0];
    // ...
}

How does the JVM initialize ATTRIBUTE_FOO? Array access operator ATTRIBUTES[0] runs in a class initializer. So, ATTRIBUTE_FOO is a runtime constant. It's not defined at compile-time.

4. Array Constant as an Annotation Attribute

Let's consider an array annotation attribute:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Marker {
    String[] value();
}

This code will not compile:

@Marker(value = Example.ATTRIBUTES)
public class Example {
    static final String[] ATTRIBUTES = {"foo", "bar"};
    // ...
}

First, although the final modifier protects the reference from being changed, we can still modify array elements.

Second, array literals can't be runtime constants. The JVM sets each element up in the static initializer — a limitation we described earlier.

Finally, a class file stores values of each element of that array. So, the compiler calculates each element of the attribute array, and it happens at compile-time.

Thus, we can only specify an array attribute each time:

@Marker(value = {"foo", "bar"})
public class Example {
    // ...
}

We can still use a constant as a primitive element of an array attribute.

5. Annotations in a Marker Interface: Why Doesn't it Work?

So, if an annotation attribute is an array, we have to repeat it each time. But we would like to avoid this copy-paste. Why don't we make our annotation @Inherited? We could add our annotation to a marker interface:

@Marker(value = {"foo", "bar"})
public interface MarkerInterface {
}

Then, we could make the classes that require this annotation implement it:

public class Example implements MarkerInterface {
    // ...
}

This approach won't work. The code will compile without errors. However, Java doesn't support annotation inheritance from interfaces, even if the annotations have the @Inherited annotation itself. So, a class implementing the marker interface won't inherit the annotation.

The reason for this is the problem of multiple inheritance. Indeed, if multiple interfaces have the same annotation, Java can't choose one.

So, we can't avoid this copy-paste with a marker interface.

6. Array Element as an Annotation Attribute

Suppose we have an array constant and we use this constant as an annotation attribute:

@Marker(Example.ATTRIBUTES[0])
public class Example {
    static final String[] ATTRIBUTES = {"Foo", "Bar"};
    // ...
}

This code won't compile. Annotation parameters must be a compile-time constant. But, as we considered before, an array is not a compile-time constant.

Moreover, an array access expression is not a constant expression.

What if we had a List instead of an array? Method calls do not belong to the constant expressions. Thus, using the get method of the List class results in the same error.

Instead, we should explicitly refer to a constant:

@Marker(Example.ATTRIBUTE_FOO)
public class Example {
    static final String ATTRIBUTE_FOO = "Foo";
    static final String[] ATTRIBUTES = {ATTRIBUTE_FOO, "Bar"};
    // ...
}

This way, we specify the annotation attribute value in the string constant, and the Java compiler can unambiguously find the attribute value.

7. Conclusion

In this article, we looked through the limitations of annotation parameters. We considered some examples of problems with annotation attributes. We also discussed the JVM internals in the context of these limitations.

In all examples, we used the same classes for constants and annotations. However, all these limitations hold for the cases where the constant comes from another class.