Chapter 9. Interfaces

An interface declaration may include interface modifiers.

The rules concerning annotation modifiers for an interface declaration are specified in §9.7.4 and §9.7.5.

The access modifier public (§6.6) pertains only to top level interfaces (§7.6) and member interfaces (§8.5, §9.5), not to local interfaces (§14.3).

The access modifiers protected and private pertain only to member interfaces.

The modifier static pertains only to member interfaces and local interfaces.

It is a compile-time error if the same keyword appears more than once as a modifier for an interface declaration, or if a interface declaration has more than one of the access modifiers public, protected, and private.

If two or more (distinct) interface modifiers appear in an interface declaration, then it is customary, though not required, that they appear in the order consistent with that shown above in the production for InterfaceModifier.

An interface is generic if the interface declaration declares one or more type variables (§4.4).

These type variables are known as the type parameters of the interface. The type parameter section follows the interface name and is delimited by angle brackets.

The following productions from §8.1.2 and §4.4 are shown here for convenience:

The rules concerning annotation modifiers for a type parameter declaration are specified in §9.7.4 and §9.7.5.

In an interface's type parameter section, a type variable T directly depends on a type variable S if S is the bound of T, while T depends on S if either T directly depends on S or T directly depends on a type variable U that depends on S (using this definition recursively). It is a compile-time error if a type variable in a interface's type parameter section depends on itself.

The scope and shadowing of an interface's type parameter is specified in §6.3 and §6.4.1.

References to an interface's type parameter from a static context or a nested class or interface are restricted, as specified in §6.5.5.1.

A generic interface declaration defines a set of parameterized types (§4.5), one for each possible parameterization of the type parameter section by type arguments. All of these parameterized types share the same interface at run time.

If an extends clause is provided, then the interface being declared extends each of the specified interface types and therefore inherits the member classes, member interfaces, instance methods, and static fields of each of those interface types.

The specified interface types are the direct superinterface types of the interface being declared.

Any class that implements the declared interface is also considered to implement all the interfaces that this interface extends.

The following production from §8.1.5 is shown here for convenience:

Each InterfaceType in the extends clause of an interface declaration must name an accessible interface (§6.6), or a compile-time error occurs.

If an InterfaceType has type arguments, it must denote a well-formed parameterized type (§4.5), and none of the type arguments may be wildcard type arguments, or a compile-time error occurs.

One interface is a direct superinterface of another interface if the first interface is named by one of the direct superinterface types of the second interface.

The superinterface relationship is the transitive closure of the direct superinterface relationship. An interface I is a superinterface of interface K if either of the following is true:

An interface is said to be a direct subinterface of its direct superinterface, and a subinterface of each of its superinterfaces.

While every class is an extension of class Object, there is no single interface of which all interfaces are extensions.

An interface I directly depends on a class or interface A if A is mentioned in the extends clause of I either as a superinterface or as a qualifier in the fully qualified form of a superinterface name.

An interface I depends on a class or interface A if any of the following is true:

It is a compile-time error if an interface depends on itself.

If circularly declared interfaces are detected at run time, as interfaces are loaded, then a ClassCircularityError is thrown (§12.2.1).

An interface body may contain declarations of members of the interface, that is, fields (§9.3), methods (§9.4), classes, and interfaces (§9.5).

The scope of a declaration of a member m declared in or inherited by an interface I is specified in §6.3.

Every declarator in a field declaration of an interface must have a variable initializer, or a compile-time error occurs.

The initializer need not be a constant expression (§15.29).

It is a compile-time error if the initializer of an interface field uses the simple name of the same field or another field whose declaration occurs to the right of the initializer (§3.5) in the same interface.

The initializer of an interface field may not refer to the current object using the keyword this or the keyword super, as specified in §15.8.3, §15.11.2, and §15.12.3.

At run time, the initializer is evaluated and the field assignment performed exactly once, when the interface is initialized (§12.4.2).

Note that interface fields that are constant variables (§4.12.4) are initialized before other interface fields. This also applies to static fields that are constant variables in classes (§8.3.2). Such fields will never be observed to have their default initial values (§4.12.5), even by devious programs.

