Chapter 9. Interfaces

Every interface is implicitlyabstract.

This modifier is obsolete and should not be used in new programs.

The effect of thestrictfp modifier is to make allfloat ordouble expressions within the interface declaration be explicitly FP-strict (§15.4).

This implies that all methods declared in the interface, and all nested types declared in the interface, are implicitlystrictfp.

A nested interface is implicitlystatic. That is, every member interface and local interface isstatic. It is permitted for the declaration of a member interface to redundantly specify thestatic modifier (§9.5), but it is not permitted for the declaration of a local interface (§14.3).

Because a nested interface isstatic, it has no immediately enclosing instance (§8.1.3). References from a nested interface to type parameters, instance variables, local variables, formal parameters, exception parameters, or instance methods in lexically enclosing class, interface, or method declarations are disallowed (§6.5.5.1,§6.5.6.1,§15.12.3).

• I is a direct superinterface ofK.

• WhereJ is a direct superinterface ofK,I is a superinterface ofJ, applying this definition recursively.

• I directly depends onA.

• I directly depends on a classC that depends onA (§8.1.5).

• I directly depends on an interfaceJ that depends onA, applying this definition recursively.

If two fields with the same name are inherited by an interface because, for example, two of its direct superinterfaces declare fields with that name, then a single ambiguous member results. Any use of this ambiguous member will result in a compile-time error. In the program:

interface BaseColors {    int RED = 1, GREEN = 2, BLUE = 4;}interface RainbowColors extends BaseColors {    int YELLOW = 3, ORANGE = 5, INDIGO = 6, VIOLET = 7;}interface PrintColors extends BaseColors {    int YELLOW = 8, CYAN = 16, MAGENTA = 32;}interface LotsOfColors extends RainbowColors, PrintColors {    int FUCHSIA = 17, VERMILION = 43, CHARTREUSE = RED+90;}

the interfaceLotsOfColors inherits two fields namedYELLOW. This is all right as long as the interface does not contain any reference by simple name to the fieldYELLOW. (Such a reference could occur within a variable initializer for a field.)

Even if interfacePrintColors were to give the value3 toYELLOW rather than the value8, a reference to fieldYELLOW within interfaceLotsOfColors would still be considered ambiguous.

If a single field is inherited multiple times from the same interface because, for example, both this interface and one of this interface's direct superinterfaces extend the interface that declares the field, then only a single member results. This situation does not in itself cause a compile-time error.

In the previous example, the fieldsRED,GREEN, andBLUE are inherited by interfaceLotsOfColors in more than one way, through interfaceRainbowColors and also through interfacePrintColors, but the reference to fieldRED in interfaceLotsOfColors is not considered ambiguous because only one actual declaration of the fieldRED is involved.

Example 9.3.1-1. Forward Reference to a Field

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

• m is a member of a direct superinterface type ofI,J.

• No method declared inI has a signature that is a subsignature (§8.4.2) of the signature ofm as a member ofJ.

• There exists no methodm' that is a member of a direct superinterface ofI,J' (m distinct fromm',J distinct fromJ'), such thatm' overrides from the interface ofJ' the declaration of the methodm (§9.4.1.1).

An instance methodmI declared in or inherited by interfaceI,overrides fromI another instance methodmJ declared in interfaceJ, iff all of the following are true:

The presence or absence of thestrictfp modifier has absolutely no effect on the rules for overriding methods. For example, it is permitted for a method that is not FP-strict to override an FP-strict method and it is permitted for an FP-strict method to override a method that is not FP-strict.

An overridden default method can be accessed by using a method invocation expression (§15.12) that contains the keywordsuper qualified by a superinterface name.

The relationship between the return type of an interface method and the return types of any overridden interface methods is specified in§8.4.8.3.

The relationship between thethrows clause of an interface method and thethrows clauses of any overridden interface methods is specified in§8.4.8.3.

The relationship between the signature of an interface method and the signatures of any overridden interface methods is specified in§8.4.8.3.

The relationship between the accessibility of an interface method and the accessibility of any overridden interface methods is specified in§8.4.8.3.

