Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
4396 lines (4101 sloc) 286 KB
<!DOCTYPE html
PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Chapter&nbsp;9.&nbsp;Interfaces</title>
<link rel="stylesheet" type="text/css" href="../../../javaspec.css">
<meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1">
<link rel="home" href="index.html" title="The Java&reg; Language Specification">
<link rel="up" href="index.html" title="The Java&reg; Language Specification">
<link rel="prev" href="jls-8.html" title="Chapter&nbsp;8.&nbsp;Classes">
<link rel="next" href="jls-10.html" title="Chapter&nbsp;10.&nbsp;Arrays">
<link rel="copyright" href="jls-0-front.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:rx="http://www.renderx.com/XSL/Extensions" id="logo"><img src="http://www.oracleimg.com/us/assets/oralogo-small.gif" alt="Oracle Logo"><br><p><a target="_blank" href="http://www.oracle.com/us/technologies/java/">Oracle
Technology Network</a> &gt; <a target="_blank" href="http://docs.oracle.com/javase/">Java SE</a>
&gt; <a href="index.html">Java Language Specification</a></p>
</div>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter&nbsp;9.&nbsp;Interfaces</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="jls-8.html">Prev</a>&nbsp;
</td>
<th width="60%" align="center">&nbsp;</th>
<td width="20%" align="right">&nbsp;<a accesskey="n" href="jls-10.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div lang="en" class="chapter" title="Chapter&nbsp;9.&nbsp;Interfaces">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a name="jls-9"></a>Chapter&nbsp;9.&nbsp;Interfaces
</h2>
</div>
</div>
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.1">9.1. Interface Declarations</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.1.1">9.1.1. Interface Modifiers</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.1.1.1">9.1.1.1. <code class="literal">abstract</code> Interfaces</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.1.1.2">9.1.1.2. <code class="literal">strictfp</code> Interfaces</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.1.2">9.1.2. Generic Interfaces and Type Parameters</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.1.3">9.1.3. Superinterfaces and Subinterfaces</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.1.4">9.1.4. Interface Body and Member Declarations</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.2">9.2. Interface Members</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.3">9.3. Field (Constant) Declarations</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.3.1">9.3.1. Initialization of Fields in Interfaces</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.4">9.4. Method Declarations</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.4.1">9.4.1. Inheritance and Overriding</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.4.1.1">9.4.1.1. Overriding (by Instance Methods)</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.4.1.2">9.4.1.2. Requirements in Overriding</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.4.1.3">9.4.1.3. Inheriting Methods with Override-Equivalent Signatures</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.4.2">9.4.2. Overloading</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.4.3">9.4.3. Interface Method Body</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.5">9.5. Member Type Declarations</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6">9.6. Annotation Types</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.6.1">9.6.1. Annotation Type Elements</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.2">9.6.2. Defaults for Annotation Type Elements</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.3">9.6.3. Repeatable Annotation Types</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4">9.6.4. Predefined Annotation Types</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.1">9.6.4.1. <code class="literal">@Target</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.2">9.6.4.2. <code class="literal">@Retention</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.3">9.6.4.3. <code class="literal">@Inherited</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.4">9.6.4.4. <code class="literal">@Override</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.5">9.6.4.5. <code class="literal">@SuppressWarnings</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.6">9.6.4.6. <code class="literal">@Deprecated</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.7">9.6.4.7. <code class="literal">@SafeVarargs</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.8">9.6.4.8. <code class="literal">@Repeatable</code></a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.6.4.9">9.6.4.9. <code class="literal">@FunctionalInterface</code></a></span></dt>
</dl>
</dd>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.7">9.7. Annotations</a></span></dt>
<dd>
<dl>
<dt><span class="section"><a href="jls-9.html#jls-9.7.1">9.7.1. Normal Annotations</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.7.2">9.7.2. Marker Annotations</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.7.3">9.7.3. Single-Element Annotations</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.7.4">9.7.4. Where Annotations May Appear</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.7.5">9.7.5. Multiple Annotations Of The Same Type</a></span></dt>
</dl>
</dd>
<dt><span class="section"><a href="jls-9.html#jls-9.8">9.8. Functional Interfaces</a></span></dt>
<dt><span class="section"><a href="jls-9.html#jls-9.9">9.9. Function Types</a></span></dt>
</dl>
</div>
<p class="norm"><a name="jls-9-100"></a>An interface declaration introduces a
new reference type whose members are classes, interfaces, constants,
and methods. This type has no instance variables, and typically
declares one or more <code class="literal">abstract</code> methods; otherwise unrelated classes
can implement the interface by providing implementations for its
<code class="literal">abstract</code> methods. Interfaces may not be directly
instantiated.
</p>
<p class="norm"><a name="jls-9-110"></a>A <span class="emphasis"><em>nested
interface</em></span> is any interface whose declaration occurs within
the body of another class or interface.
</p>
<p class="norm"><a name="jls-9-120"></a>A <span class="emphasis"><em>top level
interface</em></span> is an interface that is not a nested
interface.
</p>
<p class="norm"><a name="jls-9-130"></a>We distinguish between two kinds
of interfaces - normal interfaces and annotation types.
</p>
<p class="norm"><a name="jls-9-140"></a>This chapter discusses the common
semantics of all interfaces - normal interfaces, both top level
(<a class="xref" href="jls-7.html#jls-7.6" title="7.6.&nbsp;Top Level Type Declarations">&sect;7.6</a>) and nested (<a class="xref" href="jls-8.html#jls-8.5" title="8.5.&nbsp;Member Type Declarations">&sect;8.5</a>,
<a class="xref" href="jls-9.html#jls-9.5" title="9.5.&nbsp;Member Type Declarations">&sect;9.5</a>), and annotation types
(<a class="xref" href="jls-9.html#jls-9.6" title="9.6.&nbsp;Annotation Types">&sect;9.6</a>). Details that are specific to particular
kinds of interfaces are discussed in the sections dedicated to these
constructs.
</p>
<p class="norm"><a name="jls-9-150"></a>Programs can use interfaces to
make it unnecessary for related classes to share a common <code class="literal">abstract</code>
superclass or to add methods to <code class="literal">Object</code>.
</p>
<p class="norm"><a name="jls-9-160"></a>An interface may be declared to be
a <span class="emphasis"><em>direct extension</em></span> of one or more other
interfaces, meaning that it inherits all the member types, instance
methods, and constants of the interfaces it extends, except for any
members that it may override or hide.
</p>
<p class="norm"><a name="jls-9-170"></a>A class may be declared
to <span class="emphasis"><em>directly implement</em></span> one or more interfaces,
meaning that any instance of the class implements all the <code class="literal">abstract</code>
methods specified by the interface or interfaces. A class necessarily
implements all the interfaces that its direct superclasses and direct
superinterfaces do. This (multiple) interface inheritance allows
objects to support (multiple) common behaviors without sharing a
superclass.
</p>
<p class="norm"><a name="jls-9-180"></a>A variable whose declared type is
an interface type may have as its value a reference to any instance of
a class which implements the specified interface. It is not sufficient
that the class happen to implement all the <code class="literal">abstract</code> methods of the
interface; the class or one of its superclasses must actually be
declared to implement the interface, or else the class is not
considered to implement the interface.
</p>
<div class="section" title="9.1.&nbsp;Interface Declarations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.1"></a>9.1.&nbsp;Interface Declarations
</h2>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1-100"></a>An <span class="emphasis"><em>interface declaration</em></span>
specifies a new named reference type. There are two kinds of interface
declarations - <span class="emphasis"><em>normal interface declarations</em></span>
and <span class="emphasis"><em>annotation type declarations</em></span>
(<a class="xref" href="jls-9.html#jls-9.6" title="9.6.&nbsp;Annotation Types">&sect;9.6</a>).
</p>
<div id="jls-9.1-110" class="productionset"><a name="jls-9.1-110"></a>
<div class="production"><a name="jls-InterfaceDeclaration"></a>
<div class="lhs">InterfaceDeclaration:</div>
<div class="rhs">
<a href="jls-9.html#jls-NormalInterfaceDeclaration" title="NormalInterfaceDeclaration">NormalInterfaceDeclaration</a> <br>
<a href="jls-9.html#jls-AnnotationTypeDeclaration" title="AnnotationTypeDeclaration">AnnotationTypeDeclaration</a>
</div>
</div>
<div class="production"><a name="jls-NormalInterfaceDeclaration"></a>
<div class="lhs">NormalInterfaceDeclaration:</div>
<div class="rhs">
{<a href="jls-9.html#jls-InterfaceModifier" title="InterfaceModifier">InterfaceModifier</a>}
<code class="literal">interface</code> <a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a>
[<a href="jls-8.html#jls-TypeParameters" title="TypeParameters">TypeParameters</a>]
[<a href="jls-9.html#jls-ExtendsInterfaces" title="ExtendsInterfaces">ExtendsInterfaces</a>]
<a href="jls-9.html#jls-InterfaceBody" title="InterfaceBody">InterfaceBody</a>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1-120"></a>The
<span class="emphasis"><em>Identifier</em></span> in an interface declaration specifies the name of the
interface.
</p>
<p class="norm-error"><a name="jls-9.1-200"></a>It is a
compile-time error if an interface has the same simple name as any of
its enclosing classes or interfaces.
</p>
<p class="norm-static"><a name="jls-9.1-210"></a>The scope and shadowing of an
interface declaration is specified in <a class="xref" href="jls-6.html#jls-6.3" title="6.3.&nbsp;Scope of a Declaration">&sect;6.3</a> and
<a class="xref" href="jls-6.html#jls-6.4" title="6.4.&nbsp;Shadowing and Obscuring">&sect;6.4</a>.
</p>
<div class="section" title="9.1.1.&nbsp;Interface Modifiers">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.1.1"></a>9.1.1.&nbsp;Interface Modifiers
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.1-100"></a>An
interface declaration may include <span class="emphasis"><em>interface
modifiers</em></span>.
</p>
<div id="jls-9.1.1-110" class="productionset"><a name="jls-9.1.1-110"></a>
<div class="production"><a name="jls-InterfaceModifier"></a>
<div class="lhs">InterfaceModifier:</div>
<div class="rhs">
<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a> <code class="literal">public</code> <code class="literal">protected</code> <code class="literal">private</code> <br>
<code class="literal">abstract</code> <code class="literal">static</code> <code class="literal">strictfp</code>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.1.1-200"></a>The rules for
annotation modifiers on an interface declaration are specified in
<a class="xref" href="jls-9.html#jls-9.7.4" title="9.7.4.&nbsp;Where Annotations May Appear">&sect;9.7.4</a> and <a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>.
</p>
<p class="norm-static"><a name="jls-9.1.1-300"></a>The access
modifier <code class="literal">public</code> (<a class="xref" href="jls-6.html#jls-6.6" title="6.6.&nbsp;Access Control">&sect;6.6</a>) pertains to every kind
of interface declaration.
</p>
<p class="norm-static"><a name="jls-9.1.1-310"></a>The access
modifiers <code class="literal">protected</code> and <code class="literal">private</code> pertain only to member interfaces
whose declarations are directly enclosed by a class declaration
(<a class="xref" href="jls-8.html#jls-8.5.1" title="8.5.1.&nbsp;Static Member Type Declarations">&sect;8.5.1</a>).
</p>
<p class="norm-static"><a name="jls-9.1.1-320"></a>The
modifier <code class="literal">static</code> pertains only to member interfaces
(<a class="xref" href="jls-8.html#jls-8.5.1" title="8.5.1.&nbsp;Static Member Type Declarations">&sect;8.5.1</a>, <a class="xref" href="jls-9.html#jls-9.5" title="9.5.&nbsp;Member Type Declarations">&sect;9.5</a>), not to top
level interfaces (<a class="xref" href="jls-7.html#jls-7.6" title="7.6.&nbsp;Top Level Type Declarations">&sect;7.6</a>).
</p>
<p class="norm-error"><a name="jls-9.1.1-330"></a>It is a
compile-time error if the same keyword appears more than once as a
modifier for an interface declaration.
</p>
<p class="note">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 <span class="emphasis"><em>InterfaceModifier</em></span>.
</p>
<div class="section" title="9.1.1.1.&nbsp;abstract Interfaces">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.1.1.1"></a>9.1.1.1.&nbsp;<code class="literal">abstract</code> Interfaces
</h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.1.1-100"></a>Every
interface is implicitly <code class="literal">abstract</code>.
</p>
<p class="note">This modifier is obsolete and should not be used in
new programs.
</p>
</div>
<div class="section" title="9.1.1.2.&nbsp;strictfp Interfaces">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.1.1.2"></a>9.1.1.2.&nbsp;<code class="literal">strictfp</code> Interfaces
</h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.1.2-100"></a>The
effect of the <code class="literal">strictfp</code> modifier is to make all <code class="literal">float</code> or <code class="literal">double</code>
expressions within the interface declaration be explicitly FP-strict
(<a class="xref" href="jls-15.html#jls-15.4" title="15.4.&nbsp;FP-strict Expressions">&sect;15.4</a>).
</p>
<p class="norm-static"><a name="jls-9.1.1.2-110"></a>This implies
that all methods declared in the interface, and all nested types
declared in the interface, are implicitly <code class="literal">strictfp</code>.
</p>
</div>
</div>
<div class="section" title="9.1.2.&nbsp;Generic Interfaces and Type Parameters">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.1.2"></a>9.1.2.&nbsp;Generic Interfaces and Type Parameters
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.2-100"></a>An
interface is <span class="emphasis"><em>generic</em></span> if it declares one or more
type variables (<a class="xref" href="jls-4.html#jls-4.4" title="4.4.&nbsp;Type Variables">&sect;4.4</a>).
</p>
<p class="norm-static"><a name="jls-9.1.2-110"></a>These type
variables are known as the <span class="emphasis"><em>type parameters</em></span> of the
interface. The type parameter section follows the interface name and
is delimited by angle brackets.
</p>
<p class="note">The following productions from
<a class="xref" href="jls-8.html#jls-8.1.2" title="8.1.2.&nbsp;Generic Classes and Type Parameters">&sect;8.1.2</a> and <a class="xref" href="jls-4.html#jls-4.4" title="4.4.&nbsp;Type Variables">&sect;4.4</a> are shown
here for convenience:
</p>
<div id="d5e14688" class="productionset"><a name="d5e14688"></a>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">TypeParameters:</div>
<div class="rhs">
<code class="literal">&lt;</code> <a href="jls-8.html#jls-TypeParameterList" title="TypeParameterList">TypeParameterList</a> <code class="literal">&gt;</code>
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">TypeParameterList:</div>
<div class="rhs">
<a href="jls-4.html#jls-TypeParameter" title="TypeParameter">TypeParameter</a> {<code class="literal">,</code> <a href="jls-4.html#jls-TypeParameter" title="TypeParameter">TypeParameter</a>}
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">TypeParameter:</div>
<div class="rhs">
{<a href="jls-4.html#jls-TypeParameterModifier" title="TypeParameterModifier">TypeParameterModifier</a>}
<a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a>
[<a href="jls-4.html#jls-TypeBound" title="TypeBound">TypeBound</a>]
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">TypeParameterModifier:</div>
<div class="rhs">
<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">TypeBound:</div>
<div class="rhs">
<code class="literal">extends</code> <a href="jls-4.html#jls-TypeVariable" title="TypeVariable">TypeVariable</a> <br>
<code class="literal">extends</code> <a href="jls-4.html#jls-ClassOrInterfaceType" title="ClassOrInterfaceType">ClassOrInterfaceType</a> {<a href="jls-4.html#jls-AdditionalBound" title="AdditionalBound">AdditionalBound</a>}
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">AdditionalBound:</div>
<div class="rhs">
<code class="literal">&amp;</code> <a href="jls-4.html#jls-InterfaceType" title="InterfaceType">InterfaceType</a>
</div>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.1.2-120"></a>The rules for
annotation modifiers on a type parameter declaration are specified in
<a class="xref" href="jls-9.html#jls-9.7.4" title="9.7.4.&nbsp;Where Annotations May Appear">&sect;9.7.4</a> and <a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>.
</p>
<p class="norm-static"><a name="jls-9.1.2-200"></a>In an
interface's type parameter section, a type variable
<span class="type">T</span> <span class="emphasis"><em>directly depends</em></span> on a type variable <span class="type">S</span> if
<span class="type">S</span> is the bound of <span class="type">T</span>, while <span class="type">T</span> <span class="emphasis"><em>depends</em></span> on <span class="type">S</span>
if either <span class="type">T</span> directly depends on <span class="type">S</span> or <span class="type">T</span> directly depends on a
type variable <span class="type">U</span> that depends on <span class="type">S</span> (using this definition
recursively). It is a compile-time error if a type variable in a
interface's type parameter section depends on itself.
</p>
<p class="norm-static"><a name="jls-9.1.2-210"></a>The scope
and shadowing of an interface's type parameter is specified in
<a class="xref" href="jls-6.html#jls-6.3" title="6.3.&nbsp;Scope of a Declaration">&sect;6.3</a>.
</p>
<p class="norm-error"><a name="jls-9.1.2-220"></a>It is a
compile-time error to refer to a type parameter of an interface <span class="type">I</span>
anywhere in the declaration of a field or type member of <span class="type">I</span>.
</p>
<p class="norm-dynamic"><a name="jls-9.1.2-300"></a>A generic
interface declaration defines a set of parameterized types
(<a class="xref" href="jls-4.html#jls-4.5" title="4.5.&nbsp;Parameterized Types">&sect;4.5</a>), 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.
</p>
</div>
<div class="section" title="9.1.3.&nbsp;Superinterfaces and Subinterfaces">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.1.3"></a>9.1.3.&nbsp;Superinterfaces and Subinterfaces
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.3-100"></a>If an
<code class="literal">extends</code> 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.
</p>
<p class="norm"><a name="jls-9.1.3-110"></a>These other named interfaces
are the <span class="emphasis"><em>direct superinterfaces</em></span> of the interface
being declared.
</p>
<p class="norm-static"><a name="jls-9.1.3-120"></a>Any class
that <code class="literal">implements</code> the declared interface is also considered to
implement all the interfaces that this interface <code class="literal">extends</code>.
</p>
<div id="jls-9.1.3-130" class="productionset"><a name="jls-9.1.3-130"></a>
<div class="production"><a name="jls-ExtendsInterfaces"></a>
<div class="lhs">ExtendsInterfaces:</div>
<div class="rhs">
<code class="literal">extends</code> <a href="jls-8.html#jls-InterfaceTypeList" title="InterfaceTypeList">InterfaceTypeList</a>
</div>
</div>
</div>
<p class="note">The following production from
<a class="xref" href="jls-8.html#jls-8.1.5" title="8.1.5.&nbsp;Superinterfaces">&sect;8.1.5</a> is shown here for convenience:
</p>
<div id="d5e14736" class="productionset"><a name="d5e14736"></a>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">InterfaceTypeList:</div>
<div class="rhs">
<a href="jls-4.html#jls-InterfaceType" title="InterfaceType">InterfaceType</a> {<code class="literal">,</code> <a href="jls-4.html#jls-InterfaceType" title="InterfaceType">InterfaceType</a>}
</div>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.1.3-140"></a>Each <span class="emphasis"><em>InterfaceType</em></span> in the
<code class="literal">extends</code> clause of an interface declaration must name an accessible
interface type (<a class="xref" href="jls-6.html#jls-6.6" title="6.6.&nbsp;Access Control">&sect;6.6</a>), or a compile-time error
occurs.
</p>
<p class="norm-error"><a name="jls-9.1.3-150"></a>If
an <span class="emphasis"><em>InterfaceType</em></span> has type arguments, it must
denote a well-formed parameterized type (<a class="xref" href="jls-4.html#jls-4.5" title="4.5.&nbsp;Parameterized Types">&sect;4.5</a>),
and none of the type arguments may be wildcard type arguments, or a
compile-time error occurs.
</p>
<p class="norm-static"><a name="jls-9.1.3-200"></a>Given a
(possibly generic) interface declaration
<span class="type">I</span><code class="literal">&lt;</code><span class="type">F<sub>1</sub></span>,...,<span class="type">F<sub>n</sub></span><code class="literal">&gt;</code> (<span class="emphasis"><em>n</em></span> <span class="symbol">&#8805;</span> 0),
the <span class="emphasis"><em>direct superinterfaces</em></span> of the interface type
<span class="type">I</span><code class="literal">&lt;</code><span class="type">F<sub>1</sub></span>,...,<span class="type">F<sub>n</sub></span><code class="literal">&gt;</code> are the types given in the <code class="literal">extends</code>
clause of the declaration of <span class="type">I</span>, if an <code class="literal">extends</code> clause is
present.
</p>
<p class="norm-static"><a name="jls-9.1.3-210"></a>Given a
generic interface declaration <span class="type">I</span><code class="literal">&lt;</code><span class="type">F<sub>1</sub></span>,...,<span class="type">F<sub>n</sub></span><code class="literal">&gt;</code> (<span class="emphasis"><em>n</em></span>
&gt; 0), the <span class="emphasis"><em>direct superinterfaces</em></span> of the
parameterized interface type <span class="type">I</span><code class="literal">&lt;</code><span class="type">T<sub>1</sub></span>,...,<span class="type">T<sub>n</sub></span><code class="literal">&gt;</code>, where
<span class="type">T<sub>i</sub></span> (1 <span class="symbol">&#8804;</span> <span class="emphasis"><em>i</em></span> <span class="symbol">&#8804;</span> <span class="emphasis"><em>n</em></span>) is a type, are all types
<span class="type">J</span><code class="literal">&lt;</code><span class="type">U<sub>1</sub></span> <span class="symbol">&#952;</span>,...,<span class="type">U<sub>k</sub></span> <span class="symbol">&#952;</span><code class="literal">&gt;</code>, where
<span class="type">J</span><code class="literal">&lt;</code><span class="type">U<sub>1</sub></span>,...,<span class="type">U<sub>k</sub></span><code class="literal">&gt;</code> is a direct superinterface of
<span class="type">I</span><code class="literal">&lt;</code><span class="type">F<sub>1</sub></span>,...,<span class="type">F<sub>n</sub></span><code class="literal">&gt;</code> and <span class="symbol">&#952;</span> is the
substitution <code class="literal">[<span class="type">F<sub>1</sub></span>:=<span class="type">T<sub>1</sub></span>,...,<span class="type">F<sub>n</sub></span>:=<span class="type">T<sub>n</sub></span>]</code>.
</p>
<p class="norm-static"><a name="jls-9.1.3-300"></a>The <span class="emphasis"><em>superinterface</em></span>
relationship is the transitive closure of the direct superinterface
relationship. An interface <span class="type">K</span> is a superinterface of interface <span class="type">I</span> if
either of the following is true:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm"><a name="jls-9.1.3-300-A"></a><span class="type">K</span> is a direct
superinterface of <span class="type">I</span>.
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.1.3-300-B"></a>There exists an
interface <span class="type">J</span> such that <span class="type">K</span> is a superinterface of <span class="type">J</span>, and <span class="type">J</span>
is a superinterface of <span class="type">I</span>, applying this definition
recursively.
</p>
</li>
</ul>
</div>
<p class="norm-static"><a name="jls-9.1.3-310"></a>Interface
<span class="type">I</span> is said to be a <span class="emphasis"><em>subinterface</em></span> of interface <span class="type">K</span>
whenever <span class="type">K</span> is a superinterface of <span class="type">I</span>.
</p>
<p class="norm-static"><a name="jls-9.1.3-320"></a>While
every class is an extension of class <code class="literal">Object</code>, there is no single
interface of which all interfaces are extensions.
</p>
<p class="norm-static"><a name="jls-9.1.3-400"></a>An
interface <span class="type">I</span> <span class="emphasis"><em>directly depends</em></span> on a type <span class="type">T</span> if
<span class="type">T</span> is mentioned in the <code class="literal">extends</code> clause of <span class="type">I</span> either as a
superinterface or as a qualifier within a superinterface name.
</p>
<p class="norm-static"><a name="jls-9.1.3-410"></a>An
interface <span class="type">I</span> <span class="emphasis"><em>depends</em></span> on a reference type <span class="type">T</span> if
any of the following is true:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm"><a name="jls-9.1.3-410-A"></a>
<span class="type">I</span> directly depends on <span class="type">T</span>.
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.1.3-410-B"></a>
<span class="type">I</span> directly depends on a class <span class="type">C</span> that depends on <span class="type">T</span>
(<a class="xref" href="jls-8.html#jls-8.1.5" title="8.1.5.&nbsp;Superinterfaces">&sect;8.1.5</a>).
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.1.3-410-C"></a>
<span class="type">I</span> directly depends on an interface <span class="type">J</span> that depends on <span class="type">T</span>
(using this definition recursively).
</p>
</li>
</ul>
</div>
<p class="norm-error"><a name="jls-9.1.3-420"></a>It is a
compile-time error if an interface depends on itself.
</p>
<p class="norm-dynamic"><a name="jls-9.1.3-430"></a>If circularly declared interfaces
are detected at run time, as interfaces are loaded, then a
<code class="literal">ClassCircularityError</code> is thrown (<a class="xref" href="jls-12.html#jls-12.2.1" title="12.2.1.&nbsp;The Loading Process">&sect;12.2.1</a>).
</p>
</div>
<div class="section" title="9.1.4.&nbsp;Interface Body and Member Declarations">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.1.4"></a>9.1.4.&nbsp;Interface Body and Member Declarations
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.4-100"></a>The body
of an interface may declare members of the interface, that is, fields
(<a class="xref" href="jls-9.html#jls-9.3" title="9.3.&nbsp;Field (Constant) Declarations">&sect;9.3</a>), methods (<a class="xref" href="jls-9.html#jls-9.4" title="9.4.&nbsp;Method Declarations">&sect;9.4</a>),
classes (<a class="xref" href="jls-9.html#jls-9.5" title="9.5.&nbsp;Member Type Declarations">&sect;9.5</a>), and interfaces
(<a class="xref" href="jls-9.html#jls-9.5" title="9.5.&nbsp;Member Type Declarations">&sect;9.5</a>).
</p>
<div id="jls-9.1.4-110" class="productionset"><a name="jls-9.1.4-110"></a>
<div class="production"><a name="jls-InterfaceBody"></a>
<div class="lhs">InterfaceBody:</div>
<div class="rhs">
<code class="literal">{</code> {<a href="jls-9.html#jls-InterfaceMemberDeclaration" title="InterfaceMemberDeclaration">InterfaceMemberDeclaration</a>} <code class="literal">}</code>
</div>
</div>
<div class="production"><a name="jls-InterfaceMemberDeclaration"></a>
<div class="lhs">InterfaceMemberDeclaration:</div>
<div class="rhs">
<a href="jls-9.html#jls-ConstantDeclaration" title="ConstantDeclaration">ConstantDeclaration</a> <br>
<a href="jls-9.html#jls-InterfaceMethodDeclaration" title="InterfaceMethodDeclaration">InterfaceMethodDeclaration</a> <br>
<a href="jls-8.html#jls-ClassDeclaration" title="ClassDeclaration">ClassDeclaration</a> <br>
<a href="jls-9.html#jls-InterfaceDeclaration" title="InterfaceDeclaration">InterfaceDeclaration</a> <br>
<code class="literal">;</code>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.1.4-120"></a>The scope
of a declaration of a member <code class="varname">m</code> declared in or inherited by an
interface type <span class="type">I</span> is specified in <a class="xref" href="jls-6.html#jls-6.3" title="6.3.&nbsp;Scope of a Declaration">&sect;6.3</a>.
</p>
</div>
</div>
<div class="section" title="9.2.&nbsp;Interface Members">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.2"></a>9.2.&nbsp;Interface Members
</h2>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.2-100"></a>The members
of an interface type are:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm-static"><a name="jls-9.2-100-A"></a>
Members declared in the body of the interface
(<a class="xref" href="jls-9.html#jls-9.1.4" title="9.1.4.&nbsp;Interface Body and Member Declarations">&sect;9.1.4</a>).
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.2-100-B"></a>
Members inherited from any direct superinterfaces
(<a class="xref" href="jls-9.html#jls-9.1.3" title="9.1.3.&nbsp;Superinterfaces and Subinterfaces">&sect;9.1.3</a>).
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.2-100-C"></a>If an
interface has no direct superinterfaces, then the interface
implicitly declares a <code class="literal">public</code> <code class="literal">abstract</code> member method <code class="varname">m</code> with
signature <span class="type">s</span>, return type <span class="type">r</span>, and
<code class="literal">throws</code> clause <span class="type">t</span> corresponding to each <code class="literal">public</code>
instance method <code class="varname">m</code> with signature <span class="type">s</span>, return
type <span class="type">r</span>, and <code class="literal">throws</code> clause <span class="type">t</span> declared
in <code class="literal">Object</code>, unless an <code class="literal">abstract</code> method with the same
signature, same return type, and a compatible <code class="literal">throws</code> clause is
explicitly declared by the interface.
</p>
<p class="norm-error"><a name="jls-9.2-100-C.1"></a>It is
a compile-time error if the interface explicitly declares such a
method <code class="varname">m</code> in the case where <code class="varname">m</code> is declared to be <code class="literal">final</code> in
<code class="literal">Object</code>.
</p>
<p class="norm-error"><a name="jls-9.2-100-C.2"></a>It is a
compile-time error if the interface explicitly declares a method
with a signature that is override-equivalent
(<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>) to a <code class="literal">public</code> method of <code class="literal">Object</code>,
but which has a different return type, or an incompatible
<code class="literal">throws</code> clause, or is not <code class="literal">abstract</code>.
</p>
</li>
</ul>
</div>
<p class="norm-static"><a name="jls-9.2-110"></a>The interface
inherits, from the interfaces it extends, all members of those
interfaces, except for fields, classes, and interfaces that it hides;
<code class="literal">abstract</code> or default methods that it overrides
(<a class="xref" href="jls-9.html#jls-9.4.1" title="9.4.1.&nbsp;Inheritance and Overriding">&sect;9.4.1</a>); and <code class="literal">static</code> methods.
</p>
<p class="norm-static"><a name="jls-9.2-120"></a>Fields,
methods, and member types of an interface type may have the same name,
since they are used in different contexts and are disambiguated by
different lookup procedures (<a class="xref" href="jls-6.html#jls-6.5" title="6.5.&nbsp;Determining the Meaning of a Name">&sect;6.5</a>). However, this
is discouraged as a matter of style.
</p>
</div>
<div class="section" title="9.3.&nbsp;Field (Constant) Declarations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.3"></a>9.3.&nbsp;Field (Constant) Declarations
</h2>
</div>
</div>
</div>
<div id="jls-9.3-100" class="productionset"><a name="jls-9.3-100"></a>
<div class="production"><a name="jls-ConstantDeclaration"></a>
<div class="lhs">ConstantDeclaration:</div>
<div class="rhs">
{<a href="jls-9.html#jls-ConstantModifier" title="ConstantModifier">ConstantModifier</a>}
<a href="jls-8.html#jls-UnannType" title="UnannType">UnannType</a>
<a href="jls-8.html#jls-VariableDeclaratorList" title="VariableDeclaratorList">VariableDeclaratorList</a> <code class="literal">;</code>
</div>
</div>
<div class="production"><a name="jls-ConstantModifier"></a>
<div class="lhs">ConstantModifier:</div>
<div class="rhs">
<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a> <code class="literal">public</code> <br>
<code class="literal">static</code> <code class="literal">final</code>
</div>
</div>
</div>
<p class="note">See <a class="xref" href="jls-8.html#jls-8.3" title="8.3.&nbsp;Field Declarations">&sect;8.3</a> for
<span class="emphasis"><em>UnannType</em></span>. The following productions from
<a class="xref" href="jls-4.html#jls-4.3" title="4.3.&nbsp;Reference Types and Values">&sect;4.3</a> and <a class="xref" href="jls-8.html#jls-8.3" title="8.3.&nbsp;Field Declarations">&sect;8.3</a> are shown here
for convenience:
</p>
<div id="d5e14970" class="productionset"><a name="d5e14970"></a>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">VariableDeclaratorList:</div>
<div class="rhs">
<a href="jls-8.html#jls-VariableDeclarator" title="VariableDeclarator">VariableDeclarator</a> {<code class="literal">,</code> <a href="jls-8.html#jls-VariableDeclarator" title="VariableDeclarator">VariableDeclarator</a>}
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">VariableDeclarator:</div>
<div class="rhs">
<a href="jls-8.html#jls-VariableDeclaratorId" title="VariableDeclaratorId">VariableDeclaratorId</a> [<code class="literal">=</code> <a href="jls-8.html#jls-VariableInitializer" title="VariableInitializer">VariableInitializer</a>]
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">VariableDeclaratorId:</div>
<div class="rhs">
<a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a> [<a href="jls-4.html#jls-Dims" title="Dims">Dims</a>]
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">Dims:</div>
<div class="rhs">
{<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>} <code class="literal">[</code> <code class="literal">]</code> {{<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>} <code class="literal">[</code> <code class="literal">]</code>}
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">VariableInitializer:</div>
<div class="rhs">
<a href="jls-15.html#jls-Expression" title="Expression">Expression</a> <br>
<a href="jls-10.html#jls-ArrayInitializer" title="ArrayInitializer">ArrayInitializer</a>
</div>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.3-110"></a>The rules for
annotation modifiers on an interface field declaration are specified
in <a class="xref" href="jls-9.html#jls-9.7.4" title="9.7.4.&nbsp;Where Annotations May Appear">&sect;9.7.4</a> and <a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>.
</p>
<p class="norm-static"><a name="jls-9.3-120"></a>Every field
declaration in the body of an interface is implicitly <code class="literal">public</code>,
<code class="literal">static</code>, and <code class="literal">final</code>. It is permitted to redundantly specify any or
all of these modifiers for such fields.
</p>
<p class="note">If two or more (distinct) field modifiers appear in
a field declaration, it is customary, though not required, that they
appear in the order consistent with that shown above in the production
for <span class="emphasis"><em>ConstantModifier</em></span>.
</p>
<p class="norm-error"><a name="jls-9.3-130"></a>It is a
compile-time error if the same keyword appears more than once as a
modifier for a field declaration.
</p>
<p class="norm-error"><a name="jls-9.3-140"></a>It is a
compile-time error for the body of an interface declaration to declare
two fields with the same name.
</p>
<p class="norm-static"><a name="jls-9.3-200"></a>The declared
type of a field is denoted by the <span class="emphasis"><em>UnannType</em></span> that
appears in the field declaration, followed by any bracket pairs that
follow the <span class="emphasis"><em>Identifier</em></span> in the declarator.
</p>
<p class="norm-static"><a name="jls-9.3-300"></a>If the
interface declares a field with a certain name, then the declaration
of that field is said to <span class="emphasis"><em>hide</em></span> any and all
accessible declarations of fields with the same name in
superinterfaces of the interface.
</p>
<p class="norm-error"><a name="jls-9.3-400"></a>It is
possible for an interface to inherit more than one field with the same
name. Such a situation does not in itself cause a compile-time
error. However, any attempt within the body of the interface to refer
to any such field by its simple name will result in a compile-time
error, because such a reference is ambiguous.
</p>
<p class="norm-static"><a name="jls-9.3-410"></a>There might
be several paths by which the same field declaration might be
inherited from an interface. In such a situation, the field is
considered to be inherited only once, and it may be referred to by its
simple name without ambiguity.
</p>
<div class="example"><a name="d5e14994"></a><p class="title"><b>Example&nbsp;9.3-1.&nbsp;Ambiguous Inherited Fields</b></p>
<div class="example-contents">
<p class="note">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:
</p><pre class="programlisting">
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;
}
</pre><p class="note">the interface <code class="literal">LotsOfColors</code>
inherits two fields named <code class="literal">YELLOW</code>. This is all right
as long as the interface does not contain any reference by simple name
to the field <code class="literal">YELLOW</code>. (Such a reference could occur
within a variable initializer for a field.)
</p>
<p class="note">Even if interface <code class="literal">PrintColors</code>
were to give the value <code class="literal">3</code>
to <code class="literal">YELLOW</code> rather than the
value <code class="literal">8</code>, a reference to
field <code class="literal">YELLOW</code> within
interface <code class="literal">LotsOfColors</code> would still be considered
ambiguous.
</p>
</div>
</div><br class="example-break"><div class="example"><a name="d5e15009"></a><p class="title"><b>Example&nbsp;9.3-2.&nbsp;Multiply Inherited Fields</b></p>
<div class="example-contents">
<p class="note">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.
</p>
<p class="note">In the previous example, the
fields <code class="literal">RED</code>, <code class="literal">GREEN</code>,
and <code class="literal">BLUE</code> are inherited by
interface <code class="literal">LotsOfColors</code> in more than one way,
through interface <code class="literal">RainbowColors</code> and also through
interface <code class="literal">PrintColors</code>, but the reference to
field <code class="literal">RED</code> in
interface <code class="literal">LotsOfColors</code> is not considered ambiguous
because only one actual declaration of the
field <code class="literal">RED</code> is involved.
</p>
</div>
</div><br class="example-break"><div class="section" title="9.3.1.&nbsp;Initialization of Fields in Interfaces">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.3.1"></a>9.3.1.&nbsp;Initialization of Fields in Interfaces
</h3>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.3.1-100"></a>Every
declarator in a field declaration of an interface must have a variable
initializer, or a compile-time error occurs.
</p>
<p class="norm-static"><a name="jls-9.3.1-110"></a>The
initializer need not be a constant expression
(<a class="xref" href="jls-15.html#jls-15.28" title="15.28.&nbsp;Constant Expressions">&sect;15.28</a>).
</p>
<p class="norm-error"><a name="jls-9.3.1-200"></a>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
textually later in the same interface.
</p>
<p class="norm-error"><a name="jls-9.3.1-210"></a>It is a
compile-time error if the keyword <code class="literal">this</code>
(<a class="xref" href="jls-15.html#jls-15.8.3" title="15.8.3.&nbsp;this">&sect;15.8.3</a>) or the keyword <code class="literal">super</code>
(<a class="xref" href="jls-15.html#jls-15.11.2" title="15.11.2.&nbsp;Accessing Superclass Members using super">&sect;15.11.2</a>, <a class="xref" href="jls-15.html#jls-15.12" title="15.12.&nbsp;Method Invocation Expressions">&sect;15.12</a>) occurs in
the initializer of an interface field, unless the occurrence is within
the body of an anonymous class (<a class="xref" href="jls-15.html#jls-15.9.5" title="15.9.5.&nbsp;Anonymous Class Declarations">&sect;15.9.5</a>).
</p>
<p class="norm-dynamic"><a name="jls-9.3.1-300"></a>At run
time, the initializer is evaluated and the field assignment performed
exactly once, when the interface is initialized
(<a class="xref" href="jls-12.html#jls-12.4.2" title="12.4.2.&nbsp;Detailed Initialization Procedure">&sect;12.4.2</a>).
</p>
<p class="norm-dynamic"><a name="jls-9.3.1-310"></a>Note that
interface fields that are constant variables (<a class="xref" href="jls-4.html#jls-4.12.4" title="4.12.4.&nbsp;final Variables">&sect;4.12.4</a>) are
initialized before other interface fields. This also applies to
<code class="literal">static</code> fields that are constant variables in classes
(<a class="xref" href="jls-8.html#jls-8.3.2" title="8.3.2.&nbsp;Field Initialization">&sect;8.3.2</a>). Such fields
will never be observed to have their default initial values
(<a class="xref" href="jls-4.html#jls-4.12.5" title="4.12.5.&nbsp;Initial Values of Variables">&sect;4.12.5</a>), even by devious programs.
</p>
<div class="example"><a name="d5e15042"></a><p class="title"><b>Example&nbsp;9.3.1-1.&nbsp;Forward Reference to a Field</b></p>
<div class="example-contents"><pre class="programlisting">
interface Test {
float f = j;
int j = 1;
int k = k + 1;
}
</pre><p class="note">This program causes two compile-time errors,
because <code class="literal">j</code> is referred to in the initialization
of <code class="literal">f</code> before <code class="literal">j</code> is declared, and
because the initialization of <code class="literal">k</code> refers
to <code class="literal">k</code> itself.
</p>
</div>
</div><br class="example-break"></div>
</div>
<div class="section" title="9.4.&nbsp;Method Declarations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.4"></a>9.4.&nbsp;Method Declarations
</h2>
</div>
</div>
</div>
<div id="jls-9.4-100" class="productionset"><a name="jls-9.4-100"></a>
<div class="production"><a name="jls-InterfaceMethodDeclaration"></a>
<div class="lhs">InterfaceMethodDeclaration:</div>
<div class="rhs">
{<a href="jls-9.html#jls-InterfaceMethodModifier" title="InterfaceMethodModifier">InterfaceMethodModifier</a>}
<a href="jls-8.html#jls-MethodHeader" title="MethodHeader">MethodHeader</a>
<a href="jls-8.html#jls-MethodBody" title="MethodBody">MethodBody</a>
</div>
</div>
<div class="production"><a name="jls-InterfaceMethodModifier"></a>
<div class="lhs">InterfaceMethodModifier:</div>
<div class="rhs">
<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a> <code class="literal">public</code> <br>
<code class="literal">abstract</code> <code class="literal">default</code> <code class="literal">static</code> <code class="literal">strictfp</code>
</div>
</div>
</div>
<p class="note">The following productions from
<a class="xref" href="jls-8.html#jls-8.4" title="8.4.&nbsp;Method Declarations">&sect;8.4</a>, <a class="xref" href="jls-8.html#jls-8.4.5" title="8.4.5.&nbsp;Method Result">&sect;8.4.5</a>, and
<a class="xref" href="jls-8.html#jls-8.4.7" title="8.4.7.&nbsp;Method Body">&sect;8.4.7</a> are shown here for convenience:
</p>
<div id="d5e15073" class="productionset"><a name="d5e15073"></a>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">MethodHeader:</div>
<div class="rhs">
<a href="jls-8.html#jls-Result" title="Result">Result</a> <a href="jls-8.html#jls-MethodDeclarator" title="MethodDeclarator">MethodDeclarator</a> [<a href="jls-8.html#jls-Throws" title="Throws">Throws</a>] <br>
<a href="jls-8.html#jls-TypeParameters" title="TypeParameters">TypeParameters</a> {<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>}
<a href="jls-8.html#jls-Result" title="Result">Result</a> <a href="jls-8.html#jls-MethodDeclarator" title="MethodDeclarator">MethodDeclarator</a> [<a href="jls-8.html#jls-Throws" title="Throws">Throws</a>]
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">Result:</div>
<div class="rhs">
<a href="jls-8.html#jls-UnannType" title="UnannType">UnannType</a> <br>
<code class="literal">void</code>
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">MethodDeclarator:</div>
<div class="rhs">
<a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a>
<code class="literal">(</code> [<a href="jls-8.html#jls-FormalParameterList" title="FormalParameterList">FormalParameterList</a>] <code class="literal">)</code>
[<a href="jls-4.html#jls-Dims" title="Dims">Dims</a>]
</div>
</div>
</div>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">MethodBody:</div>
<div class="rhs">
<a href="jls-14.html#jls-Block" title="Block">Block</a> <br>
<code class="literal">;</code>
</div>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.4-110"></a>The rules for
annotation modifiers on an interface method declaration are specified
in <a class="xref" href="jls-9.html#jls-9.7.4" title="9.7.4.&nbsp;Where Annotations May Appear">&sect;9.7.4</a> and <a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>.
</p>
<p class="norm-static"><a name="jls-9.4-120"></a>Every method
declaration in the body of an interface is implicitly <code class="literal">public</code>
(<a class="xref" href="jls-6.html#jls-6.6" title="6.6.&nbsp;Access Control">&sect;6.6</a>). It is permitted, but discouraged as a
matter of style, to redundantly specify the <code class="literal">public</code> modifier for a
method declaration in an interface.
</p>
<p class="norm-static"><a name="jls-9.4-200"></a>A
<span class="emphasis"><em>default method</em></span> is a method that is declared in an
interface with the <code class="literal">default</code> modifier; its body is always represented
by a block. It provides a default implementation for any class that
implements the interface without overriding the method. Default
methods are distinct from concrete methods
(<a class="xref" href="jls-8.html#jls-8.4.3.1" title="8.4.3.1.&nbsp;abstract Methods">&sect;8.4.3.1</a>), which are declared in classes.
</p>
<p class="norm-static"><a name="jls-9.4-210"></a>An interface can
declare <code class="literal">static</code> methods, which are invoked without reference to a
particular object.
</p>
<p class="norm-error"><a name="jls-9.4-220"></a>It is a
compile-time error to use the name of a type parameter of any
surrounding declaration in the header or body of a <code class="literal">static</code> method of
an interface.
</p>
<p class="norm-dynamic"><a name="jls-9.4-230"></a>The effect of the
<code class="literal">strictfp</code> modifier is to make all <code class="literal">float</code> or <code class="literal">double</code> expressions
within the body of a default or <code class="literal">static</code> method be explicitly
FP-strict (<a class="xref" href="jls-15.html#jls-15.4" title="15.4.&nbsp;FP-strict Expressions">&sect;15.4</a>).
</p>
<p class="norm-static"><a name="jls-9.4-240"></a>An interface
method lacking a <code class="literal">default</code> modifier or a <code class="literal">static</code> modifier is
implicitly <code class="literal">abstract</code>, so its body is represented by a semicolon, not
a block. It is permitted, but discouraged as a matter of style, to
redundantly specify the <code class="literal">abstract</code> modifier for such a method
declaration.
</p>
<p class="norm-error"><a name="jls-9.4-300"></a>It is a
compile-time error if the same keyword appears more than once as a
modifier for a method declaration in an interface.
</p>
<p class="norm-error"><a name="jls-9.4-310"></a>It is a
compile-time error if a method is declared with more than one of the
modifiers <code class="literal">abstract</code>, <code class="literal">default</code>, or <code class="literal">static</code>.
</p>
<p class="norm-error"><a name="jls-9.4-320"></a>It is a
compile-time error if an <code class="literal">abstract</code> method declaration contains the
keyword <code class="literal">strictfp</code>.
</p>
<p class="norm-error"><a name="jls-9.4-400"></a>It is a
compile-time error for the body of an interface to declare, explicitly
or implicitly, two methods with override-equivalent signatures
(<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>). However, an interface may inherit
several <code class="literal">abstract</code> methods with such signatures
(<a class="xref" href="jls-9.html#jls-9.4.1" title="9.4.1.&nbsp;Inheritance and Overriding">&sect;9.4.1</a>).
</p>
<p class="norm-static"><a name="jls-9.4-500"></a>A method in
an interface may be generic. The rules for type parameters of a
generic method in an interface are the same as for a generic method in
a class (<a class="xref" href="jls-8.html#jls-8.4.4" title="8.4.4.&nbsp;Generic Methods">&sect;8.4.4</a>).
</p>
<div class="section" title="9.4.1.&nbsp;Inheritance and Overriding">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.4.1"></a>9.4.1.&nbsp;Inheritance and Overriding
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.4.1-100"></a>An interface <span class="type">I</span>
<span class="emphasis"><em>inherits</em></span> from its direct superinterfaces all
<code class="literal">abstract</code> and default methods <code class="varname">m</code> for which all of the following are
true:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm-static"><a name="jls-9.4.1-100-A"></a>
<code class="varname">m</code> is a member of a direct superinterface, <span class="type">J</span>, of <span class="type">I</span>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.4.1-100-B"></a>
No method declared in <span class="type">I</span> has a signature that is a subsignature
(<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>) of the signature of <code class="varname">m</code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.4.1-100-C"></a>
There exists no method <code class="varname">m</code>' that is a member of a direct
superinterface, <span class="type">J</span>', of <span class="type">I</span> (<code class="varname">m</code> distinct from <code class="varname">m</code>', <span class="type">J</span>
distinct from <span class="type">J</span>'), such that <code class="varname">m</code>' overrides from <span class="type">J</span>' the
declaration of the method <code class="varname">m</code>.
</p>
</li>
</ul>
</div>
<p class="note">Note that methods are overridden on a
signature-by-signature basis. If, for example, an interface declares
two <code class="literal">public</code> methods with the same name (<a class="xref" href="jls-9.html#jls-9.4.2" title="9.4.2.&nbsp;Overloading">&sect;9.4.2</a>),
and a subinterface overrides one of them, the subinterface still
inherits the other method.
</p>
<p class="note">
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:
</p><pre class="screen">
interface I {
default String name() { return "unnamed"; }
}
interface J extends I {
default String name() { return getClass().getName(); }
}
interface K extends I {}
interface Child extends J, K {}
</pre><p class="note"><code class="literal">K</code>
inherits <code class="literal">name()</code> from <code class="literal">I</code>,
but <code class="literal">Child</code> inherits <code class="literal">name()</code> from
<code class="literal">J</code>, not <code class="literal">K</code>. This is
because <code class="literal">name()</code> from <code class="literal">J</code>
overrides <code class="literal">I.name()</code>.
</p>
<p class="norm-static"><a name="jls-9.4.1-200"></a>An interface does
not inherit <code class="literal">static</code> methods from its superinterfaces.
</p>
<p class="norm-error"><a name="jls-9.4.1-210"></a>If an interface
<span class="type">I</span> declares a <code class="literal">static</code> method <code class="varname">m</code>, and the signature of <code class="varname">m</code> is a
subsignature of an instance method <code class="varname">m</code>' in a superinterface of <span class="type">I</span>,
and <code class="varname">m</code>' would otherwise be accessible to code in <span class="type">I</span>, then a
compile-time error occurs.
</p>
<p class="note">
In essence, a <code class="literal">static</code> method in an interface cannot "hide" an
instance method in a superinterface. This is similar to the rule in
<a class="xref" href="jls-8.html#jls-8.4.8.2" title="8.4.8.2.&nbsp;Hiding (by Class Methods)">&sect;8.4.8.2</a> whereby a <code class="literal">static</code> method in a class
cannot hide an instance method in a superclass or superinterface. Note
that the rule in <a class="xref" href="jls-8.html#jls-8.4.8.2" title="8.4.8.2.&nbsp;Hiding (by Class Methods)">&sect;8.4.8.2</a> speaks of a class that
"declares or inherits a <code class="literal">static</code> method", whereas the rule above
speaks only of an interface that "declares a <code class="literal">static</code> method", since
an interface cannot inherit a <code class="literal">static</code> method. Also note that the rule
in <a class="xref" href="jls-8.html#jls-8.4.8.2" title="8.4.8.2.&nbsp;Hiding (by Class Methods)">&sect;8.4.8.2</a> allows hiding of both instance and
<code class="literal">static</code> methods in superclasses/superinterfaces, whereas the rule
above considers only instance methods in superinterfaces.
</p>
<div class="section" title="9.4.1.1.&nbsp;Overriding (by Instance Methods)">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.4.1.1"></a>9.4.1.1.&nbsp;Overriding (by Instance Methods)
</h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.4.1.1-100"></a>An instance
method <code class="varname">m<sub>1</sub></code>, declared in or inherited by an interface
<span class="type">I</span>, <span class="emphasis"><em>overrides from <span class="type">I</span></em></span> another instance method,
<code class="varname">m<sub>2</sub></code>, declared in interface <span class="type">J</span>, iff both of the following are
true:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm-static"><a name="jls-9.4.1.1-100-A"></a><span class="type">I</span>
is a subinterface of <span class="type">J</span>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.4.1.1-100-B"></a>The
signature of <code class="varname">m<sub>1</sub></code> is a subsignature
(<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>) of the signature of <code class="varname">m<sub>2</sub></code>.
</p>
</li>
</ul>
</div>
<p class="norm-static"><a name="jls-9.4.1.1-200"></a>The presence or
absence of the <code class="literal">strictfp</code> 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.
</p>
<p class="note">An overridden default method can be accessed by
using a method invocation expression (<a class="xref" href="jls-15.html#jls-15.12" title="15.12.&nbsp;Method Invocation Expressions">&sect;15.12</a>)
that contains the keyword <code class="literal">super</code> qualified by a superinterface
name.
</p>
</div>
<div class="section" title="9.4.1.2.&nbsp;Requirements in Overriding">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.4.1.2"></a>9.4.1.2.&nbsp;Requirements in Overriding
</h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.4.1.2-100"></a>The
relationship between the return type of an interface method and the
return types of any overridden interface methods is specified in
<a class="xref" href="jls-8.html#jls-8.4.8.3" title="8.4.8.3.&nbsp;Requirements in Overriding and Hiding">&sect;8.4.8.3</a>.
</p>
<p class="norm-static"><a name="jls-9.4.1.2-200"></a>The
relationship between the <code class="literal">throws</code> clause of an interface method and
the <code class="literal">throws</code> clauses of any overridden interface methods are specified
in <a class="xref" href="jls-8.html#jls-8.4.8.3" title="8.4.8.3.&nbsp;Requirements in Overriding and Hiding">&sect;8.4.8.3</a>.
</p>
<p class="norm-static"><a name="jls-9.4.1.2-300"></a>The
relationship between the signature of an interface method and the
signatures of overridden interface methods are specified in
<a class="xref" href="jls-8.html#jls-8.4.8.3" title="8.4.8.3.&nbsp;Requirements in Overriding and Hiding">&sect;8.4.8.3</a>.
</p>
<p class="norm-error"><a name="jls-9.4.1.2-400"></a>It is a
compile-time error if a default method is override-equivalent with a
non-<code class="literal">private</code> method of the class <code class="literal">Object</code>, because any class
implementing the interface will inherit its own implementation of the
method.
</p>
<p class="note">The prohibition against declaring one of the
<code class="literal">Object</code> methods as a default method may be surprising. There are,
after all, cases like <code class="literal">java.util.List</code> in which the
behavior of <code class="literal">toString</code> and <code class="literal">equals</code>
are precisely defined. The motivation becomes clearer, however, when
some broader design decisions are understood:
</p>
<div class="note">
<ul class="note" type="disc">
<li class="listitem">
<p class="note">First, methods inherited from a superclass are
allowed to override methods inherited from superinterfaces
(<a class="xref" href="jls-8.html#jls-8.4.8.1" title="8.4.8.1.&nbsp;Overriding (by Instance Methods)">&sect;8.4.8.1</a>). So, every implementing class
would automatically override an interface's
<code class="literal">toString</code> default. This is longstanding
behavior in the Java programming language. It is not something we wish to
change with the design of default methods, because that would
conflict with the goal of allowing interfaces to unobtrusively
evolve, only providing default behavior when a class doesn't
already have it through the class hierarchy.
</p>
</li>
<li class="listitem">
<p class="note">Second, interfaces do <span class="emphasis"><em>not</em></span>
inherit from <code class="literal">Object</code>, but rather implicitly declare many of the
same methods as <code class="literal">Object</code> (<a class="xref" href="jls-9.html#jls-9.2" title="9.2.&nbsp;Interface Members">&sect;9.2</a>). So, there
is no common ancestor for the <code class="literal">toString</code>
declared in <code class="literal">Object</code> and the <code class="literal">toString</code>
declared in an interface. At best, if both were candidates for
inheritance by a class, they would conflict. Working around this
problem would require awkward commingling of the class and
interface inheritance trees.
</p>
</li>
<li class="listitem">
<p class="note">Third, use cases for declaring <code class="literal">Object</code> methods
in interfaces typically assume a linear interface hierarchy; the
feature does not generalize very well to multiple inheritance
scenarios.
</p>
</li>
<li class="listitem">
<p class="note">Fourth, the <code class="literal">Object</code> methods are so fundamental
that it seems dangerous to allow an arbitrary superinterface to
silently add a default method that changes their
behavior.
</p>
</li>
</ul>
</div>
<p class="note">An interface is free, however, to define another
method that provides behavior useful for classes that override the
<code class="literal">Object</code> methods. For example, the <code class="literal">java.util.List</code>
interface could declare an <code class="literal">elementString</code> method
that produces the string described by the contract
of <code class="literal">toString</code>; implementors
of <code class="literal">toString</code> in classes could then delegate to this
method.
</p>
</div>
<div class="section" title="9.4.1.3.&nbsp;Inheriting Methods with Override-Equivalent Signatures">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.4.1.3"></a>9.4.1.3.&nbsp;Inheriting Methods with Override-Equivalent Signatures
</h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.4.1.3-100"></a>It is
possible for an interface to inherit several methods with
override-equivalent signatures (<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>).
</p>
<p class="norm-error"><a name="jls-9.4.1.3-110"></a>If an interface
<span class="type">I</span> inherits a default method whose signature is override-equivalent
with another method inherited by <span class="type">I</span>, then a compile-time error
occurs. (This is the case whether the other method is <code class="literal">abstract</code> or
<code class="literal">default</code>.)
</p>
<p class="norm-static"><a name="jls-9.4.1.3-120"></a>Otherwise, all
the inherited methods are <code class="literal">abstract</code>, and the interface is considered
to inherit all the methods.
</p>
<p class="norm-error"><a name="jls-9.4.1.3-200"></a>One of
the inherited methods must be return-type-substitutable for every
other inherited method, or else a compile-time error occurs. (The
<code class="literal">throws</code> clauses do not cause errors in this case.)
</p>
<p class="norm-static"><a name="jls-9.4.1.3-300"></a>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.
</p>
<p class="note">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
developer 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.
</p>
<p class="note">Similarly, when an abstract and a default method
with matching signatures are inherited, 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, too. 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).
</p>
<p class="note">In contrast, the longstanding behavior for inherited
concrete methods in classes is that they override abstract methods
declared in interfaces (see <a class="xref" href="jls-8.html#jls-8.4.8" title="8.4.8.&nbsp;Inheritance, Overriding, and Hiding">&sect;8.4.8</a>). 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.
</p>
</div>
</div>
<div class="section" title="9.4.2.&nbsp;Overloading">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.4.2"></a>9.4.2.&nbsp;Overloading
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.4.2-100"></a>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 (<a class="xref" href="jls-8.html#jls-8.4.2" title="8.4.2.&nbsp;Method Signature">&sect;8.4.2</a>), then the method
name is said to be <span class="emphasis"><em>overloaded</em></span>.
</p>
<p class="norm"><a name="jls-9.4.2-110"></a>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
<code class="literal">throws</code> clauses of two methods with the same name but different
signatures that are not override-equivalent.
</p>
<div class="example"><a name="d5e15282"></a><p class="title"><b>Example&nbsp;9.4.2-1.&nbsp;Overloading an <code class="literal">abstract</code> Method Declaration</b></p>
<div class="example-contents"><pre class="programlisting">
interface PointInterface {
void move(int dx, int dy);
}
interface RealPointInterface extends PointInterface {
void move(float dx, float dy);
void move(double dx, double dy);
}
</pre><p class="note">Here, the method named <code class="literal">move</code> is
overloaded in interface <code class="literal">RealPointInterface</code> with
three different signatures, two of them declared and one
inherited. Any non-<code class="literal">abstract</code> class that implements
interface <code class="literal">RealPointInterface</code> must provide
implementations of all three method signatures.
</p>
</div>
</div><br class="example-break"></div>
<div class="section" title="9.4.3.&nbsp;Interface Method Body">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.4.3"></a>9.4.3.&nbsp;Interface Method Body
</h3>
</div>
</div>
</div>
<p class="norm"><a name="jls-9.4.3-100"></a>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.
</p>
<p class="norm"><a name="jls-9.4.3-110"></a>A <code class="literal">static</code> method also has a
block body, which provides the implementation of the method.
</p>
<p class="norm-error"><a name="jls-9.4.3-200"></a>It is a
compile-time error if an interface method declaration is <code class="literal">abstract</code>
(explicitly or implicitly) and has a block for its body.
</p>
<p class="norm-error"><a name="jls-9.4.3-210"></a>It is a
compile-time error if an interface method declaration is <code class="literal">default</code> or
<code class="literal">static</code> and has a semicolon for its body.
</p>
<p class="norm-error"><a name="jls-9.4.3-300"></a>It is a
compile-time error for the body of a <code class="literal">static</code> method to attempt to
reference the current object using the keyword <code class="literal">this</code> or the keyword
<code class="literal">super</code>.
</p>
<p class="norm-error"><a name="jls-9.4.3-310"></a>The rules
for <code class="literal">return</code> statements in a method body are specified in
<a class="xref" href="jls-14.html#jls-14.17" title="14.17.&nbsp;The return Statement">&sect;14.17</a>.
</p>
<p class="norm-error"><a name="jls-9.4.3-320"></a>If a method
is declared to have a return type (<a class="xref" href="jls-8.html#jls-8.4.5" title="8.4.5.&nbsp;Method Result">&sect;8.4.5</a>), then
a compile-time error occurs if the body of the method can complete
normally (<a class="xref" href="jls-14.html#jls-14.1" title="14.1.&nbsp;Normal and Abrupt Completion of Statements">&sect;14.1</a>).
</p>
</div>
</div>
<div class="section" title="9.5.&nbsp;Member Type Declarations">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.5"></a>9.5.&nbsp;Member Type Declarations
</h2>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.5-100"></a>Interfaces
may contain member type declarations (<a class="xref" href="jls-8.html#jls-8.5" title="8.5.&nbsp;Member Type Declarations">&sect;8.5</a>).
</p>
<p class="norm-static"><a name="jls-9.5-110"></a>A member type declaration in an
interface is implicitly <code class="literal">public</code> and <code class="literal">static</code>. It is permitted to
redundantly specify either or both of these modifiers.
</p>
<p class="norm-error"><a name="jls-9.5-120"></a>It is a
compile-time error if a member type declaration in an interface has
the modifier <code class="literal">protected</code> or <code class="literal">private</code>.
</p>
<p class="norm-error"><a name="jls-9.5-130"></a>It is a
compile-time error if the same keyword appears more than once as a
modifier for a member type declaration in an interface.
</p>
<p class="norm-static"><a name="jls-9.5-200"></a>If an interface declares a member
type with a certain name, then the declaration of
that type is said
to <span class="emphasis"><em>hide</em></span> any and all accessible declarations of
member types with the same name in superinterfaces of the
interface.
</p>
<p class="norm-static"><a name="jls-9.5-300"></a>An interface
inherits from its direct superinterfaces all the non-<code class="literal">private</code> member
types of the superinterfaces that are both accessible to code in the
interface and not hidden by a declaration in the interface.
</p>
<p class="norm-error"><a name="jls-9.5-310"></a>An interface
may inherit two or more type declarations with the same name. It is a
compile-time error to attempt to refer to any ambiguously inherited
class or interface by its simple name.
</p>
<p class="norm-static"><a name="jls-9.5-320"></a>If the same
type declaration is inherited from an interface by multiple paths, the
class or interface is considered to be inherited only once; it may be
referred to by its simple name without ambiguity.
</p>
</div>
<div class="section" title="9.6.&nbsp;Annotation Types">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="jls-9.6"></a>9.6.&nbsp;Annotation Types
</h2>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6-100"></a>An
<span class="emphasis"><em>annotation type declaration</em></span> specifies a
new <span class="emphasis"><em>annotation type</em></span>, a special kind of interface
type. To distinguish an annotation type declaration from a normal
interface declaration, the keyword <code class="literal">interface</code> is preceded by an
at-sign (<code class="literal">@</code>).
</p>
<div id="jls-9.6-110" class="productionset"><a name="jls-9.6-110"></a>
<div class="production"><a name="jls-AnnotationTypeDeclaration"></a>
<div class="lhs">AnnotationTypeDeclaration:</div>
<div class="rhs">
{<a href="jls-9.html#jls-InterfaceModifier" title="InterfaceModifier">InterfaceModifier</a>}
<code class="literal">@</code> <code class="literal">interface</code> <a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a>
<a href="jls-9.html#jls-AnnotationTypeBody" title="AnnotationTypeBody">AnnotationTypeBody</a>
</div>
</div>
</div>
<p class="note">Note that the at-sign (<code class="literal">@</code>) and the keyword
<code class="literal">interface</code> are distinct tokens. It is possible to separate them with
whitespace, but this is discouraged as a matter of style.
</p>
<p class="norm-error"><a name="jls-9.6-120"></a>The rules for
annotation modifiers on an annotation type declaration are specified
in <a class="xref" href="jls-9.html#jls-9.7.4" title="9.7.4.&nbsp;Where Annotations May Appear">&sect;9.7.4</a> and <a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>.
</p>
<p class="norm-static"><a name="jls-9.6-200"></a>The
<span class="emphasis"><em>Identifier</em></span> in an annotation type declaration specifies the name of
the annotation type.
</p>
<p class="norm-error"><a name="jls-9.6-210"></a>It is a
compile-time error if an annotation type has the same simple name as
any of its enclosing classes or interfaces.
</p>
<p class="norm-static"><a name="jls-9.6-300"></a>The direct
superinterface of every annotation type is <code class="literal">java.lang.annotation.Annotation</code>.
</p>
<p class="note">By virtue of
the <span class="emphasis"><em>AnnotationTypeDeclaration</em></span> syntax, an
annotation type declaration cannot be generic, and no <code class="literal">extends</code> clause
is permitted.
</p>
<p class="note">A consequence of the fact that an annotation type
cannot explicitly declare a superclass or superinterface is that a
subclass or subinterface of an annotation type is never itself an
annotation type. Similarly, <code class="literal">java.lang.annotation.Annotation</code> is not itself an annotation
type.
</p>
<p class="norm-static"><a name="jls-9.6-310"></a>An
annotation type inherits several members from <code class="literal">java.lang.annotation.Annotation</code>, including
the implicitly declared methods corresponding to the instance methods
of <code class="literal">Object</code>, yet these methods do not define elements of the
annotation type (<a class="xref" href="jls-9.html#jls-9.6.1" title="9.6.1.&nbsp;Annotation Type Elements">&sect;9.6.1</a>).
</p>
<p class="note">Because these methods do not define elements of the
annotation type, it is illegal to use them in annotations of that type
(<a class="xref" href="jls-9.html#jls-9.7" title="9.7.&nbsp;Annotations">&sect;9.7</a>). Without this rule, we could not ensure
that elements were of the types representable in annotations, or that
accessor methods for them would be available.
</p>
<p class="norm-static"><a name="jls-9.6-320"></a>Unless
explicitly modified herein, all of the rules that apply to normal
interface declarations apply to annotation type declarations.
</p>
<p class="note">For example, annotation types share the same
namespace as normal class and interface types; and annotation type
declarations are legal wherever interface declarations are legal, and
have the same scope and accessibility.
</p>
<div class="section" title="9.6.1.&nbsp;Annotation Type Elements">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.6.1"></a>9.6.1.&nbsp;Annotation Type Elements
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.1-100"></a>The body
of an annotation type may contain method declarations, each of which
defines an <span class="emphasis"><em>element</em></span> of the annotation type. An
annotation type has no elements other than those defined by the
methods it explicitly declares.
</p>
<div id="jls-9.6.1-120" class="productionset"><a name="jls-9.6.1-120"></a>
<div class="production"><a name="jls-AnnotationTypeBody"></a>
<div class="lhs">AnnotationTypeBody:</div>
<div class="rhs">
<code class="literal">{</code>
{<a href="jls-9.html#jls-AnnotationTypeMemberDeclaration" title="AnnotationTypeMemberDeclaration">AnnotationTypeMemberDeclaration</a>}
<code class="literal">}</code>
</div>
</div>
<div class="production"><a name="jls-AnnotationTypeMemberDeclaration"></a>
<div class="lhs">AnnotationTypeMemberDeclaration:</div>
<div class="rhs">
<a href="jls-9.html#jls-AnnotationTypeElementDeclaration" title="AnnotationTypeElementDeclaration">AnnotationTypeElementDeclaration</a> <br>
<a href="jls-9.html#jls-ConstantDeclaration" title="ConstantDeclaration">ConstantDeclaration</a> <br>
<a href="jls-8.html#jls-ClassDeclaration" title="ClassDeclaration">ClassDeclaration</a> <br>
<a href="jls-9.html#jls-InterfaceDeclaration" title="InterfaceDeclaration">InterfaceDeclaration</a> <br>
<code class="literal">;</code>
</div>
</div>
<div class="production"><a name="jls-AnnotationTypeElementDeclaration"></a>
<div class="lhs">AnnotationTypeElementDeclaration:</div>
<div class="rhs">
{<a href="jls-9.html#jls-AnnotationTypeElementModifier" title="AnnotationTypeElementModifier">AnnotationTypeElementModifier</a>}
<a href="jls-8.html#jls-UnannType" title="UnannType">UnannType</a> <a href="jls-3.html#jls-Identifier" title="Identifier">Identifier</a>
<code class="literal">(</code> <code class="literal">)</code> [<a href="jls-4.html#jls-Dims" title="Dims">Dims</a>]
[<a href="jls-9.html#jls-DefaultValue" title="DefaultValue">DefaultValue</a>] <code class="literal">;</code>
</div>
</div>
<div class="production"><a name="jls-AnnotationTypeElementModifier"></a>
<div class="lhs">AnnotationTypeElementModifier:</div>
<div class="rhs">
<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a> <code class="literal">public</code> <br>
<code class="literal">abstract</code>
</div>
</div>
</div>
<p class="note">By virtue of
the <span class="emphasis"><em>AnnotationTypeElementDeclaration</em></span> production,
a method declaration in an annotation type declaration cannot have
formal parameters, type parameters, or a <code class="literal">throws</code> clause. The
following production from <a class="xref" href="jls-4.html#jls-4.3" title="4.3.&nbsp;Reference Types and Values">&sect;4.3</a> is shown here for
convenience:
</p>
<div id="d5e15409" class="productionset"><a name="d5e15409"></a>
<div class="productionrecap-note">
<div class="production">
<div class="lhs">Dims:</div>
<div class="rhs">
{<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>} <code class="literal">[</code> <code class="literal">]</code> {{<a href="jls-9.html#jls-Annotation" title="Annotation">Annotation</a>} <code class="literal">[</code> <code class="literal">]</code>}
</div>
</div>
</div>
</div>
<p class="note">
By virtue of the <span class="emphasis"><em>AnnotationTypeElementModifier</em></span>
production, a method declaration in an annotation type declaration
cannot be <code class="literal">default</code> or <code class="literal">static</code>. Thus, an annotation type cannot
declare the same variety of methods as a normal interface type. Note
that it is still possible for an annotation type to inherit a default
method from its implicit superinterface, <code class="literal">java.lang.annotation.Annotation</code>, though no such
default method exists as of Java SE 8.
</p>
<p class="note">By convention, the only
<span class="emphasis"><em>AnnotationTypeElementModifier</em></span>s that should be
present on an annotation type element are annotations.
</p>
<p class="norm-error"><a name="jls-9.6.1-200"></a>The return
type of a method declared in an annotation type must be one of the
following, or a compile-time error occurs:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-A"></a>A primitive type
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-B"></a><code class="literal">String</code></p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-C"></a><code class="literal">Class</code> or an
invocation of <code class="literal">Class</code> (<a class="xref" href="jls-4.html#jls-4.5" title="4.5.&nbsp;Parameterized Types">&sect;4.5</a>)
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-D"></a>An enum type
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-E"></a>An annotation type
</p>
</li>
<li class="listitem">
<p class="norm"><a name="jls-9.6.1-200-F"></a>
An array type whose component type is one of the preceding types
(<a class="xref" href="jls-10.html#jls-10.1" title="10.1.&nbsp;Array Types">&sect;10.1</a>).
</p>
</li>
</ul>
</div>
<div class="informalexample">
<p class="note">This rule precludes elements with nested array
types, such as:
</p><pre class="programlisting">
@interface Verboten {
String[][] value();
}
</pre></div>
<p class="norm-static"><a name="jls-9.6.1-210"></a>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.
</p>
<p class="norm-error"><a name="jls-9.6.1-220"></a>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 <code class="literal">public</code> or
<code class="literal">protected</code> method declared in class <code class="literal">Object</code> or in the interface
<code class="literal">java.lang.annotation.Annotation</code>.
</p>
<p class="norm-error"><a name="jls-9.6.1-230"></a>It is a
compile-time error if an annotation type declaration <span class="type">T</span> contains an
element of type <span class="type">T</span>, either directly or indirectly.
</p>
<div class="informalexample">
<p class="note">For example, this is illegal:</p><pre class="programlisting">
@interface SelfRef { SelfRef value(); }
</pre><p class="note">and so is this:</p><pre class="programlisting">
@interface Ping { Pong value(); }
@interface Pong { Ping value(); }
</pre></div>
<p class="norm-static"><a name="jls-9.6.1-300"></a>An
annotation type with no elements is called a <span class="emphasis"><em>marker
annotation type</em></span>.
</p>
<p class="norm-static"><a name="jls-9.6.1-310"></a>An
annotation type with one element is called a <span class="emphasis"><em>single-element
annotation type</em></span>.
</p>
<p class="norm-static"><a name="jls-9.6.1-320"></a>By
convention, the name of the sole element in a single-element
annotation type is <code class="literal">value</code>. Linguistic support for
this convention is provided by single-element annotations
(<a class="xref" href="jls-9.html#jls-9.7.3" title="9.7.3.&nbsp;Single-Element Annotations">&sect;9.7.3</a>).
</p>
<div class="example"><a name="d5e15461"></a><p class="title"><b>Example&nbsp;9.6.1-1.&nbsp;Annotation Type Declaration</b></p>
<div class="example-contents">
<p class="note">The following annotation type declaration defines an
annotation type with several elements:
</p><pre class="programlisting">
/**
* 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
}
</pre></div>
</div><br class="example-break"><div class="example"><a name="d5e15465"></a><p class="title"><b>Example&nbsp;9.6.1-2.&nbsp;Marker Annotation Type Declaration</b></p>
<div class="example-contents">
<p class="note">The following annotation type declaration defines a
marker annotation type:
</p><pre class="programlisting">
/**
* An annotation with this type indicates that the
* specification of the annotated API element is
* preliminary and subject to change.
*/
@interface Preliminary {}
</pre></div>
</div><br class="example-break"><div class="example"><a name="d5e15469"></a><p class="title"><b>Example&nbsp;9.6.1-3.&nbsp;Single-Element Annotation Type Declarations</b></p>
<div class="example-contents">
<p class="note">The convention that a single-element annotation type
defines an element called <code class="literal">value</code> is illustrated in
the following annotation type declaration:
</p><pre class="programlisting">
/**
* Associates a copyright notice with the annotated API element.
*/
@interface Copyright {
String value();
}
</pre><p class="note">The following annotation type declaration defines a
single-element annotation type whose sole element has an array
type:
</p><pre class="programlisting">
/**
* Associates a list of endorsers with the annotated class.
*/
@interface Endorsers {
String[] value();
}
</pre><p class="note">The following annotation type declaration shows a
<code class="literal">Class</code>-typed element whose value is constrained by a bounded
wildcard:
</p><pre class="programlisting">
interface Formatter {}
// Designates a formatter to pretty-print the annotated class
@interface PrettyPrinter {
Class&lt;? extends Formatter&gt; value();
}
</pre><p class="note">The following annotation type declaration contains
an element whose type is also an annotation type:
</p><pre class="programlisting">
/**
* Indicates the author of the annotated program element.
*/
@interface Author {
Name 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();
}
</pre><p class="note">The grammar for annotation type declarations permits
other element declarations besides method declarations. For example,
one might choose to declare a nested enum for use in conjunction with
an annotation type:
</p><pre class="programlisting">
@interface Quality {
enum Level { BAD, INDIFFERENT, GOOD }
Level value();
}
</pre></div>
</div><br class="example-break"></div>
<div class="section" title="9.6.2.&nbsp;Defaults for Annotation Type Elements">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.6.2"></a>9.6.2.&nbsp;Defaults for Annotation Type Elements
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.2-100"></a>An
annotation type element may have a <span class="emphasis"><em>default value</em></span>,
specified by following the element's (empty) parameter list with the
keyword <code class="literal">default</code> and an <span class="emphasis"><em>ElementValue</em></span>
(<a class="xref" href="jls-9.html#jls-9.7.1" title="9.7.1.&nbsp;Normal Annotations">&sect;9.7.1</a>).
</p>
<div id="jls-9.6.2-110" class="productionset"><a name="jls-9.6.2-110"></a>
<div class="production"><a name="jls-DefaultValue"></a>
<div class="lhs">DefaultValue:</div>
<div class="rhs">
<code class="literal">default</code> <a href="jls-9.html#jls-ElementValue" title="ElementValue">ElementValue</a>
</div>
</div>
</div>
<p class="norm-error"><a name="jls-9.6.2-120"></a>It is a
compile-time error if the type of the element is not commensurate
(<a class="xref" href="jls-9.html#jls-9.7" title="9.7.&nbsp;Annotations">&sect;9.7</a>) with the default value specified.
</p>
<p class="norm-dynamic"><a name="jls-9.6.2-200"></a>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).
</p>
<div class="example"><a name="d5e15499"></a><p class="title"><b>Example&nbsp;9.6.2-1.&nbsp;Annotation Type Declaration With Default Values</b></p>
<div class="example-contents">
<p class="note">Here is a refinement of
the <code class="literal">RequestForEnhancement</code> annotation type from
<a class="xref" href="jls-9.html#jls-9.6.1" title="9.6.1.&nbsp;Annotation Type Elements">&sect;9.6.1</a>:
</p><pre class="programlisting">
@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]";
}
</pre></div>
</div><br class="example-break"></div>
<div class="section" title="9.6.3.&nbsp;Repeatable Annotation Types">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.6.3"></a>9.6.3.&nbsp;Repeatable Annotation Types
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.3-100"></a>An
annotation type <span class="type">T</span> is <span class="emphasis"><em>repeatable</em></span> if its
declaration is (meta-)annotated with an <code class="literal">@Repeatable</code> annotation
(<a class="xref" href="jls-9.html#jls-9.6.4.8" title="9.6.4.8.&nbsp;@Repeatable">&sect;9.6.4.8</a>) whose <code class="literal">value</code> element
indicates a <span class="emphasis"><em>containing annotation type of
<span class="type">T</span></em></span>.
</p>
<p class="norm-static"><a name="jls-9.6.3-110"></a>An
annotation type <span class="type">TC</span> is a <span class="emphasis"><em>containing annotation type of
<span class="type">T</span></em></span> if all of the following are true:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-A"></a>
<span class="type">TC</span> declares a <code class="literal">value()</code> method whose return
type is <span class="type">T</span><code class="literal">[]</code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-B"></a>
Any methods declared by <span class="type">TC</span> other
than <code class="literal">value()</code> have a default value.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-C"></a>
<span class="type">TC</span> is retained for at least as long as <span class="type">T</span>, where retention is
expressed explicitly or implicitly with the <code class="literal">@Retention</code>
annotation (<a class="xref" href="jls-9.html#jls-9.6.4.2" title="9.6.4.2.&nbsp;@Retention">&sect;9.6.4.2</a>). Specifically:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-C-A"></a>
If the retention of <span class="type">TC</span> is <code class="literal">java.lang.annotation.RetentionPolicy.SOURCE</code>, then
the retention of <span class="type">T</span> is <code class="literal">java.lang.annotation.RetentionPolicy.SOURCE</code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-C-B"></a>
If the retention of <span class="type">TC</span> is <code class="literal">java.lang.annotation.RetentionPolicy.CLASS</code>, then the
retention of <span class="type">T</span> is either <code class="literal">java.lang.annotation.RetentionPolicy.CLASS</code> or
<code class="literal">java.lang.annotation.RetentionPolicy.SOURCE</code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-C-C"></a>
If the retention of <span class="type">TC</span> is <code class="literal">java.lang.annotation.RetentionPolicy.RUNTIME</code>, then
the retention of <span class="type">T</span> is <code class="literal">java.lang.annotation.RetentionPolicy.SOURCE</code>,
<code class="literal">java.lang.annotation.RetentionPolicy.CLASS</code>, or <code class="literal">java.lang.annotation.RetentionPolicy.RUNTIME</code>.
</p>
</li>
</ul>
</div>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-D"></a>
<span class="type">T</span> is applicable to at least the same kinds of program element
as <span class="type">TC</span> (<a class="xref" href="jls-9.html#jls-9.6.4.1" title="9.6.4.1.&nbsp;@Target">&sect;9.6.4.1</a>). Specifically, if the
kinds of program element where <span class="type">T</span> is applicable are denoted by
the set <code class="varname">m<sub>1</sub></code>, and the kinds of program element where <span class="type">TC</span> is
applicable are denoted by the set <code class="varname">m<sub>2</sub></code>, then each kind in <code class="varname">m<sub>2</sub></code>
must occur in <code class="varname">m<sub>1</sub></code>, except that:
</p>
<div class="norm">
<ul class="norm" type="disc">
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-D-A"></a>
If the kind in <code class="varname">m<sub>2</sub></code> is <code class="literal">java.lang.annotation.ElementType.ANNOTATION_TYPE</code>, then at
least one of <code class="literal">java.lang.annotation.ElementType.ANNOTATION_TYPE</code> or
<code class="literal">java.lang.annotation.ElementType.TYPE</code> or <code class="literal">java.lang.annotation.ElementType.TYPE_USE</code> must occur in
<code class="varname">m<sub>1</sub></code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-D-B"></a>
If the kind in <code class="varname">m<sub>2</sub></code> is <code class="literal">java.lang.annotation.ElementType.TYPE</code>, then at least one
of <code class="literal">java.lang.annotation.ElementType.TYPE</code> or <code class="literal">java.lang.annotation.ElementType.TYPE_USE</code> must occur in
<code class="varname">m<sub>1</sub></code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-D-C"></a>
If the kind in <code class="varname">m<sub>2</sub></code> is <code class="literal">java.lang.annotation.ElementType.TYPE_PARAMETER</code>, then at
least one of <code class="literal">java.lang.annotation.ElementType.TYPE_PARAMETER</code> or
<code class="literal">java.lang.annotation.ElementType.TYPE_USE</code> must occur in <code class="varname">m<sub>1</sub></code>.
</p>
</li>
</ul>
</div>
<p class="note">This clause implements the policy that an
annotation type may be <span class="emphasis"><em>repeatable</em></span> on only
some of the kinds of program element where it
is <span class="emphasis"><em>applicable</em></span>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-E"></a>
If the declaration of <span class="type">T</span> has a (meta-)annotation that
corresponds to <code class="literal">java.lang.annotation.Documented</code>, then the declaration of <span class="type">TC</span> must
have a (meta-)annotation that corresponds to
<code class="literal">java.lang.annotation.Documented</code>.
</p>
<p class="note">Note that it is permissible for <span class="type">TC</span> to be
<code class="literal">@Documented</code> while <span class="type">T</span> is not <code class="literal">@Documented</code>.
</p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.3-110-F"></a>
If the declaration of <span class="type">T</span> has a (meta-)annotation that
corresponds to <code class="literal">java.lang.annotation.Inherited</code>, then the declaration of <span class="type">TC</span> must
have a (meta)-annotation that corresponds to <code class="literal">java.lang.annotation.Inherited</code>.
</p>
<p class="note">Note that it is permissible for <span class="type">TC</span> to be
<code class="literal">@Inherited</code> while <span class="type">T</span> is not <code class="literal">@Inherited</code>.
</p>
</li>
</ol>
</div>
<p class="norm-error"><a name="jls-9.6.3-120"></a>It is a
compile-time error if an annotation type <span class="type">T</span> is (meta-)annotated with
an <code class="literal">@Repeatable</code> annotation whose <code class="literal">value</code> element
indicates a type which is not a containing annotation type of
<span class="type">T</span>.
</p>
<div class="example"><a name="d5e15632"></a><p class="title"><b>Example&nbsp;9.6.3-1.&nbsp;Ill-formed Containing Annotation Type</b></p>
<div class="example-contents">
<p class="note">Consider the following declarations:</p><pre class="screen">
@Repeatable(FooContainer.class)
@interface Foo {}
@interface FooContainer { Object[] value(); }
</pre><p class="note">Compiling the <code class="literal">Foo</code> declaration
produces a compile-time error because <code class="literal">Foo</code> uses
<code class="literal">@Repeatable</code> to attempt to specify <code class="literal">FooContainer</code>
as its containing annotation type, but <code class="literal">FooContainer</code>
is not in fact a containing annotation type
of <code class="literal">Foo</code>. (The return type
of <code class="literal">FooContainer.value()</code> is
not <code class="literal">Foo</code><code class="literal">[]</code>.)
</p>
</div>
</div><br class="example-break"><p class="norm-static"><a name="jls-9.6.3-200"></a>The
<code class="literal">@Repeatable</code> annotation cannot be repeated, so only one containing
annotation type can be specified by a repeatable annotation
type.
</p>
<p class="note">Allowing more than one containing annotation type to
be specified would cause an undesirable choice at compile time, when
multiple annotations of the repeatable annotation type are logically
replaced with a container annotation
(<a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>).
</p>
<p class="norm-static"><a name="jls-9.6.3-210"></a>An
annotation type can be the containing annotation type of at most one
annotation type.
</p>
<p class="note">This is implied by the requirement that if the
declaration of an annotation type <span class="type">T</span> specifies a containing
annotation type of <span class="type">TC</span>, then the <code class="literal">value()</code> method of
<span class="type">TC</span> has a return type involving <span class="type">T</span>, specifically
<span class="type">T</span><code class="literal">[]</code>.
</p>
<p class="norm-static"><a name="jls-9.6.3-220"></a>An
annotation type cannot specify itself as its containing annotation
type.
</p>
<p class="note">This is implied by the requirement on
the <code class="literal">value()</code> method of the containing annotation
type. Specifically, if an annotation type <span class="type">A</span> specified itself (via
<code class="literal">@Repeatable</code>) as its containing annotation type, then the return
type of <span class="type">A</span>'s <code class="literal">value()</code> method would have to be
<span class="type">A</span><code class="literal">[]</code>; but this would cause a compile-time error since an
annotation type cannot refer to itself in its elements
(<a class="xref" href="jls-9.html#jls-9.6.1" title="9.6.1.&nbsp;Annotation Type Elements">&sect;9.6.1</a>). More generally, two annotation types
cannot specify each other to be their containing annotation types,
because cyclic annotation type declarations are illegal.
</p>
<p class="norm-static"><a name="jls-9.6.3-230"></a>An
annotation type <span class="type">TC</span> may be the containing annotation type of some
annotation type <span class="type">T</span> while also having its own containing annotation
type <span class="type">TC</span> '. That is, a containing annotation type may itself be a
repeatable annotation type.
</p>
<div class="example"><a name="d5e15673"></a><p class="title"><b>Example&nbsp;9.6.3-2.&nbsp;Restricting Where Annotations May Repeat</b></p>
<div class="example-contents">
<p class="note">An annotation whose type declaration indicates a
target of <code class="literal">java.lang.annotation.ElementType.TYPE</code> can appear in at least as many locations
as an annotation whose type declaration indicates a target of
<code class="literal">java.lang.annotation.ElementType.ANNOTATION_TYPE</code>. For example, given the following
declarations of repeatable and containing annotation types:
</p><pre class="screen">
@Target(ElementType.TYPE)
@Repeatable(FooContainer.class)
@interface Foo {}
@Target(ElementType.ANNOTATION_TYPE)
@Interface FooContainer {
Foo[] value();
}
</pre><p class="note"><code class="literal">@Foo</code> can appear on any type
declaration while <code class="literal">@FooContainer</code> can appear on only
annotation type declarations. Therefore, the following annotation type
declaration is legal:
</p><pre class="screen">
@Foo @Foo
@interface X {}
</pre><p class="note">while the following interface declaration is
illegal:
</p><pre class="screen">
@Foo @Foo
interface X {}
</pre><p class="note">More broadly, if <code class="literal">Foo</code> is a
repeatable annotation type and <code class="literal">FooContainer</code> is its
containing annotation type, then:
</p>
<div class="note">
<ul class="note" type="disc">
<li class="listitem">
<p class="note">If <code class="literal">Foo</code> has no <code class="literal">@Target</code>
meta-annotation and <code class="literal">FooContainer</code> has no
<code class="literal">@Target</code> meta-annotation, then <code class="literal">@Foo</code> may be
repeated on any program element which supports
annotations.
</p>
</li>
<li class="listitem">
<p class="note">If <code class="literal">Foo</code> has no <code class="literal">@Target</code>
meta-annotation but <code class="literal">FooContainer</code> has an
<code class="literal">@Target</code> meta-annotation, then <code class="literal">@Foo</code> may
only be repeated on program elements
where <code class="literal">@FooContainer</code> may appear.
</p>
</li>
<li class="listitem">
<p class="note">If <code class="literal">Foo</code> has an <code class="literal">@Target</code>
meta-annotation, then in the judgment of the designers of the
Java programming language, <code class="literal">FooContainer</code> must be declared
with knowledge of the <code class="literal">Foo</code>'s
applicability. Specifically, the kinds of program element
where <code class="literal">FooContainer</code> may appear must logically
be the same as, or a subset of, <code class="literal">Foo</code>'s
kinds.
</p>
<p class="note">For example, if <code class="literal">Foo</code> is
applicable to field and method declarations,
then <code class="literal">FooContainer</code> may legitimately serve
as <code class="literal">Foo</code>'s containing annotation type
if <code class="literal">FooContainer</code> is applicable to just field
declarations (preventing <code class="literal">@Foo</code> from being
repeated on method declarations). But
if <code class="literal">FooContainer</code> is applicable only to formal
parameter declarations, then <code class="literal">FooContainer</code> was
a poor choice of containing annotation type
by <code class="literal">Foo</code>
because <code class="literal">@FooContainer</code> cannot be implicitly
declared on some program elements where <code class="literal">@Foo</code>
is repeated.
</p>
<p class="note">Similarly, if <code class="literal">Foo</code> is
applicable to field and method declarations,
then <code class="literal">FooContainer</code> cannot legitimately serve
as <code class="literal">Foo</code>'s containing annotation type
if <code class="literal">FooContainer</code> is applicable to field and
parameter declarations. While it would be possible to take the
intersection of the program elements and
make <code class="literal">Foo</code> repeatable on field declarations
only, the presence of additional program elements
for <code class="literal">FooContainer</code> indicates
that <code class="literal">FooContainer</code> was not designed as a
containing annotation type for <code class="literal">Foo</code>. It would
therefore be dangerous for <code class="literal">Foo</code> to rely on
it.
</p>
</li>
</ul>
</div>
</div>
</div><br class="example-break"><div class="example"><a name="d5e15733"></a><p class="title"><b>Example&nbsp;9.6.3-3.&nbsp;A Repeatable Containing Annotation Type</b></p>
<div class="example-contents">
<p class="note">The following declarations are legal:</p><pre class="programlisting">
// Foo: Repeatable annotation type
@Repeatable(FooContainer.class)
@interface Foo { int value(); }
// FooContainer: Containing annotation type of Foo
// Also a repeatable annotation type itself
@Repeatable(FooContainerContainer.class)
@interface FooContainer { Foo[] value(); }
// FooContainerContainer: Containing annotation type of FooContainer
@interface FooContainerContainer { FooContainer[] value(); }
</pre><p class="note">Thus, an annotation whose type is a containing
annotation type may itself be repeated:
</p><pre class="programlisting">
@FooContainer({@Foo(1)}) @FooContainer({@Foo(2)})
class A {}
</pre><p class="note">An annotation type which is both repeatable and
containing is subject to the rules on mixing annotations of repeatable
annotation type with annotations of containing annotation type
(<a class="xref" href="jls-9.html#jls-9.7.5" title="9.7.5.&nbsp;Multiple Annotations Of The Same Type">&sect;9.7.5</a>). For example, it is not possible to
write multiple <code class="literal">@Foo</code> annotations alongside
multiple <code class="literal">@FooContainer</code> annotations, nor is it
possible to write multiple <code class="literal">@FooContainer</code>
annotations alongside
multiple <code class="literal">@FooContainerContainer</code>
annotations. However, if the <code class="literal">FooContainerContainer</code>
type was itself repeatable, then it would be possible to write
multiple <code class="literal">@Foo</code> annotations alongside
multiple <code class="literal">@FooContainerContainer</code> annotations.
</p>
</div>
</div><br class="example-break"></div>
<div class="section" title="9.6.4.&nbsp;Predefined Annotation Types">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="jls-9.6.4"></a>9.6.4.&nbsp;Predefined Annotation Types
</h3>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.4-100"></a>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.
</p>
<div class="section" title="9.6.4.1.&nbsp;@Target">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.6.4.1"></a>9.6.4.1.&nbsp;<code class="literal">@Target</code></h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.4.1-100"></a>An
annotation of type <code class="literal">java.lang.annotation.Target</code> is used on the declaration of an
annotation type <span class="type">T</span> to specify the contexts in which <span class="type">T</span>
is <span class="emphasis"><em>applicable</em></span>. <code class="literal">java.lang.annotation.Target</code> has a single
element, <code class="literal">value</code>, of type <code class="literal">java.lang.annotation.ElementType</code><code class="literal">[]</code>, to
specify contexts.
</p>
<p class="norm-static"><a name="jls-9.6.4.1-200"></a>
Annotation types may be applicable in <span class="emphasis"><em>declaration
contexts</em></span>, where annotations apply to declarations, or
in <span class="emphasis"><em>type contexts</em></span>, where annotations apply to
types used in declarations and expressions.
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210"></a>There
are eight declaration contexts, each corresponding to an enum constant
of <code class="literal">java.lang.annotation.ElementType</code>:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-A"></a>
Package declarations (<a class="xref" href="jls-7.html#jls-7.4.1" title="7.4.1.&nbsp;Named Packages">&sect;7.4.1</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-A.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.PACKAGE</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-B"></a>
Type declarations: class, interface, enum, and annotation type
declarations (<a class="xref" href="jls-8.html#jls-8.1.1" title="8.1.1.&nbsp;Class Modifiers">&sect;8.1.1</a>,
<a class="xref" href="jls-9.html#jls-9.1.1" title="9.1.1.&nbsp;Interface Modifiers">&sect;9.1.1</a>, <a class="xref" href="jls-8.html#jls-8.5" title="8.5.&nbsp;Member Type Declarations">&sect;8.5</a>,
<a class="xref" href="jls-9.html#jls-9.5" title="9.5.&nbsp;Member Type Declarations">&sect;9.5</a>, <a class="xref" href="jls-8.html#jls-8.9" title="8.9.&nbsp;Enum Types">&sect;8.9</a>,
<a class="xref" href="jls-9.html#jls-9.6" title="9.6.&nbsp;Annotation Types">&sect;9.6</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-B.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.TYPE</code></p>
<p class="norm-static"><a name="jls-9.6.4.1-210-B.2"></a>
Additionally, annotation type declarations correspond to
<code class="literal">java.lang.annotation.ElementType.ANNOTATION_TYPE</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-C"></a>
Method declarations (including elements of annotation types)
(<a class="xref" href="jls-8.html#jls-8.4.3" title="8.4.3.&nbsp;Method Modifiers">&sect;8.4.3</a>, <a class="xref" href="jls-9.html#jls-9.4" title="9.4.&nbsp;Method Declarations">&sect;9.4</a>,
<a class="xref" href="jls-9.html#jls-9.6.1" title="9.6.1.&nbsp;Annotation Type Elements">&sect;9.6.1</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-C.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.METHOD</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-D"></a>
Constructor declarations (<a class="xref" href="jls-8.html#jls-8.8.3" title="8.8.3.&nbsp;Constructor Modifiers">&sect;8.8.3</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-D.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.CONSTRUCTOR</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-E"></a>
Type parameter declarations of generic classes, interfaces,
methods, and constructors (<a class="xref" href="jls-8.html#jls-8.1.2" title="8.1.2.&nbsp;Generic Classes and Type Parameters">&sect;8.1.2</a>,
<a class="xref" href="jls-9.html#jls-9.1.2" title="9.1.2.&nbsp;Generic Interfaces and Type Parameters">&sect;9.1.2</a>, <a class="xref" href="jls-8.html#jls-8.4.4" title="8.4.4.&nbsp;Generic Methods">&sect;8.4.4</a>,
<a class="xref" href="jls-8.html#jls-8.8.4" title="8.8.4.&nbsp;Generic Constructors">&sect;8.8.4</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-E.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.TYPE_PARAMETER</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-F"></a>
Field declarations (including enum constants)
(<a class="xref" href="jls-8.html#jls-8.3.1" title="8.3.1.&nbsp;Field Modifiers">&sect;8.3.1</a>, <a class="xref" href="jls-9.html#jls-9.3" title="9.3.&nbsp;Field (Constant) Declarations">&sect;9.3</a>,
<a class="xref" href="jls-8.html#jls-8.9.1" title="8.9.1.&nbsp;Enum Constants">&sect;8.9.1</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-F.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.FIELD</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-G"></a>
Formal and exception parameter declarations
(<a class="xref" href="jls-8.html#jls-8.4.1" title="8.4.1.&nbsp;Formal Parameters">&sect;8.4.1</a>, <a class="xref" href="jls-9.html#jls-9.4" title="9.4.&nbsp;Method Declarations">&sect;9.4</a>,
<a class="xref" href="jls-14.html#jls-14.20" title="14.20.&nbsp;The try statement">&sect;14.20</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-G.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.PARAMETER</code></p>
</li>
<li class="listitem">
<p class="norm-static"><a name="jls-9.6.4.1-210-H"></a>
Local variable declarations (including loop variables of <code class="literal">for</code>
statements and resource variables of <code class="literal">try</code>-with-resources
statements) (<a class="xref" href="jls-14.html#jls-14.4" title="14.4.&nbsp;Local Variable Declaration Statements">&sect;14.4</a>,
<a class="xref" href="jls-14.html#jls-14.14.1" title="14.14.1.&nbsp;The basic for Statement">&sect;14.14.1</a>, <a class="xref" href="jls-14.html#jls-14.14.2" title="14.14.2.&nbsp;The enhanced for statement">&sect;14.14.2</a>,
<a class="xref" href="jls-14.html#jls-14.20.3" title="14.20.3.&nbsp;try-with-resources">&sect;14.20.3</a>)
</p>
<p class="norm-static"><a name="jls-9.6.4.1-210-H.1"></a>
Corresponds to <code class="literal">java.lang.annotation.ElementType.LOCAL_VARIABLE</code></p>
</li>
</ol>
</div>
<p class="norm-static"><a name="jls-9.6.4.1-220"></a>There
are 16 type contexts (<a class="xref" href="jls-4.html#jls-4.11" title="4.11.&nbsp;Where Types Are Used">&sect;4.11</a>), all represented by
the enum constant <code class="literal">TYPE_USE</code> of <code class="literal">java.lang.annotation.ElementType</code>.
</p>
<p class="norm-error"><a name="jls-9.6.4.1-300"></a>It is a
compile-time error if the same enum constant appears more than once in
the <code class="literal">value</code> element of an annotation of type
<code class="literal">java.lang.annotation.Target</code>.
</p>
<p class="norm-static"><a name="jls-9.6.4.1-400"></a>If an
annotation of type <code class="literal">java.lang.annotation.Target</code> is not present on the declaration of an
annotation type <span class="type">T</span>, then <span class="type">T</span> is applicable in all declaration
contexts except type parameter declarations, and in no type
contexts.
</p>
<p class="note">These contexts are the syntactic locations where
annotations were allowed in Java SE 7.
</p>
</div>
<div class="section" title="9.6.4.2.&nbsp;@Retention">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="jls-9.6.4.2"></a>9.6.4.2.&nbsp;<code class="literal">@Retention</code></h4>
</div>
</div>
</div>
<p class="norm-static"><a name="jls-9.6.4.2-100"></a>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 type <code class="literal">java.lang.annotation.Retention</code> is used to choose among