interface Test {
    float f = j;
    int   j = 1;
    int   k = k + 1;
}

An interface I inherits from its direct superinterface types all abstract and default methods m for which all of the following are true:

Note that methods are overridden on a signature-by-signature basis. If, for example, an interface declares two public methods with the same name (§9.4.2), and a subinterface overrides one of them, the subinterface still inherits the other method.

The third clause above prevents a subinterface from re-inheriting a method that has already been overridden by another of its superinterfaces. For example, in this program:

interface Top {
    default String name() { return "unnamed"; }
}
interface Left extends Top {
    default String name() { return getClass().getName(); }
}
interface Right extends Top {}

interface Bottom extends Left, Right {}

Right inherits name() from Top, but Bottom inherits name() from Left, not Right. This is because name() from Left overrides the declaration of name() in Top.

An interface does not inherit private or static methods from its superinterfaces.

If an interface I declares a private or static method m, and the signature of m is a subsignature of a public instance method m' in a superinterface type of I, and m' would otherwise be accessible to code in I, then a compile-time error occurs.

In essence, a static method in an interface cannot hide an instance method in a superinterface type. This is similar to the rule in §8.4.8.2 whereby a static method in a class cannot hide an instance method in a superclass type or superinterface type. Note that the rule in §8.4.8.2 speaks of a class that "declares or inherits a static method", whereas the rule above speaks only of an interface that "declares a static method", since an interface cannot inherit a static method. Also note that the rule in §8.4.8.2 allows hiding of both instance and static methods in superclasses/superinterfaces, whereas the rule above considers only public instance methods in superinterface types.

Along the same lines, a private method in an interface cannot override an instance method - whether public or private - in a superinterface type. This is similar to the rules in §8.4.8.1 and §8.4.8.3 whereby a private method in a class cannot override any instance method in a superclass type or superinterface type, because §8.4.8.1 requires the overridden method to be non-private and §8.4.8.3 requires the overriding method to provide at least as much access as the overridden method. In summary, only public methods in interfaces can be overridden, and only by public methods in subinterfaces or in implementing classes.

If two methods of an interface (whether both declared in the same interface, or both inherited by an interface, or one declared and one inherited) have the same name but different signatures that are not override-equivalent (§8.4.2), then the method name is said to be overloaded.

This fact causes no difficulty and never of itself results in a compile-time error. There is no required relationship between the return types or between the throws clauses of two methods with the same name but different signatures that are not override-equivalent.

interface PointInterface {
    void move(int dx, int dy);
}
interface RealPointInterface extends PointInterface {
    void move(float dx, float dy);
    void move(double dx, double dy);
}

A default method has a block body. This block of code provides an implementation of the method in the event that a class implements the interface but does not provide its own implementation of the method.

A private or static interface method also has a block body, which provides the implementation of the method.

It is a compile-time error if an interface method declaration is abstract (explicitly or implicitly) and has a block for its body.

It is a compile-time error if an interface method declaration is default, private, or static, and has a semicolon for its body.

The rules for return statements in a method body are specified in §14.17.

If a method is declared to have a return type (§8.4.5), then a compile-time error occurs if the body of the method can complete normally (§14.1).

The body of an annotation interface declaration may contain method declarations, each of which defines an element of the annotation interface. An annotation interface has no elements other than those defined by the methods declared explicitly in the annotation interface declaration.

The following production from §4.3 is shown here for convenience:

By virtue of the grammar above, a method declaration in an annotation interface declaration cannot have formal parameters, type parameters, or a throws clause; and cannot be private, default, or static. Thus, an annotation interface cannot have the same variety of methods as a normal interface. Note that it is still possible for an annotation interface to inherit a default method from its implicit superinterface, java.lang.annotation.Annotation, though no such default method exists as of Java SE 16.

By convention, the only modifiers that should be present on the declaration of an annotation interface element are annotations.

The return type of a method declared in the body of annotation interface must be one of the following, or a compile-time error occurs:

@interface Verboten {
    String[][] value();
}

The declaration of a method that returns an array is allowed to place the bracket pair that denotes the array type after the empty formal parameter list. This syntax is supported for compatibility with early versions of the Java programming language. It is very strongly recommended that this syntax is not used in new code.

