Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
9300 lines (9173 sloc) 707 KB
<html>
<head>
<title> Types, Values, and Variables</title>
<meta name="collection" content="exclude">
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="jTOC.doc.html">Contents</a> | <a href="lexical.doc.html">Prev</a> | <a href="conversions.doc.html">Next</a> | <a href="jIX.fm.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">Second Edition</font></td></tr></table>
<hr><br>
<a name="44329"></a>
<p><strong>
CHAPTER
4 </strong></p>
<a name="48440"></a>
<h1>Types, Values, and Variables</h1>
<hr><p>
<a name="97679"></a>
The Java programming language is a <em>strongly typed</em> language, which means that every variable and every expression has a type that is known at compile time. Types limit the values that a variable <a href="typesValues.doc.html#18470">(&#167;4.5)</a> can hold or that an expression can produce, limit the operations supported on those values, and determine the meaning of the operations. Strong typing helps detect errors at compile time.<p>
<a name="50743"></a>
The types of the Java programming language are divided into two categories: primitive types and reference types. The primitive types <a href="typesValues.doc.html#85587">(&#167;4.2)</a> are the <code>boolean</code> type and the numeric types. The numeric types are the integral types <code>byte</code>, <code>short</code>, <code>int</code>, <code>long</code>, and <code>char</code>, and the floating-point types <code>float</code> and <code>double</code>. The reference types <a href="typesValues.doc.html#9317">(&#167;4.3)</a> are class types, interface types, and array types. There is also a special null type. An object <a href="typesValues.doc.html#12028">(&#167;4.3.1)</a> is a dynamically created instance of a class type or a dynamically created array. The values of a reference type are references to objects. All objects, including arrays, support the methods of class <code>Object</code> <a href="typesValues.doc.html#11055">(&#167;4.3.2)</a>. String literals are represented by <code>String</code> objects <a href="typesValues.doc.html#26992">(&#167;4.3.3)</a>.<p>
<a name="50838"></a>
Names of types are used <a href="typesValues.doc.html#25948">(&#167;4.4)</a> in declarations, casts, class instance creation expressions, array creation expressions, class literals, and <code>instanceof</code> operator expressions. <p>
<a name="50800"></a>
A variable <a href="typesValues.doc.html#18470">(&#167;4.5)</a> is a storage location. A variable of a primitive type always holds a value of that exact type. A variable of a class type <i>T</i> can hold a null reference or a reference to an instance of class <i>T</i> or of any class that is a subclass of <i>T</i>. A variable of an interface type can hold a null reference or a reference to any instance of any class that implements the interface. If <i>T</i> is a primitive type, then a variable of type "array of <i>T</i>" can hold a null reference or a reference to any array of type "array of <i>T</i>"; if <i>T</i> is a reference type, then a variable of type "array of <i>T</i>" can hold a null reference or a reference to any array of type "array of <i>S</i>" such that type <i>S</i> is assignable <a href="conversions.doc.html#184206">(&#167;5.2)</a> to type <i>T</i>. A variable of type <code>Object</code> can hold a null reference or a reference to any object, whether class interface or array.<p>
<a name="11128"></a>
<h2>4.1 The Kinds of Types and Values</h2>
<a name="10737"></a>
There are two kinds of <em>types</em> in the Java programming language: primitive types <a href="typesValues.doc.html#85587">(&#167;4.2)</a> and reference types <a href="typesValues.doc.html#9317">(&#167;4.3)</a>. There are, correspondingly, two kinds of data values that can be stored in variables, passed as arguments, returned by methods, and operated on: primitive values <a href="typesValues.doc.html#85587">(&#167;4.2)</a> and reference values <a href="typesValues.doc.html#9317">(&#167;4.3)</a>.<p>
<ul><pre>
<i>Type:
<code> </code>PrimitiveType
ReferenceType
</i></pre></ul><a name="23953"></a>
There is also a special <em>null type</em>, the type of the expression <code>null</code>, which has no name. Because the null type has no name, it is impossible to declare a variable of the null type or to cast to the null type. The null reference is the only possible value of an expression of null type. The null reference can always be cast to any reference type. In practice, the programmer can ignore the null type and just pretend that <code>null</code> is merely a special literal that can be of any reference type.<p>
<a name="85587"></a>
<h2>4.2 Primitive Types and Values</h2>
<a name="9122"></a>
A <em>primitive type</em> is predefined by the Java programming language and named by its reserved keyword <a href="lexical.doc.html#229308">(&#167;3.9)</a>:<p>
<ul><pre>
<i>PrimitiveType:
NumericType
</i> <code>boolean
</code>
<i>NumericType:
IntegralType
FloatingPointType
IntegralType: one of</i>
<code>byte short int long char
</code>
<i>FloatingPointType: one of</i>
<code> float double
</code></pre></ul><a name="50919"></a>
Primitive values do not share state with other primitive values. A variable whose type is a primitive type always holds a primitive value of that same type. The value of a variable of primitive type can be changed only by assignment operations on that variable.<p>
<a name="9137"></a>
The <em>numeric types</em> are the integral types and the floating-point types. <p>
<a name="88061"></a>
The <em>integral types</em> are <code>byte</code>, <code>short</code>, <code>int</code>, and <code>long</code>, whose values are 8-bit, 16-bit, 32-bit and 64-bit signed two's-complement integers, respectively, and <code>char</code>, whose values are 16-bit unsigned integers representing Unicode characters.<p>
<a name="88062"></a>
The <em>floating-point types</em> are <code>float</code>, whose values include the 32-bit IEEE 754 floating-point numbers, and <code>double</code>, whose values include the 64-bit IEEE 754 floating-point numbers.<p>
<a name="50913"></a>
The <code>boolean</code> type has exactly two values: <code>true</code> and <code>false.</code><p>
<a name="9151"></a>
<h3>4.2.1 Integral Types and Values</h3>
<a name="50950"></a>
The values of the integral types are integers in the following ranges:<p>
<ul><a name="9163"></a>
<li>For <code>byte</code>, from -128 to 127, inclusive
<a name="9164"></a>
<li>For <code>short</code>, from -32768 to 32767, inclusive
<a name="9165"></a>
<li>For <code>int</code>, from -2147483648 to 2147483647, inclusive
<a name="9166"></a>
<li>For <code>long</code>, from -9223372036854775808 to 9223372036854775807, inclusive
<a name="51034"></a>
<li>For <code>char</code>, from <code>'\u0000'</code> to <code>'\uffff'</code> inclusive, that is, from 0 to 65535
</ul><a name="51035"></a>
<h3>4.2.2 Integer Operations</h3>
<a name="29775"></a>
The Java programming language provides a number of operators that act on integral values:<p>
<ul><a name="10358"></a>
<li>The comparison operators, which result in a value of type <code>boolean</code>:
<ul>
<a name="9181"></a>
<li>The numerical comparison operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code> <a href="expressions.doc.html#153654">(&#167;15.20.1)</a>
<a name="17601"></a>
<li>The numerical equality operators <code>==</code> and <code>!=</code> <a href="expressions.doc.html#5198">(&#167;15.21.1)</a>
</ul>
<a name="10365"></a>
<li>The numerical operators, which result in a value of type <code>int</code> or <code>long</code>:
<ul>
<a name="18334"></a>
<li>The unary plus and minus operators <code>+</code> and <code>-</code> (<a href="expressions.doc.html#24924">&#167;15.15.3</a>, <a href="expressions.doc.html#236345">&#167;15.15.4</a>)
<a name="17539"></a>
<li>The multiplicative operators <code>*</code>, <code>/</code>, and <code>%</code> <a href="expressions.doc.html#239829">(&#167;15.17)</a>
<a name="19482"></a>
<li>The additive operators <code>+</code> and <code>-</code> <a href="expressions.doc.html#13510">(&#167;15.18.2)</a>
<a name="24026"></a>
<li>The increment operator <code>++</code>, both prefix <a href="expressions.doc.html#39547">(&#167;15.15.1)</a> and postfix <a href="expressions.doc.html#39438">(&#167;15.14.1)</a>
<a name="24036"></a>
<li>The decrement operator <code>--</code>, both prefix <a href="expressions.doc.html#239136">(&#167;15.15.2)</a> and postfix <a href="expressions.doc.html#4987">(&#167;15.14.2)</a>
<a name="19496"></a>
<li>The signed and unsigned shift operators <code>&lt;&lt;</code>, <code>&gt;&gt;</code>, and <code>&gt;&gt;&gt;</code> <a href="expressions.doc.html#5121">(&#167;15.19)</a>
<a name="51061"></a>
<li>The bitwise complement operator <code>~</code> <a href="expressions.doc.html#5017">(&#167;15.15.5)</a>
<a name="17770"></a>
<li>The integer bitwise operators <code>&amp;</code>, <code>|</code>, and <code>^</code> <a href="expressions.doc.html#5233">(&#167;15.22.1)</a>
</ul>
<a name="19469"></a>
<li>The conditional operator <code>? :</code> <a href="expressions.doc.html#290293">(&#167;15.25)</a>
<a name="18373"></a>
<li>The cast operator, which can convert from an integral value to a value of any specified numeric type (<a href="conversions.doc.html#20232">&#167;5.5</a>, <a href="expressions.doc.html#238146">&#167;15.16</a>)
<a name="17774"></a>
<li>The string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a>, which, when given a <code>String</code> operand and an integral operand, will convert the integral operand to a <code>String</code> representing its value in decimal form, and then produce a newly created <code>String</code> that is the concatenation of the two strings
</ul><a name="51025"></a>
Other useful constructors, methods, and constants are predefined in the classes <code>Byte</code>, <code>Short</code>, <code>Integer</code>, <code>Long</code>, and <code>Character</code>.<p>
<a name="28057"></a>
If an integer operator other than a shift operator has at least one operand of type <code>long</code>, then the operation is carried out using 64-bit precision, and the result of the numerical operator is of type <code>long</code>. If the other operand is not <code>long</code>, it is first widened <a href="conversions.doc.html#25215">(&#167;5.1.4)</a> to type <code>long</code> by numeric promotion <a href="conversions.doc.html#26917">(&#167;5.6)</a>. Otherwise, the operation is carried out using 32-bit precision, and the result of the numerical operator is of type <code>int</code>. If either operand is not an <code>int</code>, it is first widened to type <code>int</code> by numeric promotion.<p>
<a name="9194"></a>
The built-in integer operators do not indicate overflow or underflow in any way. The only numeric operators that can throw an exception <a href="exceptions.doc.html#44043">(&#167;11)</a> are the integer divide operator <code>/</code> <a href="expressions.doc.html#5047">(&#167;15.17.2)</a> and the integer remainder operator <code>%</code> <a href="expressions.doc.html#24956">(&#167;15.17.3)</a>, which throw an <code>ArithmeticException</code> if the right-hand operand is zero. <p>
<a name="86654"></a>
The example:
<blockquote><pre>class Test {
public static void main(String[] args) {
int i = 1000000;
System.out.println(i * i);
long l = i;
System.out.println(l * l);
System.out.println(20296 / (l - i));
}
}
</pre></blockquote><a name="51131"></a>
produces the output:<p>
<blockquote><pre>-727379968
1000000000000
</pre></blockquote><a name="51199"></a>
and then encounters an <code>ArithmeticException</code> in the division by <code>l</code> <code>-</code> <code>i</code>, because <code>l</code> <code>-</code> <code>i</code> is zero. The first multiplication is performed in 32-bit precision, whereas the second multiplication is a <code>long</code> multiplication. The value <code>-727379968</code> is the decimal value of the low 32 bits of the mathematical result, <code>1000000000000</code>, which is a value too large for type <code>int</code>.<p>
<a name="51203"></a>
Any value of any integral type may be cast to or from any numeric type. There are no casts between integral types and the type <code>boolean</code>.<p>
<a name="9208"></a>
<h3>4.2.3 Floating-Point Types, Formats, and Values</h3>
<a name="87606"></a>
The floating-point types are <code>float</code> and <code>double</code>, which are conceptually associated with the single-precision 32-bit and double-precision 64-bit format IEEE 754 values and operations as specified in <em>IEEE Standard for Binary Floating-Point Arithmetic</em>, ANSI/IEEE Standard 754-1985 (IEEE, New York).<p>
<a name="88071"></a>
The IEEE 754 standard includes not only positive and negative numbers that consist of a sign and magnitude, but also positive and negative zeros, positive and negative <em>infinities</em>, and special <em>Not-a-Number </em>values (hereafter abbreviated NaN). A NaN value is used to represent the result of certain invalid operations such as dividing zero by zero. NaN constants of both <code>float</code> and <code>double</code> type are predefined as <code>Float.NaN</code> and <code>Double.NaN</code>.<p>
<a name="96776"></a>
Every implementation of the Java programming language is required to support two standard sets of floating-point values, called the <em>float value set</em> and the <em>double value set</em>. In addition, an implementation of the Java programming language may support either or both of two extended-exponent floating-point value sets, called the<em> float-extended-exponent value set</em> and the<em> double-extended-exponent value set</em>. These extended-exponent value sets may, under certain circumstances, be used instead of the standard value sets to represent the values of expressions of type <code>float</code> or <code>double</code> (<a href="conversions.doc.html#184225">&#167;5.1.8</a>, <a href="expressions.doc.html#249198">&#167;15.4</a>).<p>
<a name="96777"></a>
The finite nonzero values of any floating-point value set can all be expressed in the form <img src="typesValues.doc.anc.gif">, where <em>s</em> is +1 or -1, <em>m</em> is a positive integer less than <img src="typesValues.doc.anc1.gif">, and <em>e</em> is an integer between <img src="typesValues.doc.anc2.gif"> and <img src="typesValues.doc.anc3.gif">, inclusive, and where <em>N</em> and <em>K</em> are parameters that depend on the value set. Some values can be represented in this form in more than one way; for example, supposing that a value <em>v</em> in a value set might be represented in this form using certain values for <em>s</em>, <em>m</em>, and <em>e</em>, then if it happened that <em>m</em> were even and <em>e</em> were less than <img src="typesValues.doc.anc4.gif">, one could halve <em>m</em> and increase <em>e</em> by 1 to produce a second representation for the same value <em>v</em>. A representation in this form is called <em>normalized</em> if <img src="typesValues.doc.anc5.gif">; otherwise the representation is said to be <em>denormalized</em>. If a value in a value set cannot be represented in such a way that <img src="typesValues.doc.anc7.gif">, then the value is said to be a <em>denormalized value</em>, because it has no normalized representation.<p>
<a name="96680"></a>
The constraints on the parameters <em>N</em> and <em>K</em> (and on the derived parameters <em>E</em><sub><i>min</i></sub> and <em>E</em><sub><i>max</i></sub>) for the two required and two optional floating-point value sets are summarized in <a href="typesValues.doc.html#96802">Table 4.1</a>.
<p>
<Table Border="3">
<caption><a name="96802"></a>
<i>Floating-point value set parameters</i>
</caption>
<tr><th><a name="96683"></a>
<b> Parameter</b>
<th><a name="96685"></a>
<strong>float</strong>
<th><a name="96687"></a>
<strong>float-extended-exponent</strong>
<th><a name="96689"></a>
<b> double</b>
<th><a name="96691"></a>
<b> double-extended-exponent<b>
<tr><td><a name="96693"></a>
N<p>
<td><a name="96695"></a>
24<p>
<td><a name="96697"></a>
24<p>
<td><a name="96699"></a>
53<p>
<td><a name="96701"></a>
53<p>
<tr><td><a name="96703"></a>
K<p>
<td><a name="96705"></a>
8<p>
<td><a name="96707"></a>
<img src="chars/gtequal.gif"> 11<p>
<td><a name="96709"></a>
11<p>
<td><a name="96711"></a>
<img src="chars/gtequal.gif"> 15<p>
<tr><td><a name="96713"></a>
E<sub><i>max</i></sub><p>
<td><a name="96715"></a>
+127<p>
<td><a name="96717"></a>
<img src="chars/gtequal.gif"> +1023<p>
<td><a name="96719"></a>
+1023<p>
<td><a name="96721"></a>
<img src="chars/gtequal.gif"> +16383<p>
<tr><td><a name="96723"></a>
E<sub><i>min</i></sub><p>
<td><a name="96725"></a>
-126<p>
<td><a name="96727"></a>
<img src="chars/lt_equal.gif"> -1022<p>
<td><a name="96729"></a>
-1022<p>
<td><a name="96731"></a>
<img src="chars/lt_equal.gif"> -16382<p>
</Table>
<Table>
<tr><td>
</Table>
<p>
<a name="106189"></a>
Where one or both extended-exponent value sets are supported by an implementation, then for each supported extended-exponent value set there is a specific implementation-dependent constant <em>K</em>, whose value is constrained by <a href="typesValues.doc.html#96802">Table 4.1</a>; this value <em>K</em> in turn dictates the values for <em>E</em><sub><i>min</i></sub> and <em>E</em><sub><i>max</i></sub>.<p>
<a name="96735"></a>
Each of the four value sets includes not only the finite nonzero values that are ascribed to it above, but also NaN values and the four values positive zero, negative zero, positive infinity, and negative infinity.<p>
<a name="96736"></a>
Note that the constraints in <a href="typesValues.doc.html#96802">Table 4.1</a> are designed so that every element of the float value set is necessarily also an element of the float-extended-exponent value set, the double value set, and the double-extended-exponent value set. Likewise, each element of the double value set is necessarily also an element of the double-extended-exponent value set. Each extended-exponent value set has a larger range of exponent values than the corresponding standard value set, but does not have more precision.<p>
<a name="96737"></a>
The elements of the float value set are exactly the values that can be represented using the single floating-point format defined in the IEEE 754 standard. The elements of the double value set are exactly the values that can be represented using the double floating-point format defined in the IEEE 754 standard. Note, however, that the elements of the float-extended-exponent and double-extended-exponent value sets defined here do <em>not</em> correspond to the values that can be represented using IEEE 754 single extended and double extended formats, respectively.<p>
<a name="96744"></a>
The float, float-extended-exponent, double, and double-extended-exponent value sets are not types. It is always correct for an implementation of the Java programming language to use an element of the float value set to represent a value of type <code>float</code>; however, it may be permissible in certain regions of code for an implementation to use an element of the float-extended-exponent value set instead. Similarly, it is always correct for an implementation to use an element of the double value set to represent a value of type <code>double</code>; however, it may be permissible in certain regions of code for an implementation to use an element of the double-extended-exponent value set instead.<p>
<a name="106159"></a>
Except for NaN, floating-point values are <em>ordered</em>; arranged from smallest to largest, they are negative infinity, negative finite nonzero values, positive and negative zero, positive finite nonzero values, and positive infinity.<p>
<a name="106160"></a>
IEEE 754 allows multiple distinct NaN values for each of its single and double floating-point formats. While each hardware architecture returns a particular bit pattern for NaN when a new NaN is generated, a programmer can also create NaNs with different bit patterns to encode, for example, retrospective diagnostic information. <p>
<a name="106258"></a>
For the most part, the Java platform treats NaN values of a given type as though collapsed into a single canonical value (and hence this specification normally refers to an arbitrary NaN as though to a canonical value). However, version 1.3 the Java platform introduced methods enabling the programmer to distinguish between NaN values: the <code>Float.floatToRawIntBits</code> and <code>Double.doubleToRawLongBits</code> methods. The interested reader is referred to the specifications for the <code>Float</code> and <code>Double</code> classes for more information.<p>
<a name="86666"></a>
Positive zero and negative zero compare equal; thus the result of the expression <code>0.0==-0.0</code> is <code>true</code> and the result of <code>0.0&gt;-0.0</code> is <code>false</code>. But other operations can distinguish positive and negative zero; for example, <code>1.0/0.0</code> has the value positive infinity, while the value of <code>1.0/-0.0</code> is negative infinity.<p>
<a name="16083"></a>
NaN is <em>unordered</em>, so the numerical comparison operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code> return <code>false</code> if either or both operands are NaN <a href="expressions.doc.html#153654">(&#167;15.20.1)</a>. The equality operator <code>==</code> returns <code>false</code> if either operand is NaN, and the inequality operator <code>!=</code> returns <code>true</code> if either operand is NaN <a href="expressions.doc.html#5198">(&#167;15.21.1)</a>. In particular, <code>x!=x</code> is <code>true</code> if and only if <code>x</code> is NaN, and <code>(x&lt;y)</code> <code>==</code> <code>!(x&gt;=y)</code> will be <code>false</code> if <code>x</code> or <code>y</code> is NaN.<p>
<a name="16093"></a>
Any value of a floating-point type may be cast to or from any numeric type. There are no casts between floating-point types and the type <code>boolean</code>.<p>
<a name="9249"></a>
<h3>4.2.4 Floating-Point Operations</h3>
<a name="9981"></a>
The Java programming language provides a number of operators that act on floating-point values:<p>
<ul><a name="52058"></a>
<li>The comparison operators, which result in a value of type <code>boolean</code>:
<ul>
<a name="52062"></a>
<li>The numerical comparison operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code> <a href="expressions.doc.html#153654">(&#167;15.20.1)</a>
<a name="52066"></a>
<li>The numerical equality operators <code>==</code> and <code>!=</code> <a href="expressions.doc.html#5198">(&#167;15.21.1)</a>
</ul>
<a name="52069"></a>
<li>The numerical operators, which result in a value of type <code>float</code> or <code>double</code>:
<ul>
<a name="52076"></a>
<li>The unary plus and minus operators <code>+</code> and <code>-</code> (<a href="expressions.doc.html#24924">&#167;15.15.3</a>, <a href="expressions.doc.html#236345">&#167;15.15.4</a>)
<a name="24115"></a>
<li>The multiplicative operators <code>*</code>, <code>/</code>, and <code>%</code> <a href="expressions.doc.html#239829">(&#167;15.17)</a>
<a name="24119"></a>
<li>The additive operators <code>+</code> and <code>-</code> <a href="expressions.doc.html#13510">(&#167;15.18.2)</a>
<a name="24126"></a>
<li>The increment operator <code>++</code>, both prefix <a href="expressions.doc.html#39547">(&#167;15.15.1)</a> and postfix <a href="expressions.doc.html#39438">(&#167;15.14.1)</a>
<a name="24107"></a>
<li>The decrement operator <code>--</code>, both prefix <a href="expressions.doc.html#239136">(&#167;15.15.2)</a> and postfix <a href="expressions.doc.html#4987">(&#167;15.14.2)</a>
</ul>
<a name="19446"></a>
<li>The conditional operator <code>? :</code> <a href="expressions.doc.html#290293">(&#167;15.25)</a>
<a name="11998"></a>
<li>The cast operator, which can convert from a floating-point value to a value of any specified numeric type (<a href="conversions.doc.html#20232">&#167;5.5</a>, <a href="expressions.doc.html#238146">&#167;15.16</a>)
<a name="21842"></a>
<li>The string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a>, which, when given a <code>String</code> operand and a floating-point operand, will convert the floating-point operand to a <code>String</code> representing its value in decimal form (without information loss), and then produce a newly created <code>String</code> by concatenating the two strings
</ul><a name="12009"></a>
Other useful constructors, methods, and constants are predefined in the classes <code>Float</code>, <code>Double</code>, and <code>Math</code>.<p>
<a name="12005"></a>
If at least one of the operands to a binary operator is of floating-point type, then the operation is a floating-point operation, even if the other is integral.<p>
<a name="51262"></a>
If at least one of the operands to a numerical operator is of type <code>double</code>, then the operation is carried out using 64-bit floating-point arithmetic, and the result of the numerical operator is a value of type <code>double</code>. (If the other operand is not a <code>double</code>, it is first widened to type <code>double</code> by numeric promotion <a href="conversions.doc.html#26917">(&#167;5.6)</a>.) Otherwise, the operation is carried out using 32-bit floating-point arithmetic, and the result of the numerical operator is a value of type <code>float. </code>If the other operand is not a <code>float</code>, it is first widened to type <code>float</code> by numeric promotion.<p>
<a name="9265"></a>
Operators on floating-point numbers behave as specified by IEEE 754 (with the exception of the remainder operator <a href="expressions.doc.html#24956">(&#167;15.17.3)</a>). In particular, the Java programming language requires support of IEEE 754 <em>denormalized</em> floating-point numbers and <em>gradual underflow</em>, which make it easier to prove desirable properties of particular numerical algorithms. Floating-point operations do not "flush to zero" if the calculated result is a denormalized number.<p>
<a name="9274"></a>
The Java programming language requires that floating-point arithmetic behave as if every floating-point operator rounded its floating-point result to the result precision. <em>Inexact</em> results must be rounded to the representable value nearest to the infinitely precise result; if the two nearest representable values are equally near, the one with its least significant bit zero is chosen. This is the IEEE 754 standard's default rounding mode known as <em>round to nearest</em>.<p>
<a name="10346"></a>
The language uses <em>round toward zero</em> when converting a floating value to an integer <a href="conversions.doc.html#25363">(&#167;5.1.3)</a>, which acts, in this case, as though the number were truncated, discarding the mantissa bits. Rounding toward zero chooses at its result the format's value closest to and no greater in magnitude than the infinitely precise result.<p>
<a name="9290"></a>
Floating-point operators produce no exceptions <a href="exceptions.doc.html#44043">(&#167;11)</a>. An operation that overflows produces a signed infinity, an operation that underflows produces a denormalized value or a signed zero, and an operation that has no mathematically definite result produces NaN. All numeric operations with NaN as an operand produce NaN as a result. As has already been described, NaN is unordered, so a numeric comparison operation involving one or two NaNs returns <code>false</code> and any <code>!=</code> comparison involving NaN returns <code>true</code>, including <code>x!=x</code> when <code>x</code> is NaN.<p>
<a name="9291"></a>
The example program:
<blockquote><pre>class Test {
public static void main(String[] args) {
// An example of overflow:
double d = 1e308;
System.out.print("overflow produces infinity: ");
System.out.println(d + "*10==" + d*10);
// An example of gradual underflow:
d = 1e-305 * Math.PI;
System.out.print("gradual underflow: " + d + "\n &#32; &#32; &#32;");
for (int i = 0; i &lt; 4; i++)
System.out.print(" " + (d /= 100000));
System.out.println();
// An example of NaN:
System.out.print("0.0/0.0 is Not-a-Number: ");
d = 0.0/0.0;
System.out.println(d);
// An example of inexact results and rounding:
System.out.print("inexact results with float:");
for (int i = 0; i &lt; 100; i++) {
float z = 1.0f / i;
if (z * i != 1.0f)
System.out.print(" " + i);
}
System.out.println();
// Another example of inexact results and rounding:
System.out.print("inexact results with double:");
for (int i = 0; i &lt; 100; i++) {
double z = 1.0 / i;
if (z * i != 1.0)
System.out.print(" " + i);
}
System.out.println();
// An example of cast to integer rounding:
System.out.print("cast to int rounds toward 0: ");
d = 12345.6;
System.out.println((int)d + " " + (int)(-d));
}
}
</pre></blockquote><a name="23297"></a>
produces the output:<p>
<blockquote><pre>overflow produces infinity: 1.0e+308*10==Infinity
gradual underflow: 3.141592653589793E-305
3.1415926535898E-310 3.141592653E-315 3.142E-320 0.0
0.0/0.0 is Not-a-Number: NaN
inexact results with float: 0 41 47 55 61 82 83 94 97
inexact results with double: 0 49 98
cast to int rounds toward 0: 12345 -12345
</pre></blockquote>
<a name="22309"></a>
This example demonstrates, among other things, that gradual underflow can result in a gradual loss of precision.
<a name="11717"></a>
The results when <code>i</code> is <code>0</code> involve division by zero, so that <code>z</code> becomes positive infinity, and <code>z</code> <code>*</code> <code>0</code> is NaN, which is not equal to <code>1.0</code>.
</pre></blockquote><a name="11527"></a>
<h3>4.2.5 The <code>boolean</code> Type and <code>boolean</code> Values</h3>
<a name="9295"></a>
The <code>boolean</code> type represents a logical quantity with two possible values, indicated by the literals <code>true</code> and <code>false</code> <a href="lexical.doc.html#49652">(&#167;3.10.3)</a>. The boolean operators are:<p>
<ul><a name="17733"></a>
<li>The relational operators <code>==</code> and <code>!=</code> <a href="expressions.doc.html#54508">(&#167;15.21.2)</a>
<a name="17734"></a>
<li>The logical-complement operator <code>!</code> <a href="expressions.doc.html#13350">(&#167;15.15.6)</a>
<a name="17736"></a>
<li>The logical operators <code>&amp;</code>, <code>^</code>, and <code>|</code> <a href="expressions.doc.html#5242">(&#167;15.22.2)</a>
<a name="17737"></a>
<li>The conditional-and and conditional-or operators <code>&amp;&amp;</code> <a href="expressions.doc.html#5247">(&#167;15.23)</a> and <code>||</code> <a href="expressions.doc.html#54532">(&#167;15.24)</a>
<a name="19467"></a>
<li>The conditional operator <code>? :</code> <a href="expressions.doc.html#290293">(&#167;15.25)</a>
<a name="21871"></a>
<li>The string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a>, which, when given a <code>String</code> operand and a boolean operand, will convert the boolean operand to a <code>String</code> (either <code>"true"</code> or <code>"false"</code>), and then produce a newly created <code>String</code> that is the concatenation of the two strings
</ul><a name="17738"></a>
Boolean expressions determine the control flow in several kinds of statements:<p>
<ul><a name="17742"></a>
<li>The <code>if</code> statement <a href="statements.doc.html#5991">(&#167;14.9)</a>
<a name="17743"></a>
<li>The <code>while</code> statement <a href="statements.doc.html#237277">(&#167;14.11)</a>
<a name="17745"></a>
<li>The <code>do</code> statement <a href="statements.doc.html#6045">(&#167;14.12)</a>
<a name="17747"></a>
<li>The <code>for</code> statement <a href="statements.doc.html#24588">(&#167;14.13)</a>
</ul><a name="48454"></a>
A <code>boolean</code> expression also determines which subexpression is evaluated in the conditional <code>?&#32;:</code> operator <a href="expressions.doc.html#290293">(&#167;15.25)</a>.<p>
<a name="48458"></a>
Only <code>boolean</code> expressions can be used in control flow statements and as the first operand of the conditional operator <code>?&#32;:</code>. An integer <code>x</code> can be converted to a <code>boolean</code>, following the C language convention that any nonzero value is <code>true</code>, by the expression <code>x!=0</code>. An object reference <code>obj</code> can be converted to a <code>boolean</code>, following &#32;the C language convention that any reference other than <code>null</code> is <code>true</code>, by the expression <code>obj!=null</code>.<p>
<a name="9299"></a>
A cast of a <code>boolean</code> value to type <code>boolean</code> is allowed <a href="conversions.doc.html#25209">(&#167;5.1.1)</a>; no other casts on type <code>boolean</code> are allowed. A <code>boolean</code> can be converted to a string by string conversion <a href="conversions.doc.html#186035">(&#167;5.4)</a>.<p>
<a name="9317"></a>
<h2>4.3 Reference Types and Values</h2>
<a name="9664"></a>
There are three kinds of <em>reference types</em>: class types <a href="classes.doc.html#3857">(&#167;8)</a>, interface types <a href="interfaces.doc.html#238678">(&#167;9)</a>, and array types <a href="arrays.doc.html#27803">(&#167;10)</a>.<p>
<ul><pre>
<i>ReferenceType:
ClassOrInterfaceType
ArrayType
ClassOrInterfaceType:
ClassType
InterfaceType
ClassType:
TypeName
InterfaceType:
TypeName
ArrayType:
Type<code> [ ]
</i>
</code></pre></ul><a name="9678"></a>
Names are described in <a href="names.doc.html#48086">&#167;6</a>; type names in <a href="names.doc.html#106941">&#167;6.5</a> and, specifically, <a href="names.doc.html#73064">&#167;6.5.5</a>.<p>
<a name="87599"></a>
The sample code:
<blockquote><pre>class Point { int[] metrics; }
interface Move { void move(int deltax, int deltay); }
</pre></blockquote><a name="11032"></a>
declares a class type <code>Point</code>, an interface type <code>Move</code>, and uses an array type <code>int[]</code> (an array of <code>int</code>) to declare the field <code>metrics</code> of the class <code>Point</code>.<p>
<a name="12028"></a>
<h3>4.3.1 Objects</h3>
<a name="86707"></a>
An <em>object</em> is a <em>class</em> <em>instance</em> or an array.<p>
<a name="106237"></a>
The reference values (often just <em>references</em>) are <em>pointers </em>to these objects, and a special null reference, which refers to no object.<p>
<a name="49853"></a>
A class instance is explicitly created by a class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>. An array is explicitly created by an array creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>.<p>
<a name="49899"></a>
A new class instance is implicitly created when the string concatenation operator + <a href="expressions.doc.html#39990">(&#167;15.18.1)</a> is used in an expression, resulting in a new object of type <code>String</code> (<a href="typesValues.doc.html#26992">&#167;4.3.3</a>). A new array object is implicitly created when an array initializer expression <a href="arrays.doc.html#11358">(&#167;10.6)</a> is evaluated; this can occur when a class or interface is initialized <a href="execution.doc.html#44557">(&#167;12.4)</a>, when a new instance of a class is created <a href="expressions.doc.html#41147">(&#167;15.9)</a>, or when a local variable declaration statement is executed <a href="statements.doc.html#5920">(&#167;14.4)</a>.<p>
<a name="49960"></a>
Many of these cases are illustrated in the following example:
<blockquote><pre>class Point {
int x, y;
Point() { System.out.println("default"); }
Point(int x, int y) { this.x = x; this.y = y; }
// A Point instance is explicitly created at class initialization time:
static Point origin = new Point(0,0);
// A String can be implicitly created by a + operator:
public String toString() {
return "(" + x + "," + y + ")";
}
}
class Test {
public static void main(String[] args) {
// A Point is explicitly created using newInstance:
Point p = null;
try {
p = (Point)Class.forName("Point").newInstance();
} catch (Exception e) {
System.out.println(e);
}
// An array is implicitly created by an array constructor:
Point a[] = { new Point(0,0), new Point(1,1) };
// Strings are implicitly created by + operators:
System.out.println("p: " + p);
System.out.println("a: { " + a[0] + ", "
&#32;+ a[1] + " }");
// An array is explicitly created by an array creation expression:
String sa[] = new String[2];
sa[0] = "he"; sa[1] = "llo";
System.out.println(sa[0] + sa[1]);
}
}
</pre></blockquote><a name="87328"></a>
which produces the output:<p>
<blockquote><pre>default
p: (0,0)
a: { (0,0), (1,1) }
hello
</pre></blockquote><a name="49965"></a>
The operators on references to objects are:<p>
<ul><a name="31321"></a>
<li>Field access, using either a qualified name <a href="names.doc.html#104285">(&#167;6.6)</a> or a field access expression <a href="expressions.doc.html#41267">(&#167;15.11)</a>
<a name="31328"></a>
<li>Method invocation <a href="expressions.doc.html#20448">(&#167;15.12)</a>
<a name="31378"></a>
<li>The cast operator (<a href="conversions.doc.html#20232">&#167;5.5</a>, <a href="expressions.doc.html#238146">&#167;15.16</a>)
<a name="31345"></a>
<li>The string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a>, which, when given a <code>String</code> operand and a reference, will convert the reference to a <code>String</code> by invoking the <code>toString</code> method of the referenced object (using <code>"null"</code> if either the reference or the result of <code>toString</code> is a null reference), and then will produce a newly created <code>String</code> that is the concatenation of the two strings
<a name="31399"></a>
<li>The <code>instanceof</code> operator <a href="expressions.doc.html#80289">(&#167;15.20.2)</a>
<a name="31306"></a>
<li>The reference equality operators <code>==</code> and <code>!=</code> <a href="expressions.doc.html#236163">(&#167;15.21.3)</a>
<a name="19595"></a>
<li>The conditional operator <code>?&#32;:</code> <a href="expressions.doc.html#290293">(&#167;15.25)</a>.
</ul><a name="28239"></a>
There may be many references to the same object. Most objects have state, stored in the fields of objects that are instances of classes or in the variables that are the components of an array object. If two variables contain references to the same object, the state of the object can be modified using one variable's reference to the object, and then the altered state can be observed through the reference in the other variable.<p>
<a name="87600"></a>
The example program:
<blockquote><pre>class Value { int val; }
class Test {
public static void main(String[] args) {
int i1 = 3;
int i2 = i1;
i2 = 4;
System.out.print("i1==" + i1);
System.out.println(" but i2==" + i2);
Value v1 = new Value();
v1.val = 5;
Value v2 = v1;
v2.val = 6;
System.out.print("v1.val==" + v1.val);
System.out.println(" and v2.val==" + v2.val);
}
}
</pre></blockquote><a name="11050"></a>
produces the output:<p>
<blockquote><pre>i1==3 but i2==4
v1.val==6 and v2.val==6
</pre></blockquote><a name="11053"></a>
because <code>v1.val</code> and <code>v2.val</code> reference the same instance variable <a href="typesValues.doc.html#28536">(&#167;4.5.3)</a> in the one <code>Value</code> object created by the only <code>new</code> expression, while <code>i1</code> and <code>i2</code> are different variables.<p>
<a name="17783"></a>
See <a href="arrays.doc.html#27803">&#167;10</a> and <a href="expressions.doc.html#46168">&#167;15.10</a> for examples of the creation and use of arrays.
<a name="17053"></a>
Each object has an associated lock <a href="memory.doc.html#28460">(&#167;17.13)</a>, which is used by <code>synchronized</code> methods <a href="classes.doc.html#78188">(&#167;8.4.3)</a> and the <code>synchronized</code> statement <a href="statements.doc.html#255769">(&#167;14.18)</a> to provide control over concurrent access to state by multiple threads (<a href="memory.doc.html#28457">&#167;17.12</a>).<p>
<a name="11055"></a>
<h3>4.3.2 The Class Object</h3>
<a name="26999"></a>
The class <code>Object</code> is a superclass <a href="classes.doc.html#15372">(&#167;8.1)</a> of all other classes. A variable of type <code>Object</code> can hold a reference to any object, whether it is an instance of a class or an array <a href="arrays.doc.html#27803">(&#167;10)</a>. All class and array types inherit the methods of class <code>Object</code>, which are summarized here:<p>
<blockquote><pre>package java.lang;
<a name="45609"></a>
public class Object {
<a name="51634"></a> public final Class getClass() { . . . }
<a name="51635"></a> public String toString() { . . . }
<a name="51636"></a> public boolean equals(Object obj) { . . . }
<a name="51637"></a> public int hashCode() { . . . }
<a name="51638"></a> protected Object clone()
<a name="86088"></a> throws CloneNotSupportedException { . . . }
<a name="87378"></a> public final void wait()
throws IllegalMonitorStateException,
InterruptedException { . . . }
<a name="51641"></a> public final void wait(long millis)
<a name="87381"></a> throws IllegalMonitorStateException,
<a name="87383"></a> InterruptedException { . . . }
<a name="51642"></a> public final void wait(long millis, int nanos) { . . . }
<a name="87385"></a> throws IllegalMonitorStateException,
<a name="87386"></a> InterruptedException { . . . }
<a name="87373"></a> public final void notify() { . . . }
<a name="87374"></a> throws IllegalMonitorStateException
<a name="87387"></a> public final void notifyAll() { . . . }
<a name="87389"></a> throws IllegalMonitorStateException
<a name="51644"></a> protected void finalize()
<a name="86090"></a> throws Throwable { . . . }
<a name="51645"></a>}
</pre></blockquote><a name="45610"></a>
The members of <code>Object</code> are as follows:<p>
<ul><a name="12048"></a>
<li>The method <code>getClass</code> returns the <code>Class</code> object that represents the class of the object. A <code>Class</code> object exists for each reference type. It can be used, for example, to discover the fully qualified name of a class, its members, its immediate superclass, and any interfaces that it implements. A class method that is declared <code>synchronized</code> <a href="classes.doc.html#260369">(&#167;8.4.3.6)</a> synchronizes on the lock associated with the <code>Class</code> object of the class.
<a name="12066"></a>
<li>The method <code>toString</code> returns a <code>String</code> representation of the object.
<a name="12104"></a>
<li>The methods <code>equals</code> and <code>hashCode</code> are very useful in hashtables such as <code>java.util.Hashtable</code>. The method <code>equals</code> defines a notion of object equality, which is based on value, not reference, comparison.
<a name="12115"></a>
<li>The method <code>clone</code> is used to make a duplicate of an object.
<a name="12116"></a>
<li>The methods <code>wait</code>, <code>notify</code>, and <code>notifyAll</code> are used in concurrent programming using threads, as described in <a href="memory.doc.html#26250">&#167;17</a>.
<a name="12117"></a>
<li>The method <code>finalize</code> is run just before an object is destroyed and is described in <a href="execution.doc.html#44748">&#167;12.6</a>.
</ul><a name="26992"></a>
<h3>4.3.3 The Class String</h3>
<a name="27000"></a>
Instances of class <code>String</code> represent sequences of Unicode characters. A &#32;<code>String</code> object has a constant (unchanging) value. String literals <a href="lexical.doc.html#101083">(&#167;3.10.5)</a> are references to instances of class <code>String</code>.<p>
<a name="52188"></a>
The string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a> implicitly creates a new <code>String</code> object.<p>
<a name="97058"></a>
<h3>4.3.4 When Reference Types Are the Same</h3>
<a name="96897"></a>
Two reference types are the <em>same compile-time type</em> if they have the same binary name <a href="binaryComp.doc.html#44909">(&#167;13.1)</a>, in which case they are sometimes said to be the <em>same class</em> or the <em>same interface</em>.<p>
<a name="97070"></a>
At run time, several reference types with the same binary name may be loaded simultaneously by different class loaders. These types may or may not represent the same type declaration. Even if two such types do represent the same type declaration, they are considered distinct.<p>
<a name="96917"></a>
Two reference types are the <em>same run-time type</em> if:<p>
<ul><a name="86567"></a>
<li>They are both class or both interface types, are loaded by the same class loader, and have the same binary name <a href="binaryComp.doc.html#44909">(&#167;13.1)</a>, in which case they are sometimes said to be the <em>same run-time class</em> or the <em>same run-time interface</em>.
<a name="86576"></a>
<li>They are both array types, and their component types are the same run-time type<a href="arrays.doc.html#27803">(&#167;10)</a>.
</ul><a name="25948"></a>
<h2>4.4 Where Types Are Used</h2>
<a name="52309"></a>
Types are used when they appear in declarations or in certain expressions.<p>
<a name="85893"></a>
The following code fragment contains one or more instances of most kinds of usage of a type:
<blockquote><pre>import java.util.Random;
class MiscMath {
int divisor;
MiscMath(int divisor) {
this.divisor = divisor;
}
float ratio(long l) {
try {
l /= divisor;
} catch (Exception e) {
if (e instanceof ArithmeticException)
l = Long.MAX_VALUE;
else
l = 0;
}
return (float)l;
}
double gausser() {
Random r = new Random();
double[] val = new double[2];
val[0] = r.nextGaussian();
val[1] = r.nextGaussian();
return (val[0] + val[1]) / 2;
}
}
</pre></blockquote><a name="53860"></a>
In this example, types are used in declarations of the following:<p>
<ul><a name="53864"></a>
<li>Imported types <a href="packages.doc.html#70209">(&#167;7.5)</a>; here the type <code>Random</code>, imported from the type<code> java.util.Random</code> of the package <code>java.util</code>, is declared
<a name="49983"></a>
<li>Fields, which are the class variables and instance variables of classes <a href="classes.doc.html#40898">(&#167;8.3)</a>, and constants of interfaces <a href="interfaces.doc.html#78642">(&#167;9.3)</a>; here the field <code>divisor</code> in the class <code>MiscMath</code> &#32;is declared to be of type <code>int</code>
<a name="49990"></a>
<li>Method parameters <a href="classes.doc.html#38698">(&#167;8.4.1)</a>; here the parameter <code>l</code> of the method <code>ratio</code> is declared to be of type <code>long</code>
<a name="52378"></a>
<li>Method results <a href="classes.doc.html#40420">(&#167;8.4)</a>; here the result of the method <code>ratio</code> is declared to be of type <code>float</code>, and the result of the method <code>gausser</code> is declared to be of type <code>double</code>
<a name="38145"></a>
<li>Constructor parameters <a href="classes.doc.html#29488">(&#167;8.8.1)</a>; here the parameter of the constructor for<code> MiscMath</code> is declared to be of type <code>int</code>
<a name="12250"></a>
<li>Local variables (<a href="statements.doc.html#5920">&#167;14.4</a>, <a href="statements.doc.html#24588">&#167;14.13</a>); the local variables <code>r</code> and <code>val</code> of the method <code>gausser</code> are declared to be of types <code>Random</code> and <code>double[]</code> (array of <code>double</code>)
<a name="52411"></a>
<li>Exception handler parameters <a href="statements.doc.html#79311">(&#167;14.19)</a>; here the exception handler parameter <code>e</code> of the <code>catch</code> clause is declared to be of type <code>Exception</code>
</ul><a name="25979"></a>
and in expressions of the following kinds:<p>
<ul><a name="52468"></a>
<li>Class instance creations <a href="expressions.doc.html#41147">(&#167;15.9)</a>; here a local variable <code>r</code> of method <code>gausser</code> is initialized by a class instance creation expression that uses the type <code>Random </code>
<a name="96936"></a>
<li>Array creations <a href="expressions.doc.html#46168">(&#167;15.10)</a>; here the local variable <code>val</code> of method <code>gausser</code> is initialized by an array creation expression that creates an array of <code>double</code> with size 2
<a name="52427"></a>
<li>Casts <a href="expressions.doc.html#238146">(&#167;15.16)</a>; here the <code>return</code> statement of the method <code>ratio</code> uses the <code>float</code> type in a cast
<a name="25987"></a>
<li>The <code>instanceof</code> operator <a href="expressions.doc.html#80289">(&#167;15.20.2)</a>; here the <code>instanceof</code> operator tests whether <code>e</code> is assignment compatible with the type <code>ArithmeticException</code>
</ul><a name="18470"></a>
<h2>4.5 Variables</h2>
<a name="10872"></a>
A variable is a storage location and has an associated type, sometimes called its <em>compile-time type</em>, that is either a primitive type <a href="typesValues.doc.html#85587">(&#167;4.2)</a> or a reference type <a href="typesValues.doc.html#9317">(&#167;4.3)</a>. A variable always contains a value that is assignment compatible <a href="conversions.doc.html#184206">(&#167;5.2)</a> with its type. A variable's value is changed by an assignment <a href="expressions.doc.html#5281">(&#167;15.26)</a> or by a prefix or postfix <code>++</code> (increment) or <code>--</code> (decrement) operator (<a href="expressions.doc.html#39438">&#167;15.14.1</a>, <a href="expressions.doc.html#4987">&#167;15.14.2</a>, <a href="expressions.doc.html#39547">&#167;15.15.1</a>, <a href="expressions.doc.html#239136">&#167;15.15.2</a>).<p>
<a name="24555"></a>
Compatibility of the value of a variable with its type is guaranteed by the design of the Java programming language. Default values are compatible <a href="typesValues.doc.html#96595">(&#167;4.5.5)</a> and all assignments to a variable are checked for assignment compatibility <a href="conversions.doc.html#184206">(&#167;5.2)</a>, usually at compile time, but, in a single case involving arrays, a run-time check is made <a href="arrays.doc.html#11430">(&#167;10.10)</a>.<p>
<a name="28344"></a>
<h3>4.5.1 Variables of Primitive Type</h3>
<a name="17088"></a>
A variable of a primitive type always holds a value of that exact primitive type.<p>
<a name="28345"></a>
<h3>4.5.2 Variables of Reference Type</h3>
<a name="10877"></a>
A variable of reference type can hold either of the following:<p>
<ul><a name="52494"></a>
<li>A null reference
<a name="52496"></a>
<li>A reference to any object <a href="typesValues.doc.html#9317">(&#167;4.3)</a> whose class <a href="typesValues.doc.html#24887">(&#167;4.5.6)</a> is assignment compatible <a href="conversions.doc.html#184206">(&#167;5.2)</a> with the type of the variable
</ul><a name="28536"></a>
<h3>4.5.3 Kinds of Variables</h3>
<a name="10883"></a>
There are seven kinds of variables:<p>
<ol>
<a name="10884"></a>
<li>A <em>class variable</em> is a field declared using the keyword <code>static</code> within a class declaration <a href="classes.doc.html#37544">(&#167;8.3.1.1)</a>, or with or without the keyword <code>static</code> within an interface declaration <a href="interfaces.doc.html#78642">(&#167;9.3)</a>. A class variable is created when its class or interface is prepared <a href="execution.doc.html#47979">(&#167;12.3.2)</a> and is initialized to a default value <a href="typesValues.doc.html#96595">(&#167;4.5.5)</a>. The class variable effectively ceases to exist when its class or interface is unloaded <a href="execution.doc.html#74294">(&#167;12.7)</a>.
<a name="51516"></a>
<li>An <em>instance variable</em> is a field declared within a class declaration without using the keyword <code>static</code> <a href="classes.doc.html#37544">(&#167;8.3.1.1)</a>. If a class <i>T</i> has a field <i>a</i> that is an instance variable, then a new instance variable <i>a</i> is created and initialized to a default value <a href="typesValues.doc.html#96595">(&#167;4.5.5)</a> as part of each newly created object of class <i>T</i> or of any class that is a subclass of <i>T</i> <a href="classes.doc.html#262560">(&#167;8.1.3)</a>. The instance variable effectively ceases to exist when the object of which it is a field is no longer referenced, after any necessary finalization of the object <a href="execution.doc.html#44748">(&#167;12.6)</a> has been completed.
<a name="10895"></a>
<li><em>Array components</em> are unnamed variables that are created and initialized to default values <a href="typesValues.doc.html#96595">(&#167;4.5.5)</a> whenever a new object that is an array is created <a href="expressions.doc.html#46168">(&#167;15.10)</a>. The array components effectively cease to exist when the array is no longer referenced. See <a href="arrays.doc.html#27803">&#167;10</a> for a description of arrays.
<a name="24632"></a>
<li><em>Method parameters</em> <a href="classes.doc.html#38698">(&#167;8.4.1)</a> name argument values passed to a method. For every parameter declared in a method declaration, a new parameter variable is created each time that method is invoked <a href="expressions.doc.html#20448">(&#167;15.12)</a>. The new variable is initialized with the corresponding argument value from the method invocation. The method parameter effectively ceases to exist when the execution of the body of the method is complete.
<a name="24657"></a>
<li><em>Constructor parameters</em> <a href="classes.doc.html#29488">(&#167;8.8.1)</a> name argument values passed to a constructor. For every parameter declared in a constructor declaration, a new parameter variable is created each time a class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a> or explicit constructor invocation <a href="classes.doc.html#78435">(&#167;8.8.5)</a> invokes that constructor. The new variable is initialized with the corresponding argument value from the creation expression or constructor invocation. The constructor parameter effectively ceases to exist when the execution of the body of the constructor is complete.
<a name="10903"></a>
<li>An <em>exception-handler parameter</em> is created each time an exception is caught by a <code>catch</code> clause of a <code>try</code> statement <a href="statements.doc.html#79311">(&#167;14.19)</a>. The new variable is initialized with the actual object associated with the exception (<a href="exceptions.doc.html#44153">&#167;11.3</a>, <a href="statements.doc.html#237350">&#167;14.17</a>). The exception-handler parameter effectively ceases to exist when execution of the block associated with the <code>catch</code> clause is complete.
<a name="24801"></a>
<li><em>Local variables</em> are declared by local variable declaration statements <a href="statements.doc.html#5920">(&#167;14.4)</a>. Whenever the flow of control enters a block <a href="statements.doc.html#246838">(&#167;14.2)</a> or <code>for</code> statement <a href="statements.doc.html#24588">(&#167;14.13)</a>, a new variable is created for each local variable declared in a local variable declaration statement immediately contained within that block or <code>for</code> statement. A local variable declaration statement may contain an expression which initializes the variable. The local variable with an initializing expression is not initialized, however, until the local variable declaration statement that declares it is executed. (The rules of definite assignment <a href="defAssign.doc.html#25979">(&#167;16)</a> prevent the value of a local variable from being used before it has been initialized or otherwise assigned a value.) The local variable effectively ceases to exist when the execution of the block or <code>for</code> statement is complete.
</ol>
Were it not for one exceptional situation, a local variable could always be regarded as being created when its local variable declaration statement is executed. The exceptional situation involves the <code>switch</code> statement <a href="statements.doc.html#35518">(&#167;14.10)</a>, where it is possible for control to enter a block but bypass execution of a local variable declaration statement. Because of the restrictions imposed by the rules of definite assignment <a href="defAssign.doc.html#">(&#167;16)</a>, however, the local variable declared by such a bypassed local variable declaration statement cannot be used before it has been definitely assigned a value by an assignment expression <a href="expressions.doc.html#5281">(&#167;15.26)</a>.
<a name="24836"></a>
The following example contains several different kinds of variables:
<blockquote><pre>
class Point {
static int numPoints; // numPoints is a class variable
int x, y; // x and y are instance variables
int[] w = new int[10]; // w[0] is an array component
int setX(int x) { // x is a method parameter
int oldx = this.x; // oldx is a local variable
this.x = x;
return oldx;
}
}
</pre></blockquote><a name="10931"></a>
<h3>4.5.4 final Variables</h3>
<a name="96639"></a>
A variable can be declared <code>final</code>. A final variable may only be assigned to once. It is a compile time error if a final variable is assigned to unless it is definitely unassigned <a href="defAssign.doc.html#25979">(&#167;16)</a> immediately prior to the assignment.<p>
<a name="96971"></a>
A <em>blank final</em> is a final variable whose declaration lacks an initializer. <p>
<a name="96975"></a>
Once a <code>final</code> variable has been assigned, it always contains the same value. If a <code>final</code> variable holds a reference to an object, then the state of the object may be changed by operations on the object, but the variable will always refer to the same object. This applies also to arrays, because arrays are objects; if a <code>final</code> variable holds a reference to an array, then the components of the array may be changed by operations on the array, but the variable will always refer to the same array.<p>
<a name="103462"></a>
Declaring a variable <code>final</code> can serve as useful documentation that its value will not change and can help avoid programming errors.
<a name="96976"></a>
<p>In the example:
<blockquote><pre>class Point {
int x, y;
int useCount;
Point(int x, int y) { this.x = x; this.y = y; }
final static Point origin = new Point(0, 0);
}
</pre></blockquote><a name="96596"></a>
the class <code>Point</code> declares a <code>final</code> class variable <code>origin</code>. The <code>origin</code> variable holds a reference to an object that is an instance of class <code>Point</code> whose coordinates are (0, 0). The value of the variable <code>Point.origin</code> can never change, so it always refers to the same <code>Point</code> object, the one created by its initializer. However, an operation on this <code>Point</code> object might change its state-for example, modifying its <code>useCount</code> or even, misleadingly, its <code>x</code> or <code>y</code> coordinate.<p>
<a name="96595"></a>
<h3>4.5.5 Initial Values of Variables</h3>
<a name="10935"></a>
Every variable in a program must have a value before its value is used:<p>
<ul><a name="10946"></a>
<li>Each class variable, instance variable, or array component is initialized with a <em>default value</em> when it is created (<a href="expressions.doc.html#41147">&#167;15.9</a>, <a href="expressions.doc.html#46168">&#167;15.10</a>):
<ul>
<a name="10947"></a>
<li>For type <code>byte</code>, the default value is zero, that is, the value of <code>(byte)0</code>.
<a name="10948"></a>
<li>For type <code>short</code>, the default value is zero, that is, the value of <code>(short)0</code>.
<a name="10949"></a>
<li>For type <code>int</code>, the default value is zero, that is, <code>0</code>.
<a name="10950"></a>
<li>For type <code>long</code>, the default value is zero, that is, <code>0L</code>.
<a name="10951"></a>
<li>For type <code>float</code>, the default value is positive zero, that is, <code>0.0f</code>.
<a name="46977"></a>
<li>For type <code>double</code>, the default value is positive zero, that is, <code>0.0d</code>.
<a name="46978"></a>
<li>For type <code>char</code>, the default value is the null character, that is, <code>'\u0000'</code>.
<a name="46979"></a>
<li>For type <code>boolean</code>, the default value is <code>false</code>.
<a name="10955"></a>
<li>For all reference types <a href="typesValues.doc.html#9317">(&#167;4.3)</a>, the default value is <code>null</code>.
</ul>
<a name="11353"></a>
<li>Each method parameter <a href="classes.doc.html#38698">(&#167;8.4.1)</a> is initialized to the corresponding argument value provided by the invoker of the method <a href="expressions.doc.html#20448">(&#167;15.12)</a>.
<a name="38160"></a>
<li>Each constructor parameter <a href="classes.doc.html#29488">(&#167;8.8.1)</a> is initialized to the corresponding argument value provided by a class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a> or explicit constructor invocation <a href="classes.doc.html#78435">(&#167;8.8.5)</a>.
<a name="11354"></a>
<li>An exception-handler parameter <a href="statements.doc.html#79311">(&#167;14.19)</a> is initialized to the thrown object representing the exception (<a href="exceptions.doc.html#44153">&#167;11.3</a>, <a href="statements.doc.html#237350">&#167;14.17</a>).
<a name="11569"></a>
<li>A local variable (<a href="statements.doc.html#5920">&#167;14.4</a>, <a href="statements.doc.html#24588">&#167;14.13</a>) must be explicitly given a value before it is used, by either initialization <a href="statements.doc.html#5920">(&#167;14.4)</a> or assignment <a href="expressions.doc.html#5281">(&#167;15.26)</a>, in a way that can be verified by the compiler using the rules for definite assignment <a href="defAssign.doc.html#25979">(&#167;16)</a>.
</ul><a name="30962"></a>
The example program:<p>
<blockquote><pre>class Point {
static int npoints;
int x, y;
Point root;
}
class Test {
public static void main(String[] args) {
System.out.println("npoints=" + Point.npoints);
Point p = new Point();
System.out.println("p.x=" + p.x + ", p.y=" + p.y);
System.out.println("p.root=" + p.root);
}
}
</pre></blockquote><a name="12324"></a>
prints:<p>
<blockquote><pre>npoints=0
p.x=0, p.y=0
p.root=null
</pre></blockquote><a name="24882"></a>
illustrating the default initialization of <code>npoints</code>, which occurs when the class <code>Point</code> is prepared <a href="execution.doc.html#47979">(&#167;12.3.2)</a>, and the default initialization of <code>x</code>, <code>y</code>, and <code>root</code>, which occurs when a new <code>Point</code> is instantiated. See <a href="execution.doc.html#44410">&#167;12</a> for a full description of all aspects of loading, linking, and initialization of classes and interfaces, plus a description of the instantiation of classes to make new class instances.<p>
<a name="24887"></a>
<h3>4.5.6 Types, Classes, and Interfaces</h3>
<a name="24888"></a>
In the Java programming language, every variable and every expression has a type that can be determined at compile time. The type may be a primitive type or a reference type. Reference types include class types and interface types. Reference types are introduced by type declarations, which include class declarations <a href="classes.doc.html#15372">(&#167;8.1)</a> and interface declarations <a href="interfaces.doc.html#35470">(&#167;9.1)</a>. We often use the term <em>type</em> to refer to either a class or an interface.<p>
<a name="97724"></a>
Every object belongs to some particular class: the class that was mentioned in the creation expression that produced the object, the class whose <code>Class</code> object was used to invoke a reflective method to produce the object, or the <code>String</code> class for objects implicitly created by the string concatenation operator <code>+</code> <a href="expressions.doc.html#39990">(&#167;15.18.1)</a>. This class is called the <em>class of the object</em>. (Arrays also have a class, as described at the end of this section.) An object is said to be an instance of its class and of all superclasses of its class.<p>
<a name="96875"></a>
Sometimes a variable or expression is said to have a "run-time type". This refers to the class of the object referred to by the value of the variable or expression at run time, assuming that the value is not <code>null</code>. <p>
<a name="96880"></a>
The compile time type of a variable is always declared, and the compile time type of an expression can be deduced at compile time. The compile time type limits the possible values that the variable can hold or the expression can produce at run time. If a run-time value is a reference that is not <code>null</code>, it refers to an object or array that has a class, and that class will necessarily be compatible with the compile-time type.<p>
<a name="24895"></a>
Even though a variable or expression may have a compile-time type that is an interface type, there are no instances of interfaces. A variable or expression whose type is an interface type can reference any object whose class implements <a href="classes.doc.html#34031">(&#167;8.1.4)</a> that interface.<p>
<a name="24918"></a>
Here is an example of creating new objects and of the distinction between the type of a variable and the class of an object:
<blockquote><pre>public interface Colorable {
void setColor(byte r, byte g, byte b);
}
class Point { int x, y; }
class ColoredPoint extends Point implements Colorable {
byte r, g, b;
public void setColor(byte rv, byte gv, byte bv) {
r = rv; g = gv; b = bv;
}
}
class Test {
public static void main(String[] args) {
Point p = new Point();
ColoredPoint cp = new ColoredPoint();
p = cp;
Colorable c = cp;
}
}
</pre></blockquote><a name="52612"></a>
In this example:<p>
<ul><a name="52613"></a>
<li>The local variable <code>p</code> of the method <code>main</code> of class <code>Test</code> has type <code>Point</code> and is initially assigned a reference to a new instance of class <code>Point</code>.
<a name="52614"></a>
<li>The local variable <code>cp</code> similarly has as its type <code>ColoredPoint</code>, and is initially assigned a reference to a new instance of class <code>ColoredPoint</code>.
<a name="52615"></a>
<li>The assignment of the value of <code>cp</code> to the variable <code>p</code> causes <code>p</code> to hold a reference to a <code>ColoredPoint</code> object. This is permitted because <code>ColoredPoint</code> is a subclass of <code>Point</code>, so the class <code>ColoredPoint</code> is assignment compatible <a href="conversions.doc.html#184206">(&#167;5.2)</a> with the type <code>Point</code>. A <code>ColoredPoint</code> object includes support for all the methods of a <code>Point</code>. In addition to its particular fields <code>r</code>, <code>g</code>, and <code>b</code>, it has the fields of class <code>Point</code>, namely <code>x</code> and <code>y</code>.
<a name="52586"></a>
<li>The local variable <code>c</code> has as its type the interface type <code>Colorable</code>, so it can hold a reference to any object whose class implements <code>Colorable</code>; specifically, it can hold a reference to a <code>ColoredPoint</code>.
<a name="24972"></a>
<li>Note that an expression such as "<code>new Colorable()</code>" is not valid because it is not possible to create an instance of an interface, only of a class.
</ul><a name="24976"></a>
Every array also has a class; the method <code>getClass</code>, when invoked for an array object, will return a class object (of class <code>Class</code>) that represents the class of the array. <p>
<a name="103397"></a>
The classes for arrays have strange names that are not valid identifiers; for example, the class for an array of <code>int</code> components has the name "<code>[I</code>" and so the value of the expression:
<blockquote><pre>new int[10].getClass().getName()
</pre></blockquote><a name="103415"></a>
is the string <code>"[I"</code>; see the specification of <code>Class.getName</code> for details.<p>
<hr>
<table border="0" width="100%">
<tr>
<td><a href="jTOC.doc.html">Contents</a> | <a href="lexical.doc.html">Prev</a> | <a href="conversions.doc.html">Next</a> | <a href="jIX.fm.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">Second Edition</font></td></tr></table>
<i><a href="jcopyright.doc.html">Copyright</a> &#169 2000 Sun Microsystems, Inc.
All rights reserved</i>
<br>
Please send any comments or corrections via our <a href="http://developers.sun.com/contact/feedback.jsp?&category=doc&mailsubject=Java%20Language%20Specification%20Feedback">feedback form</a>
</font>
<script language="JavaScript" src="/js/omi/jsc/s_code_remote.js"></script></body></html>
<html>
<head>
<title> Names</title>
<meta name="collection" content="exclude">
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="jTOC.doc.html">Contents</a> | <a href="conversions.doc.html">Prev</a> | <a href="packages.doc.html">Next</a> | <a href="jIX.fm.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">Second Edition</font></td></tr></table>
<hr><br>
<a name="48086"></a>
<p><strong>
CHAPTER
6 </strong></p>
<a name="44352"></a>
<h1>Names</h1>
<hr><p>
<a name="10551"></a>
Names are used to refer to entities declared in a program. A declared entity <a href="names.doc.html#33757">(&#167;6.1)</a> is a package, class type, interface type, member (class, interface, field, or method) of a reference type, parameter (to a method, constructor, or exception handler), or local variable.<p>
<a name="56343"></a>
Names in programs are either simple, consisting of a single identifier, or qualified, &#32;consisting of a sequence of identifiers separated by "<code>.</code>" tokens <a href="names.doc.html#31692">(&#167;6.2)</a>.<p>
<a name="56234"></a>
Every declaration that introduces a name has a <em>scope</em> <a href="names.doc.html#103228">(&#167;6.3)</a>, which is the part of the program text within which the declared entity can be referred to by a simple name.<p>
<a name="56241"></a>
Packages and reference types (that is, class types, interface types, and array types) have members <a href="names.doc.html#106443">(&#167;6.4)</a>. A member can be referred to using a qualified name <i>N</i><code>.</code><i>x</i>, where <i>N</i> is a simple or qualified name and <i>x</i> is an identifier. If <i>N</i> names a package, then <i>x</i> is a member of that package, which is either a class or interface type or a subpackage. If <i>N</i> names a reference type or a variable of a reference type, then <i>x</i> names a member of that type, which is either a class, an interface, a field, or a method.<p>
<a name="34249"></a>
In determining the meaning of a name <a href="names.doc.html#106941">(&#167;6.5)</a>, the context of the occurrence is used to disambiguate among packages, types, variables, and methods with the same name.<p>
<a name="56266"></a>
Access control <a href="names.doc.html#104285">(&#167;6.6)</a> can be specified in a class, interface, method, or field declaration to control when <em>access</em> to a member is allowed. Access is a different concept from scope; access specifies the part of the program text within which the declared entity can be referred to by a qualified name, a field access expression <a href="expressions.doc.html#41267">(&#167;15.11)</a>, or a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a> in which the method is not specified by a simple name. The default access is that a member can be accessed anywhere within the package that contains its declaration; other possibilities are <code>public</code>, <code>protected</code>, and <code>private</code>.<p>
<a name="27329"></a>
Fully qualified and canonical names <a href="names.doc.html#25430">(&#167;6.7)</a> and naming conventions <a href="names.doc.html#73307">(&#167;6.8)</a> are also discussed in this chapter.<p>
<a name="31249"></a>
The name of a field, parameter, or local variable may be used as an expression <a href="expressions.doc.html#39438">(&#167;15.14.1)</a>. The name of a method may appear in an expression only as part of a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a>. The name of a class or interface type may appear in an expression only as part of a class literal <a href="expressions.doc.html#251530">(&#167;15.8.2)</a>, a qualified this expression <a href="expressions.doc.html#251603">(&#167;15.8.4)</a>, a class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>, an array creation expression <a href="expressions.doc.html#46168">(&#167;15.10)</a>, a cast expression <a href="expressions.doc.html#238146">(&#167;15.16)</a>, or an <code>instanceof</code> expression <a href="expressions.doc.html#80289">(&#167;15.20.2)</a>, or as part of a qualified name for a field or method. The name of a package may appear in an expression only as part of a qualified name for a class or interface type.<p>
<a name="33757"></a>
<h2>6.1 Declarations</h2>
<a name="33759"></a>
A <i>declaration</i> introduces an entity into a program and includes an identifier <a href="lexical.doc.html#40625">(&#167;3.8)</a> that can be used in a name to refer to this entity. A declared entity is one of the following:<p>
<ul><a name="60314"></a>
<li>A package, declared in a <code>package</code> declaration <a href="packages.doc.html#26619">(&#167;7.4)</a>
<a name="60319"></a>
<li>An imported type, declared in a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> or a type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a>
<a name="27103"></a>
<li>A class, declared in a class type declaration <a href="classes.doc.html#15372">(&#167;8.1)</a>
<a name="27107"></a>
<li>An interface, declared in an interface type declaration <a href="interfaces.doc.html#35470">(&#167;9.1)</a>
<a name="103106"></a>
<li>A member of a reference type (<a href="classes.doc.html#21831">&#167;8.2</a>, <a href="interfaces.doc.html#32392">&#167;9.2</a>, <a href="arrays.doc.html#64347">&#167;10.7</a>), one of the following:
<ul>
<a name="103114"></a>
<li>A member class (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>).
<a name="103122"></a>
<li>A member interface (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>).
<a name="71624"></a>
<li>A field, one of the following:
<ul>
<a name="20168"></a>
<li>A field declared in a class type <a href="classes.doc.html#40898">(&#167;8.3)</a>
<a name="20172"></a>
<li>A constant field declared in an interface type <a href="interfaces.doc.html#78642">(&#167;9.3)</a>
<a name="20173"></a>
<li>The field <code>length</code>, which is implicitly a member of every array type <a href="arrays.doc.html#64347">(&#167;10.7)</a>
</ul>
<a name="33764"></a>
<li>A method, one of the following:
<ul>
<a name="38090"></a>
<li>A method (<code>abstract</code> or otherwise) declared in a class type <a href="classes.doc.html#40420">(&#167;8.4)</a>
<a name="33944"></a>
<li>A method (always <code>abstract</code>) declared in an interface type <a href="interfaces.doc.html#78651">(&#167;9.4)</a>
</ul>
</ul>
<a name="31380"></a>
<li>A parameter, one of the following:
<ul>
<a name="33773"></a>
<li>A parameter of a method or constructor of a class (<a href="classes.doc.html#38698">&#167;8.4.1</a>, <a href="classes.doc.html#29488">&#167;8.8.1</a>)
<a name="33775"></a>
<li>A parameter of an <code>abstract</code> method of an interface <a href="interfaces.doc.html#78651">(&#167;9.4)</a>
<a name="31398"></a>
<li>A parameter of an exception handler declared in a <code>catch</code> clause of a <code>try</code> statement <a href="statements.doc.html#79311">(&#167;14.19)</a>
</ul>
<a name="31392"></a>
<li>A local variable, one of the following:
<ul>
<a name="33776"></a>
<li>A local variable declared in a block <a href="statements.doc.html#5920">(&#167;14.4)</a>
<a name="33777"></a>
<li>A local variable declared in a <code>for</code> statement <a href="statements.doc.html#24588">(&#167;14.13)</a>
</ul>
</ul><a name="56358"></a>
Constructors <a href="classes.doc.html#41652">(&#167;8.8)</a> are also introduced by declarations, but use the name of the class in which they are declared rather than introducing a new name.<p>
<a name="31692"></a>
<h2>6.2 Names and Identifiers</h2>
<a name="61760"></a>
A <em>name</em> is used to refer to an entity declared in a program.<p>
<a name="61763"></a>
There are two forms of names: simple names and qualified names. A <em>simple name</em> is a single identifier. A <em>qualified name</em> consists of a name, a "<code>.</code>" token, and an identifier.<p>
<a name="21637"></a>
In determining the meaning of a name <a href="names.doc.html#106941">(&#167;6.5)</a>, the context in which the name appears is taken into account. The rules of <a href="names.doc.html#106941">&#167;6.5</a> distinguish among contexts where a name must denote (refer to) a package <a href="names.doc.html#22349">(&#167;6.5.3)</a>, a type <a href="names.doc.html#73064">(&#167;6.5.5)</a>, a variable or value in an expression <a href="names.doc.html#21650">(&#167;6.5.6)</a>, or a method <a href="names.doc.html#21652">(&#167;6.5.7)</a>.<p>
<a name="33483"></a>
Not all identifiers in programs are a part of a name. Identifiers are also used in the following situations:<p>
<ul><a name="33485"></a>
<li>In declarations <a href="names.doc.html#33757">(&#167;6.1)</a>, where an identifier may occur to specify the name by which the declared entity will be known
<a name="33490"></a>
<li>In field access expressions <a href="expressions.doc.html#41267">(&#167;15.11)</a>, where an identifier occurs after a "<code>.</code>" token to indicate a member of an object that is the value of an expression or the keyword <code>super</code> that appears before the "<code>.</code>" token
<a name="33491"></a>
<li>In some method invocation expressions <a href="expressions.doc.html#20448">(&#167;15.12)</a>, where an identifier may occur after a "<code>.</code>" token and before a "<code>(</code>" token to indicate a method to be invoked for an object that is the value of an expression or the keyword <code>super</code> that appears before the "<code>.</code>" token
<a name="76093"></a>
<li>In qualified class instance creation expressions <a href="expressions.doc.html#41147">(&#167;15.9)</a>, where an identifier occurs immediately to the right of the leftmost new token to indicate a type that must be a member of the compile-time type of the primary expression preceding the "." preceding the leftmost new token.
<a name="33492"></a>
<li>As labels in labeled statements <a href="statements.doc.html#78993">(&#167;14.7)</a> and in <code>break</code> <a href="statements.doc.html#6842">(&#167;14.14)</a> and <code>continue</code> <a href="statements.doc.html#6122">(&#167;14.15)</a> statements that refer to statement labels.
</ul><a name="79896"></a>
In the example:<p>
<blockquote><pre>class Test {
public static void main(String[] args) {
Class c = System.out.getClass();
System.out.println(c.toString().length() +
args[0].length() + args.length);
}
}
</pre></blockquote><a name="61602"></a>
the identifiers <code>Test</code>, <code>main</code>, and the first occurrences of <code>args</code> and <code>c</code> are not names; rather, they are used in declarations to specify the names of the declared entities. The names <code>String</code>, <code>Class</code>, <code>System.out.getClass</code>, <code>System.out.println</code>, <code>c.toString</code>, <code>args</code>, and <code>args.length</code> appear in the example. The first occurrence of <code>length</code> is not a name, but rather an identifier appearing in a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a>. The second occurrence of <code>length</code> is not a name, but rather an identifier appearing in a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a>.<p>
<a name="61609"></a>
The identifiers used in labeled statements and their associated <code>break</code> and <code>continue</code> statements are completely separate from those used in declarations. Thus, the following code is valid:
<blockquote><pre>class TestString {
char[] value;
int offset, count;
int indexOf(TestString str, int fromIndex) {
char[] v1 = value, v2 = str.value;
int max = offset + (count - str.count);
int start = offset + ((fromIndex &lt; 0) ? 0 : fromIndex);
i:
for (int i = start; i &lt;= max; i++)
{
int n = str.count, j = i, k = str.offset;
while (n-- != 0) {
if (v1[j++] != v2[k++])
continue i;
}
return i - offset;
}
return -1;
}
}
</pre></blockquote><a name="103223"></a>
This code was taken from a version of the class <code>String</code> and its method <code>indexOf</code>, where the label was originally called <code>test</code>. Changing the label to have the same name as the local variable <code>i</code> does not obscure <a href="names.doc.html#104058">(&#167;6.3.2)</a> the label in the scope of the declaration of <code>i</code>. The identifier <code>max</code> could also have been used as the statement label; the label would not obscure the local variable <code>max</code> within the labeled statement.<p>
<a name="103228"></a>
<h2>6.3 Scope of a Declaration</h2>
<a name="103232"></a>
The <em>scope</em> of a declaration is the region of the program within which the entity declared by the declaration can be referred to using a simple name (provided it is visible <a href="names.doc.html#34133">(&#167;6.3.1)</a>). A declaration is said to be <em>in scope</em> at a particular point in a program if and only if the declaration's scope includes that point. <p>
<a name="103908"></a>
The scoping rules for various constructs are given in the sections that describe those constructs. For convenience, the rules are repeated here:<p>
<a name="108808"></a>
The scope of the declaration of an observable <a href="packages.doc.html#13180">(&#167;7.4.3)</a> top level package is all observable compilation units <a href="packages.doc.html#40031">(&#167;7.3)</a>. The declaration of a package that is not observable is never in scope. Subpackage declarations are never in scope.<p>
<a name="108865"></a>
The scope of a type imported by a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> or type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a> is all the class and interface type declarations <a href="packages.doc.html#26783">(&#167;7.6)</a> in the compilation unit in which the import declaration appears.<p>
<a name="108901"></a>
The scope of a top level type is all type declarations in the package in which the top level type is declared.<p>
<a name="109152"></a>
The scope of a label declared by a labeled statement is the statement immediately enclosed by the labeled statement.<p>
<a name="109195"></a>
The scope of a declaration of a member m declared in or inherited by a class type C is the entire body of <i>C</i>, including any nested type declarations.<p>
<a name="109234"></a>
The scope of the declaration of a member m declared in or inherited by an interface type I is the entire body of <i>I</i>, including any nested type declarations.<p>
<a name="108452"></a>
The scope of a parameter of a method <a href="classes.doc.html#38698">(&#167;8.4.1)</a> or constructor <a href="classes.doc.html#29488">(&#167;8.8.1)</a> is the entire body of the method or constructor.<p>
<a name="108957"></a>
The scope of a local variable declaration in a block <a href="statements.doc.html#32644">(&#167;14.4.2)</a> is the rest of the block in which the declaration appears, starting with its own initializer <a href="statements.doc.html#5920">(&#167;14.4)</a> and including any further declarators to the right in the local variable declaration statement. <p>
<a name="108996"></a>
The scope of a local class declared in a block is the rest of the immediately enclosing block, including its own class declaration.<p>
<a name="109032"></a>
The scope of a local variable declared in the <em>ForInit</em> part of a <code>for</code> statement <a href="statements.doc.html#24588">(&#167;14.13)</a> includes all of the following:<p>
<ul><a name="109037"></a>
<li>Its own initializer
<a name="109040"></a>
<li>Any further declarators to the right in the <em>ForInit</em> part of the <code>for</code> statement
<a name="109041"></a>
<li>The <em>Expression</em> and <em>ForUpdate</em> parts of the <code>for</code> statement
<a name="109042"></a>
<li>The contained <em>Statement</em>
</ul><a name="109075"></a>
The scope of a parameter of an exception handler that is declared in a <code>catch</code> clause of a <code>try</code> statement <a href="statements.doc.html#79311">(&#167;14.19)</a> is the entire block associated with the <code>catch</code>.<p>
<a name="107230"></a>
These rules imply that declarations of class and interface types need not appear before uses of the types.<p>
<a name="20278"></a>
In the example:
<blockquote><pre>package points;
class Point {
int x, y;
PointList list;
Point next;
}
class PointList {
Point first;
}
</pre></blockquote><a name="34047"></a>
the use of <code>PointList</code> in class <code>Point</code> is correct, because the scope of the class declaration <code>PointList</code> includes both class <code>Point</code> and class <code>PointList</code>, as well as any other type declarations in other compilation units of package <code>points</code>.<p>
<a name="34133"></a>
<h3>6.3.1 Shadowing Declarations</h3>
<a name="34051"></a>
Some declarations may be <em>shadowed</em> in part of their scope by another declaration of the same name, in which case a simple name cannot be used to refer to the declared entity.<p>
<a name="84195"></a>
A declaration <i>d</i> of a type named <i>n</i> shadows the declarations of any other types named <i>n</i> that are in scope at the point where <i>d</i> occurs throughout the scope of <i>d</i>.<p>
<a name="84205"></a>
A declaration <i>d</i> of a field, local variable, method parameter, constructor parameter or exception handler parameter named <i>n</i> shadows the declarations of any other fields, local variables, method parameters, constructor parameters or exception handler parameters named <i>n</i> that are in scope at the point where <i>d</i> occurs throughout the scope of <i>d</i>.<p>
<a name="84220"></a>
A declaration <i>d</i> of a label named <i>n</i> shadows the declarations of any other labels named <i>n</i> that are in scope at the point where <i>d</i> occurs throughout the scope of <i>d</i>.<p>
<a name="84229"></a>
A declaration <i>d</i> of a method named <i>n</i> shadows the declarations of any other methods named <i>n</i> that are in an enclosing scope at the point where <i>d</i> occurs throughout the scope of <i>d</i>.<p>
<a name="103966"></a>
A package declaration never shadows any other declaration. <p>
<a name="109278"></a>
A single-type-import declaration <i>d</i> in a compilation unit <i>c</i> of package <i>p</i> that imports a type named <i>n</i> shadows the declarations of:<p>
<ul><a name="109280"></a>
<li>any top level type named <i>n</i> declared in another compilation unit of <i>p</i>.
<a name="109281"></a>
<li>any type named <i>n</i> imported by a type-import-on-demand declaration in <i>c</i>.
</ul><a name="109282"></a>
throughout <i>c.</i><p>
<a name="109313"></a>
A type-import-on-demand declaration never causes any other declaration to be shadowed.<p>
<a name="108437"></a>
A declaration <i>d</i> is said to be <em>visible at point </em><i>p</i><em> in a program</em> if the scope of <i>d</i> includes <i>p</i>, and <i>d</i> is not shadowed by any other declaration at <i>p</i>. When the program point we are discussing is clear from context, we will often simply say that a declaration is <em>visible</em>.<p>
<a name="104510"></a>
Note that shadowing is distinct from hiding (<a href="classes.doc.html#40898">&#167;8.3</a>, <a href="classes.doc.html#227928">&#167;8.4.6.2</a>, <a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#78642">&#167;9.3</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>). Hiding, in the technical sense defined in this specification, applies only to members which would otherwise be inherited but are not because of a declaration in a subclass. Shadowing is also distinct from obscuring <a href="names.doc.html#104058">(&#167;6.3.2)</a>.
<p>
<a name="62323"></a>
Here is an example of shadowing of a field declaration by a local variable declaration:
<blockquote><pre>class Test {
static int x = 1;
public static void main(String[] args) {
int x = 0;
System.out.print("x=" + x);
System.out.println(", Test.x=" + Test.x);
}
}
</pre></blockquote><a name="34060"></a>
produces the output:<p>
<blockquote><pre>x=0, Test.x=1
</pre></blockquote><a name="34062"></a>
This example declares:<p>
<ul><a name="62327"></a>
<li>a class <code>Test</code>
<a name="62331"></a>
<li>a class (<code>static</code>) variable <code>x</code> that is a member of the class <code>Test</code>
<a name="62332"></a>
<li>a class method <code>main</code> that is a member of the class <code>Test</code>
<a name="62333"></a>
<li>a parameter <code>args</code> of the <code>main</code> method
<a name="62334"></a>
<li>a local variable <code>x</code> of the <code>main</code> method
<a name="34066"></a>
</ul>
Since the scope of a class variable includes the entire body of the class <a href="classes.doc.html#21831">(&#167;8.2)</a> the class variable <code>x</code> would normally be available throughout the entire body of the method <code>main</code>. In this example, however, the class variable <code>x</code> is shadowed within the body of the method <code>main</code> by the declaration of the local variable <code>x</code>.
<p>
<a name="62312"></a>
A local variable has as its scope the rest of the block in which it is declared <a href="statements.doc.html#32644">(&#167;14.4.2)</a>; in this case this is the rest of the body of the <code>main</code> method, namely its initializer "<code>0</code>" and the invocations of <code>print</code> and <code>println</code>.
<a name="62314"></a>
<p>
This means that:
<a name="62313"></a>
<ul>
<li>The expression "<code>x</code>" in the invocation of <code>print</code> refers to (denotes) the value of the local variable <code>x</code>.
<a name="62320"></a>
<li>The invocation of <code>println</code> uses a qualified name <a href="names.doc.html#104285">(&#167;6.6)</a> <code>Test.x</code>, which uses the class type name <code>Test</code> to access the class variable <code>x</code>, because the declaration of <code>Test.x</code> is shadowed at this point and cannot be referred to by its simple name.
<a name="104040"></a>
</ul>
The following example illustrates the shadowing of one type declaration by another:
</ul><blockquote><pre>import java.util.*;
class Vector {
int val[] = { 1 , 2 };
<a name="104044"></a>
}<p>
class Test {
public static void main(String[] args) {
Vector v = new Vector();
System.out.println(v.val[0]);
}
}
</pre></blockquote><a name="104051"></a>
compiles and prints:<p>
<blockquote><pre>1
</pre></blockquote><a name="104053"></a>
using the class <code>Vector</code> declared here in preference to class <code>java.util.Vector</code> that might be imported on demand.<p>
<a name="104058"></a>
<h3>6.3.2 Obscured Declarations</h3>
<a name="62307"></a>
A simple name may occur in contexts where it may potentially be interpreted as the name of a variable, a type or a package. In these situations, the rules of <a href="names.doc.html#106941">&#167;6.5</a> specify that a variable will be chosen in preference to a type, and that a type will be chosen in preference to a package. Thus, it is may sometimes be impossible to refer to a visible type or package declaration via its simple name. We say that such a declaration is <em>obscured</em>. <p>
<a name="106440"></a>
Obscuring is distinct from shadowing <a href="names.doc.html#34133">(&#167;6.3.1)</a> and hiding (<a href="classes.doc.html#40898">&#167;8.3</a>, <a href="classes.doc.html#227928">&#167;8.4.6.2</a>, <a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#78642">&#167;9.3</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>). The naming conventions of <a href="names.doc.html#73307">&#167;6.8</a> help reduce obscuring.
<p>
<a name="106443"></a>
<h2>6.4 Members and Inheritance</h2>
<a name="86672"></a>
Packages and reference types have <em>members</em>. <p>
<a name="56531"></a>
This section provides an overview of the members of packages and reference types here, as background for the discussion of qualified names and the determination of the meaning of names. For a complete description of membership, see <a href="packages.doc.html#26535">&#167;7.1</a>, <a href="classes.doc.html#21831">&#167;8.2</a>, <a href="interfaces.doc.html#32392">&#167;9.2</a>, and <a href="arrays.doc.html#64347">&#167;10.7</a>.
<p>
<a name="34993"></a>
<h3>6.4.1 The Members of a Package</h3>
<a name="104077"></a>
The members of a package <a href="packages.doc.html#34412">(&#167;7)</a> are specified in <a href="packages.doc.html#26535">&#167;7.1</a>. For convenience, we repeat that specification here:<p>
<a name="108769"></a>
The members of a package are subpackages and all the top level <a href="packages.doc.html#26783">(&#167;7.6)</a> class <a href="classes.doc.html#3857">(&#167;8)</a> and top level interface <a href="interfaces.doc.html#238678">(&#167;9)</a> types declared in all the compilation units <a href="packages.doc.html#40031">(&#167;7.3)</a> of the package.<p>
<a name="98547"></a>
In general, the subpackages of a package are determined by the host system <a href="packages.doc.html#37758">(&#167;7.2)</a>. However, the package <code>java</code> always includes the subpackages <code>lang</code> and <code>io</code> and may include other subpackages. No two distinct members of the same package may have the same simple name <a href="packages.doc.html#26535">(&#167;7.1)</a>, but members of different packages may have the same simple name. <p>
<a name="107146"></a>
For example, it is possible to declare a package:
<blockquote><pre>package vector;
public class Vector { Object[] vec; }
</pre></blockquote><a name="34986"></a>
that has as a member a <code>public</code> class named <code>Vector</code>, even though the package <code>java.util</code> also declares a class named <code>Vector</code>. These two class types are different, reflected by the fact that they have different fully qualified names <a href="names.doc.html#25430">(&#167;6.7)</a>. The fully qualified name of this example <code>Vector</code> is <code>vector.Vector</code>, whereas <code>java.util.Vector</code> is the fully qualified name of the standard <code>Vector</code> class. Because the package <code>vector</code> contains a class named <code>Vector</code>, it cannot also have a subpackage named <code>Vector</code>.<p>
<a name="34757"></a>
<h3>6.4.2 The Members of a Class Type</h3>
<a name="104101"></a>
The members of a class type <a href="classes.doc.html#21831">(&#167;8.2)</a> are classes (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>), interfaces (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>), fields (<a href="classes.doc.html#40898">&#167;8.3</a>, <a href="interfaces.doc.html#78642">&#167;9.3</a>, <a href="arrays.doc.html#64347">&#167;10.7</a>), and methods (<a href="classes.doc.html#40420">&#167;8.4</a>, <a href="interfaces.doc.html#78651">&#167;9.4</a>). Members are either declared in the type, or <i>inherited </i>because they are accessible members of a superclass or superinterface which are neither private nor hidden nor overridden <a href="classes.doc.html#228745">(&#167;8.4.6)</a>.<p>
<a name="34765"></a>
The members of a class type are all of the following:
<ul><a name="34768"></a>
<li>Members inherited from its direct superclass <a href="classes.doc.html#262560">(&#167;8.1.3)</a>, if it has one (the class <code>Object</code> has no direct superclass)
<a name="34777"></a>
<li>Members inherited from any direct superinterfaces <a href="classes.doc.html#34031">(&#167;8.1.4)</a>
<a name="34778"></a>
<li>Members declared in the body of the class <a href="classes.doc.html#18988">(&#167;8.1.5)</a>
</ul><a name="62337"></a>
Constructors <a href="classes.doc.html#41652">(&#167;8.8)</a> are not members.<p>
<a name="31685"></a>
There is no restriction against a field and a method of a class type having the same simple name. Likewise, there is no restriction against a member class or member interface of a class type having the same simple name as a field or method of that class type.
<a name="56650"></a>
<p>
A class may have two or more fields with the same simple name if they are declared in different interfaces and inherited. An attempt to refer to any of the fields by its simple name results in a compile-time error (<a href="names.doc.html#54547">&#167;6.5.7.2</a>, <a href="classes.doc.html#21831">&#167;8.2</a>).
<a name="31689"></a>
<p>
In the example:
<blockquote><pre>interface Colors {
int WHITE = 0, BLACK = 1;
}
interface Separates {
int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
}
class Test implements Colors, Separates {
public static void main(String[] args) {
System.out.println(BLACK); // compile-time error: ambiguous
}
}
</pre></blockquote><a name="25294"></a>
the name <code>BLACK</code> in the method <code>main</code> is ambiguous, because class <code>Test</code> has two members named <code>BLACK</code>, one inherited from <code>Colors</code> and one from <code>Separates</code>.<p>
<a name="23306"></a>
A class type may have two or more methods with the same simple name if the methods have different signatures <a href="classes.doc.html#38649">(&#167;8.4.2)</a>, that is, if they have different numbers of parameters or different parameter types in at least one parameter position. Such a method member name is said to be <em>overloaded</em>.
<p>
<a name="31700"></a>
A class type may contain a declaration for a method with the same name and the same signature as a method that would otherwise be inherited from a superclass or superinterface. In this case, the method of the superclass or superinterface is not inherited. If the method not inherited is <code>abstract</code>, then the new declaration is said to <em>implement</em> it; if the method not inherited is not <code>abstract</code>, then the new declaration is said to <em>override</em> it.<p>
<a name="31699"></a>
In the example:
<blockquote><pre>class Point {
float x, y;
void move(int dx, int dy) { x += dx; y += dy; }
void move(float dx, float dy) { x += dx; y += dy; }
public String toString() { return "("+x+","+y+")"; }
}
</pre></blockquote><a name="31707"></a>
the class <code>Point</code> has two members that are methods with the same name, <code>move</code>. The overloaded <code>move</code> method of class <code>Point</code> chosen for any particular method invocation is determined at compile time by the overloading resolution procedure given in <a href="expressions.doc.html#20448">&#167;15.12</a>.<p>
<a name="62345"></a>
In this example, the members of the class <code>Point</code> are the <code>float</code> instance variables <code>x</code> and <code>y</code> declared in <code>Point</code>, the two declared <code>move</code> methods, the declared <code>toString</code> method, and the members that <code>Point</code> inherits from its implicit direct superclass <code>Object</code> <a href="typesValues.doc.html#11055">(&#167;4.3.2)</a>, such as the method <code>hashCode</code>. Note that <code>Point</code> does not inherit the <code>toString</code> method of class <code>Object</code> because that method is overridden by the declaration of the <code>toString</code> method in class <code>Point</code>.
<p>
<a name="34849"></a>
<h3>6.4.3 The Members of an Interface Type</h3>
<a name="109115"></a>
The members of an interface type <a href="interfaces.doc.html#32392">(&#167;9.2)</a> may be classes (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>), interfaces (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>), fields (<a href="classes.doc.html#40898">&#167;8.3</a>, <a href="interfaces.doc.html#78642">&#167;9.3</a>, <a href="arrays.doc.html#64347">&#167;10.7</a>), and methods (<a href="classes.doc.html#40420">&#167;8.4</a>, <a href="interfaces.doc.html#78651">&#167;9.4</a>).The members of an interface are:<p>
<ul><a name="109116"></a>
<li>Those members declared in the interface.
<a name="109119"></a>
<li>Those members inherited from direct superinterfaces.
<a name="109120"></a>
<li>If an interface has no direct superinterfaces, then the interface implicitly declares a public abstract member method <i>m</i> with signature <i>s</i>, return type <i>r</i>, and <code>throws</code> clause <i>t</i> corresponding to each public instance method <i>m</i> with signature <i>s</i>, return type <i>r</i>, and <code>throws</code> clause <i>t</i> declared in <code>Object</code>, unless a method with the same signature, same return type, and a compatible <code>throws</code> clause is explicitly declared by the interface.
</ul><a name="108393"></a>
An interface may have two or more fields with the same simple name if they are declared in different interfaces and inherited. An attempt to refer to any such field by its simple name results in a compile-time error (<a href="names.doc.html#22022">&#167;6.5.6.1</a>, <a href="interfaces.doc.html#32392">&#167;9.2</a>).<p>
<a name="61795"></a>
In the example:
<blockquote><pre>interface Colors {
int WHITE = 0, BLACK = 1;
}
interface Separates {
int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
}
interface ColorsAndSeparates extends Colors, Separates {
int DEFAULT = BLACK; // compile-time error: ambiguous
}
</pre></blockquote><a name="35254"></a>
the members of the interface <code>ColorsAndSeparates</code> include those members inherited from <code>Colors</code> and those inherited from <code>Separates</code>, namely <code>WHITE</code>, <code>BLACK</code> (first of two), <code>CYAN</code>, <code>MAGENTA</code>, <code>YELLOW</code>, and <code>BLACK</code> (second of two). The member name <code>BLACK</code> is ambiguous in the interface <code>ColorsAndSeparates</code>.<p>
<a name="27725"></a>
<h3>6.4.4 The Members of an Array Type</h3>
<a name="86520"></a>
The members of an array type are specified in <a href="arrays.doc.html#64347">&#167;10.7</a>. For convenience, we repeat that specification here.<p>
<a name="108751"></a>
The members of an array type are all of the following:<p>
<ul><a name="108753"></a>
<li>The <code>public</code> <code>final</code> field <code>length</code>, which contains the number of components of the array (<code>length</code> may be positive or zero)
<a name="108755"></a>
<li>The <code>public</code> method <code>clone</code>, which overrides the method of the same name in class <code>Object</code> and throws no checked exceptions
<a name="108757"></a>
<li>All the members inherited from class <code>Object</code>; the only method of <code>Object</code> that is not inherited is its <code>clone</code> method
</ul><a name="27727"></a>
<p>
<a name="98552"></a>
The example:<p>
<blockquote><pre>class Test {
public static void main(String[] args) {
int[] ia = new int[3];
int[] ib = new int[6];
System.out.println(ia.getClass() == ib.getClass());
System.out.println("ia has length=" + ia.length);
}
}
</pre></blockquote><a name="27736"></a>
produces the output:<p>
<blockquote><pre>true
ia has length=3
</pre></blockquote><a name="106936"></a>
This example uses the method <code>getClass</code> inherited from class <code>Object</code> and the field <code>length</code>. The result of the comparison of the <code>Class</code> objects in the first <code>println</code> demonstrates that all arrays whose components are of type <code>int</code> are instances of the same array type, which is <code>int[]</code>.<p>
<a name="106941"></a>
<h2>6.5 Determining the Meaning of a Name</h2>
<a name="106943"></a>
The meaning of a name depends on the context in which it is used. The determination of the meaning of a name requires three steps. First, context causes a name syntactically to fall into one of six categories: <em>PackageName</em>, <em>TypeName</em>, <em>ExpressionName</em>, <em>MethodName</em>, <em>PackageOrTypeName, </em>or <em>AmbiguousName</em>. Second, a name that is initially classified by its context as an <em>AmbiguousName</em> or as a <em>Package-OrTypeName</em> is then reclassified to be a <em>PackageName</em>, <em>TypeName</em>, or <em>ExpressionName</em>. Third, the resulting category then dictates the final determination of the meaning of the name (or a compilation error if the name has no meaning).<p>
<ul><pre><i>
PackageName:
Identifier
PackageName . Identifier
TypeName:
Identifier
PackageOrTypeName . Identifier
ExpressionName:
Identifier
AmbiguousName . Identifier
MethodName:
Identifier
AmbiguousName . Identifier
PackageOrTypeName:
Identifier
PackageOrTypeName . Identifier
AmbiguousName:
Identifier
AmbiguousName . Identifier
</i></pre></ul>
<a name="32744"></a>
The use of context helps to minimize name conflicts between entities of different kinds. Such conflicts will be rare if the naming conventions described in <a href="names.doc.html#73307">&#167;6.8</a> are followed. Nevertheless, conflicts may arise unintentionally as types developed by different programmers or different organizations evolve. For example, types, methods, and fields may have the same name. It is always possible to distinguish between a method and a field with the same name, since the context of a use always tells whether a method is intended.
</pre></ul><a name="32740"></a>
<h3>6.5.1 Syntactic Classification of a Name According to Context</h3>
<a name="32741"></a>
A name is syntactically classified as a <em>PackageName</em> in these contexts:<p>
<ul><a name="32159"></a>
<li>In a package declaration <a href="packages.doc.html#26619">(&#167;7.4)</a>
<a name="32492"></a>
<li>To the left of the "<code>.</code>" in a qualified <em>PackageName</em>
</ul><a name="32149"></a>
A name is syntactically classified as a <em>TypeName</em> in these contexts:<p>
<ul><a name="32174"></a>
<li>In a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a>
<a name="32178"></a>
<li>In an <code>extends</code> clause in a class declaration <a href="classes.doc.html#262560">(&#167;8.1.3)</a>
<a name="32182"></a>
<li>In an <code>implements</code> clause in a class declaration <a href="classes.doc.html#34031">(&#167;8.1.4)</a>
<a name="34302"></a>
<li>In an <code>extends</code> clause in an interface declaration <a href="interfaces.doc.html#78598">(&#167;9.1.2)</a>
<a name="32290"></a>
<li>As a <em>Type</em> (or the part of a <em>Type</em> that remains after all brackets are deleted) in any of the following contexts:
<ul>
<a name="32310"></a>
<li>In a field declaration (<a href="classes.doc.html#40898">&#167;8.3</a>, <a href="interfaces.doc.html#78642">&#167;9.3</a>)
<a name="32322"></a>
<li>As the result type of a method (<a href="classes.doc.html#40420">&#167;8.4</a>, <a href="interfaces.doc.html#78651">&#167;9.4</a>)
<a name="32355"></a>
<li>As the type of a formal parameter of a method or constructor (<a href="classes.doc.html#38698">&#167;8.4.1</a>, <a href="classes.doc.html#29488">&#167;8.8.1</a>, <a href="interfaces.doc.html#78651">&#167;9.4</a>)
<a name="32266"></a>
<li>As the type of an exception that can be thrown by a method or constructor (<a href="classes.doc.html#78323">&#167;8.4.4</a>, <a href="classes.doc.html#244611">&#167;8.8.4</a>, <a href="interfaces.doc.html#78651">&#167;9.4</a>)
<a name="32224"></a>
<li>As the type of a local variable <a href="statements.doc.html#5920">(&#167;14.4)</a>
<a name="72827"></a>
<li>As the type of an exception parameter in a <code>catch</code> clause of a <code>try</code> statement <a href="statements.doc.html#79311">(&#167;14.19)</a>
<a name="72840"></a>
<li>As the type in a class literal <a href="expressions.doc.html#251530">(&#167;15.8.2)</a>
<a name="104184"></a>
<li>As the qualifying type of a qualified <code>this</code> expression <a href="expressions.doc.html#251603">(&#167;15.8.4)</a>.
<a name="72842"></a>
<li>As the class type which is to be instantiated in an unqualified class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>
<a name="83309"></a>
<li>As the direct superclass or direct superinterface of an anonymous class <a href="expressions.doc.html#252986">(&#167;15.9.5)</a> which is to be instantiated in an unqualified class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>
<a name="32240"></a>
<li>As the element type of an array to be created in an array creation expression <a href="expressions.doc.html#46168">(&#167;15.10)</a>
<a name="104188"></a>
<li>As the qualifying type of field access using the keyword <code>super</code> <a href="expressions.doc.html#20860">(&#167;15.11.2)</a>
<a name="104192"></a>
<li>As the qualifying type of a method invocation using the keyword <code>super</code> <a href="expressions.doc.html#20448">(&#167;15.12)</a>
<a name="32244"></a>
<li>As the type mentioned in the cast operator of a cast expression <a href="expressions.doc.html#238146">(&#167;15.16)</a>
<a name="32248"></a>
<li>As the type that follows the <code>instanceof</code> relational operator <a href="expressions.doc.html#80289">(&#167;15.20.2)</a>
</ul>
</ul><a name="32435"></a>
A name is syntactically classified as an <em>ExpressionName</em> in these contexts:<p>
<ul><a name="32464"></a>
<li>As the qualifying expression in a qualified superclass constructor invocation <a href="classes.doc.html#229267">(&#167;8.8.5.1)</a>
<a name="104200"></a>
<li>As the qualifying expression in a qualified class instance creation expression <a href="expressions.doc.html#41147">(&#167;15.9)</a>
<a name="104201"></a>
<li>As the array reference expression in an array access expression <a href="expressions.doc.html#239587">(&#167;15.13)</a>
<a name="32459"></a>
<li>As a <em>PostfixExpression</em> <a href="expressions.doc.html#36254">(&#167;15.14)</a>
<a name="32477"></a>
<li>As the left-hand operand of an assignment operator <a href="expressions.doc.html#5281">(&#167;15.26)</a>
</ul><a name="32437"></a>
A name is syntactically classified as a <em>MethodName</em> in this context:<p>
<ul><a name="32480"></a>
<li>Before the "<code>(</code>" in a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a>
</ul><a name="72939"></a>
A name is syntactically classified as a <em>PackageOrTypeName</em> in these contexts:<p>
<ul><a name="72943"></a>
<li>To the left of the "." in a qualified TypeName
<a name="73268"></a>
<li>In a type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a>
</ul><a name="32439"></a>
A name is syntactically classified as an <em>AmbiguousName</em> in these contexts:<p>
<ul><a name="32496"></a>
<li>To the left of the "<code>.</code>" in a qualified <em>ExpressionName</em>
<a name="32499"></a>
<li>To the left of the "<code>.</code>" in a qualified <em>MethodName</em>
<a name="72113"></a>
<li>To the left of the "<code>.</code>" in a qualified <em>AmbiguousName</em>
</ul><a name="32725"></a>
<h3>6.5.2 Reclassification of Contextually Ambiguous Names</h3>
<a name="32133"></a>
An <em>AmbiguousName</em> is then reclassified as follows:<p>
<ul><a name="32505"></a>
<li>If the <em>AmbiguousName</em> is a simple name, consisting of a single <em>Identifier</em>:
<ul>
<a name="32544"></a>
<li>If the <em>Identifier</em> appears within the scope <a href="names.doc.html#103228">(&#167;6.3)</a> of a local variable declaration <a href="statements.doc.html#5920">(&#167;14.4)</a> or parameter declaration (<a href="classes.doc.html#38698">&#167;8.4.1</a>, <a href="classes.doc.html#29488">&#167;8.8.1</a>, <a href="statements.doc.html#79311">&#167;14.19</a>) or field declaration <a href="classes.doc.html#40898">(&#167;8.3)</a> with that name, then the <em>AmbiguousName</em> is reclassified as an <em>ExpressionName</em>.
<a name="32843"></a>
<li>Otherwise, if the <em>Identifier</em> appears within the scope <a href="names.doc.html#103228">(&#167;6.3)</a> of a local class declaration <a href="statements.doc.html#247766">(&#167;14.3)</a> or member type declaration (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>) with that name, then the <em>AmbiguousName</em> is reclassified as a <em>TypeName</em>.
<a name="71975"></a>
<li>Otherwise, if a type of that name is declared in the compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a> containing the <em>Identifier</em>, either by a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> or by a top level class <a href="classes.doc.html#3857">(&#167;8)</a> or interface type declaration <a href="interfaces.doc.html#238678">(&#167;9)</a>, then the <em>AmbiguousName</em> is reclassified as a <em>TypeName</em>.
<a name="32853"></a>
<li>Otherwise, if a type of that name is declared in another compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a> of the package <a href="packages.doc.html#26535">(&#167;7.1)</a> of the compilation unit containing the <em>Identifier</em>, &#32;then the <em>AmbiguousName</em> is reclassified as a <em>TypeName</em>.
<a name="32860"></a>
<li>Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a> of the compilation unit containing the <em>Identifier</em>, &#32;then the <em>AmbiguousName</em> is reclassified as a <em>TypeName</em>.
<a name="32864"></a>
<li>Otherwise, if a type of that name is declared by more than one type-import-on-demand declaration of the compilation unit containing the <em>Identifier</em>, then a compile-time error results.
<a name="32535"></a>
<li>Otherwise, the <em>AmbiguousName</em> is reclassified as a <em>PackageName</em>. A later step determines whether or not a package of that name actually exists.
</ul>
<a name="32506"></a>
<li>If the <em>AmbiguousName</em> is a qualified name, consisting of a name, a "<code>.</code>", and an <em>Identifier</em>, then the name to the left of the "<code>.</code>" is first reclassified, for it is itself an <em>AmbiguousName</em>. There is then a choice:
<ul>
<a name="32509"></a>
<li>If the name to the left of the "<code>.</code>" is reclassified as a <em>PackageName</em>, then if there is a package whose name is the name to the left of the "<code>.</code>" and that package contains a declaration of a type whose name is the same as the <em>Identifier</em>, then this <em>AmbiguousName</em> is reclassified as a <em>TypeName</em>. Otherwise, this <em>AmbiguousName</em> is reclassified as a <em>PackageName</em>. A later step determines whether or not a package of that name actually exists.
<a name="72049"></a>
<li>If the name to the left of the "<code>.</code>" is reclassified as a <em>TypeName</em>, then if the Identifier is the name of a method or field of the class or interface denoted by TypeName, this <em>AmbiguousName</em> is reclassified as an <em>ExpressionName. </em>Otherwise, if the Identifier is the name of a member type of the class or interface denoted by TypeName, this AmbiguousName is reclassified as a TypeName. Otherwise, a compile-time error results.
<a name="79937"></a>
<li>If the name to the left of the "<code>.</code>" is reclassified as an <em>ExpressionName</em>, then let T be the type of the expression denoted by ExpressionName. If the Identifier is the name of a method or field of the class or interface denoted by T, this <em>AmbiguousName</em> is reclassified as an <em>ExpressionName</em>. Otherwise, if the Identifier is the name of a member type (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>) of the class or interface denoted by T, then this AmbiguousName is reclassified as a TypeName. Otherwise, a compile-time error results.
<a name="60456"></a>
</ul>
<p>
As an example, consider the following contrived "library code":
</ul><blockquote><pre>package org.rpgpoet;
import java.util.Random;
interface Music { Random[] wizards = new Random[4]; }
</pre></blockquote><a name="60464"></a>
and then consider this example code in another package:<p>
<blockquote><pre>package bazola;
class Gabriel {
static int n = org.rpgpoet.Music.wizards.length;
}
</pre></blockquote><a name="60483"></a>
First of all, the name <code>org.rpgpoet.Music.wizards.length</code> is classified as an <em>ExpressionName</em> because it functions as a <i>PostfixExpression</i>. Therefore, each of the names:<p>
<a name="107486"></a>
<blockquote><pre>org.rpgpoet.Music.wizards
org.rpgpoet.Music
org.rpgpoet
org
</pre></blockquote><a name="86574"></a>
is initially classified as an <em>AmbiguousName</em>. These are then reclassified:<p>
<ul><a name="60526"></a>
<li>The simple name <code>org</code> is reclassified as a <em>PackageName</em> (since there is no variable or type named <code>org</code> in scope).
<a name="60530"></a>
<li>Next, assuming that there is no class or interface named <code>rpgpoet</code> in any compilation unit of package <code>org</code> (and we know that there is no such class or interface because package <code>org</code> has a subpackage named <code>rpgpoet</code>), the qualified name <code>org.rpgpoet</code> is reclassified as a <em>PackageName</em>.
<a name="60542"></a>
<li>Next, because package <code>org.rpgpoet</code> has an interface type named <code>Music</code>, the qualified name <code>org.rpgpoet.Music</code> is reclassified as a <em>TypeName</em>.
<a name="80032"></a>
<li>Finally, because the name <code>org.rpgpoet.Music</code> is a <em>TypeName</em>, the qualified name <code>org.rpgpoet.Music.wizards</code> is reclassified as an <em>ExpressionName</em>.
</ul><a name="22349"></a>
<h3>6.5.3 Meaning of Package Names</h3>
<a name="32757"></a>
The meaning of a name classified as a <em>PackageName</em> is determined as follows.<p>
<a name="22481"></a>
<h4>6.5.3.1 Simple Package Names</h4>
<a name="21719"></a>
If a package name consists of a single <em>Identifier</em>, then this identifier denotes a top level package named by that identifier. If no top level package of that name is in scope <a href="packages.doc.html#70172">(&#167;7.4.4)</a>, then a compile-time error occurs.<p>
<a name="22482"></a>
<h4>6.5.3.2 Qualified Package Names</h4>
<a name="21727"></a>
If a package name is of the form <i>Q</i><code>.</code><i>Id</i>, then <i>Q</i> must also be a package name. The package name <i>Q</i><code>.</code><i>Id</i> names a package that is the member named <i>Id</i> within the package named by <i>Q</i>. If <i>Q</i> does not name an observable package <a href="packages.doc.html#13180">(&#167;7.4.3)</a>, or <i>Id</i> is not the simple name an observable subpackage of that package, then a compile-time error occurs.<p>
<a name="21721"></a>
<h3>6.5.4 Meaning of <i>PackageOrTypeNames</i></h3>
<a name="73065"></a>
<h4>6.5.4.1 Simple <i>PackageOrTypeNames</i></h4>
<a name="73113"></a>
If the <i>PackageOrTypeName</i>, <i>Q</i>, occurs in the scope of a type named <i>Q</i>, then the <i>PackageOrTypeName</i> is reclassified as a <i>TypeName</i>. <p>
<a name="107160"></a>
Otherwise, the <i>PackageOrTypeName</i> is reclassified as a <i>PackageName</i>. The meaning of the <i>PackageOrTypeName</i> is the meaning of the reclassified name.<p>
<a name="73067"></a>
<h4>6.5.4.2 Qualified <i>PackageOrTypeNames</i></h4>
<a name="73097"></a>
Given a qualified <i>PackageOrTypeName</i> of the form <i>Q.Id</i>, if the type or package denoted by <i>Q</i> has a member type named <i>Id</i>, then the qualified <i>PackageOrTypeName</i> name is reclassified as a <i>TypeName</i>. <p>
<a name="107161"></a>
Otherwise, it is reclassified as a <i>PackageName</i>. The meaning of the qualified <i>PackageOrTypeName</i> is the meaning of the reclassified name.<p>
<a name="73064"></a>
<h3>6.5.5 Meaning of Type Names</h3>
<a name="32763"></a>
The meaning of a name classified as a <em>TypeName</em> is determined as follows.<p>
<a name="21810"></a>
<h4>6.5.5.1 Simple Type Names</h4>
<a name="32799"></a>
If a type name consists of a single <em>Identifier</em>, then the identifier must occur in the scope of a declaration of a type with this name, or a compile-time error occurs. <p>
<a name="107164"></a>
It is possible that the identifier occurs within the scope of more than one type with that name, in which case the type denoted by the name is determined as follows:<p>
<ul><a name="21741"></a>
<li>If the simple type name occurs within the scope of a visible local class declaration <a href="statements.doc.html#247766">(&#167;14.3)</a> with that name, then the simple type name denotes that local class type.
<a name="72329"></a>
<li>Otherwise, if the simple type name occurs within the scope of exactly one visible member type (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>), then the simple type name denotes that member type.
<a name="72330"></a>
<li>Otherwise, if the simple type name occurs within the scope of more than one visible member type, then the name is ambiguous as a type name; a compile-time error occurs.
<a name="72322"></a>
<li>Otherwise, if a type with that name is declared in the current compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a>, either by a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> or by a declaration of a class or interface &#32;type <a href="packages.doc.html#26783">(&#167;7.6)</a>, then the simple type name denotes that type.
<a name="21751"></a>
<li>Otherwise, if a type with that name is declared in another compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a> of the package <a href="packages.doc.html#26535">(&#167;7.1)</a> containing the identifier, then the identifier denotes that type.
<a name="21758"></a>
<li>Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a> of the compilation unit containing the identifier, then the simple type name denotes that type.
<a name="32932"></a>
<li>Otherwise, if a type of that name is declared by more than one type-import-on-demand declaration of the compilation unit, then the name is ambiguous as a type name; a compile-time error occurs.
<a name="79949"></a>
<li>Otherwise, the name is undefined as a type name; a compile-time error occurs.
</ul><a name="32934"></a>
This order for considering type declarations is designed to choose the most explicit of two or more applicable type declarations.<p>
<a name="21811"></a>
<h4>6.5.5.2 Qualified Type Names</h4>
<a name="72865"></a>
If a type name is of the form <i>Q</i><code>.</code><i>Id</i>, then <i>Q</i> must be either a type name or a package name. If <i>Id</i> names exactly one type that is a member of the type or package denoted by <i>Q</i>, then the qualified type name denotes that type. If <i>Id</i> does not name a member type (<a href="classes.doc.html#246026">&#167;8.5</a>, <a href="interfaces.doc.html#252566">&#167;9.5</a>) within <i>Q</i>, or the member type named <i>Id</i> within <i>Q</i> is not accessible <a href="names.doc.html#104285">(&#167;6.6)</a>, or <i>Id</i> names more than one member type within <i>Q</i>, then a compile-time error occurs. <p>
<a name="32816"></a>
The example:
<blockquote><pre>package wnj.test;
class Test {
public static void main(String[] args) {
java.util.Date date =
new java.util.Date(System.currentTimeMillis());
System.out.println(date.toLocaleString());
}
}
</pre></blockquote><a name="21797"></a>
produced the following output the first time it was run:<p>
<blockquote><pre>Sun Jan 21 22:56:29 1996
</pre></blockquote><a name="21799"></a>
In this example the name <code>java.util.Date</code> must denote a type, so we first use the procedure recursively to determine if <code>java.util</code> is an accessible type or a package, which it is, and then look to see if the type <code>Date</code> is accessible in this package.<p>
<a name="21650"></a>
<h3>6.5.6 Meaning of Expression Names</h3>
<a name="32767"></a>
The meaning of a name classified as an <em>ExpressionName</em> is determined as follows.<p>
<a name="22022"></a>
<h4>6.5.6.1 Simple Expression Names</h4>
<a name="22023"></a>
If an expression name consists of a single <em>Identifier</em>, then:<p>
<ul><a name="22030"></a>
<li>If the <em>Identifier</em> appears within the scope <a href="names.doc.html#103228">(&#167;6.3)</a> of a visible local variable declaration <a href="statements.doc.html#5920">(&#167;14.4)</a> or visible parameter declaration (<a href="classes.doc.html#38698">&#167;8.4.1</a>, <a href="classes.doc.html#29488">&#167;8.8.1</a>, <a href="statements.doc.html#79311">&#167;14.19</a>) with that name, then the expression name denotes a variable, that is, that local variable or parameter. There is necessarily at most one such local variable or parameter. The type of the expression name is the declared type of the local variable or parameter.
<a name="22052"></a>
<li>Otherwise, if the <em>Identifier</em> appears within a class declaration <a href="classes.doc.html#3857">(&#167;8)</a>:
<ul>
<a name="22062"></a>
<li>If the Identifier appears within the scope <a href="names.doc.html#103228">(&#167;6.3)</a> of a visible field declaration with that name, then there must be a lexically enclosing type declaration of which that field is a member. Let T be the innermost such declaration. If there is not exactly one member of T that is a field with that name, then a compile-time error results.
<a name="22063"></a>
<li>Otherwise, if the single member field with that name is declared <code>final</code> <a href="classes.doc.html#35962">(&#167;8.3.1.2)</a>, then the expression name denotes the value of the field. The type of the expression name is the declared type of the field. If the <i>Identifier</i> appears in a context that requires a variable and not a value, then a compile-time error occurs.
<a name="22077"></a>
<li>Otherwise, the expression name denotes a variable, the single member field with that name. The type of the expression name is the field's declared type.
</ul>
</ul>
<ul>If the field is an instance variable <a href="classes.doc.html#37544">(&#167;8.3.1.1)</a>, the expression name must appear within the declaration of an instance method <a href="classes.doc.html#40420">(&#167;8.4)</a>, constructor <a href="classes.doc.html#41652">(&#167;8.8)</a>, or instance variable initializer <a href="classes.doc.html#38013">(&#167;8.3.2.2)</a>. If it appears within a <code>static</code> method <a href="classes.doc.html#229128">(&#167;8.4.3.2)</a>, static initializer <a href="classes.doc.html#39245">(&#167;8.7)</a>, or initializer for a <code>static</code> variable (<a href="classes.doc.html#37544">&#167;8.3.1.1</a>, <a href="execution.doc.html#44630">&#167;12.4.2</a>), then a compile-time error occurs.
</ul><ul><a name="60376"></a>
<li>Otherwise, the identifier appears within an interface declaration <a href="interfaces.doc.html#238678">(&#167;9)</a>:
<ul>
<a name="60380"></a>
<li>If the Identifier appears within the scope <a href="names.doc.html#103228">(&#167;6.3)</a> of a visible field declaration with that name, then there must be an enclosing type declaration T of which that field is a member. If there is not exactly one member of T that is a field with that name, then a compile-time error results.
<a name="32963"></a>
<li>Otherwise, the expression name denotes the value of the single member field of that name. The type of the expression name is the declared type of the field. If the <i>Identifier</i> appears in a context that requires a variable and not a value, then a compile-time error occurs.
</ul>
</ul><a name="79966"></a>
In the example:<p>
<blockquote><pre>class Test {
static int v;
static final int f = 3;
public static void main(String[] args) {
int i;
i = 1;
v = 2;
f = 33; // compile-time error
System.out.println(i + " " + v + " " + f);
}
}
</pre></blockquote><a name="22130"></a>
the names used as the left-hand-sides in the assignments to <code>i</code>, <code>v</code>, and <code>f</code> denote the local variable <code>i</code>, the field <code>v</code>, and the value of <code>f</code> (not the variable <code>f</code>, because <code>f</code> is a <code>final</code> variable). The example therefore produces an error at compile time because the last assignment does not have a variable as its left-hand side. If the erroneous assignment is removed, the modified code can be compiled and it will produce the output:<p>
<blockquote><pre>1 2 3
</pre></blockquote><a name="22133"></a>
<h4>6.5.6.2 Qualified Expression Names</h4>
<a name="33085"></a>
If an expression name is of the form <i>Q</i><code>.</code><i>Id</i>, then <i>Q</i> has already been classified as a package name, a type name, or an expression name:<p>
<ul><a name="22747"></a>
<li>If <i>Q</i> is a package name, then a compile-time error occurs.
<a name="22294"></a>
<li>If <i>Q</i> is a type name that names a class type <a href="classes.doc.html#3857">(&#167;8)</a>, then:
<ul>
<a name="22298"></a>
<li>If there is not exactly one accessible <a href="names.doc.html#104285">(&#167;6.6)</a> member of the class type that is a field named <i>Id</i>, then a compile-time error occurs.
<a name="22299"></a>
<li>Otherwise, if the single accessible member field is not a class variable (that is, it is not declared <code>static</code>), then a compile-time error occurs.
<a name="41289"></a>
<li>Otherwise, if the class variable is declared <code>final</code>, then <i>Q</i><code>.</code><i>Id</i> denotes the value of the class variable. The type of the expression <i>Q</i><code>.</code><i>Id</i> is the declared type of the class variable. If <i>Q</i><code>.</code><i>Id</i> appears in a context that requires a variable and not a value, then a compile-time error occurs.
<a name="22303"></a>
<li>Otherwise, <i>Q</i><code>.</code><i>Id</i> denotes the class variable. The type of the expression <i>Q</i><code>.</code><i>Id</i> is the declared type of the class variable.
</ul>
<a name="22145"></a>
<li>If <i>Q</i> is a type name that names an interface type <a href="interfaces.doc.html#238678">(&#167;9)</a>, then:
<ul>
<a name="33167"></a>
<li>If there is not exactly one accessible <a href="names.doc.html#104285">(&#167;6.6)</a> member of the interface type that is a field named <i>Id</i>, then a compile-time error occurs.
<a name="33169"></a>
<li>Otherwise, <i>Q</i><code>.</code><i>Id</i> denotes the value of the field. The type of the expression <i>Q</i><code>.</code><i>Id</i> is the declared type of the field. If <i>Q</i><code>.</code><i>Id</i> appears in a context that requires a variable and not a value, then a compile-time error occurs.
</ul>
<a name="22165"></a>
<li>If <i>Q</i> is an expression name, let <i>T</i> be the type of the expression <i>Q</i>:
<ul>
<a name="22169"></a>
<li>If <i>T</i> is not a reference type, a compile-time error occurs.
<a name="33185"></a>
<li>If there is not exactly one accessible <a href="names.doc.html#104285">(&#167;6.6)</a> member of the type <i>T</i> that is a field named <i>Id</i>, then a compile-time error occurs.
<a name="22170"></a>
<li>Otherwise, if this field is any of the following:
<ul>
<a name="33204"></a>
<li>A field of an interface type
<a name="33205"></a>
<li>A <code>final</code> field of a class type (which may be either a class variable or an instance variable)
<a name="33208"></a>
<li>The <code>final</code> field <code>length</code> of an array type
<br>then <i>Q</i><code>.</code><i>Id</i> denotes the value of the field. The type of the expression <i>Q</i><code>.</code><i>Id</i> is the declared type of the field. If <i>Q</i><code>.</code><i>Id</i> appears in a context that requires a variable and not a value, then a compile-time error occurs.
<br>
</ul>
<a name="22173"></a>
<li>Otherwise, <i>Q</i><code>.</code><i>Id</i> denotes a variable, the field <i>Id</i> of class <i>T</i>, which may be either a class variable or an instance variable. The type of the expression <i>Q</i><code>.</code><i>Id</i> is the declared type of the field
<a name="98602"></a>
<p>The example:
</ul>
</ul><blockquote><pre>class Point {
int x, y;
static int nPoints;
}
class Test {
public static void main(String[] args) {
int i = 0;
i.x++; // compile-time error
Point p = new Point();
p.nPoints(); // compile-time error
}
}
</pre></blockquote><a name="22187"></a>
encounters two compile-time errors, because the <code>int</code> variable <code>i</code> has no members, and because <code>nPoints</code> is not a method of class <code>Point</code>.<p>
<a name="21652"></a>
<h3>6.5.7 Meaning of Method Names</h3>
<a name="32771"></a>
A <em>MethodName</em> can appear only in a method invocation expression <a href="expressions.doc.html#20448">(&#167;15.12)</a>. The meaning of a name classified as a <em>MethodName</em> is determined as follows.<p>
<a name="54512"></a>
<h4>6.5.7.1 Simple Method Names</h4>
<a name="104325"></a>
If a method name consists of a single <em>Identifier</em>, then <em>Identifier</em> is the method name to be used for method invocation. The <em>Identifier</em> must name at least one method of a class or interface within whose declaration the <em>Identifier</em> appears. See <a href="expressions.doc.html#20448">&#167;15.12</a> for further discussion of the interpretation of simple method names in method invocation expressions.<p>
<a name="54547"></a>
<h4>6.5.7.2 Qualified Method Names</h4>
<a name="104276"></a>
If a method name is of the form <i>Q</i><code>.</code><i>Id</i>, then <i>Q</i> has already been classified as a package name, a type name, or an expression name. If <i>Q</i> is a package name, then a compile-time error occurs. Otherwise, <i>Id</i> is the method name to be used for method invocation. If <i>Q</i> is a type name, then <i>Id</i> must name at least one <code>static</code> method of the type <i>Q</i>. If <i>Q</i> is an expression name, then let <i>T</i> be the type of the expression <i>Q</i>; <i>Id</i> must name at least one method of the type <i>T</i>. See <a href="expressions.doc.html#20448">&#167;15.12</a> for further discussion of the interpretation of qualified method names in method invocation expressions.<p>
<a name="104285"></a>
<h2>6.6 Access Control</h2>
<a name="33924"></a>
The Java programming language provides mechanisms for <em>access control</em>, to prevent the users of a package or class from depending on unnecessary details of the implementation of that package or class. If access is permitted, then the accessed entity is said to be <em>accessible</em>.<p>
<a name="104333"></a>
Note that accessibility is a static property that can be determined at compile time; it depends only on types and declaration modifiers. Qualified names are a means of access to members of packages and reference types; related means of access include field access expressions <a href="expressions.doc.html#41267">(&#167;15.11)</a> and method invocation expressions <a href="expressions.doc.html#20448">(&#167;15.12)</a>. All three are syntactically similar in that a "<code>.</code>" token appears, preceded by some indication of a package, type, or expression having a type and followed by an <em>Identifier</em> that names a member of the package or type. These are collectively known as constructs for <em>qualified access</em>.<p>
<a name="104350"></a>
Access control applies to qualified access and to the invocation of constructors by class instance creation expressions <a href="expressions.doc.html#41147">(&#167;15.9)</a> and explicit constructor invocations <a href="classes.doc.html#78435">(&#167;8.8.5)</a>. Accessibility also affects inheritance of class members <a href="classes.doc.html#21831">(&#167;8.2)</a>, including hiding and method overriding <a href="classes.doc.html#227927">(&#167;8.4.6.1)</a>.<p>
<a name="102765"></a>
<h3>6.6.1 Determining Accessibility</h3>
<ul><a name="102769"></a>
<li>A package is always <em>accessible</em>.
<a name="102776"></a>
<li>If a class or interface type is declared <code>public</code>, then it may be accessed by any code, provided that the compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a> in which it is declared is observable. If a top level class or interface type is not declared <code>public</code>, then it may be accessed only from within the package in which it is declared.
<a name="106781"></a>
<li>An array type is accessible if and only if its element type is accessible.
<a name="62410"></a>
<li>A member (class, interface, field, or method) of a reference (class, interface, or array) type or a constructor of a class type is accessible only if the type is accessible and the member or constructor is declared to permit access:
<ul>
<a name="62795"></a>
<li>If the member or constructor is declared <code>public</code>, then access is permitted. All members of interfaces are implicitly <code>public</code>.
<a name="62561"></a>
<li>Otherwise, if the member or constructor is declared <code>protected</code>, then access is permitted only when one of the following is true:
<ul><ul>
<a name="62562"></a>
<li>Access to the member or constructor occurs from within the package containing the class in which the <code>protected</code> member or constructor is declared.
<a name="62452"></a>
<li>Access is correct as described in <a href="names.doc.html#62587">&#167;6.6.2</a>.
</ul>
</ul><a name="62857"></a>
<li>Otherwise, if the member or constructor is declared <code>private</code>, then access is permitted if and only if it occurs within the body of the top level class <a href="packages.doc.html#26783">(&#167;7.6)</a> that encloses the declaration of the member.
<a name="62586"></a>
<li>Otherwise, we say there is default access, which is permitted only when the access occurs from within the package in which the type is declared.
</ul>
</ul><a name="62587"></a>
<h3>6.6.2 Details on <code>protected Access</code></h3>
<a name="62638"></a>
A <code>protected</code> member or constructor of an object may be accessed from outside the package in which it is declared only by code that is responsible for the implementation of that object. <p>
<a name="60602"></a>
<h4>6.6.2.1 Access to a <code>protected</code> Member</h4>
<a name="104383"></a>
Let <i>C</i> be the class in which a <code>protected</code> member m is declared. Access is permitted only within the body of a subclass <i>S </i>of <i>C</i>. In addition, if <i>Id</i> denotes an instance field or instance method, then:<p>
<ul><a name="33946"></a>
<li>If the access is by a qualified name <i>Q</i><code>.</code><i>Id</i>, where <i>Q</i> is an <em>ExpressionName</em>, then the access is permitted if and only if the type of the expression <i>Q</i> is <i>S</i> or a subclass of <i>S</i>.
<a name="72727"></a>
<li>If the access is by a field access expression <i>E</i><code>.</code><i>Id</i>, where <i>E</i> is a <em>Primary</em> expression, or by a method invocation expression <i>E</i><code>.</code><i>Id</i><code>(</code>. . .<code>)</code>, where <i>E</i> is a <em>Primary</em> expression, then the access is permitted if and only if the type of <i>E</i> is <i>S</i> or a subclass of <i>S</i>.
</ul><a name="72728"></a>
<h4>6.6.2.2 Qualified Access to a <code>protected</code> Constructor</h4>
<a name="72596"></a>
Let <i>C</i> be the class in which a <code>protected</code> constructor is declared and let <i>S</i> be the innermost class in whose declaration the use of the <code>protected</code> constructor occurs. Then:<p>
<ul><a name="73445"></a>
<li>If the access is by a superclass constructor invocation <code>super(</code>. . .<code>)</code> or by a qualified superclass constructor invocation of the form <i>E</i><code>.super(. . .)</code>, where <i>E</i> is a <i>Primary</i> expression,<i> </i>then the access is permitted.
<a name="95698"></a>
<li>If the access is by an anonymous class instance creation expression of the form <code>new</code><i> C</i><code>(. . .){...}</code> or by a qualified class instance creation expression of the form <i>E</i><code>.new C(. . .){...}</code>, where <i>E</i> is a <i>Primary</i> expression, then the access is permitted.
<a name="95700"></a>
<li>Otherwise, if the access is by a simple class instance creation expression of the form <code>new</code> <i>C</i><code>(</code>. . .<code>)</code> or by a qualified class instance creation expression of the form <i>E</i><code>.new C(. . .)</code>, where <i>E</i> is a <i>Primary</i> expression, then the access is not permitted. A <code>protected</code> constructor can be accessed by a class instance creation expression (that does not declare an anonymous class) only from within the package in which it is defined.
</ul><a name="62666"></a>
<h3>6.6.3 An Example of Access Control</h3>
<a name="62647"></a>
For examples of access control, consider the two compilation units:<p>
<blockquote><pre>package points;
class PointVec { Point[] vec; }
</pre></blockquote><a name="33960"></a>
and:<p>
<blockquote><pre>package points;
public class Point {
protected int x, y;
public void move(int dx, int dy) { x += dx; y += dy; }
public int getX() { return x; }
public int getY() { return y; }
}
</pre></blockquote><a name="33968"></a>
which declare two class types in the package <code>points</code>:<p>
<ul><a name="33969"></a>
<li>The class type <code>PointVec</code> is not <code>public</code> and not part of the <code>public</code> interface of the package <code>points</code>, but rather can be used only by other classes in the package.
<a name="33970"></a>
<li>The class type <code>Point</code> is declared <code>public</code> and is available to other packages. It is part of the <code>public</code> interface of the package <code>points</code>.
<a name="33971"></a>
<li>The methods <code>move</code>, <code>getX</code>, and <code>getY</code> of the class <code>Point</code> are declared <code>public</code> and so are available to any code that uses an object of type <code>Point</code>.
<a name="33972"></a>
<li>The fields <code>x</code> and <code>y</code> are declared <code>protected</code> and are accessible outside the package <code>points</code> only in subclasses of class <code>Point,</code> and only when they are fields of objects that are being implemented by the code that is accessing them.
</ul><a name="33976"></a>
See <a href="names.doc.html#36191">&#167;6.6.7</a> for an example of how the <code>protected</code> access modifier limits access. <p>
<a name="36060"></a>
<h3>6.6.4 Example: Access to <code>public</code> and <code>Non-public</code> Classes</h3>
<a name="36063"></a>
If a class lacks the <code>public</code> modifier, access to the class declaration is limited to the package in which it is declared <a href="names.doc.html#104285">(&#167;6.6)</a>. In the example:<p>
<blockquote><pre>package points;
public class Point {
public int x, y;
public void move(int dx, int dy) { x += dx; y += dy; }
}
class PointList {
Point next, prev;
}
</pre></blockquote><a name="36084"></a>
two classes are declared in the compilation unit. The class <code>Point</code> is available outside the package <code>points</code>, while the class <code>PointList</code> is available for access only within the package. <p>
<a name="107165"></a>
Thus a compilation unit in another package can access <code>points.Point</code>, either by using its fully qualified name:
<blockquote><pre>package pointsUser;
class Test {
public static void main(String[] args) {
points.Point p = new points.Point();
System.out.println(p.x + " " + p.y);
}
}
</pre></blockquote><a name="36092"></a>
or by using a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> that mentions the fully qualified name, so that the simple name may be used thereafter:<p>
<blockquote><pre>package pointsUser;
import points.Point;
class Test {
public static void main(String[] args) {
Point p = new Point();
System.out.println(p.x + " " + p.y);
}
}
</pre></blockquote><a name="36104"></a>
However, this compilation unit cannot use or import <code>points.PointList</code>, which is not declared <code>public</code> and is therefore inaccessible outside package <code>points</code>.<p>
<a name="36154"></a>
<h3>6.6.5 Example: Default-Access Fields, Methods, and Constructors</h3>
<a name="36155"></a>
If none of the access modifiers <code>public</code>, <code>protected</code>, or <code>private</code> are specified, a class member or constructor is accessible throughout the package that contains the declaration of the class in which the class member is declared, but the class member or constructor is not accessible in any other package. <p>
<a name="107169"></a>
If a <code>public</code> class has a method or constructor with default access, then this method or constructor is not accessible to or inherited by a subclass declared outside this package.
<a name="60607"></a>
<p>
For example, if we have:
<blockquote><pre>package points;
public class Point {
public int x, y;
void move(int dx, int dy) { x += dx; y += dy; }
public void moveAlso(int dx, int dy) { move(dx, dy); }
}
</pre></blockquote><a name="36161"></a>
then a subclass in another package may declare an unrelated <code>move</code> method, with the same signature <a href="classes.doc.html#24510">(&#167;8.3.2)</a> and return type. Because the original <code>move</code> method is not accessible from package <code>morepoints</code>, <code>super</code> may not be used:<p>
<blockquote><pre>package morepoints;
public class PlusPoint extends points.Point {
public void move(int dx, int dy) {
super.move(dx, dy); // compile-time error
moveAlso(dx, dy);
}
}
</pre></blockquote><a name="61629"></a>
Because move of <code>Point</code> is not overridden by <code>move</code> in <code>PlusPoint</code>, the method <code>moveAlso</code> in <code>Point</code> never calls the method move in <code>PlusPoint</code>.<p>
<a name="61639"></a>
Thus if you delete the <code>super.move</code> call from <code>PlusPoint</code> and execute the test program:
<blockquote><pre>import points.Point;
import morepoints.PlusPoint;
class Test {
public static void main(String[] args) {
PlusPoint pp = new PlusPoint();
pp.move(1, 1);
}
}
</pre></blockquote><a name="61640"></a>
it terminates normally. If move of <code>Point</code> were overridden by <code>move</code> in <code>PlusPoint</code>, then this program would recurse infinitely, until a <code>StackoverflowError</code> occurred.<p>
<a name="36250"></a>
<h3>6.6.6 Example: <code>public</code> Fields, Methods, and Constructors</h3>
<a name="36251"></a>
A <code>public</code> class member or constructor is accessible throughout the package where it is declared and from any other package, provided the package in which it is declared is observable <a href="packages.doc.html#13180">(&#167;7.4.3)</a>. For example, in the compilation unit:<p>
<blockquote><pre>package points;
public class Point {
int x, y;
public void move(int dx, int dy) {
x += dx; y += dy;
moves++;
}
public static int moves = 0;
}
</pre></blockquote><a name="36189"></a>
the <code>public</code> class <code>Point</code> has as <code>public</code> members the <code>move</code> method and the <code>moves</code> field. These <code>public</code> members are accessible to any other package that has access to package <code>points</code>. The fields <code>x</code> and <code>y</code> are not <code>public</code> and therefore are accessible only from within the package <code>points</code>.<p>
<a name="36191"></a>
<h3>6.6.7 Example: <code>protected</code> Fields, Methods, and Constructors</h3>
<a name="36201"></a>
Consider this example, where the <code>points</code> package declares:<p>
<blockquote><pre>package points;
public class Point {
protected int x, y;
void warp(threePoint.Point3d a) {
if (a.z &gt; 0) // compile-time error: cannot access a.z
a.delta(this);
}
}
</pre></blockquote><a name="36204"></a>
and the <code>threePoint</code> package declares:<p>
<blockquote><pre>package threePoint;
import points.Point;
public class Point3d extends Point {
protected int z;
public void delta(Point p) {
p.x += this.x; // compile-time error: cannot access p.x
p.y += this.y; // compile-time error: cannot access p.y
}
public void delta3d(Point3d q) {
q.x += this.x;
q.y += this.y;
q.z += this.z;
}
}
</pre></blockquote><a name="36210"></a>
which defines a class <code>Point3d</code>. A compile-time error occurs in the method <code>delta </code>here: it cannot access the protected members <code>x</code> and <code>y</code> of its parameter <code>p</code>, because while <code>Point3d</code> (the class in which the references to fields <code>x</code> and <code>y</code> occur) is a subclass of <code>Point</code> (the class in which <code>x</code> and <code>y</code> are declared), it is not involved in the implementation of a <code>Point</code> (the type of the parameter <code>p</code>). The method <code>delta3d</code> can access the protected members of its parameter <code>q</code>, because the class <code>Point3d</code> is a subclass of <code>Point</code> and is involved in the implementation of a <code>Point3d</code>.<p>
<a name="36214"></a>
The method <code>delta</code> could try to cast (<a href="conversions.doc.html#20232">&#167;5.5</a>, <a href="expressions.doc.html#238146">&#167;15.16</a>) its parameter to be a <code>Point3d</code>, but this cast would fail, causing an exception, if the class of <code>p</code> at run time were not <code>Point3d</code>.
<a name="61715"></a>
<p>A compile-time error also occurs in the method warp: it cannot access the protected member <code>z</code> of its parameter <code>a</code>, because while the class <code>Point</code> (the class in which the reference to field <code>z</code> occurs) is involved in the implementation of a <code>Point3d</code> (the type of the parameter <code>a</code>), it is not a subclass of <code>Point3d</code> (the class in which <code>z</code> is declared).
<a name="36233"></a>
<h3>6.6.8 Example: <code>private</code> Fields, Methods, and Constructors</h3>
<a name="36235"></a>
A <code>private</code> class member or constructor is accessible only within the class body in which the member is declared and is not inherited by subclasses. In the example:<p>
<blockquote><pre>class Point {
Point() { setMasterID(); }
int x, y;
private int ID;
private static int masterID = 0;
private void setMasterID() { ID = masterID++; }
}
</pre></blockquote><a name="36243"></a>
the <code>private</code> members <code>ID,</code> <code>masterID</code>, and <code>setMasterID</code> may be used only within the body of class <code>Point</code>. They may not be accessed by qualified names, field access expressions, or method invocation expressions outside the body of the declaration of <code>Point</code>.<p>
<a name="62528"></a>
See <a href="classes.doc.html#16830">&#167;8.8.8</a> for an example that uses a <code>private</code> constructor.
<a name="25430"></a>
<h2>6.7 Fully Qualified Names and Canonical Names</h2>
<a name="24074"></a>
Every package, top level class, top level interface, and primitive type has a <em>fully qualified name</em>. An array type has a fully qualified name if and only if its element type has a fully qualified name.<p>
<ul><a name="9478"></a>
<li>The fully qualified name of a primitive type is the keyword for that primitive type, namely <code>boolean</code>, <code>char</code>, <code>byte</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>, or <code>double</code>.
<a name="33330"></a>
<li>The fully qualified name of a named package that is not a subpackage of a named package is its simple name.
<a name="33332"></a>
<li>The fully qualified name of a named package that is a subpackage of another named package consists of the fully qualified name of the containing package, followed by "<code>.</code>", followed by the simple (member) name of the subpackage.
<a name="28912"></a>
<li>The fully qualified name of a top level class or top level interface that is declared in an unnamed package is the simple name of the class or interface.
<a name="33340"></a>
<li>The fully qualified name of a top level class or top level interface that is declared in a named package consists of the fully qualified name of the package, followed by "<code>.</code>", followed by the simple name of the class or interface.
<a name="71701"></a>
<li>A member class or member interface <i>M</i> of another class <i>C</i> has a fully qualified name if and only if <i>C</i> has a fully qualified name. In that case, the fully qualified name of <i>M</i> consists of the fully qualified name of <i>C</i>, followed by ".", followed by the simple name of <i>M</i>.
<a name="79979"></a>
<li>The fully qualified name of an array type consists of the fully qualified name of the component type of the array type followed by "<code>[]</code>".
</ul><a name="79984"></a>
Examples:<p>
<ul><a name="79981"></a>
<li>The fully qualified name of the type <code>long</code> is "<code>long</code>".
<a name="12351"></a>
<li>The fully qualified name of the package <code>java.lang</code> is "<code>java.lang</code>" because it is subpackage <code>lang</code> of package <code>java</code>.
<a name="33392"></a>
<li>The fully qualified name of the class <code>Object</code>, which is defined in the package <code>java.lang</code>, is "<code>java.lang.Object</code>".
<a name="33394"></a>
<li>The fully qualified name of the interface <code>Enumeration</code>, which is defined in the package <code>java.util</code>, is "<code>java.util.Enumeration</code>".
<a name="33378"></a>
<li>The fully qualified name of the type "array of <code>double</code>" is "<code>double[]</code>".
<a name="33380"></a>
<li>The fully qualified name of the type "array of array of array of array of <code>String</code>" is "<code>java.lang.String[][][][]</code>".
</ul><a name="12352"></a>
In the example:<p>
<blockquote><pre>package points;
class Point { int x, y; }
class PointVec {
Point[] vec;
}
</pre></blockquote><a name="73301"></a>
the fully qualified name of the type <code>Point</code> is "<code>points.Point</code>"; the fully qualified name of the type <code>PointVec</code> is "<code>points.PointVec</code>"; and the fully qualified name of the type of the field <code>vec</code> of class <code>PointVec</code> is "<code>points.Point[]</code>".<p>
<a name="73354"></a>
Every package, top level class, top level interface, and primitive type has a canonical name. An array type has a canonical name if and only if its element type has a canonical name. A member class or member interface <i>M</i> declared in another class <i>C</i> has a canonical name if and only if <i>C</i> has a canonical name. In that case, the canonical name of <i>M</i> consists of the canonical name of <i>C</i>, followed by ".", followed by the simple name of <i>M</i>. For every package, top level class, top level interface and primitive type, the canonical name is the same as the fully qualified name. The canonical name of an array type is defined only when the component type of the array has a canonical name. In that case, the canonical name of the array type consists of the canonical name of the component type of the array type followed by "<code>[]</code>".<p>
<a name="81303"></a>
The difference between a fully qualified name and a canonical name can be seen in examples such as:
<blockquote><pre>package p;
class O1 { class I{}}
class O2 extends O1{};
</pre></blockquote><a name="81324"></a>
In this example both <code>p.O1.I</code> and <code>p.O2.I</code> are fully qualified names that denote the same class, but only <code>p.O1.I</code> is its canonical name.<p>
<a name="73307"></a>
<h2>6.8 Naming Conventions</h2>
<a name="9218"></a>
The class libraries of the Java platform attempt to use, whenever possible, names chosen according to the conventions presented here. These conventions help to make code more readable and avoid certain kinds of name conflicts.<p>
<a name="34468"></a>
We recommend these conventions for use in all programs written in the Java programming language. However, these conventions should not be followed slavishly if long-held conventional usage dictates otherwise. So, for example, the <code>sin</code> and <code>cos</code> methods of the class <code>java.lang.Math</code> have mathematically conventional names, even though these method names flout the convention suggested here because they are short and are not verbs.
<a name="9184"></a>
<h3>6.8.1 Package Names</h3>
<a name="9253"></a>
Names of packages that are to be made widely available should be formed as described in <a href="packages.doc.html#40169">&#167;7.7</a>. Such names are always qualified names whose first identifier consists of two or three lowercase letters that name an Internet domain, such as <code>com</code>, <code>edu</code>, <code>gov</code>, <code>mil</code>, <code>net</code>, <code>org</code>, or a two-letter ISO country code such as <code>uk</code> or <code>jp</code>. Here are examples of hypothetical unique names that might be formed under this convention:<p>
<blockquote><pre>com.JavaSoft.jag.Oak
org.npr.pledge.driver
uk.ac.city.rugby.game
<a name="32841"></a>
</pre></blockquote>
Names of packages intended only for local use should have a first identifier that begins with a lowercase letter, but that first identifier specifically should not be the identifier <code>java</code>; package names that start with the identifier <code>java</code> are reserved by Sun for naming Java platform packages.
<a name="81419"></a>
<p>
When package names occur in expressions:
<ul><a name="81420"></a>
<li>If a package name is obscured by a field declaration, then <code>import</code> declarations <a href="packages.doc.html#70209">(&#167;7.5)</a> can usually be used to make available the type names declared in that package.
<a name="34379"></a>
<li>If a package name is obscured by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other code.
<a name="34365"></a>
<p>
The first component of a package name is normally not easily mistaken for a type name, as a type name normally begins with a single uppercase letter. (The Java programming language does not actually rely on case distinctions to determine whether a name is a package name or a type name.)
</ul><a name="29466"></a>
<h3>6.8.2 Class and Interface Type Names</h3>
<a name="32824"></a>
Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed case with the first letter of each word capitalized. For example:<p>
<blockquote><pre><code>ClassLoader
</code><code>SecurityManager
</code><code>Thread
</code><code>Dictionary
</code>BufferedInputStream
</pre></blockquote>
<a name="9111"></a>
Likewise, names of interface types should be short and descriptive, not overly long, in mixed case with the first letter of each word capitalized. The name may be a descriptive noun or noun phrase, which is appropriate when an interface is used as if it were an abstract superclass, such as interfaces <code>java.io.DataInput</code> and <code>java.io.DataOutput</code>; or it may be an adjective describing a behavior, as for the interfaces <code>Runnable</code> and <code>Cloneable</code>.
<a name="12992"></a>
<p>
Obscuring involving class and interface type names is rare. Names of fields, parameters, and local variables normally do not obscure type names because they conventionally begin with a lowercase letter whereas type names conventionally begin with an uppercase letter.
</pre></blockquote><a name="9322"></a>
<h3>6.8.3 Method Names</h3>
<a name="34563"></a>
Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase and the first letter of any subsequent words capitalized. Here are some additional specific conventions for method names:<p>
<ul><a name="34587"></a>
<li>Methods to <code>get</code> and <code>set</code> an attribute that might be thought of as a variable <i>V</i> should be named <code>get</code>V and <code>set</code>V. An example is the methods <code>getPriority</code> and <code>setPriority</code> of class <code>Thread</code>.
<a name="34594"></a>
<li>A method that returns the length of something should be named <code>length</code>, as in class <code>String</code>.
<a name="9341"></a>
<li>A method that tests a <code>boolean</code> condition <i>V</i> about an object should be named <code>is</code>V. An example is the method <code>isInterrupted</code> of class <code>Thread</code>.
<a name="34650"></a>
<li>A method that converts its object to a particular format <em>F</em> should be named <code>to</code>F. Examples are the method <code>toString</code> of class <code>Object</code> and the methods <code>toLocaleString</code> and <code>toGMTString</code> of class <code>java.util.Date</code>.
</ul><a name="34660"></a>
Whenever possible and appropriate, basing the names of methods in a new class on names in an existing class that is similar, especially a class from the Java Application Programming Interface classes, will make it easier to use.<p>
<a name="9384"></a>
Method names cannot obscure or be obscured by other names <a href="names.doc.html#21652">(&#167;6.5.7)</a>.
<a name="9351"></a>
<h3>6.8.4 Field Names</h3>
<a name="32831"></a>
Names of fields that are not <code>final</code> should be in mixed case with a lowercase first letter and the first letters of subsequent words capitalized. Note that well-designed classes have very few <code>public</code> or <code>protected</code> fields, except for fields that are constants (<code>final</code> <code>static</code> fields) <a href="names.doc.html#9367">(&#167;6.8.5)</a>.<p>
<a name="56830"></a>
Fields should have names that are nouns, noun phrases, or abbreviations for nouns. Examples of this convention are the fields <code>buf</code>, <code>pos</code>, and <code>count</code> of the class <code>java.io.ByteArrayInputStream</code> and the field <code>bytesTransferred</code> of the class <code>java.io.InterruptedIOException</code>.
<a name="13055"></a>
<p>Obscuring involving field names is rare.
<ul><a name="29526"></a>
<li>If a field name obscures a package name, then an <code>import</code> declaration <a href="packages.doc.html#70209">(&#167;7.5)</a> can usually be used to make available the type names declared in that package.
<a name="13069"></a>
<li>If a field name obscures a type name, then a fully qualified name for the type can be used unless the type name denotes a local class <a href="statements.doc.html#247766">(&#167;14.3)</a>.
<a name="29539"></a>
<li>Field names cannot obscure method names.
<a name="9539"></a>
<li>If a field name is shadowed by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other code.
</ul><a name="9367"></a>
<h3>6.8.5 Constant Names</h3>
<a name="9368"></a>
The names of constants in interface types should be, and <code>final</code> variables of class types may conventionally be, a sequence of one or more words, acronyms, or abbreviations, all uppercase, with components separated by underscore "<code>_</code>" characters. Constant names should be descriptive and not unnecessarily abbreviated. Conventionally they may be any appropriate part of speech. Examples of names for constants include <code>MIN_VALUE</code>, <code>MAX_VALUE</code>, <code>MIN_RADIX</code>, and <code>MAX_RADIX</code> of the class <code>Character</code>.<p>
<a name="9563"></a>
A group of constants that represent alternative values of a set, or, less frequently, masking bits in an integer value, are sometimes usefully specified with a common acronym as a name prefix, as in:
<blockquote><pre>interface ProcessStates {
int PS_RUNNING = 0;
int PS_SUSPENDED = 1;
}
</pre></blockquote><a name="13087"></a>
Obscuring involving constant names is rare:<p>
<ul><a name="62840"></a>
<li>Constant names normally have no lowercase letters, so they will not normally obscure names of packages or types, nor will they normally shadow fields, whose names typically contain at least one lowercase letter.
<a name="62841"></a>
<li>Constant names cannot obscure method names, because they are distinguished syntactically.
</ul><a name="62552"></a>
<h3>6.8.6 Local Variable and Parameter Names</h3>
<a name="81404"></a>
Local variable and parameter names should be short, yet meaningful. They are often short sequences of lowercase letters that are not words. For example:<p>
<ul><a name="81405"></a>
<li>Acronyms, that is the first letter of a series of words, as in <code>cp</code> for a variable holding a reference to a <code>ColoredPoint</code>
<a name="12410"></a>
<li>Abbreviations, as in <code>buf</code> holding a pointer to a <code>buffer</code> of some kind
<a name="12434"></a>
<li>Mnemonic terms, organized in some way to aid memory and understanding, typically by using a set of local variables with conventional names patterned after the names of parameters to widely used classes. For example:
<ul>
<a name="12435"></a>
<li><code>in</code> and <code>out</code>, whenever some kind of input and output are involved, patterned after the fields of <code>System</code>
<a name="12436"></a>
<li><code>off</code> and <code>len</code>, whenever an offset and length are involved, patterned after the parameters to the <code>read</code> and <code>write</code> methods of the interfaces <code>DataInput</code> and <code>DataOutput</code> of <code>java.io</code>
<a name="12367"></a>
</ul>
</ul>
<p>One-character local variable or parameter names should be avoided, except for temporary and looping variables, or where a variable holds an undistinguished value of a type. Conventional one-character names are:
<a name="9148"></a>
<ul>
<li><code>b</code> for a <code>byte</code>
<a name="9149"></a>
<li><code>c</code> for a <code>char</code>
<a name="12485"></a>
<li><code>d</code> for a <code>double</code>
<a name="9150"></a>
<li><code>e</code> for an <code>Exception</code>
<a name="12479"></a>
<li><code>f</code> for a <code>float</code>
<a name="9151"></a>
<li><code>i</code>, <code>j</code>, and <code>k</code> for integers
<a name="12846"></a>
<li><code>l</code> for a <code>long</code>
<a name="9155"></a>
<li><code>o</code> for an <code>Object</code>
<a name="12475"></a>
<li><code>s</code> for a <code>String</code>
<a name="12474"></a>
<li><code>v</code> for an arbitrary value of some type
<a name="34406"></a>
</ul>
Local variable or parameter names that consist of only two or three lowercase letters should not conflict with the initial country codes and domain names that are the first component of unique package names <a href="packages.doc.html#40169">(&#167;7.7)</a>.
</ul><a name="65318"></a>
<p>
<hr>
<table border="0" width="100%">
<tr>
<td><a href="jTOC.doc.html">Contents</a> | <a href="conversions.doc.html">Prev</a> | <a href="packages.doc.html">Next</a> | <a href="jIX.fm.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">Second Edition</font></td></tr></table>
<i><a href="jcopyright.doc.html">Copyright</a> &#169 2000 Sun Microsystems, Inc.
All rights reserved</i>
<br>
Please send any comments or corrections via our <a href="http://developers.sun.com/contact/feedback.jsp?&category=doc&mailsubject=Java%20Language%20Specification%20Feedback">feedback form</a>
</font>
<script language="JavaScript" src="/js/omi/jsc/s_code_remote.js"></script></body></html>
<html>
<head>
<title> Packages</title>
<meta name="collection" content="exclude">
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="jTOC.doc.html">Contents</a> | <a href="names.doc.html">Prev</a> | <a href="classes.doc.html">Next</a> | <a href="jIX.fm.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">Second Edition</font></td></tr></table>
<hr><br>
<a name="34412"></a>
<p><strong>
CHAPTER
7 </strong></p>
<a name="60384"></a>
<h1>Packages</h1>
<hr><p>
<a name="61541"></a>
Programs are organized as sets of packages. Each package has its own set of names for types, which helps to prevent name conflicts. A top level type is accessible <a href="names.doc.html#104285">(&#167;6.6)</a> outside the package that declares it only if the type is declared <code>public</code>.<p>
<a name="26517"></a>
The naming structure for packages is hierarchical <a href="packages.doc.html#26535">(&#167;7.1)</a>. The members of a package are class and interface types <a href="packages.doc.html#26783">(&#167;7.6)</a>, which are declared in compilation units of the package, and subpackages, which may contain compilation units and subpackages of their own.<p>
<a name="40294"></a>
A package can be stored in a file system <a href="packages.doc.html#37546">(&#167;7.2.1)</a> or in a database <a href="packages.doc.html#37739">(&#167;7.2.2)</a>. Packages that are stored in a file system have certain constraints on the organization of their compilation units to allow a simple implementation to find classes easily.<p>
<a name="26522"></a>
A package consists of a number of compilation units <a href="packages.doc.html#40031">(&#167;7.3)</a>. A compilation unit automatically has access to all types declared in its package and also automatically imports<em> </em>all of the public types declared in the predefined package<em> </em><code>java.lang</code>.<p>
<a name="26526"></a>
For small programs and casual development, a package can be unnamed <a href="packages.doc.html#26639">(&#167;7.4.2)</a> or have a simple name, but if code is to be widely distributed, unique package names should be chosen <a href="packages.doc.html#40169">(&#167;7.7)</a>. This can prevent the conflicts that would otherwise occur if two development groups happened to pick the same package name and these packages were later to be used in a single program.
<a name="26535"></a>
<h2>7.1 Package Members</h2>
<a name="91953"></a>
The members of a package are subpackages and all the top level <a href="packages.doc.html#26783">(&#167;7.6)</a> class <a href="classes.doc.html#3857">(&#167;8)</a> and top level interface <a href="interfaces.doc.html#238678">(&#167;9)</a> types declared in all the compilation units <a href="packages.doc.html#40031">(&#167;7.3)</a> of the package.<p>
<a name="85252"></a>
For example, in the Java Application Programming Interface:<p>
<ul><a name="37559"></a>
<li>The package <code>java</code> has subpackages <code>awt</code>, <code>applet</code>, <code>io</code>, <code>lang</code>, <code>net</code>, and <code>util</code>, but no compilation units.
<a name="37560"></a>
<li>The package <code>java.awt</code> has a subpackage named <code>image</code>, as well as a number of compilation units containing declarations of class and interface types.
</ul><a name="13127"></a>
If the fully qualified name <a href="names.doc.html#25430">(&#167;6.7)</a> of a package is <i>P</i>, and <i>Q</i> is a subpackage of <i>P</i>, then <i>P</i><code>.</code><i>Q</i> is the fully qualified name of the subpackage.<p>
<a name="77109"></a>
A package may not contain two members of the same name, or a compile-time error results. <p>
<a name="77111"></a>
Here are some examples:
<ul><a name="37575"></a>
<li>Because the package <code>java.awt</code> has a subpackage <code>image</code>, it cannot (and does not) contain a declaration of a class or interface type named <code>image</code>.
<a name="73657"></a>
<li>If there is a package named <code>mouse</code> and a member type <code>Button</code> in that package (which then might be referred to as <code>mouse.Button</code>), then there cannot be any package with the fully qualified name <code>mouse.Button</code> or <code>mouse.Button.Click</code>.
<a name="73658"></a>
<li>If <code>com.sun.java.jag</code> is the fully qualified name of a type, then there cannot be any package whose fully qualified name is either <code>com.sun.java.jag</code> or <code>com.sun.java.jag.scrabble</code>.
<a name="73659"></a>
</ul>
The hierarchical naming structure for packages is intended to be convenient for organizing related packages in a conventional manner, but has no significance in itself other than the prohibition against a package having a subpackage with the same simple name as a top level type <a href="packages.doc.html#26783">(&#167;7.6)</a> declared in that package. There is no special access relationship between a package named <code>oliver</code> and another package named <code>oliver.twist</code>, or between packages named <code>evelyn.wood</code> and <code>evelyn.waugh</code>. For example, the code in a package named <code>oliver.twist</code> has no better access to the types declared within package <code>oliver</code> than code in any other package.
<a name="37758"></a>
<h2>7.2 Host Support for Packages</h2>
<a name="37780"></a>
Each host determines how packages, compilation units, and subpackages are created and stored, and which compilation units are observable <a href="packages.doc.html#40031">(&#167;7.3)</a> in a particular compilation. <p>
<a name="89673"></a>
The observability of compilation units in turn determines which packages are observable, and which packages are in scope.
<a name="73467"></a>
<p>The packages may be stored in a local file system in simple implementations of the Java platform. Other implementations may use a distributed file system or some form of database to store source and/or binary code.
<a name="37546"></a>
<h3>7.2.1 Storing Packages in a File System</h3>
<a name="37463"></a>
As an extremely simple example, all the packages and source and binary code on a system might be stored in a single directory and its subdirectories. Each immediate subdirectory of this directory would represent a top level package, that is, one whose fully qualified name consists of a single simple name. The directory might contain the following immediate subdirectories:<p>
<blockquote><pre>com
gls
jag
java
wnj
</pre></blockquote><a name="37477"></a>
where directory <code>java</code> would contain the Java Application Programming Interface packages; the directories <code>jag</code>, <code>gls</code>, and <code>wnj</code> might contain packages that three of the authors of this specification created for their personal use and to share with each other within this small group; and the directory <code>com</code> would contain packages procured from companies that used the conventions described in <a href="packages.doc.html#40169">&#167;7.7</a> to generate unique names for their packages.<p>
<a name="37480"></a>
Continuing the example, the directory <code>java</code> would contain, among others, the following subdirectories:
<blockquote><pre>applet
awt
io
lang
net
util
</pre></blockquote><a name="37490"></a>
corresponding to the packages <code>java.applet</code>, <code>java.awt</code>, <code>java.io</code>, <code>java.lang</code>, <code>java.net</code>, and <code>java.util</code> that are defined as part of the Java Application Programming Interface.<p>
<a name="37491"></a>
Still continuing the example, if we were to look inside the directory <code>util</code>, we might see the following files:
<blockquote><pre>
BitSet.java Observable.java
BitSet.class Observable.class
Date.java Observer.java
Date.class Observer.class
...
</pre></blockquote><a name="37466"></a>
where each of the <code>.java</code> files contains the source for a compilation unit <a href="packages.doc.html#40031">(&#167;7.3)</a> that contains the definition of a class or interface whose binary compiled form is contained in the corresponding <code>.class</code> file.<p>
<a name="37599"></a>
Under this simple organization of packages, an implementation of the Java platform would transform a package name into a pathname by concatenating the components of the package name, placing a file name separator (directory indicator) between adjacent components.
<a name="91586"></a>
<p>For example, if this simple organization were used on a UNIX system, where the file name separator is <code>/</code>, the package name:
<blockquote><pre>jag.scrabble.board
</pre></blockquote><a name="37601"></a>
would be transformed into the directory name:<p>
<blockquote><pre>jag/scrabble/board
</pre></blockquote><a name="37603"></a>
and:<p>
<blockquote><pre>com.sun.sunsoft.DOE
</pre></blockquote><a name="37605"></a>
would be transformed to the directory name:<p>
<blockquote><pre><code>com/sun/sunsoft/DOE
</code><a name="77903"></a>
</pre></blockquote>
A package name component or class name might contain a character that cannot correctly appear in a host file system's ordinary directory name, such as a Unicode character on a system that allows only ASCII characters in file names. As a convention, the character can be escaped by using, say, the <code>@</code> character followed by four hexadecimal digits giving the numeric value of the character, as in the <code>\u</code><i>xxxx</i> escape <a href="lexical.doc.html#100850">(&#167;3.3)</a>, so that the package name:
<blockquote><pre>
children.activities.crafts.papierM\u00e2ch\u00e9
</pre></blockquote><a name="77910"></a>
which can also be written using full Unicode as:<p>
<blockquote><pre>children.activities.crafts.papierM&acirc;ch&eacute;
</pre></blockquote><a name="37616"></a>
might be mapped to the directory name:<p>
<blockquote><pre>children/activities/crafts/papierM@00e2ch@00e9
</pre></blockquote><a name="37618"></a>
If the <code>@</code> character is not a valid character in a file name for some given host file system, then some other character that is not valid in an identifier could be used instead.<p>
<a name="37739"></a>
<h3>7.2.2 Storing Packages in a Database</h3>
<a name="37740"></a>
A host system may store packages and their compilation units and subpackages in a database.<p>
<a name="85462"></a>
Such a database must not impose the optional restrictions <a href="packages.doc.html#26783">(&#167;7.6)</a> on compilation units in file-based implementations. For example, a system that uses a database to store packages may not enforce a maximum of one <code>public</code> class or interface per compilation unit.
<a name="74243"></a>
<p>
Systems that use a database must, however, provide an option to convert a program to a form that obeys the restrictions, for purposes of export to file-based implementations.<p>
<a name="40031"></a>
<h2>7.3 Compilation Units</h2>
<a name="26594"></a>
<em>CompilationUnit </em>is the goal symbol <a href="grammars.doc.html#40415">(&#167;2.1)</a> for the syntactic grammar <a href="grammars.doc.html#151185">(&#167;2.3)</a> of Java programs. It is defined by the following productions:<p>
<ul><pre>
<em>CompilationUnit</em>:
<em> PackageDeclaration</em><sub><i>opt</i></sub><code> </code>ImportDeclarations<sub><i>opt</i></sub><code> </code>TypeDeclarations<sub><i>opt
</i></sub>
<i>ImportDeclarations:
ImportDeclaration
ImportDeclarations<code> </code>ImportDeclaration
TypeDeclarations:
TypeDeclaration
TypeDeclarations<code> </code>TypeDeclaration
</i></pre></ul><a name="24124"></a>
Types declared in different compilation units can depend on each other, circularly. A Java compiler must arrange to compile all such types at the same time.<p>
<a name="35022"></a>
A <em>compilation unit</em> consists of three parts, each of which is optional:<p>
<ul><a name="35029"></a>
<li>A <code>package</code> declaration <a href="packages.doc.html#26619">(&#167;7.4)</a>, giving the fully qualified name <a href="names.doc.html#25430">(&#167;6.7)</a> of the package to which the compilation unit belongs. A compilation unit that has no package declaration is part of an unnamed package <a href="packages.doc.html#26639">(&#167;7.4.2)</a>.
<a name="35033"></a>
<li><code>import</code> declarations <a href="packages.doc.html#70209">(&#167;7.5)</a> that allow types from other packages to be referred to using their simple names
<a name="35037"></a>
<li>Top level type declarations <a href="packages.doc.html#26783">(&#167;7.6)</a> of class and interface types
</ul><a name="70276"></a>
Which compilation units are <em>observable</em> is determined by the host system. However, all the compilation units of the package <code>java</code> and its subpackages <code>lang</code> and <code>io</code> must always be observable. The observability of a compilation unit influences the observability of its package <a href="packages.doc.html#13180">(&#167;7.4.3)</a>.<p>
<a name="26614"></a>
Every compilation unit automatically and implicitly imports every <code>public</code> type name declared by the predefined package <code>java.lang</code>, so that the names of all those types are available as simple names, as described in <a href="packages.doc.html#26741">&#167;7.5.3</a>.<p>
<a name="26619"></a>
<h2>7.4 Package Declarations</h2>
<a name="35052"></a>
A package declaration appears within a compilation unit to indicate the package to which the compilation unit belongs.<p>
<a name="26621"></a>
<h3>7.4.1 Named Packages</h3>
<a name="26626"></a>
A <em>package declaration</em> in a compilation unit specifies the name <a href="names.doc.html#31692">(&#167;6.2)</a> of the package to which the compilation unit belongs.<p>
<ul><pre>
<em>PackageDeclaration:
</em><code>package </code><em>PackageName</em><code> ;
</code></pre></ul><a name="26629"></a>
The package name mentioned in a package declaration must be the fully qualified name <a href="names.doc.html#25430">(&#167;6.7)</a> of the package.<p>
<a name="26639"></a>
<h3>7.4.2 Unnamed Packages</h3>
<a name="70410"></a>
A compilation unit that has no package declaration is part of an unnamed package. <p>
<a name="73463"></a>
Note that an unnamed package cannot have subpackages, since the syntax of a package declaration always includes a reference to a named top level package.
<p>
<a name="73468"></a>
As an example, the compilation unit:<p>
<blockquote><pre>class FirstCall {
public static void main(String[] args) {
System.out.println("Mr. Watson, come here. "
+ "I want you.");
}
}
</pre></blockquote><a name="35114"></a>
defines a very simple compilation unit as part of an unnamed package.<p>
<a name="73470"></a>
An implementation of the Java platform must support at least one unnamed package; it may support more than one unnamed package but is not required to do so. Which compilation units are in each unnamed package is determined by the host system.<p>
<a name="73469"></a>
In implementations of the Java platform that use a hierarchical file system for storing packages, one typical strategy is to associate an unnamed package with each directory; only one unnamed package is observable at a time, namely the one that is associated with the "current working directory." The precise meaning of "current working directory" depends on the host system.
<a name="73471"></a>
<p>
Unnamed packages are provided by the Java platform principally for convenience when developing small or temporary applications or when just beginning development.
<a name="13180"></a>
<h3>7.4.3 Observability of a Package</h3>
<a name="70173"></a>
A package is <em>observable</em> if and only if either:<p>
<ul><a name="70174"></a>
<li>A compilation unit containing a declaration of the package is observable.
<a name="70175"></a>
<li>A subpackage of the package is observable.
<a name="89676"></a>
</ul>
One can conclude from the rule above and from the requirements on observable compilation units, that the packages <code>java</code>, <code>java.lang</code>, and <code>java.io</code> are always observable.
<a name="70172"></a>
<h3>7.4.4 Scope of a Package Declaration</h3>
<a name="91970"></a>
The scope of the declaration of an observable <a href="packages.doc.html#13180">(&#167;7.4.3)</a> top level package is all observable compilation units <a href="packages.doc.html#40031">(&#167;7.3)</a>. The declaration of a package that is not observable is never in scope. Subpackage declarations are never in scope.<p>
<a name="87388"></a>
It follows that the package <code>java</code> is always in scope <a href="names.doc.html#103228">(&#167;6.3)</a>.
<p>
<a name="91991"></a>
Package declarations never shadow other declarations.<p>
<a name="70209"></a>
<h2>7.5 Import Declarations</h2>
<a name="26658"></a>
An <em>import declaration</em> allows a named type to be referred to by a simple name <a href="names.doc.html#31692">(&#167;6.2)</a> that consists of a single identifier. Without the use of an appropriate <code>import</code> declaration, the only way to refer to a type declared in another package is to use a fully qualified name <a href="names.doc.html#25430">(&#167;6.7)</a>.<p>
<ul><pre>
<em>ImportDeclaration</em>:
SingleTypeImportDeclaration
TypeImportOnDemandDeclaration
</pre></ul><a name="37962"></a>
A single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> imports a single named type, by mentioning its canonical name. A type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a> imports all the accessible types of a named type or package as needed.<p>
<a name="92000"></a>
The scope of a type imported by a single-type-import declaration <a href="packages.doc.html#26699">(&#167;7.5.1)</a> or type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a> is all the class and interface type declarations <a href="packages.doc.html#26783">(&#167;7.6)</a> in the compilation unit in which the import declaration appears.<p>
<a name="69951"></a>
An <code>import</code> declaration makes types available by their simple names only within the compilation unit that actually contains the <code>import</code> declaration. The scope of the entities(s) it introduces specifically does not include the <code>package</code> statement, other <code>import</code> declarations in the current compilation unit, or other compilation units in the same package. See <a href="packages.doc.html#24151">&#167;7.5.4</a> for an illustrative example.<p>
<a name="26699"></a>
<h3>7.5.1 Single-Type-Import Declaration</h3>
<a name="13275"></a>
A <em>single-type-import declaration </em>imports a single type by giving its canonical name, making it available under a simple name in the class and interface declarations of the compilation unit in which the single-type import declaration appears.<p>
<ul><pre>
<i>SingleTypeImportDeclaration:</i>
<code> import </code><i>TypeName</i> ;
</pre></ul><a name="29086"></a>
The <em>TypeName</em> must be the canonical name of a class or interface type; a compile-time error occurs if the named type does not exist. The named type must be accessible <a href="names.doc.html#104285">(&#167;6.6)</a> or a compile-time error occurs.<p>
<a name="91940"></a>
A single-type-import declaration <i>d</i> in a compilation unit <i>c</i> of package <i>p</i> that imports a type named <i>n</i> shadows the declarations of:<p>
<ul><a name="91942"></a>
<li>any top level type named <i>n</i> declared in another compilation unit of <i>p</i>.
<a name="91943"></a>
<li>any type named <i>n</i> imported by a type-import-on-demand declaration in <i>c</i>.
</ul><a name="91944"></a>
throughout <i>c.</i><p>
<a name="37971"></a>
The example:
<blockquote><pre>import java.util.Vector;
</pre></blockquote><a name="45771"></a>
causes the simple name <code>Vector</code> to be available within the class and interface declarations in a compilation unit. Thus, the simple name <code>Vector</code> refers to the type <code>Vector</code> in the package <code>java.util</code> in all places where it is not shadowed <a href="names.doc.html#34133">(&#167;6.3.1)</a> or obscured <a href="names.doc.html#104058">(&#167;6.3.2)</a> by a declaration of a field, parameter, local variable, or nested type declaration with the same name.<p>
<a name="73473"></a>
If two single-type-import declarations in the same compilation unit attempt to import types with the same simple name, then a compile-time error occurs, unless the two types are the same type, in which case the duplicate declaration is ignored. If another top level type with the same simple name is otherwise declared in the current compilation unit except by a type-import-on-demand declaration <a href="packages.doc.html#26725">(&#167;7.5.2)</a>, then a compile-time error occurs. <p>
<a name="73474"></a>
So the sample program:
<blockquote><pre>import java.util.Vector;
class Vector { Object[] vec; }
</pre></blockquote><a name="29137"></a>
causes a compile-time error because of the duplicate declaration of <code>Vector</code>, as does:<p>
<blockquote><pre>import java.util.Vector;
import myVector.Vector;
</pre></blockquote><a name="29140"></a>
where <code>myVector</code> is a package containing the compilation unit:<p>
<blockquote><pre>package myVector;
public class Vector { Object[] vec; }
</pre></blockquote><a name="73475"></a>
The compiler keeps track of types by their binary names <a href="binaryComp.doc.html#44909">(&#167;13.1)</a>.<p>
<a name="60471"></a>
Note that an import statement cannot import a subpackage, only a type. For example, it does not work to try to import <code>java.util</code> and then use the name <code>util.Random</code> to refer to the type <code>java.util.Random</code>:
<blockquote><pre>
import java.util; // incorrect: compile-time error
class Test { util.Random generator; }
</pre></blockquote><a name="26725"></a>
<h3>7.5.2 Type-Import-on-Demand Declaration</h3>
<a name="26727"></a>
A <em>type-import-on-demand declaration</em> allows all accessible <a href="names.doc.html#104285">(&#167;6.6)</a> types declared in the type or package named by a canonical name to be imported as needed.<p>
<ul><pre>
<i>TypeImportOnDemandDeclaration:</i>
<em> </em><code>import </code><i>PackageOrType<em>Name</i></em><code> . * ;
</code></pre></ul><a name="91257"></a>
It is a compile-time error for a type-import-on-demand declaration to name a type or package that is not accessible. Two or more type-import-on-demand declarations in the same compilation unit may name the same type or package; the effect is as if there were exactly one such declaration. It is not a compile-time error to name the current package or <code>java.lang</code> in a type-import-on-demand declaration. The type-import-on-demand declaration is ignored in such cases<p>
<a name="92030"></a>
A type-import-on-demand declaration never causes any other declaration to be shadowed.<p>
<a name="91265"></a>
The example:<p>