It is a compile-time error if a default method is override-equivalent (§8.4.2) with a non-private method of the classObject, because any class implementing the interface will inherit its own implementation of the method.

The prohibition against declaring one of theObject methods as a default method may be surprising. There are, after all, cases likejava.util.List in which the behavior oftoString andequals are precisely defined. The motivation becomes clearer, however, when some broader design decisions are understood:

An interface is free, however, to define another method that provides behavior useful for classes that override theObject methods. For example, thejava.util.List interface could declare anelementString method that produces the string described by the contract oftoString; implementors oftoString in classes could then delegate to this method.

It is possible for an interface to inherit several methods with override-equivalent signatures (§8.4.2).

If an interfaceI inherits a default method whose signature is override-equivalent with another method inherited byI, then a compile-time error occurs. (This is the case whether the other method isabstract ordefault.)

Otherwise, all the inherited methods areabstract, and the interface is considered to inherit all the methods.

One of the inherited methods must be return-type-substitutable for every other inherited method, or else a compile-time error occurs. (Thethrows clauses do not cause errors in this case.)

There might be several paths by which the same method declaration is inherited from an interface. This fact causes no difficulty and never, of itself, results in a compile-time error.

Naturally, when two different default methods with matching signatures are inherited by a subinterface, there is a behavioral conflict. We actively detect this conflict and notify the programmer with an error, rather than waiting for the problem to arise when a concrete class is compiled. The error can be avoided by declaring a new method that overrides, and thus prevents the inheritance of, all conflicting methods.

Similarly, when an abstract method and a default method with matching signatures are inherited by a subinterface, we produce an error. In this case, it would be possible to give priority to one or the other - perhaps we would assume that the default method provides a reasonable implementation for the abstract method. But this is risky, since other than the coincidental name and signature, we have no reason to believe that the default method behaves consistently with the abstract method's contract - the default method may not have even existed when the subinterface was originally developed. It is safer in this situation to ask the user to actively assert that the default implementation is appropriate (via an overriding declaration).

In contrast, the longstanding behavior for inherited concrete methods in classes is that they override abstract methods declared in interfaces (see§8.4.8). The same argument about potential contract violation applies here, but in this case there is an inherent imbalance between classes and interfaces. We prefer, in order to preserve the independent nature of class hierarchies, to minimize class-interface clashes by simply giving priority to concrete methods.

Example 9.4.2-1. Overloading anabstract Method Declaration

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 primitive type

• String

• Class or an invocation ofClass (§4.5)

• An enum class type

• An annotation interface type

• An array type whose component type is one of the preceding types (§10.1).

This rule precludes elements with nested array types, such as:

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

For example, this is illegal:

@interface SelfRef { SelfRef value(); }

and so is this:

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

Example 9.6.1-1. Annotation Interface Declaration

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

Example 9.6.1-2. Marker Annotation Interface Declaration

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

Example 9.6.1-3. Single-Element Annotation Interface Declarations

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

Example 9.6.2-1. Annotation Interface Declaration With Default Values

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

1. AC declares avalue() method whose return type isA[].

2. Any methods declared byAC other thanvalue() have a default value.

3. AC is retained for at least as long asA, where retention is expressed explicitly or implicitly with the@Retention annotation (§9.6.4.2). Specifically:

   • If the retention ofAC isjava.lang.annotation.RetentionPolicy.SOURCE, then the retention ofA isjava.lang.annotation.RetentionPolicy.SOURCE.

   • If the retention ofAC isjava.lang.annotation.RetentionPolicy.CLASS, then the retention ofA is eitherjava.lang.annotation.RetentionPolicy.CLASS orjava.lang.annotation.RetentionPolicy.SOURCE.

   • If the retention ofAC isjava.lang.annotation.RetentionPolicy.RUNTIME, then the retention ofA isjava.lang.annotation.RetentionPolicy.SOURCE,java.lang.annotation.RetentionPolicy.CLASS, orjava.lang.annotation.RetentionPolicy.RUNTIME.