It is a compile-time error if any method declared in an annotation interface has a signature that is override-equivalent (§8.4.2) to that of any public or protected method declared in class Object or in interface java.lang.annotation.Annotation.

It is a compile-time error if the declaration of an annotation interface T contains an element of type T, either directly or indirectly.

@interface SelfRef { SelfRef value(); }

@interface Ping { Pong value(); }
@interface Pong { Ping value(); }

An annotation interface with no elements is called a marker annotation interface.

An annotation interface with one element is called a single-element annotation interface.

By convention, the name of the sole element in a single-element annotation interface is value. Linguistic support for this convention is provided by single-element annotations (§9.7.3).

/**
 * Describes the "request-for-enhancement" (RFE)
 * that led to the presence of the annotated API element.
 */
@interface RequestForEnhancement {
    int    id();        // Unique ID number associated with RFE
    String synopsis();  // Synopsis of RFE
    String engineer();  // Name of engineer who implemented RFE
    String date();      // Date RFE was implemented
}

/**
 * An annotation with this type indicates that the 
 * specification of the annotated API element is 
 * preliminary and subject to change.
 */
@interface Preliminary {}

/**
 * Associates a copyright notice with the annotated API element.
 */
@interface Copyright {
    String value();
}

/**
 * Associates a list of endorsers with the annotated class.
 */
@interface Endorsers {
    String[] value();
}

interface Formatter {}

// Designates a formatter to pretty-print the annotated class
@interface PrettyPrinter {
    Class<? extends Formatter> value();
}

/**
 * Indicates the author of the annotated program element.
 */
@interface Author {
    Name value();
}
/**
 * A person's name.  This annotation interface is not 
 * designed to be used directly to annotate program elements, 
 * but to define elements of other annotation interfaces.
 */
@interface Name {
    String first();
    String last();
}

@interface Quality {
    enum Level { BAD, INDIFFERENT, GOOD }
    Level value();
}

An annotation interface element may have a default value, specified by attaching the keyword default and a value to the method declaration which defines the element.

The following productions from §9.7.1 are shown here for convenience:

It is a compile-time error if the type of the element is not commensurate (§9.7) with the default value specified.

Default values are not compiled into annotations, but rather applied dynamically at the time annotations are read. Thus, changing a default value affects annotations even in classes that were compiled before the change was made (presuming these annotations lack an explicit value for the defaulted element).

@interface RequestForEnhancement {
    int    id();       // No default - must be specified in 
                       // each annotation
    String synopsis(); // No default - must be specified in 
                       // each annotation
    String engineer()  default "[unassigned]";
    String date()      default "[unimplemented]";
}

An annotation interface A is repeatable if its declaration is (meta-)annotated with an @Repeatable annotation (§9.6.4.8) whose value element indicates a containing annotation interface of A.

An annotation interface AC is a containing annotation interface of A if all of the following are true:

It is a compile-time error if an annotation interface A is (meta-)annotated with an @Repeatable annotation whose value element indicates a type which is not a containing annotation interface of A.

import java.lang.annotation.Repeatable;

@Repeatable(FooContainer.class)
@interface Foo {}

@interface FooContainer { Object[] value(); }

The @Repeatable annotation cannot be repeated, so only one containing annotation interface can be specified by a repeatable annotation interface.

Allowing more than one containing annotation interface to be specified would cause an undesirable choice at compile time, when multiple annotations of the repeatable annotation interface are logically replaced with a container annotation (§9.7.5).

An annotation interface can be the containing annotation interface of at most one annotation interface.

This is implied by the requirement that if the declaration of an annotation interface A specifies a containing annotation interface of AC, then the value() method of AC has a return type involving A, specifically A[].

An annotation interface cannot specify itself as its containing annotation interface.

This is implied by the requirement on the value() method of the containing annotation interface. Specifically, if an annotation interface A specified itself (via @Repeatable) as its containing annotation interface, then the return type of A's value() method would have to be A[]; but this would cause a compile-time error since an annotation interface cannot refer to itself in its elements (§9.6.1). More generally, two annotation interfaces cannot specify each other as their containing annotation interface, because cyclic annotation interface declarations are illegal.

