An interface declaration may include interface modifiers.

If an annotation a (§9.7) on an interface declaration corresponds to an annotation type T (§9.6), and T has a (meta-)annotation m that corresponds to java.lang.annotation.Target, then m must have an element whose value is java.lang.annotation.ElementType.TYPE, or a compile-time error occurs.

The access modifier public (§6.6) pertains to every kind of interface declaration.

The access modifiers protected and private pertain only to member interfaces within a directly enclosing class or enum declaration (§8.5.1).

The modifier static pertains only to member interfaces (§8.5.1, §9.5), not to top level interfaces (§7.6).

It is a compile-time error if the same modifier appears more than once in an interface declaration.

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 it 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.

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 of an interface's type parameter is specified in §6.3.

It is a compile-time error to refer to a type parameter of an interface I anywhere in the declaration of a field or type member of I.

A generic interface declaration defines a set of parameterized types (§4.5), one for each possible invocation 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 other named interfaces and therefore inherits the member types, methods, and constants of each of the other named interfaces.

These other named interfaces are the direct superinterfaces 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 is repeated from §4.3 and §8.1.5 to make the presentation here clearer:

Given a (possibly generic) interface declaration for I<F₁,...,F_n> (n ≥ 0), the direct superinterfaces of the interface type I<F₁,...,F_n> are the types given in the extends clause of the declaration of I if an extends clause is present.

Let I<F₁,...,F_n> (n > 0), be a generic interface declaration. The direct superinterfaces of the parameterized interface type I<T₁,...,T_n>, where T_i (1 ≤ i ≤ n) is a type, are all types J<U₁ θ,...,U_k θ>, where J<U₁,...,U_k> is a direct superinterface of I<F₁,...,F_n>, and θ is the substitution [F1:=T1,...,Fn:=Tn].

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

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

Interface I is said to be a subinterface of interface K whenever K is a superinterface of I.

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 type T if T is mentioned in the extends clause of I either as a superinterface or as a qualifier within a superinterface name.

An interface I depends on a reference type T if any of the following conditions hold:

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 (§12.2), then a ClassCircularityError is thrown.

The body of an interface may declare members of the interface, that is, fields (§9.3), methods (§9.4), classes (§9.5), and interfaces (§9.5).

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

Every field in the body of an interface must have an initialization expression, which need not be a constant expression (§15.28), or a compile-time error occurs.

It is a compile-time error if an initialization expression for an interface field contains a reference by simple name to the same field or to another field whose declaration occurs textually later in the same interface.

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

If the keyword this (§15.8.3) or the keyword super (§15.11.2, §15.12) occurs in an initialization expression for a field of an interface, then unless the occurrence is within the body of an anonymous class (§15.9.5), a compile-time error occurs.

The variable initializer is evaluated and the assignment performed exactly once, when the interface is initialized (§12.4.2).

At run time, interface fields that are initialized with constant expressions (§15.28) are initialized first (§12.4.2). This also applies to static final fields in classes (§8.3.2.1). These fields are "constants" that will never be observed to have their default initial values (§4.12.5), even by devious programs (§13.4.9).

An interface inherits from its direct superinterfaces all methods of the superinterfaces that are not overridden by a declaration in the interface.

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.

class BufferEmpty     extends Exception {}
class BufferException extends Exception {} 

interface Buffer {
    char get() throws BufferEmpty, BufferException;
}
interface InfiniteBuffer extends Buffer {
    char get() throws BufferException;  // override
}

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);
}

Each method declaration in an annotation type declaration defines an element of the annotation type.

Annotation types can have zero or more elements. An annotation type has no elements other than those defined by the methods it explicitly declares.

By virtue of the AnnotationTypeElementDeclaration syntax, a method declaration in an annotation type declaration cannot have any formal parameters or type parameters, or a throws clause.

By convention, no AbstractMethodModifiers should be present on an annotation type element except for annotations.

/**
 * 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 {}

It is a compile-time error if the return type of a method declared in an annotation type is not one of the following: a primitive type, String, Class, any parameterized invocation of Class, an enum type (§8.9), an annotation type, or an array type (§10) whose element type is one of the preceding types.

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

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

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

@interface SelfRef { SelfRef value(); }

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

By convention, the name of the sole element in a single-element annotation type is value. Linguistic support for this convention is provided by the single element annotation construct (§9.7.3); one must obey the convention in order to take advantage of the construct.

/**
 * 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();
}

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

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

An annotation type element may have a default value specified for it. This is done by following its (empty) parameter list with the keyword default and the default value of the element.

Defaults are applied dynamically at the time annotations are read; default values are not compiled into annotations. 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).

An ElementValue (§9.7) is used to specify a default value.

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

@interface RequestForEnhancementDefault {
    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]";
}

Several annotation types are predefined in the libraries of the Java SE platform. Some of these predefined annotation types have special semantics. These semantics are specified in this section. This section does not provide a complete specification for the predefined annotations contained here in; that is the role of the appropriate API specifications. Only those semantics that require special behavior on the part of a Java compiler or Java Virtual Machine implementation are specified here.

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() {..} }

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

A normal annotation is used to annotate a program element.

The TypeName names the annotation type corresponding to the annotation.

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

It is a compile-time error if TypeName does not name an annotation type that is accessible (§6.6) at the point where the annotation is used.

The Identifier in an ElementValuePair must be the simple name of one of the elements (i.e. methods) of the annotation type identified by TypeName; otherwise, a compile-time error occurs.

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

An ElementValueArrayInitializer is similar to a normal array initializer (§10.6), except that annotations are permitted in place of expressions.

An element type T is commensurate with an element value V if and only if one of the following conditions is true:

Note that null is not a legal element value for any element type.

It is a compile-time error if the element type is not commensurate with the ElementValue.

If the element type is not an annotation type or an array type, ElementValue must be a ConditionalExpression (§15.25).

A ConditionalExpression is simply an expression without assignments, and not necessarily an expression involving the conditional operator (? :). ConditionalExpression is preferred over Expression in ElementValue because an element value has a simple structure (constant expression or class literal or enum constant) that may easily be represented in binary form.

If the element type is an array type and the corresponding ElementValue is not an ElementValueArrayInitializer, then an array value whose sole element is the value represented by the ElementValue is associated with the element. Otherwise, if the corresponding ElementValue is an ElementValueArrayInitializer, then the array value represented by the ElementValueArrayInitializer is associated with the element.

In other words, it is permissible to omit the curly braces when a single-element array is to be associated with an array-valued annotation type element.

Note that the array's element type cannot be an array type. That is, nested array types are not permitted as element types. (While the annotation syntax would permit this, the annotation type declaration syntax would not.)

An ElementValue is always FP-strict (§15.4).

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

An annotation type may be used to annotate its own declaration. More generally, circularities in the transitive closure of the "annotates" relation are permitted.

For example, it is legal to annotate an annotation type declaration with another annotation type, and to annotate the latter type's declaration with the former type. (The pre-defined meta-annotation types 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");
}

The second form of annotation, marker annotation, is a shorthand designed for use with marker annotation types.

It is shorthand for the normal annotation:

@Identifier()

It is legal to use the marker annotation form for annotation types with elements, so long as all the elements have default values.

@Preliminary public class TimeTravel { ... }

The third form of annotation, single-element annotation, is a shorthand designed for use with single-element annotation types.

It is shorthand for the normal annotation:

@Identifier(value = ElementValue)

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

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

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

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

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

class GorgeousFormatter implements Formatter { ... }

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

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

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