4. A is applicable to at least the same kinds of program element asAC (§9.6.4.1). Specifically, if the kinds of program element whereA is applicable are denoted by the setm1, and the kinds of program element whereAC is applicable are denoted by the setm2, then each kind inm2 must occur inm1, except that:

   • If the kind inm2 isjava.lang.annotation.ElementType.ANNOTATION_TYPE, then at least one ofjava.lang.annotation.ElementType.ANNOTATION_TYPE orjava.lang.annotation.ElementType.TYPE orjava.lang.annotation.ElementType.TYPE_USE must occur inm1.

   • If the kind inm2 isjava.lang.annotation.ElementType.TYPE, then at least one ofjava.lang.annotation.ElementType.TYPE orjava.lang.annotation.ElementType.TYPE_USE must occur inm1.

   • If the kind inm2 isjava.lang.annotation.ElementType.TYPE_PARAMETER, then at least one ofjava.lang.annotation.ElementType.TYPE_PARAMETER orjava.lang.annotation.ElementType.TYPE_USE must occur inm1.

   This clause implements the policy that an annotation interface may berepeatable on only some of the kinds of program element where it isapplicable.

5. If the declaration ofA has a (meta-)annotation that corresponds tojava.lang.annotation.Documented, then the declaration ofAC must have a (meta-)annotation that corresponds tojava.lang.annotation.Documented.

   Note that it is permissible forAC to be@Documented whileA is not@Documented.

6. If the declaration ofA has a (meta-)annotation that corresponds tojava.lang.annotation.Inherited, then the declaration ofAC must have a (meta)-annotation that corresponds tojava.lang.annotation.Inherited.

   Note that it is permissible forAC to be@Inherited whileA is not@Inherited.

Example 9.6.3-1. Ill-formed Containing Annotation Interface

import java.lang.annotation.Repeatable;@Repeatable(FooContainer.class)@interface Foo {}@interface FooContainer { Object[] value(); }

Example 9.6.3-2. Restricting Where Annotations May Repeat

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 @Foointerface Intf {}

Example 9.6.3-3. A Repeatable Containing Annotation Interface

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

An annotation of typejava.lang.annotation.Target is used on the declaration of an annotation interfaceA to specify the contexts in whichA isapplicable.java.lang.annotation.Target has a single element,value, of typejava.lang.annotation.ElementType[], to specify contexts.

Annotation interfaces may be applicable indeclaration contexts, where annotations apply to declarations, or intype contexts, where annotations apply to types used in declarations and expressions.

There are ten declaration contexts, each corresponding to an enum constant ofjava.lang.annotation.ElementType:

There are 17 type contexts (§4.11), all represented by the enum constantTYPE_USE ofjava.lang.annotation.ElementType.

It is a compile-time error if the same enum constant appears more than once in thevalue element of an annotation of typejava.lang.annotation.Target.

If an annotation of typejava.lang.annotation.Target is not present on the declaration of an annotation interfaceA, thenA is applicable in all ten declaration contexts and in all 17 type contexts.

Annotations may be present only in source code, or they may be present in the binary form of a class or interface. An annotation that is present in the binary form may or may not be available at run time via the reflection libraries of the Java SE Platform. The annotation interfacejava.lang.annotation.Retention is used to choose among these possibilities.

If an annotationa corresponds to an annotation interfaceA, andA has a (meta-)annotationm that corresponds tojava.lang.annotation.Retention, then:

IfA does not have a (meta-)annotation that corresponds tojava.lang.annotation.Retention, then a Java compiler must treatA as if it has a (meta-)annotation that corresponds tojava.lang.annotation.Retention with an element whose value isjava.lang.annotation.RetentionPolicy.CLASS.

The annotation interfacejava.lang.annotation.Inherited is used to indicate that annotations on a classC corresponding to a given annotation interface are inherited by subclasses ofC.

Programmers occasionally overload a method declaration when they mean to override it, leading to subtle problems. The annotation interfaceOverride supports early detection of such problems.

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

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

If a method declaration in class or interfaceQ is annotated with@Override, then one of the following three conditions must be true, or a compile-time error occurs:

This behavior differs from Java SE 5.0, where@Override only caused a compile-time error if applied to a method that implemented a method from a superinterface that was not also present in a superclass.

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

Java compilers are increasingly capable of issuing helpful "lint-like" warnings. To encourage the use of such warnings, there should be some way to disable a warning in a part of the program when the programmer knows that the warning is inappropriate.

The annotation interfaceSuppressWarnings supports programmer control over warnings otherwise issued by a Java compiler. It defines a single element that is an array ofString.

If a declaration is annotated with@SuppressWarnings(value = {S1, ...,Sk}), then a Java compiler must suppress (that is, not report) any warning specified by one ofS₁ ...S_k if that warning would have been generated as a result of the annotated declaration or any of its parts.

The Java programming language defines four kinds of warnings that can be specified by@SuppressWarnings:

Any other string specifies a non-standard warning. A Java compiler must ignore any such string that it does not recognize.

Compiler vendors are encouraged to document the strings they support for@SuppressWarnings, and to cooperate to ensure that the same strings are recognized across multiple compilers.

Programmers are sometimes discouraged from using certain program elements (modules, classes, interfaces, fields, methods, and constructors) because they are considered dangerous or because a better alternative exists. The annotation interfaceDeprecated allows a compiler to warn about uses of these program elements.

Adeprecated program element is a module, class, interface, field, method, or constructor whose declaration is annotated with@Deprecated. The manner in which a program element is deprecated depends on the value of theforRemoval element of the annotation:

A Java compiler must produce adeprecation warning when an ordinarily deprecated program element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:

A Java compiler must produce aremoval warning when a terminally deprecated program element is used (overridden, invoked, or referenced by name) in the declaration of a program element (whether explicitly or implicitly declared), unless:

Terminal deprecation is sufficiently urgent that the use of a terminally deprecated element will cause a removal warningeven if the using element is itself deprecated, since there is no guarantee that both elements will be removed at the same time. To dismiss the warning but continue using the element, the programmer must manually acknowledge the risk via an@SuppressWarnings annotation.

No deprecation warning or removal warning is produced when:

A module declaration that exports or opens a package is usually controlled by the same programmer or team that controls the package's declaration. As such, there is little benefit in warning that the package declaration is annotated with@Deprecated when the package is exported or opened by the module declaration. In contrast, a module declaration that exports or opens a packageto a friend module is usually not controlled by the same programmer or team that controls the friend module. Simply exporting or opening the package does not make the module declaration rely on the friend module, so there is little value in warning if the friend module is deprecated; the programmer of the module declaration would almost always wish to suppress such a warning.

The only implicit declaration that can cause a deprecation warning or removal warning is a container annotation (§9.7.5). Namely, ifT is a repeatable annotation interface andTC is its containing annotation interface, andTC is deprecated, then repeating the@T annotation will cause a warning. The warning is due to the implicit@TC container annotation. It is strongly discouraged to deprecate a containing annotation interface without deprecating the corresponding repeatable annotation interface.

A variable arity parameter with a non-reifiable element type (§4.7) can cause heap pollution (§4.12.2) and give rise to compile-time unchecked warnings (§5.1.9). However, such warnings are uninformative if the body of the variable arity method is well-behaved with respect to the variable arity parameter.

The annotation interfaceSafeVarargs, when used to annotate a method or constructor declaration, makes a programmer assertion that prevents a Java compiler from reporting unchecked warnings for the declaration or invocation of a variable arity method or constructor where the compiler would otherwise do so due to the variable arity parameter having a non-reifiable element type.

The annotation@SafeVarargs has non-local effects because it suppresses unchecked warnings at method invocation expressions, in addition to an unchecked warning pertaining to the declaration of the variable arity method itself (§8.4.1). In contrast, the annotation@SuppressWarnings("unchecked") has local effects because it only suppresses unchecked warnings pertaining to the declaration of a method.

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

It is a compile-time error if a fixed arity method or constructor declaration is annotated with the annotation@SafeVarargs.

It is a compile-time error if a variable arity method declaration that is neitherstatic norfinal norprivate is annotated with the annotation@SafeVarargs.