An annotation interface AC may be the containing annotation interface of some annotation interface A while also having its own containing annotation interface SC. That is, a containing annotation interface may itself be a repeatable annotation interface.

import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;

@Target(ElementType.TYPE)
@Repeatable(FooContainer.class)
@interface Foo {}

@Target(ElementType.ANNOTATION_TYPE)
@interface FooContainer {
    Foo[] value();
}

@Foo @Foo
@interface Anno {}

@Foo @Foo
interface Intf {}

import java.lang.annotation.Repeatable;

// Foo: Repeatable annotation interface
@Repeatable(FooContainer.class)
@interface Foo { int value(); }

// FooContainer: Containing annotation interface of Foo
// Also a repeatable annotation interface itself
@Repeatable(FooContainerContainer.class)
@interface FooContainer { Foo[] value(); }

// FooContainerContainer: Containing annotation interface
// of FooContainer
@interface FooContainerContainer { FooContainer[] value(); }

@FooContainer({@Foo(1)}) @FooContainer({@Foo(2)})
class Test {}

Several annotation interfaces are predefined in the Java SE Platform API. Some of the predefined annotation interfaces have special semantics in the Java programming language and require special behavior on the part of a Java compiler, as specified in this section. This section does not provide a complete specification for the predefined annotation interfaces, for which the reader is referred to the Java SE Platform API documentation (§1.4).

public boolean equals(Foo that) { ... }

public boolean equals(Object that) { ... }

class Foo     { @Override public int hashCode() {..} }
interface Bar { @Override int hashCode(); }

interface Quux { @Override Object clone(); }

class Beep { @Override protected Object clone() {..} }

record Roo(int x) {
    @Override
    public int x() {
        return Math.abs(x);
    }
}

public static <T> boolean
  addAll(Collection<? super T> c, T... elements)

A normal annotation specifies the name of an annotation interface and optionally a list of comma-separated element-value pairs. Each pair contains an element value that is associated with an element of the annotation interface (§9.6.1).

Note that the at sign (@) is a token unto itself (§3.11). It is possible to put whitespace between it and the TypeName, but this is discouraged as a matter of style.

The TypeName specifies the annotation interface corresponding to the annotation. The annotation is said to be "of" that interface.

The TypeName must name an accessible annotation interface (§6.6), or a compile-time error occurs.

The Identifier in an element-value pair must be the simple name of one of the elements (that is, methods) of the annotation interface, or a compile-time error occurs.

The return type of this method defines the element type of the element-value pair.

If the element type is an array type, then it is not required to use curly braces to specify the element value of the element-value pair. If the element value is not an ElementValueArrayInitializer, then an array value whose sole element is the element value is associated with the element. If the element value is an ElementValueArrayInitializer, then the array value represented by the ElementValueArrayInitializer is associated with the element.

It is a compile-time error if the element type is not commensurate with the element value. An element type T is commensurate with an element value v if and only if one of the following is true:

Note that if T is not an array type or an annotation interface, the element value must be a ConditionalExpression (§15.25). The use of ConditionalExpression rather than a more general production like Expression is a syntactic trick to prevent assignment expressions as element values. Since an assignment expression is not a constant expression, it cannot be a commensurate element value for a primitive or String-typed element.

Formally, it is invalid to speak of an ElementValue as FP-strict (§15.4) because it might be an annotation or a class literal. Still, we can speak informally of ElementValue as FP-strict when it is either a constant expression or an array of constant expressions or an annotation whose element values are (recursively) found to be constant expressions; after all, every constant expression is FP-strict.

A normal annotation must contain an element-value pair for every element of the corresponding annotation interface, except for those elements with default values, or a compile-time error occurs.

A normal annotation may, but is not required to, contain element-value pairs for elements with default values.

It is customary, though not required, that element-value pairs in an annotation are presented in the same order as the corresponding elements in the annotation interface declaration.

An annotation on an annotation interface declaration is known as a meta-annotation.

An annotation of interface A may appear as a meta-annotation on the declaration of the interface A itself. More generally, circularities in the transitive closure of the "annotates" relation are permitted.

For example, it is legal to annotate the declaration of an annotation interface S with a meta-annotation of interface T, and to annotate T's own declaration with a meta-annotation of interface S. The predefined annotation interfaces (§9.6.4) contain several such circularities.

@RequestForEnhancement(
    id       = 2868724,
    synopsis = "Provide time-travel functionality",
    engineer = "Mr. Peabody",
    date     = "4/1/2004"
)
public static void travelThroughTime(Date destination) { ... }

@RequestForEnhancement(
    id       = 4561414,
    synopsis = "Balance the federal budget"
)
public static void balanceFederalBudget() {
    throw new UnsupportedOperationException("Not implemented");
}

A marker annotation is a shorthand designed for use with marker annotation interfaces (§9.6.1).

It is shorthand for the normal annotation:

@TypeName()

It is legal to use marker annotations for annotation interfaces with elements, so long as all the elements have default values (§9.6.2).

@Preliminary public class TimeTravel { ... }

A single-element annotation is a shorthand designed for use with single-element annotation interfaces (§9.6.1).

It is shorthand for the normal annotation:

@TypeName(value = ElementValue)

It is legal to use single-element annotations for annotation interfaces with multiple elements, so long as one element is named value and all other elements have default values (§9.6.2).

@Copyright("2002 Yoyodyne Propulsion Systems, Inc.")
public class OscillationOverthruster { ... }

@Endorsers({"Children", "Unscrupulous dentists"})
public class Lollipop { ... }

@Endorsers("Epicurus")
public class Pleasure { ... }

class GorgeousFormatter implements Formatter { ... }

@PrettyPrinter(GorgeousFormatter.class)
public class Petunia { ... }

// Illegal; String is not a subtype of Formatter
@PrettyPrinter(String.class)
public class Begonia { ... }

@Author(@Name(first = "Joe", last = "Hacker"))
public class BitTwiddle { ... }

@Quality(Quality.Level.GOOD)
public class Karma { ... }

A declaration annotation is an annotation that applies to a declaration, and whose annotation interface is applicable in the declaration context (§9.6.4.1) represented by that declaration; or an annotation that applies to a class, interface, or type parameter declaration, and whose annotation interface is applicable in type contexts (§4.11).

A type annotation is an annotation that applies to a type (or any part of a type), and whose annotation interface is applicable in type contexts.

@Foo int f;

@C int @A [] @B [] f;

@C int f;
@C int[] f;
@C int[][] f;

It is customary, though not required, to write declaration annotations before all other modifiers, and type annotations immediately before the type to which they apply.

It is possible for an annotation to appear at a syntactic location in a program where it could plausibly apply to a declaration, or a type, or both. This can happen in any of the six declaration contexts where modifiers immediately precede the type of the declared entity:

The grammar of the Java programming language unambiguously treats annotations at these locations as modifiers for a declaration (§8.3), but that is purely a syntactic matter. Whether an annotation applies to the declaration or to the type of the declared entity - and thus, whether the annotation is a declaration annotation or a type annotation - depends on the applicability of the annotation's interface:

In the second and third cases above, the type which is closest to the annotation is determined as follows:

It is a compile-time error if an annotation of interface A is syntactically a modifier for:

Six of these eleven clauses mention "... or in type contexts" because they characterize the six syntactic locations, mentioned earlier in this section, where an annotation could plausibly apply to a declaration or a type. Furthermore, two of the eleven clauses - for class and interface declarations, and for type parameter declarations - mention "... or in type contexts" because it is sometimes convenient to be able to apply an annotation whose interface is meta-annotated with @Target(ElementType.TYPE_USE) (thus, applicable in type contexts) to the declaration of a class, interface, or type parameter.

A type annotation is admissible if both of the following are true:

The intuition behind the second clause is that if Outer.this is legal in a nested class enclosed by Outer, then Outer may be annotated because it represents the type of some object at run time. On the other hand, if Outer.this is not legal - because the class where it appears has no enclosing instance of Outer at run time - then Outer may not be annotated because it is logically just a name, akin to components of a package name in a fully qualified type name.