Since@SafeVarargs is only applicable tostatic methods,final and/orprivate instance methods, and constructors, the annotation is not usable where method overriding occurs. Annotation inheritance only works for annotations on classes (not on methods, interfaces, or constructors), so an@SafeVarargs-style annotation cannot be passed through instance methods in classes or through interfaces.

The annotation interfacejava.lang.annotation.Repeatable is used on the declaration of arepeatable annotation interface to indicate its containing annotation interface (§9.6.3).

Note that an@Repeatable meta-annotation on the declaration ofA, indicatingAC, isnot sufficient to makeAC the containing annotation interface ofA. There are numerous well-formedness rules forAC to be considered the containing annotation interface ofA.

The annotation interfaceFunctionalInterface is used to indicate that an interface is meant to be a functional interface (§9.8). It facilitates early detection of inappropriate method declarations appearing in or inherited by an interface that is meant to be functional.

It is a compile-time error if an interface declaration is annotated with@FunctionalInterface but is not, in fact, a functional interface.

Because some interfaces are functional incidentally, it is not necessary or desirable that all declarations of functional interfaces be annotated with@FunctionalInterface.

• T is an array typeE[], and either:

  • Ifv is aConditionalExpression or anAnnotation, thenv is commensurate withE; or

  • Ifv is anElementValueArrayInitializer, then each element value thatv contains is commensurate withE.

    AnElementValueArrayInitializer is similar to a normal array initializer (§10.6), except that anElementValueArrayInitializer may syntactically contain annotations as well as expressions and nested initializers. However, nested initializers are not semantically legal in anElementValueArrayInitializer because they are never commensurate with array-typed elements in annotation interface declarations (nested array types not permitted).

• T is not an array type, and the type ofv is assignment compatible (§5.2) withT, and:

  • IfT is a primitive type orString, thenv is a constant expression (§15.29).

  • IfT isClass or an invocation ofClass (§4.5), thenv is a class literal (§15.8.2).

  • IfT is an enum class type (§8.9), thenv is an enum constant (§8.9.1).

  • v is notnull.

Example 9.7.1-1. Normal Annotations

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

Example 9.7.2-1. Marker Annotations

@Preliminary public class TimeTravel { ... }

Example 9.7.3-1. Single-Element Annotations

@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 { ... }

For example, given the field declaration:

@Foo int f;

@Foo is a declaration annotation onf ifFoo is meta-annotated by@Target(ElementType.FIELD), and a type annotation onint ifFoo is meta-annotated by@Target(ElementType.TYPE_USE). It is possible for@Foo to be both a declaration annotation and a type annotation simultaneously.

Type annotations can apply to an array type or any component type thereof (§10.1). For example, assuming thatA,B, andC are annotation interfaces meta-annotated with@Target(ElementType.TYPE_USE), then given the field declaration:

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

@A applies to the array typeint[][],@B applies to its component typeint[], and@C applies to the element typeint. For more examples, see§10.2.

An important property of this syntax is that, in two declarations that differ only in the number of array levels, the annotations to the left of the type refer to the same type. For example,@C applies to the typeint in all of the following declarations:

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

• Method declarations (including elements of annotation interfaces)

• Constructor declarations

• Field declarations (including enum constants)

• Formal and exception parameter declarations

• Local variable declarations

• Record component declarations

• If the annotation's interface is applicable in the declaration context corresponding to the declaration, and not in type contexts, then the annotation is deemed to apply only to the declaration.

• If the annotation's interface is applicable in type contexts, and not in the declaration context corresponding to the declaration, then the annotation is deemed to apply only to the type which is closest to the annotation.

• If the annotation's interface is applicable in the declaration context corresponding to the declarationand in type contexts, then the annotation is deemed to apply to both the declarationand the type which is closest to the annotation.

• If the annotation appears before avoid method declaration or a local variable declaration that usesvar (§14.4), then there is no closest type. If the annotation's interface is deemed to apply only to the type which is closest to the annotation, a compile-time error occurs.