@Target(ElementType.TYPE_USE)
@interface Foo {}

class A {
    static class B {}
}

@Foo A.B x;  // Illegal 

@Target(ElementType.TYPE_USE)
@interface Foo {}

class Test {
    static class C {
        class D {}
    }

    @Foo C.D x;  // Legal 
}

It is a compile-time error if an annotation of interface A applies to the outermost level of a type in a type context, and A is not applicable in type contexts or the declaration context (if any) which occupies the same syntactic location.

It is a compile-time error if an annotation of interface A applies to a part of a type (that is, not the outermost level) in a type context, and A is not applicable in type contexts.

It is a compile-time error if an annotation of interface A applies to a type (or any part of a type) in a type context, and A is applicable in type contexts, but the annotation is not admissible.

For example, assume an annotation interface TA which is meta-annotated with just @Target(ElementType.TYPE_USE). The terms @TA java.lang.Object and java.@TA lang.Object are illegal because the simple name to which @TA is closest is classified as a package name. On the other hand, java.lang.@TA Object is legal.

Note that the illegal terms are illegal "everywhere". The ban on annotating package names applies broadly: to locations which are solely type contexts, such as class ... extends @TA java.lang.Object {...}, and to locations which are both declaration and type contexts, such as @TA java.lang.Object f;. (There are no locations which are solely declaration contexts where a package name could be annotated, as package, class, interface, and type parameter declarations introduce only simple names.)

If TA is additionally meta-annotated with @Target(ElementType.FIELD), then the term @TA java.lang.Object is legal in locations which are both declaration and type contexts, such as a field declaration @TA java.lang.Object f;. Here, @TA is deemed to apply to the declaration of f (and not to the type java.lang.Object) because TA is applicable in the field declaration context.

It is a compile-time error if multiple annotations of the same interface A appear in a declaration context or type context, unless A is repeatable (§9.6.3) and both A and the containing annotation interface of A are applicable in the declaration context or type context (§9.6.4.1).

It is customary, though not required, for multiple annotations of the same interface to appear consecutively.

If a declaration context or type context has multiple annotations of a repeatable annotation interface A, then it is as if the context has no explicitly declared annotations of interface A and one implicitly declared annotation of the containing annotation interface of A.

The implicitly declared annotation is called the container annotation, and the multiple annotations of interface A which appeared in the context are called the base annotations. The elements of the (array-typed) value element of the container annotation are all the base annotations in the left-to-right order in which they appeared in the context.

It is a compile-time error if, in a declaration context or type context, there are multiple annotations of a repeatable annotation interface A and any annotations of the containing annotation interface of A.

In other words, it is not possible to repeat annotations where an annotation of the same interface as their container also appears. This prohibits obtuse code like:

@Foo(0) @Foo(1) @FooContainer({@Foo(2)})
class A {}

If this code was legal, then multiple levels of containment would be needed: first the base annotations of interface Foo would be contained by an implicitly declared container annotation of interface FooContainer, then that annotation and the explicitly declared annotation of interface FooContainer would be contained in yet another implicitly declared annotation. This complexity is undesirable in the judgment of the designers of the Java programming language. Another approach, treating the base annotations of interface Foo as if they had occurred alongside @Foo(2) in the explicit @FooContainer annotation, is undesirable because it could change how reflective programs interpret the @FooContainer annotation.

It is a compile-time error if, in a declaration context or type context, there is one annotation of a repeatable annotation interface A and multiple annotations of the containing annotation interface of A.

This rule is designed to allow the following code:

@Foo(1) @FooContainer({@Foo(2)})
class A {}

With only one base annotation of the repeatable annotation interface Foo, no container annotation is implicitly declared, even if FooContainer is the containing annotation interface of Foo. However, repeating the annotation of interface FooContainer, as in:

@Foo(1) @FooContainer({@Foo(2)}) @FooContainer({@Foo(3)})
class A {}

is prohibited, even if FooContainer is repeatable with a containing annotation interface of its own. It is obtuse to repeat annotations which are themselves containers when an annotation of the underlying repeatable interface is present.