• If the annotation appears before a constructor declaration, then the closest type is the type of the newly constructed object. The type of the newly constructed object is the fully qualified name of the type immediately enclosing the constructor declaration. Within that fully qualified name, the annotation applies to the simple type name indicated by the constructor declaration.

• In all other cases, the closest type is the type written in source code for the declared entity; if that type is an array type, then the element type is deemed to be closest to the annotation.

  For example, in the fielddeclaration@Foo public static String f;, the type which is closest to@Foo isString. (If the type of the field declaration had been written asjava.lang.String, thenjava.lang.String would be the type closest to@Foo, and later rules would prohibit a type annotation from applying to the package namejava.) In the generic method declaration@Foo <T> int[] m() {...}, the type written for the declared entity isint[], so@Foo applies to the element typeint.

  Local variable declarations which do not usevar are similar to formal parameter declarations of lambda expressions, in that both allow declaration annotations and type annotations in source code, but only the type annotations can be stored in theclass file.

• a module declaration, butA is not applicable to module declarations.

• a package declaration, butA is not applicable to package declarations.

• a class or interface declaration, butA is not applicable to type declarations or in type contexts; or

  an annotation interface declaration, butA is not applicable to annotation interface declarations or type declarations or in type contexts.

• a method declaration (including an element of an annotation interface), butA is not applicable to method declarations or in type contexts.

• a constructor declaration, butA is not applicable to constructor declarations or in type contexts.

• a type parameter declaration of a generic class, interface, method, or constructor, butA is not applicable to type parameter declarations or in type contexts.

• a field declaration (or an enum constant), butA is not applicable to field declarations or in type contexts.

• a formal or exception parameter declaration, butA is not applicable to formal and exception parameter declarations or in type contexts.

• a receiver parameter, butA is not applicable in type contexts.

• a local variable declaration in either a statement or a pattern, butA is not applicable to local variable declarations or in type contexts.

• a record component, butA is not applicable to record component declarations, field declarations, method declarations, or formal and exception parameter declarations, or in type contexts.

• The simple name to which the annotation is closest is classified as aTypeName, not aPackageName.

• If the simple name to which the annotation is closest is followed by "." and anotherTypeName - that is, the annotation appears as@Foo T.U - thenU denotes an inner class ofT.

For example, in the following program, it is not possible to writeA.this in the body ofB, asB has no lexically enclosing instances. Therefore, it is not possible to apply@Foo toA in the typeA.B, becauseA is logically just a name, not a type.

@Target(ElementType.TYPE_USE)@interface Foo {}class A {    static class B {}}@Foo A.B x;  // Illegal

On the other hand, in the following program, it is possible to writeC.this in the body ofD. Therefore, it is possible to apply@Foo toC in the typeC.D, becauseC represents the type of some object at run time.

@Target(ElementType.TYPE_USE)@interface Foo {}class Test {    static class C {        class D {}    }    @Foo C.D x;  // Legal }

A simple example of a functional interface is:

interface Runnable {    void run();}

The following interface is not functional because it declares nothing which is not already a member ofObject:

interface NonFunc {    boolean equals(Object obj);}

However, its subinterface can be functional by declaring anabstract method which is not a member ofObject:

interface Func extends NonFunc {    int compare(String o1, String o2);}

Similarly, the well known interfacejava.util.Comparator<T> is functional because it has oneabstract non-Object method:

interface Comparator<T> {    boolean equals(Object obj);    int compare(T o1, T o2);}

The following interface is not functional because while it only declares oneabstract method which is not a member ofObject, it declarestwoabstract methods which are notpublic members ofObject:

interface Foo {    int m();    Object clone();}

In the following interface hierarchy,Z is a functional interface because while it inherits twoabstract methods which are not members ofObject, they have the same signature, so the inherited methods logically represent a single method:

interface X { int m(Iterable<String> arg); }interface Y { int m(Iterable<String> arg); }interface Z extends X, Y {}

Similarly,Z is a functional interface in the following interface hierarchy becauseY.m is a subsignature ofX.m and is return-type-substitutable forX.m:

interface X { Iterable m(Iterable<String> arg); }interface Y { Iterable<String> m(Iterable arg); }interface Z extends X, Y {}

The definition offunctional interface respects the fact that an interface cannot have two members which are not subsignatures of each other, yet have the same erasure (§9.4.1.2). Thus, in the following three interface hierarchies whereZ causes a compile-time error,Z is not a functional interface: (because none of itsabstract members are subsignatures of all otherabstract members)

interface X { int m(Iterable<String> arg); }interface Y { int m(Iterable<Integer> arg); }interface Z extends X, Y {}interface X { int m(Iterable<String> arg, Class c); }interface Y { int m(Iterable arg, Class<?> c); }interface Z extends X, Y {}interface X<T> { void m(T arg); }interface Y<T> { void m(T arg); }interface Z<A, B> extends X<A>, Y<B> {}

Similarly, the definition of "functional interface" respects the fact that an interface may only have methods with override-equivalent signatures if one is return-type-substitutable for all the others. Thus, in the following interface hierarchy whereZ causes a compile-time error,Z is not a functional interface: (because none of itsabstract members are return-type-substitutable for all otherabstract members)

interface X { long m(); }interface Y { int  m(); }interface Z extends X, Y {}

In the following example, the declarations ofFoo<T,N> andBar are legal: in each, the methods calledm are not subsignatures of each other, but do have different erasures. Still, the fact that the methods in each are not subsignatures meansFoo<T,N> andBar are not functional interfaces. However,Baz is a functional interface because the methods it inherits fromFoo<Integer,Integer> have the same signature and so logically represent a single method.

interface Foo<T, N extends Number> {    void m(T arg);    void m(N arg);}interface Bar extends Foo<String, Integer> {}interface Baz extends Foo<Integer, Integer> {}

Finally, the following examples demonstrate the same rules as above, but with generic methods:

interface Exec { <T> T execute(Action<T> a); }  // Functionalinterface X { <T> T execute(Action<T> a); }interface Y { <S> S execute(Action<S> a); }interface Exec extends X, Y {}  // Functional: signatures are logically "the same"interface X { <T>   T execute(Action<T> a); }interface Y { <S,T> S execute(Action<S> a); }interface Exec extends X, Y {}  // Error: different signatures, same erasure

Functional interfaces can be generic, such asjava.util.function.Predicate<T>. Such a functional interface may be parameterized in a way that produces distinctabstract methods - that is, multiple methods that cannot be legally overridden with a single declaration. For example:

interface I    { Object m(Class c); }interface J<S> { S m(Class<?> c); }interface K<T> { T m(Class<?> c); }interface Functional<S,T> extends I, J<S>, K<T> {}

Functional<S,T> is a functional interface -I.m is return-type-substitutable forJ.m andK.m - but the functional interface typeFunctional<String,Integer> clearly cannot be implemented with a single method. However, other parameterizations ofFunctional<S,T> which are functional interface types are possible.

Given the following interfaces:

interface X { void m() throws IOException; }interface Y { void m() throws EOFException; }interface Z { void m() throws ClassNotFoundException; }

the function type of:

interface XY extends X, Y {}

is:

()->void throws EOFException

while the function type of:

interface XYZ extends X, Y, Z {}

is:

()->void (throws nothing)

Given the following interfaces:

interface A {    List<String> foo(List<String> arg)      throws IOException, SQLTransientException;}interface B {    List foo(List<String> arg)      throws EOFException, SQLException, TimeoutException;}interface C {    List foo(List arg) throws Exception;}

the function type of:

interface D extends A, B {}

is:

(List<String>)->List<String>  throws EOFException, SQLTransientException

while the function type of:

interface E extends A, B, C {}

is:

(List)->List throws EOFException, SQLTransientException

A function type may be generic, as a functional interface's abstract method may be generic. For example, in the following interface hierarchy:

interface G1 {    <E extends Exception> Object m() throws E;}interface G2 {    <F extends Exception> String m() throws Exception;}interface G extends G1, G2 {}

the function type ofG is:

<F extends Exception> ()->String throws F

A generic function type for a functional interface may be implemented by a method reference expression (§15.13), but not by a lambda expression (§15.27) as there is no syntax for generic lambda expressions.