Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
9858 lines (9818 sloc) 686 KB
<html>
<head>
<meta name="collection" content="exclude">
<title>The Java Language Specification
Types, Values, and Variables</title>
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="index.html">Contents</a> | <a href="3.doc.html">Prev</a> | <a href="5.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">First Edition</font></td></tr></table>
<hr><br>
<a name="95843"></a>
<p><strong>
CHAPTER
4 </strong></p>
<a name="95845"></a>
<h1>Types, Values, and Variables</h1>
<hr><p>
<a name="45200"></a>
Java is a <i>strongly typed</i> 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="4.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 language are divided into two categories: primitive types and reference types. The primitive types <a href="4.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="4.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="4.doc.html#12028">(&#167;4.3.1)</a> in Java 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="4.doc.html#11055">(&#167;4.3.2)</a>. String literals are represented by <code>String</code> objects <a href="4.doc.html#26992">(&#167;4.3.3)</a>.<p>
<a name="50838"></a>
Types are the same <a href="4.doc.html#52197">(&#167;4.3.4)</a> if they have the same fully qualified names and are loaded by the same class loader. Names of types are used <a href="4.doc.html#25948">(&#167;4.4)</a> in declarations, in casts, in class instance creation expressions, in array creation expressions, and in <code>instanceof</code> operator expressions.<p>
<a name="50800"></a>
A variable <a href="4.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><em></em> can hold a null reference or a reference to an instance of class <i>T</i><em></em> 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><em></em>" can hold a null reference or a reference to any array of type "array of <i>T</i><em></em>"; if <i>T</i> is a reference type, then a variable of type "array of <i>T</i><em></em>" can hold a null reference or a reference to any array of type "array of <i>S</i><em></em>" such that type <i>S</i><em></em> is assignable <a href="5.doc.html#170768">(&#167;5.2)</a> to type <i>T</i><em></em>. A variable of type <code>Object</code> can hold a null reference or a reference to any object, whether class instance 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 <i>types</i> in Java: primitive types <a href="4.doc.html#85587">(&#167;4.2)</a> and reference types
<a href="4.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="4.doc.html#85587">(&#167;4.2)</a> and reference values <a href="4.doc.html#9317">(&#167;4.3)</a>.
<p><ul><pre>
<i>Type:<br>
</i> <i>PrimitiveType<br>
ReferenceType
</i></pre></ul><a name="23953"></a>
There is also a special <i>null type</i>, 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 Java 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 <i>primitive type</i> is predefined by the Java language and named by its reserved
keyword <a href="3.doc.html#229308">(&#167;3.9)</a>:
<p><ul><pre>
<i>PrimitiveType:<br>
NumericType<br>
</i><code>boolean
</code>
<i>NumericType:<br>
IntegralType<br>
FloatingPointType
</i>
<i>IntegralType:</i> <i>one</i> <i>of<br>
</i> <code>byte short int long char
</code>
<i>FloatingPointType:</i> <i>one</i> <i>of<br>
</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 <i>numeric types</i> are the integral types and the floating-point types. <p>
<a name="88061"></a>
The <i>integral types</i> 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 <i>floating-point types</i> are <code>float</code>, whose values are 32-bit IEEE 754 floating-point numbers, and <code>double</code>, whose values are 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>
Java 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="15.doc.html#153654">(&#167;15.19.1)</a>
<a name="17601"></a>
<li>The numerical equality operators <code>==</code> and <code>!=</code> <a href="15.doc.html#5198">(&#167;15.20.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="15.doc.html#24924">&#167;15.14.3</a>, <a href="15.doc.html#236345">&#167;15.14.4</a>)
<a name="17539"></a>
<li>The multiplicative operators <code>*</code>, <code>/</code>, and <code>%</code> <a href="15.doc.html#239829">(&#167;15.16)</a>
<a name="19482"></a>
<li>The additive operators <code>+</code> and <code>-</code> <a href="15.doc.html#13510">(&#167;15.17.2)</a>
<a name="24026"></a>
<li>The increment operator <code>++</code>, both prefix <a href="15.doc.html#39547">(&#167;15.14.1)</a> and postfix <a href="15.doc.html#39438">(&#167;15.13.2)</a>
<a name="24036"></a>
<li>The decrement operator <code>--</code>, both prefix <a href="15.doc.html#239136">(&#167;15.14.2)</a> and postfix <a href="15.doc.html#4987">(&#167;15.13.3)</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="15.doc.html#5121">(&#167;15.18)</a>
<a name="51061"></a>
<li>The bitwise complement operator <code>~</code> <a href="15.doc.html#5017">(&#167;15.14.5)</a>
<a name="17770"></a>
<li>The integer bitwise operators <code>&amp;</code>, <code>|</code>, and <code>^</code> <a href="15.doc.html#5233">(&#167;15.21.1)</a>
</ul>
<a name="19469"></a>
<li>The conditional operator <code>? :</code> <a href="15.doc.html#5257">(&#167;15.24)</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="5.doc.html#176921">&#167;5.4</a>, <a href="15.doc.html#238146">&#167;15.15</a>)
<a name="17774"></a>
<li>The string concatenation operator <code>+</code> <a href="15.doc.html#39990">(&#167;15.17.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>Integer</code> <a href="javalang.doc6.html#14348">(&#167;20.7)</a>, <code>Long</code> <a href="javalang.doc7.html#46750">(&#167;20.8)</a>, and <code>Character</code> <a href="javalang.doc4.html#14345">(&#167;20.5)</a>.
<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="5.doc.html#25222">(&#167;5.1.2)</a> to type <code>long</code> by numeric promotion <a href="5.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="11.doc.html#44043">(&#167;11)</a> are the integer divide operator <code>/</code> <a href="15.doc.html#5047">(&#167;15.16.2)</a> and the integer remainder operator <code>%</code> <a href="15.doc.html#24956">(&#167;15.16.3)</a>, which throw an <code>ArithmeticException</code> if the right-hand operand is zero. <p>
<a name="86654"></a>
The example:<p>
<pre><a name="51117"></a>
class Test {
<a name="51118"></a> public static void main(String[] args) {
<a name="51119"></a> int i = 1000000;
<a name="51254"></a> System.out.println(i * i);
<a name="51216"></a> long l = i;
<a name="86535"></a> System.out.println(l * l);
<a name="86536"></a> System.out.println(20296 / (l - i));
<a name="86537"></a> }
<a name="86538"></a>}
</pre><a name="51131"></a>
produces the output:
<p><pre><a name="51149"></a>
-727379968
<a name="51133"></a>1000000000000
</pre><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 and Values</h3>
<a name="87606"></a>
The floating-point types are <code>float</code> and <code>double</code>, representing the single-precision
32-bit and double-precision 64-bit format IEEE 754 values and operations as
specified in <i>IEEE Standard for Binary Floating-Point Arithmetic</i>, ANSI/IEEE
Standard 754-1985 (IEEE, New York).
<p><a name="88071"></a>
The IEEE 754 standard includes not only positive and negative sign-magnitude numbers, but also positive and negative zeros, positive and negative <i>infinities</i>, and a special <i>Not-a-Number </i>(hereafter abbreviated NaN). The NaN value is used to represent the result of certain 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> <a href="javalang.doc8.html#1411">(&#167;20.9.5)</a> and <code>Double.NaN</code> <a href="javalang.doc9.html#13844">(&#167;20.10.5)</a>.<p>
<a name="9219"></a>
The finite nonzero values of type <code>float</code> are of the form <img src="4.doc.anc.gif">, where <i>s</i> is +1 or -1, <i>m</i> is a positive integer less than <img src="4.doc.anc2.gif">, and <i>e</i> is an integer between -149 and 104, inclusive. Values of that form such that <i>m</i> is positive but less than <img src="4.doc.anc5.gif"> and <i>e</i> is equal to -149 are said to be <i>denormalized</i>.<p>
<a name="9223"></a>
The finite nonzero values of type <code>double</code> are of the form <img src="4.doc.anc1.gif">, where <i>s</i> is +1 or -1, <i>m</i> is a positive integer less than <img src="4.doc.anc3.gif">, and <i>e</i> is an integer between -1075 and 970, inclusive. Values of that form such that <i>m</i> is positive but less than <img src="4.doc.anc6.gif"> and <i>e</i> is equal to -1075 are said to be <i>denormalized</i>.<p>
<a name="86665"></a>
Except for NaN, floating-point values are <i>ordered</i>; arranged from smallest to largest, they are negative infinity, negative finite nonzero values, negative zero, positive zero, positive finite nonzero values, and positive infinity.<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. The operations <code>Math.min</code> and <code>Math.max</code> also distinguish positive zero and negative zero.<p>
<a name="16083"></a>
NaN is <i>unordered</i>, 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="15.doc.html#153654">(&#167;15.19.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="15.doc.html#5198">(&#167;15.20.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>
Java 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="15.doc.html#153654">(&#167;15.19.1)</a>
<a name="52066"></a>
<li>The numerical equality operators <code>==</code> and <code>!=</code> <a href="15.doc.html#5198">(&#167;15.20.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="15.doc.html#24924">&#167;15.14.3</a>, <a href="15.doc.html#236345">&#167;15.14.4</a>)
<a name="24115"></a>
<li>The multiplicative operators <code>*</code>, <code>/</code>, and <code>%</code> <a href="15.doc.html#239829">(&#167;15.16)</a>
<a name="24119"></a>
<li>The additive operators <code>+</code> and <code>-</code> <a href="15.doc.html#13510">(&#167;15.17.2)</a>
<a name="24126"></a>
<li>The increment operator <code>++</code>, both prefix <a href="15.doc.html#39547">(&#167;15.14.1)</a> and postfix <a href="15.doc.html#39438">(&#167;15.13.2)</a>
<a name="24107"></a>
<li>The decrement operator <code>--</code>, both prefix <a href="15.doc.html#239136">(&#167;15.14.2)</a> and postfix <a href="15.doc.html#4987">(&#167;15.13.3)</a>
</ul>
<a name="19446"></a>
<li>The conditional operator <code>? :</code> <a href="15.doc.html#5257">(&#167;15.24)</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="5.doc.html#176921">&#167;5.4</a>, <a href="15.doc.html#238146">&#167;15.15</a>)
<a name="21842"></a>
<li>The string concatenation operator <code>+</code> <a href="15.doc.html#39990">(&#167;15.17.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> <a href="javalang.doc8.html#14394">(&#167;20.9)</a>, <code>Double</code> <a href="javalang.doc9.html#14390">(&#167;20.10)</a>, and <code>Math</code> <a href="javalang.doc10.html#47547">(&#167;20.11)</a>.
<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="5.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 exactly as specified by IEEE 754. In particular, Java requires support of IEEE 754 <i>denormalized</i> floating-point numbers and <i>gradual underflow</i>, which make it easier to prove desirable properties of particular numerical algorithms. Floating-point operations in Java do not "flush to zero" if the calculated result is a denormalized number.<p>
<a name="9274"></a>
Java requires that floating-point arithmetic behave as if every floating-point operator rounded its floating-point result to the result precision. <i>Inexact</i> 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 <i>round to nearest</i>.<p>
<a name="10346"></a>
Java uses <i>round toward zero</i> when converting a floating value to an integer <a href="5.doc.html#175672">(&#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>
Java floating-point operators produce no exceptions <a href="11.doc.html#44043">(&#167;11)</a>. An operation that overflows produces a signed infinity, an operation that underflows produces 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:<p>
<pre><a name="9292"></a>
class Test {
<a name="45603"></a>
public static void main(String[] args) {
<a name="49672"></a>
// An example of overflow:
<a name="49673"></a> double d = 1e308;
<a name="86539"></a> System.out.print("overflow produces infinity: ");
<a name="86540"></a> System.out.println(d + "*10==" + d*10);
<a name="86541"></a>
// An example of gradual underflow:
<a name="49678"></a> d = 1e-305 * Math.PI;
<a name="85624"></a> System.out.print("gradual underflow: " + d + "\n &#32; &#32; &#32;");
<a name="49679"></a> for (int i = 0; i &lt; 4; i++)
<a name="49680"></a> System.out.print(" " + (d /= 100000));
<a name="49755"></a> System.out.println();
<a name="49756"></a>
// An example of NaN:
<a name="49757"></a> System.out.print("0.0/0.0 is Not-a-Number: ");
<a name="49685"></a> d = 0.0/0.0;
<a name="85896"></a> System.out.println(d);
<a name="49698"></a>
// An example of inexact results and rounding:
<a name="49701"></a> System.out.print("inexact results with float:");
<a name="49702"></a> for (int i = 0; i &lt; 100; i++) {
<a name="49703"></a> float z = 1.0f / i;
<a name="49704"></a> if (z * i != 1.0f)
<a name="49705"></a> System.out.print(" " + i);
<a name="49706"></a> }
<a name="20012"></a> System.out.println();
<a name="85847"></a>
// Another example of inexact results and rounding:
<a name="49707"></a> System.out.print("inexact results with double:");
<a name="49708"></a> for (int i = 0; i &lt; 100; i++) {
<a name="49709"></a> double z = 1.0 / i;
<a name="49710"></a> if (z * i != 1.0)
<a name="49711"></a> System.out.print(" " + i);
<a name="49712"></a> }
<a name="49713"></a> System.out.println();
<a name="10212"></a>
// An example of cast to integer rounding:
<a name="49718"></a> System.out.print("cast to int rounds toward 0: ");
<a name="49719"></a> d = 12345.6;
<a name="49720"></a> System.out.println((int)d + " " + (int)(-d));
<a name="49721"></a> }
<a name="49722"></a>}
</pre><a name="23297"></a>
produces the output:
<p><pre><a name="23314"></a>
overflow produces infinity: 1.0e+308*10==Infinity
<a name="23315"></a>gradual underflow: 3.141592653589793E-305
<a name="85613"></a> 3.1415926535898E-310 3.141592653E-315 3.142E-320 0.0
<a name="23316"></a>0.0/0.0 is Not-a-Number: NaN
<a name="23317"></a>inexact results with float: 0 41 47 55 61 82 83 94 97
<a name="23318"></a>inexact results with double: 0 49 98
<a name="23303"></a>cast to int rounds toward 0: 12345 -12345
</pre><a name="22309"></a>
This example demonstrates, among other things, that gradual underflow can result in a gradual loss of precision.<p>
<a name="11717"></a>
The inexact 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>.<p>
<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="3.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="15.doc.html#54508">(&#167;15.20.2)</a>
<a name="17734"></a>
<li>The logical-complement operator <code>!</code> <a href="15.doc.html#13350">(&#167;15.14.6)</a>
<a name="17736"></a>
<li>The logical operators <code>&amp;</code>, <code>^</code>, and <code>|</code> <a href="15.doc.html#5242">(&#167;15.21.2)</a>
<a name="17737"></a>
<li>The conditional-and and conditional-or operators <code>&amp;&amp;</code> <a href="15.doc.html#5247">(&#167;15.22)</a> and <code>||</code> <a href="15.doc.html#54532">(&#167;15.23)</a>
<a name="19467"></a>
<li>The conditional operator <code>? :</code> <a href="15.doc.html#5257">(&#167;15.24)</a>
<a name="21871"></a>
<li>The string concatenation operator <code>+</code> <a href="15.doc.html#39990">(&#167;15.17.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="14.doc.html#5991">(&#167;14.8)</a>
<a name="17743"></a>
<li>The <code>while</code> statement <a href="14.doc.html#237277">(&#167;14.10)</a>
<a name="17745"></a>
<li>The <code>do</code> statement <a href="14.doc.html#6045">(&#167;14.11)</a>
<a name="17747"></a>
<li>The <code>for</code> statement <a href="14.doc.html#24588">(&#167;14.12)</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="15.doc.html#5257">(&#167;15.24)</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="5.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="5.doc.html#176921">(&#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 <i>reference types</i>: class types <a href="8.doc.html#3857">(&#167;8)</a>, interface types <a href="9.doc.html#238678">(&#167;9)</a>, and
array types <a href="10.doc.html#27803">(&#167;10)</a>.
<p><ul><pre>
<i>ReferenceType:<br>
ClassOrInterfaceType<br>
ArrayType
</i>
<i>ClassOrInterfaceType:<br>
ClassType<br>
InterfaceType
</i>
<i>ClassType:<br>
TypeName
</i>
<i>InterfaceType:<br>
TypeName
</i>
<i>ArrayType:<br>
</i> <i>Type</i><code> [ ]
</code></pre></ul><a name="9678"></a>
Names are described in <a href="6.doc.html#48086">&#167;6</a>; type names in <a href="6.doc.html#20569">&#167;6.5</a> and, specifically, <a href="6.doc.html#21721">&#167;6.5.4</a>.
<p><a name="87599"></a>
The sample code:<p>
<pre><br><a name="10435"></a>class Point { int[] metrics; }
<br><a name="10414"></a>interface Move { void move(int deltax, int deltay); }
</pre><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 <i>object</i> is a <i>class</i> <i>instance</i> or an array.
<p><a name="86710"></a>
The reference values (often just <i>references</i>) are <i>pointers </i>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="15.doc.html#41147">(&#167;15.8)</a>, or by invoking the <code>newInstance</code> method of class <code>Class</code> <a href="javalang.doc2.html#28532">(&#167;20.3.8)</a>. An array is explicitly created by an array creation expression <a href="15.doc.html#41147">(&#167;15.8)</a>.<p>
<a name="49899"></a>
A new class instance is implicitly created when the string concatenation operator + <a href="15.doc.html#39990">(&#167;15.17.1)</a> is used in an expression, resulting in a new object of type <code>String</code> (<a href="4.doc.html#26992">&#167;4.3.3</a>, <a href="javalang.doc11.html#14460">&#167;20.12</a>). A new array object is implicitly created when an array initializer expression <a href="10.doc.html#11358">(&#167;10.6)</a> is evaluated; this can occur when a class or interface is initialized <a href="12.doc.html#44557">(&#167;12.4)</a>, when a new instance of a class is created <a href="15.doc.html#41147">(&#167;15.8)</a>, or when a local variable declaration statement is executed <a href="14.doc.html#5920">(&#167;14.3)</a>.<p>
<a name="49960"></a>
Many of these cases are illustrated in the following example:<p>
<pre><a name="49961"></a>
class Point {
<a name="51683"></a> int x, y;
<a name="86692"></a> Point() { System.out.println("default"); }
<a name="86696"></a> Point(int x, int y) { this.x = x; this.y = y; }
<a name="51733"></a>
// A Point instance is explicitly created at class initialization time:
<a name="51732"></a> static Point origin = new Point(0,0);
<a name="51734"></a>
// A String can be implicitly created by a + operator:
<a name="51682"></a> public String toString() {<br>
return "(" + x + "," + y + ")";<br>
}
<a name="51684"></a>}
<br><a name="51685"></a>
class Test {
<a name="51686"></a> public static void main(String[] args) {
<a name="51735"></a> // A Point is explicitly created using newInstance:
<a name="23341"></a> Point p = null;
<a name="23324"></a> try {
<a name="51687"></a> p = (Point)Class.forName("Point").newInstance();
<a name="23327"></a> } catch (Exception e) {
<a name="23350"></a> System.out.println(e);
<a name="23351"></a> }
<br><a name="51738"></a>
// An array is implicitly created by an array constructor:
<a name="51688"></a> Point a[] = { new Point(0,0), new Point(1,1) };
<br><a name="51757"></a>
// Strings are implicitly created by + operators:
<a name="51689"></a> System.out.println("p: " + p);
<a name="51690"></a> System.out.println("a: { " + a[0] + ", "<br>
&#32;+ a[1] + " }");
<br><a name="51745"></a>
// An array is explicitly created by an array creation expression:
<a name="51693"></a> String sa[] = new String[2];
<a name="51697"></a> sa[0] = "he"; sa[1] = "llo";
<a name="51698"></a> System.out.println(sa[0] + sa[1]);
<a name="51699"></a> }
<a name="49976"></a>}
</pre><a name="87328"></a>
which produces the output:
<p><pre><a name="87331"></a>
default
<a name="87332"></a>p: (0,0)
<a name="87333"></a>a: { (0,0), (1,1) }
<a name="87329"></a>hello
</pre><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="6.doc.html#33916">(&#167;6.6)</a> or a field access expression <a href="15.doc.html#41267">(&#167;15.10)</a>
<a name="31328"></a>
<li>Method invocation <a href="15.doc.html#20448">(&#167;15.11)</a>
<a name="31378"></a>
<li>The cast operator (<a href="5.doc.html#176921">&#167;5.4</a>, <a href="15.doc.html#238146">&#167;15.15</a>)
<a name="31345"></a>
<li>The string concatenation operator <code>+</code> <a href="15.doc.html#39990">(&#167;15.17.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 <a href="javalang.doc1.html#1152">(&#167;20.1.2)</a> 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="15.doc.html#80289">(&#167;15.19.2)</a>
<a name="31306"></a>
<li>The reference equality operators <code>==</code> and <code>!=</code> <a href="15.doc.html#236163">(&#167;15.20.3)</a>
<a name="19595"></a>
<li>The conditional operator <code>?&#32;:</code> <a href="15.doc.html#5257">(&#167;15.24)</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:<p>
<pre><a name="11036"></a>class Value { int val; }
</pre><pre><a name="87412"></a>
class Test {
<a name="87413"></a> public static void main(String[] args) {
<a name="87414"></a> int i1 = 3;
<a name="52134"></a> int i2 = i1;
<a name="52135"></a> i2 = 4;
<a name="50355"></a> System.out.print("i1==" + i1);
<a name="50357"></a> System.out.println(" but i2==" + i2);
<a name="50359"></a> Value v1 = new Value();
<a name="50361"></a> v1.val = 5;
<a name="52142"></a> Value v2 = v1;
<a name="52143"></a> v2.val = 6;
<a name="50363"></a> System.out.print("v1.val==" + v1.val);
<a name="50365"></a> System.out.println(" and v2.val==" + v2.val);
<a name="50367"></a> }
<a name="50369"></a>}
</pre><a name="11050"></a>
produces the output:
<p><pre><a name="11051"></a>
i1==3 but i2==4
<a name="45608"></a>v1.val==6 and v2.val==6
</pre><a name="11053"></a>
because <code>v1.val</code> and <code>v2.val</code> reference the same instance variable <a href="4.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="10.doc.html#27803">&#167;10</a> and <a href="15.doc.html#46168">&#167;15.9</a> for examples of the creation and use of arrays.<p>
<a name="17053"></a>
Each object has an associated lock <a href="17.doc.html#28460">(&#167;17.13)</a>, which is used by <code>synchronized</code> methods <a href="8.doc.html#78188">(&#167;8.4.3)</a> and the <code>synchronized</code> statement <a href="14.doc.html#79287">(&#167;14.17)</a> to provide control over concurrent access to state by multiple threads (<a href="17.doc.html#28457">&#167;17.12</a>, <a href="javalang.doc18.html#2658">&#167;20.20</a>).<p>
<a name="11055"></a>
<h3>4.3.2 The Class <code>Object</code></h3>
<a name="26999"></a>
The standard class <code>Object</code> is a superclass <a href="8.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="10.doc.html#27803">(&#167;10)</a>. All class and array types inherit the methods of class <code>Object</code>,
which are summarized here and completely specified in <a href="javalang.doc1.html#46442">&#167;20.1</a>:
<p><pre><a name="12035"></a>package java.lang;
</pre><pre><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()<br>
throws IllegalMonitorStateException,<br>
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><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> <a href="javalang.doc2.html#14342">(&#167;20.3)</a> 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="8.doc.html#55408">(&#167;8.4.3.5)</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 declared for the benefit of hashtables such as <code>java.util.Hashtable</code> <a href="javautil.doc7.html#7569">(&#167;21.7)</a>. 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="17.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="12.doc.html#44748">&#167;12.6</a>.
</ul><a name="26992"></a>
<h3>4.3.3 The Class <code>String</code></h3>
<a name="27000"></a>
Instances of class <code>String</code> <a href="javalang.doc11.html#14460">(&#167;20.12)</a> represent sequences of Unicode characters.
A &#32;<code>String</code> object has a constant (unchanging) value. String literals <a href="3.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="15.doc.html#39990">(&#167;15.17.1)</a> implicitly creates a new <code>String</code> object.<p>
<a name="52197"></a>
<h3>4.3.4 When Reference Types Are the Same</h3>
<a name="22319"></a>
Two reference types the <i>same type</i> 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 fully-qualified name <a href="6.doc.html#33916">(&#167;6.6)</a>, in which case they are sometimes said to be the <i>same class</i> or the <i>same interface</i>.
<a name="86576"></a>
<li>They are both array types, and have the same component type <a href="10.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 each kind of usage of a type:<p>
<pre><br><a name="52319"></a>import java.util.Random;
<br></pre><pre><a name="52320"></a>
class MiscMath {
<br><a name="19644"></a> int divisor;
<br><a name="85892"></a>
MiscMath(int divisor) {
<a name="85931"></a> this.divisor = divisor;
<a name="85932"></a> }
<br><a name="19646"></a>
float ratio(long l) {
<a name="52325"></a> try {
<a name="52326"></a> l /= divisor;
<a name="52327"></a> } catch (Exception e) {
<a name="52328"></a> if (e instanceof ArithmeticException)
<a name="52329"></a> l = Long.MAX_VALUE;
<a name="52330"></a> else
<a name="52331"></a> l = 0;
<a name="52332"></a> }
<a name="52333"></a> return (float)l;
<a name="52334"></a> }
<br><a name="19664"></a>
double gausser() {
<a name="19665"></a> Random r = new Random();
<a name="19666"></a> double[] val = new double[2];
<a name="19667"></a> val[0] = r.nextGaussian();
<a name="19668"></a> val[1] = r.nextGaussian();
<a name="19669"></a> return (val[0] + val[1]) / 2;
<a name="19670"></a> }
<br><a name="52342"></a>}
</pre><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="7.doc.html#26656">(&#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="8.doc.html#40898">(&#167;8.3)</a>, and constants of interfaces <a href="9.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="8.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="8.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="8.doc.html#29488">(&#167;8.6.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="14.doc.html#5920">&#167;14.3</a>, <a href="14.doc.html#24588">&#167;14.12</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="14.doc.html#79311">(&#167;14.18)</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="15.doc.html#41147">(&#167;15.8)</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="87680"></a>
<li>Array creations <a href="15.doc.html#46168">(&#167;15.9)</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="15.doc.html#238146">(&#167;15.15)</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="15.doc.html#80289">(&#167;15.19.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
<i>compile-time type</i>, that is either a primitive type <a href="4.doc.html#85587">(&#167;4.2)</a> or a reference type <a href="4.doc.html#9317">(&#167;4.3)</a>.
A variable always contains a value that is assignment compatible <a href="5.doc.html#170768">(&#167;5.2)</a> with its
type. A variable's value is changed by an assignment <a href="15.doc.html#5281">(&#167;15.25)</a> or by a prefix or
postfix <code>++</code> (increment) or <code>--</code> (decrement) operator (<a href="15.doc.html#39438">&#167;15.13.2</a>, <a href="15.doc.html#4987">&#167;15.13.3</a>, <a href="15.doc.html#39547">&#167;15.14.1</a>,
<a href="15.doc.html#239136">&#167;15.14.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 language. Default values are compatible <a href="4.doc.html#10931">(&#167;4.5.4)</a> and all assignments to a variable are checked for assignment compatibility <a href="5.doc.html#170768">(&#167;5.2)</a>, usually at compile time, but, in a single case involving arrays, a run-time check is made <a href="10.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="4.doc.html#9317">(&#167;4.3)</a> whose class <a href="4.doc.html#24887">(&#167;4.5.5)</a> is assignment compatible <a href="5.doc.html#170768">(&#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 <i>class variable</i> is a field declared using the keyword <code>static</code> within a class declaration <a href="8.doc.html#37544">(&#167;8.3.1.1)</a>, or with or without the keyword <code>static</code> within an interface declaration <a href="9.doc.html#78642">(&#167;9.3)</a>. A class variable is created when its class or interface is loaded <a href="12.doc.html#44459">(&#167;12.2)</a> and is initialized to a default value <a href="4.doc.html#10931">(&#167;4.5.4)</a>. The class variable effectively ceases to exist when its class or interface is unloaded <a href="12.doc.html#44850">(&#167;12.8)</a>, after any necessary finalization of the class or interface <a href="12.doc.html#44748">(&#167;12.6)</a> has been completed.
<a name="51516"></a>
<li>An <i>instance variable</i> is a field declared within a class declaration without using the keyword <code>static</code> <a href="8.doc.html#37544">(&#167;8.3.1.1)</a>. If a class <code>T</code> 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="4.doc.html#10931">(&#167;4.5.4)</a> as part of each newly created object of class <code>T</code> or of any class that is a subclass of <code>T</code> <a href="8.doc.html#21723">(&#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="12.doc.html#44748">(&#167;12.6)</a> has been completed.
<a name="10895"></a>
<li><i>Array components</i> are unnamed variables that are created and initialized to default values <a href="4.doc.html#10931">(&#167;4.5.4)</a> whenever a new object that is an array is created <a href="15.doc.html#46168">(&#167;15.9)</a>. The array components effectively cease to exist when the array is no longer referenced. See <a href="10.doc.html#27803">&#167;10</a> for a description of arrays.
<a name="24632"></a>
<li><i>Method parameters</i> <a href="8.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="15.doc.html#20448">(&#167;15.11)</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><i>Constructor parameters</i> <a href="8.doc.html#29488">(&#167;8.6.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="15.doc.html#41147">(&#167;15.8)</a> or explicit constructor invocation <a href="8.doc.html#78435">(&#167;8.6.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 <i>exception-handler parameter</i> is created each time an exception is caught by a <code>catch</code> clause of a <code>try</code> statement <a href="14.doc.html#79311">(&#167;14.18)</a>. The new variable is initialized with the actual object associated with the exception (<a href="11.doc.html#44153">&#167;11.3</a>, <a href="14.doc.html#237350">&#167;14.16</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><i>Local variables</i> are declared by local variable declaration statements <a href="14.doc.html#5920">(&#167;14.3)</a>. Whenever the flow of control enters a block <a href="14.doc.html#24644">(&#167;14.2)</a> or <code>for</code> statement <a href="14.doc.html#24588">(&#167;14.12)</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="16.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>
<ul><a name="24816"></a>
<br><br>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="14.doc.html#35518">(&#167;14.9)</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="16.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="15.doc.html#5281">(&#167;15.25)</a>.
</ul><a name="24836"></a>
The following example contains several different kinds of variables:<p>
<pre><a name="10918"></a>
class Point {
<a name="45636"></a> static int numPoints; // numPoints is a class variable
<a name="50087"></a> int x, y; // x and y are instance variables
<a name="50089"></a> int[] w = new int[10]; // w[0] is an array component
<a name="52523"></a> int setX(int x) { // x is a method parameter
<a name="52524"></a> int oldx = this.x; // oldx is a local variable
<a name="10925"></a> this.x = x;
<a name="10926"></a> return oldx;
<a name="10927"></a> }
<a name="10928"></a>}
</pre><a name="10931"></a>
<h3>4.5.4 Initial Values of Variables</h3>
<a name="10935"></a>
Every variable in a Java 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 <i>default value</i> when it is created (<a href="15.doc.html#41147">&#167;15.8</a>, <a href="15.doc.html#46168">&#167;15.9</a>, <a href="javalang.doc2.html#15088">&#167;20.3.6</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="4.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="8.doc.html#38698">(&#167;8.4.1)</a> is initialized to the corresponding argument value provided by the invoker of the method <a href="15.doc.html#20448">(&#167;15.11)</a>.
<a name="38160"></a>
<li>Each constructor parameter <a href="8.doc.html#29488">(&#167;8.6.1)</a> is initialized to the corresponding argument value provided by a class instance creation expression <a href="15.doc.html#41147">(&#167;15.8)</a> or explicit constructor invocation <a href="8.doc.html#78435">(&#167;8.6.5)</a>.
<a name="11354"></a>
<li>An exception-handler parameter <a href="14.doc.html#79311">(&#167;14.18)</a> is initialized to the thrown object representing the exception (<a href="11.doc.html#44153">&#167;11.3</a>, <a href="14.doc.html#237350">&#167;14.16</a>).
<a name="11569"></a>
<li>A local variable (<a href="14.doc.html#5920">&#167;14.3</a>, <a href="14.doc.html#24588">&#167;14.12</a>) must be explicitly given a value before it is used, by either initialization <a href="14.doc.html#5920">(&#167;14.3)</a> or assignment <a href="15.doc.html#5281">(&#167;15.25)</a>, in a way that can be verified by the compiler using the rules for definite assignment <a href="16.doc.html#25979">(&#167;16)</a>.
</ul><a name="30962"></a>
The example program:
<p><pre><a name="30963"></a>
class Point {
<a name="12302"></a> static int npoints;
<a name="12303"></a> int x, y;
<a name="12309"></a> Point root;
<a name="12307"></a>}
<br><a name="12308"></a>
class Test {
<a name="12310"></a> public static void main(String[] args) {
<a name="50091"></a> System.out.println("npoints=" + Point.npoints);
<a name="12326"></a> Point p = new Point();
<a name="12327"></a> System.out.println("p.x=" + p.x + ", p.y=" + p.y);
<a name="12328"></a> System.out.println("p.root=" + p.root);
<a name="12332"></a> }
<a name="12329"></a>}
</pre><a name="12324"></a>
prints:
<p><pre><a name="12336"></a>
npoints=0
<a name="12337"></a>p.x=0, p.y=0
<a name="12325"></a>p.root=null
</pre><a name="24882"></a>
illustrating the default initialization of <code>npoints</code>, which occurs when the class
<code>Point</code> is prepared <a href="12.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="12.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.5 Variables Have Types, Objects Have Classes</h3>
<a name="24888"></a>
Every object belongs to some particular class: the class that was mentioned in the
creation expression that produced the object, the class whose class object was
used to invoke the <code>newInstance</code> method <a href="javalang.doc2.html#15088">(&#167;20.3.6)</a> to produce the object, or the
<code>String</code> class for objects implicitly created by the string concatenation operator <code>+
</code><a href="15.doc.html#39990">(&#167;15.17.1)</a>. This class is called the <i>class of the object</i>. (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="24900"></a>
(Sometimes a variable or expression is said to have a "run-time type" but that is an abuse of terminology; it 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>. Properly speaking, type is a compile-time notion. A variable or expression has a type; an object or array has no type, but belongs to a class.)<p>
<a name="24901"></a>
The type of a variable is always declared, and the type of an expression can be deduced at compile time. The 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 (not a type), 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="8.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:<p>
<pre><a name="52597"></a>
public interface Colorable {
<a name="24921"></a> void setColor(byte r, byte g, byte b);
<a name="24922"></a>}
<br><a name="52598"></a>class Point { int x, y; }
<a name="52599"></a>
class ColoredPoint extends Point implements Colorable {
<br><a name="52600"></a> byte r, g, b;
<br><a name="52601"></a>
public void setColor(byte rv, byte gv, byte bv) {
<a name="23360"></a> r = rv; g = gv; b = bv;
<a name="23361"></a> }
<br><a name="52604"></a>}
<br><a name="52605"></a>
class Test {
<a name="52606"></a> public static void main(String[] args) {
<a name="52607"></a> Point p = new Point();
<a name="52608"></a> ColoredPoint cp = new ColoredPoint();
<a name="52609"></a> p = cp;
<a name="52610"></a> Colorable c = cp;
<a name="23366"></a> }
<a name="52611"></a>}
</pre><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="5.doc.html#170768">(&#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> <a href="javalang.doc1.html#13783">(&#167;20.1.1)</a>, when invoked for an array object, will return a class object (of class <code>Class</code>) that represents the class of the array. The classes for arrays have strange names that are not valid Java 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:<p>
<pre><a name="24985"></a>new int[10].getClass().getName()
</pre><a name="85679"></a>
is the string <code>"[I"</code>; see <a href="javalang.doc1.html#13783">&#167;20.1.1</a> for details.
<p>
<hr>
<!-- This inserts footnotes-->
<table border="0" width="100%">
<tr>
<td><a href="index.html">Contents</a> | <a href="3.doc.html">Prev</a> | <a href="5.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">First Edition</font></td></tr></table>
<p>
<font size=-1>Java Language Specification (HTML generated by Suzette Pelouch on April 03, 1998)<br>
<i><a href="jcopyright.doc.html">Copyright &#169 1996 Sun Microsystems, Inc.</a>
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>
<meta name="collection" content="exclude">
<title>The Java Language Specification
Names</title>
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="index.html">Contents</a> | <a href="5.doc.html">Prev</a> | <a href="7.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">First 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 Java program. A declared
entity <a href="6.doc.html#33757">(&#167;6.1)</a> is a package, class type, interface type, member (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 Java 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="6.doc.html#31692">(&#167;6.2)</a>.<p>
<a name="56234"></a>
Every name introduced by a declaration has a <i>scope</i> <a href="6.doc.html#33623">(&#167;6.3)</a>, which is the part of the Java 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="6.doc.html#31814">(&#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 field or a method.<p>
<a name="34249"></a>
In determining the meaning of a name <a href="6.doc.html#20569">(&#167;6.5)</a>, Java uses the context of the occurrence to disambiguate among packages, types, variables, and methods with the same name.<p>
<a name="56266"></a>
Access control <a href="6.doc.html#33916">(&#167;6.6)</a> can be specified in a class, interface, method, or field declaration to control when <i>access</i> to a member is allowed. Access is a different concept from scope; access specifies the part of the Java program text within which the declared entity can be referred to by a qualified name, a field access expression <a href="15.doc.html#41267">(&#167;15.10)</a>, or a method invocation expression <a href="15.doc.html#20448">(&#167;15.11)</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 names <a href="6.doc.html#25430">(&#167;6.7)</a> and naming conventions <a href="6.doc.html#11186">(&#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="15.doc.html#4984">(&#167;15.13.1)</a>. The name of a method may appear in an expression only as part of a method invocation expression <a href="15.doc.html#20448">(&#167;15.11)</a>. The name of a class or interface type may appear in an expression only as part of a class instance creation expression <a href="15.doc.html#41147">(&#167;15.8)</a>, an array creation expression <a href="15.doc.html#46168">(&#167;15.9)</a>, a cast expression <a href="15.doc.html#238146">(&#167;15.15)</a>, or an <code>instanceof</code> expression <a href="15.doc.html#80289">(&#167;15.19.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 Java program and includes an identifier
<a href="3.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="7.doc.html#26619">(&#167;7.4)</a>
<a name="60319"></a>
<li>An imported type, declared in a single-type-import declaration <a href="7.doc.html#26699">(&#167;7.5.1)</a> or a type-import-on-demand declaration <a href="7.doc.html#26725">(&#167;7.5.2)</a>
<a name="27103"></a>
<li>A class, declared in a class type declaration <a href="8.doc.html#15372">(&#167;8.1)</a>
<a name="27107"></a>
<li>An interface, declared in an interface type declaration <a href="9.doc.html#35470">(&#167;9.1)</a>
<a name="27117"></a>
<li>A member of a reference type (<a href="8.doc.html#21831">&#167;8.2</a>, <a href="9.doc.html#32392">&#167;9.2</a>, <a href="10.doc.html#11364">&#167;10.7</a>), one of the following:
<ul>
<a name="20164"></a>
<li>A field, one of the following:
<ul>
<a name="20168"></a>
<li>A field declared in a class type <a href="8.doc.html#40898">(&#167;8.3)</a>
<a name="20172"></a>
<li>A constant field declared in an interface type <a href="9.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="10.doc.html#11364">(&#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="8.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="9.doc.html#78651">(&#167;9.4)</a>
</ul>
</ul>
</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="8.doc.html#38698">&#167;8.4.1</a>, <a href="8.doc.html#29488">&#167;8.6.1</a>)
<a name="33775"></a>
<li>A parameter of an <code>abstract</code> method of an interface <a href="9.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="14.doc.html#79311">(&#167;14.18)</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="14.doc.html#5920">(&#167;14.3)</a>
<a name="33777"></a>
<li>A local variable declared in a <code>for</code> statement <a href="14.doc.html#24588">(&#167;14.12)</a>
</ul>
</ul><a name="56358"></a>
Constructors <a href="8.doc.html#41652">(&#167;8.6)</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 <i>name</i> is used to refer to an entity declared in a Java program.
<p><a name="61763"></a>
There are two forms of names: simple names and qualified names. A <i>simple name</i> is a single identifier. A <i>qualified name</i> 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="6.doc.html#20569">(&#167;6.5)</a>, the Java language takes into account the context in which the name appears. It distinguishes among contexts where a name must denote (refer to) a package <a href="6.doc.html#22349">(&#167;6.5.3)</a>, a type <a href="6.doc.html#21721">(&#167;6.5.4)</a>, a variable or value in an expression <a href="6.doc.html#21650">(&#167;6.5.5)</a>, or a method <a href="6.doc.html#21652">(&#167;6.5.6)</a>.<p>
<a name="33483"></a>
Not all identifiers in Java 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="6.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="15.doc.html#41267">(&#167;15.10)</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="15.doc.html#20448">(&#167;15.11)</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="33492"></a>
<li>As labels in labeled statements <a href="14.doc.html#78993">(&#167;14.6)</a> and in <code>break</code> <a href="14.doc.html#6842">(&#167;14.13)</a> and <code>continue</code> <a href="14.doc.html#6122">(&#167;14.14)</a> statements that refer to statement labels
</ul><a name="38317"></a>
In the example:
<p><pre><a name="38318"></a>
class Test {
<a name="38319"></a> public static void main(String[] args) {
<a name="31441"></a> Class c = System.out.getClass();
<a name="38320"></a> System.out.println(c.toString().length() +
<a name="31466"></a> args[0].length() + args.length);
<a name="38324"></a> }
<a name="38325"></a>}
</pre><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="15.doc.html#20448">(&#167;15.11)</a>. The second occurrence of <code>length</code> is not a name, but
rather an identifier appearing in a method invocation expression <a href="15.doc.html#20448">(&#167;15.11)</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:<p>
<pre><a name="38178"></a>
class TestString {
<br><a name="38277"></a> char[] value;
<br><br><a name="38278"></a> int offset, count;
<br><a name="38262"></a> int indexOf(TestString str, int fromIndex) {
<a name="38179"></a> char[] v1 = value, v2 = str.value;
<a name="38309"></a> int max = offset + (count - str.count);
<a name="31499"></a> int start = offset + ((fromIndex &lt; 0) ? 0 : fromIndex);
<a name="38310"></a> i:
<a name="38312"></a> for (int i = start; i &lt;= max; i++)<br>
{
<a name="38184"></a> int n = str.count, j = i, k = str.offset;
<a name="38187"></a> while (n-- != 0) {
<a name="38188"></a> if (v1[j++] != v2[k++])
<a name="38189"></a> continue i;
<a name="38191"></a> }
<a name="38241"></a> return i - offset;
<a name="38251"></a> }
<a name="38194"></a> return -1;
<a name="38266"></a> }
<a name="38274"></a>}
</pre><a name="54045"></a>
This code was taken from a version of the class <code>String</code> and its method <code>indexOf</code>
<a href="javalang.doc11.html#30903">(&#167;20.12.26)</a>, 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 hide 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 hide the local variable <code>max</code> within the labeled statement.
<p><a name="33623"></a>
<h2>6.3 Scope of a Simple Name</h2>
<a name="34028"></a>
The <i>scope</i> 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:
<p><ul><a name="56405"></a>
<li>The scope of a package, as introduced by a <code>package</code> declaration, is determined by the host system <a href="7.doc.html#13180">(&#167;7.4.3)</a>. All Java code is within the scope of the standard package named <code>java</code>, so the package <code>java</code> can always be referred to by Java code.
<a name="31532"></a>
<li>The scope of a type imported by a single-type-import declaration <a href="7.doc.html#26699">(&#167;7.5.1)</a> or type-import-on-demand declaration <a href="7.doc.html#26725">(&#167;7.5.2)</a> is all the class and interface type declarations <a href="7.doc.html#26783">(&#167;7.6)</a> in the compilation unit in which the import declaration appears.
<a name="56422"></a>
<li>The scope of a type introduced by a class type declaration <a href="8.doc.html#39196">(&#167;8.1.1)</a> or interface type declaration <a href="9.doc.html#39713">(&#167;9.1.1)</a> is the declarations of all class and interface types in all the compilation units <a href="7.doc.html#40031">(&#167;7.3)</a> of the package in which it is declared.
<a name="19824"></a>
<li>The scope of a member declared in or inherited by a class type <a href="8.doc.html#21831">(&#167;8.2)</a> or interface type <a href="9.doc.html#32392">(&#167;9.2)</a> is the entire declaration of the class or interface type. The declaration of a member needs to appear before it is used only when the use is in a field initialization expression (<a href="8.doc.html#24510">&#167;8.3.2</a>, <a href="12.doc.html#44630">&#167;12.4.2</a>, <a href="12.doc.html#44670">&#167;12.5</a>). This means that a compile-time error results from the test program:
</ul><pre><a name="19834"></a>
class Test {
<a name="19835"></a> int i = j; // compile-time error: incorrect forward reference
<a name="19836"></a> int j = 1;
<a name="19837"></a> }
</pre><ul><a name="19838"></a>
<br><br>whereas the following example compiles without error:
</ul><pre><a name="19839"></a>
class Test {
<a name="19840"></a> Test() { k = 2; }
<a name="19841"></a> int j = 1;
<a name="19842"></a> int i = j;
<a name="19843"></a> int k;
<a name="19844"></a> }
</pre><ul><a name="19848"></a>
<br><br>even though the constructor <a href="8.doc.html#41652">(&#167;8.6)</a> for <code>Test</code> refers to the field <code>k</code> that is declared three lines later.
</ul><ul><a name="31556"></a>
<li>The scope of a parameter of a method <a href="8.doc.html#38698">(&#167;8.4.1)</a> is the entire body of the method.
</ul><ul><a name="31566"></a>
<li>The scope of a parameter of a constructor <a href="8.doc.html#29488">(&#167;8.6.1)</a> is the entire body of the constructor.
<a name="19941"></a>
<li>The scope of a local variable declaration in a block <a href="14.doc.html#32644">(&#167;14.3.2)</a> is the rest of the block in which the declaration appears, starting with its own initializer <a href="14.doc.html#5920">(&#167;14.3)</a> and including any further declarators to the right in the local variable declaration statement.
<a name="56450"></a>
<li>The scope of a local variable declared in the <i>ForInit</i> part of a <code>for</code> statement <a href="14.doc.html#24588">(&#167;14.12)</a> includes all of the following:
<ul>
<a name="23092"></a>
<li>Its own initializer
<a name="56451"></a>
<li>Any further declarators to the right in the <i>ForInit</i> part of the <code>for</code> statement
<a name="56452"></a>
<li>The <i>Expression</i> and <i>ForUpdate</i> parts of the <code>for</code> statement
<a name="56453"></a>
<li>The contained <i>Statement</i>
</ul>
<a name="56454"></a>
<li>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="14.doc.html#79311">(&#167;14.18)</a> is the entire block associated with the <code>catch</code>.
</ul><a name="56458"></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:<p>
<pre><a name="56459"></a>package points;
</pre><pre><a name="56460"></a>
class Point {
<a name="56461"></a> int x, y;
<a name="56462"></a> PointList list;
<a name="56463"></a> Point next;
<a name="56464"></a>}
<a name="56465"></a>
class PointList {
<a name="56466"></a> Point first;
<a name="56468"></a>}
</pre><a name="34047"></a>
the use of <code>PointList</code> in class <code>Point</code> is correct, because the scope of the class type
name <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 Hiding Names</h3>
<a name="34051"></a>
Some declarations may be hidden <a href="6.doc.html#34133">(&#167;6.3.1)</a> 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="62323"></a>
The example:<p>
<pre><a name="34052"></a>
class Test {
<a name="34053"></a> static int x = 1;
<a name="34054"></a> public static void main(String[] args) {
<a name="34055"></a> int x = 0;
<a name="34056"></a> System.out.print("x=" + x);
<a name="34057"></a> System.out.println(", Test.x=" + Test.x);
<a name="34058"></a> }
<a name="34059"></a>}
</pre><a name="34060"></a>
produces the output:
<p><pre><a name="34061"></a>x=0, Test.x=1
</pre><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
</ul><a name="34066"></a>
Since the scope of a class variable includes the entire body of the class <a href="8.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 hidden 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="14.doc.html#32644">(&#167;14.3.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>.<p>
<a name="62314"></a>
This means that:<p>
<ul><a name="62313"></a>
<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="6.doc.html#33916">(&#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 hidden at this point and cannot be referred to by its simple name.
</ul><a name="62307"></a>
If the standard naming conventions <a href="6.doc.html#11186">(&#167;6.8)</a> are followed, then hiding that would make the identification of separate naming contexts matter should be rare. The following contrived example involves hiding because it does not follow the standard naming conventions:<p>
<pre><a name="34080"></a>
class Point { int x, y; }
<a name="34083"></a>
class Test {
<a name="34084"></a>
static Point Point(int x, int y) {
<a name="34085"></a> Point p = new Point();
<a name="34086"></a> p.x = x; p.y = y;
<a name="34087"></a> return p;
<a name="34088"></a> }
<br><a name="34089"></a>
public static void main(String[] args) {
<a name="34090"></a> int Point;
<a name="34091"></a> Point[] pa = new Point[2];
<a name="34092"></a> for (Point = 0; Point &lt; 2; Point++) {
<a name="34093"></a> pa[Point] = new Point();
<a name="34094"></a> pa[Point].x = Point;
<a name="34095"></a> pa[Point].y = Point;
<a name="34096"></a> }
<a name="34097"></a> System.out.println(pa[0].x + "," + pa[0].y);
<a name="34098"></a> System.out.println(pa[1].x + "," + pa[1].y);
<a name="34099"></a> Point p = Point(3, 4);
<a name="34100"></a> System.out.println(p.x + "," + p.y);
<a name="34101"></a> }
<br><a name="34102"></a>}
</pre><a name="34103"></a>
This compiles without error and executes to produce the output:
<p><pre><a name="34104"></a>
0,0
<a name="34105"></a>1,1<br>
3,4
</pre><a name="34106"></a>
Within the body of <code>main</code>, the lookups of <code>Point</code> find different declarations depending
on the context of the use:
<p><ul><a name="34107"></a>
<li>In the expression "<code>new</code> <code>Point[2]</code>", the two occurrences of the class instance creation expression "<code>new</code> <code>Point()</code>", and at the start of three different local variable declaration statements, the <code>Point</code> is a <i>TypeName</i> <a href="6.doc.html#21721">(&#167;6.5.4)</a> and denotes the class type <code>Point</code> in each case.
<a name="34268"></a>
<li>In the method invocation expression "<code>Point(3,</code> <code>4)</code>" the occurrence of <code>Point</code> is a <i>MethodName </i><a href="6.doc.html#21652">(&#167;6.5.6)</a> and denotes the class (<code>static</code>) method <code>Point</code>.
<a name="34114"></a>
<li>All other names are <i>ExpressionName</i>s <a href="6.doc.html#21650">(&#167;6.5.5)</a> and refer to the local variable <code>Point</code>.
</ul><a name="34119"></a>
The example:
<p><pre><a name="34120"></a>import java.util.*;
</pre><pre><a name="34121"></a>
class Vector {
<a name="34122"></a> int val[] = { 1 , 2 };
<a name="34123"></a>}
<br><a name="34124"></a>
class Test {
<a name="34125"></a> public static void main(String[] args) {
<a name="34126"></a> Vector v = new Vector();
<a name="34127"></a> System.out.println(v.val[0]);
<a name="34128"></a> }
<a name="34129"></a>}
</pre><a name="34130"></a>
compiles and prints:
<p><pre><a name="34131"></a>1
</pre><a name="56469"></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="31814"></a>
<h2>6.4 Members and Inheritance</h2>
<a name="23209"></a>
Packages and reference types have <i>members</i>. The members of a package <a href="7.doc.html#34412">(&#167;7)</a> are
subpackages <a href="7.doc.html#26535">(&#167;7.1)</a> and all the class <a href="8.doc.html#3857">(&#167;8)</a> and interface <a href="9.doc.html#238678">(&#167;9)</a> types declared in all
the compilation units <a href="7.doc.html#40031">(&#167;7.3)</a> of the package. The members of a reference type
<a href="4.doc.html#9317">(&#167;4.3)</a> are fields (<a href="8.doc.html#40898">&#167;8.3</a>, <a href="9.doc.html#78642">&#167;9.3</a>, <a href="10.doc.html#11364">&#167;10.7</a>) and methods (<a href="8.doc.html#40420">&#167;8.4</a>, <a href="9.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 hidden nor overridden <a href="8.doc.html#228745">(&#167;8.4.6)</a>.
<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="7.doc.html#26535">&#167;7.1</a>, <a href="8.doc.html#21831">&#167;8.2</a>, <a href="9.doc.html#32392">&#167;9.2</a>, and <a href="10.doc.html#11364">&#167;10.7</a>.<p>
<a name="34993"></a>
<h3>6.4.1 The Members of a Package</h3>
<a name="23133"></a>
A member of a package <a href="7.doc.html#34412">(&#167;7)</a> is a subpackage <a href="7.doc.html#26535">(&#167;7.1)</a>, or a class <a href="8.doc.html#3857">(&#167;8)</a> or interface
<a href="9.doc.html#238678">(&#167;9)</a> type declared in a compilation unit <a href="7.doc.html#40031">(&#167;7.3)</a> of the package.
<p><a name="56555"></a>
In general, the subpackages of a package are determined by the host system <a href="7.doc.html#37758">(&#167;7.2)</a>. However, the standard package <code>java</code> always includes the subpackages <code>lang</code>, <code>util</code>, <code>io</code>, and <code>net</code> and may include other subpackages. No two distinct members of the same package may have the same simple name <a href="7.doc.html#26535">(&#167;7.1)</a>, but members of different packages may have the same simple name. For example, it is possible to declare a package:<p>
<pre><a name="34982"></a>package vector;
<a name="34983"></a>public class Vector { Object[] vec; }
</pre><a name="34986"></a>
that has as a member a <code>public</code> class named <code>Vector</code>, even though the standard
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="6.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="34765"></a>
The members of a class type <a href="8.doc.html#21831">(&#167;8.2)</a> are fields and methods. The members of a
class type are all of the following:
<p><ul><a name="34768"></a>
<li>Members inherited from its direct superclass <a href="8.doc.html#21723">(&#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="8.doc.html#34031">(&#167;8.1.4)</a>
<a name="34778"></a>
<li>Members declared in the body of the class <a href="8.doc.html#18988">(&#167;8.1.5)</a>
</ul><a name="62337"></a>
Constructors <a href="8.doc.html#41652">(&#167;8.6)</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.<p>
<a name="56650"></a>
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="6.doc.html#54547">&#167;6.5.6.2</a>, <a href="8.doc.html#21831">&#167;8.2</a>).<p>
<a name="31689"></a>
In the example:<p>
<pre><a name="25284"></a>
interface Colors {
<a name="25285"></a> int WHITE = 0, BLACK = 1;
<a name="25286"></a>}
<a name="31681"></a>
interface Separates {
<a name="25287"></a> int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
<a name="25288"></a>}
<a name="25289"></a>
class Test implements Colors, Separates {
<a name="25290"></a> public static void main(String[] args) {
<a name="25291"></a> System.out.println(BLACK); // compile-time error: ambiguous
<a name="25292"></a> }
<a name="25293"></a>}
</pre><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="8.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 <i>overloaded</i>.<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 <i>implement</i> it; if the method not inherited is not <code>abstract</code>, then the new declaration is said to <i>override</i> it.<p>
<a name="31699"></a>
In the example:<p>
<pre><a name="38566"></a>
class Point {
<a name="38567"></a> float x, y;
<a name="38568"></a> void move(int dx, int dy) { x += dx; y += dy; }
<a name="31704"></a> void move(float dx, float dy) { x += dx; y += dy; }
<a name="31705"></a> public String toString() { return "("+x+","+y+")"; }
<a name="31706"></a>}
</pre><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="15.doc.html#20448">&#167;15.11</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="4.doc.html#11055">(&#167;4.3.2)</a>, such as the method <code>hashCode</code> <a href="javalang.doc1.html#13784">(&#167;20.1.4)</a>. Note that <code>Point</code> does not inherit the <code>toString</code> method <a href="javalang.doc1.html#1152">(&#167;20.1.2)</a> 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="31765"></a>
The members of an interface type <a href="9.doc.html#32392">(&#167;9.2)</a> are fields and methods. The members of
an interface are all of the following:
<p><ul><a name="31784"></a>
<li>Members inherited from any direct superinterfaces <a href="9.doc.html#78598">(&#167;9.1.3)</a>
<a name="31788"></a>
<li>Members declared in the body of the interface <a href="9.doc.html#236431">(&#167;9.1.4)</a>
</ul><a name="31831"></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="6.doc.html#22022">&#167;6.5.5.1</a>, <a href="9.doc.html#32392">&#167;9.2</a>).<p>
<a name="61795"></a>
In the example:<p>
<pre><a name="20498"></a>
interface Colors {
<a name="20499"></a> int WHITE = 0, BLACK = 1;
<a name="20500"></a>}
<a name="31851"></a>
interface Separates {
<a name="20501"></a> int CYAN = 0, MAGENTA = 1, YELLOW = 2, BLACK = 3;
<a name="20502"></a>}
<a name="35253"></a>interface ColorsAndSeparates extends Colors, Separates {<br>
int DEFAULT = BLACK; // compile-time error: ambiguous<br>
}
</pre><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="36005"></a>
The members of an array type <a href="10.doc.html#11364">(&#167;10.7)</a> are all of the following:
<p><ul><a name="23342"></a>
<li>Members inherited from its implicit superclass <code>Object</code> (<a href="4.doc.html#11055">&#167;4.3.2</a>, <a href="javalang.doc1.html#46442">&#167;20.1</a>)
<a name="23344"></a>
<li>The field <code>length</code>, which is a constant (<code>final</code>) field of every array; its type is <code>int</code> and it contains the number of components of the array
</ul><a name="27727"></a>
The example:
<p><pre><a name="27728"></a>
class Test {
<a name="27729"></a> public static void main(String[] args) {
<a name="27730"></a> int[] ia = new int[3];
<a name="27731"></a> int[] ib = new int[6];
<a name="27733"></a> System.out.println(ia.getClass() == ib.getClass());
<a name="31873"></a> System.out.println("ia has length=" + ia.length);
<a name="27734"></a> }
<a name="27735"></a>}
</pre><a name="27736"></a>
produces the output:
<p><pre><a name="31879"></a>
true
<a name="27737"></a>ia has length=3
</pre><a name="27739"></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 second
<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="20569"></a>
<h2>6.5 Determining the Meaning of a Name</h2>
<a name="22344"></a>
The meaning of a name in Java 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 five categories: <i>PackageName</i>, <i>TypeName</i>,
<i>ExpressionName</i>, <i>MethodName</i>, or <i>AmbiguousName</i>. Second, a name that is initially
classified by its context as an <i>AmbiguousName</i> is then reclassified by certain
scoping rules to be a <i>PackageName</i>, <i>TypeName</i>, or <i>ExpressionName</i>. 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:<br>
</i> <i>Identifier<br>
</i> <i>PackageName</i><code> . </code><i>Identifier
</i>
<i>TypeName:<br>
</i> <i>Identifier<br>
</i> <i>PackageName</i><code> . </code><i>Identifier
</i>
<i>ExpressionName:<br>
</i> <i>Identifier<br>
</i> <i>AmbiguousName</i><code> . </code><i>Identifier
</i>
<i>MethodName:<br>
</i> <i>Identifier<br>
</i> <i>AmbiguousName</i><code> . </code><i>Identifier
</i>
<i>AmbiguousName:<br>
</i> <i>Identifier<br>
</i> <i>AmbiguousName</i><code> . </code><i>Identifier
</i></pre></ul><a name="32744"></a>
Java's 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="6.doc.html#11186">&#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. Java never has trouble distinguishing between a method and a field with the same name, since the context of a use always tells whether a method or a field is intended.<p>
<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 <i>PackageName</i> in these contexts:
<p><ul><a name="32159"></a>
<li>In a package declaration <a href="7.doc.html#26619">(&#167;7.4)</a>
<a name="32164"></a>
<li>In a type-import-on-demand declaration <a href="7.doc.html#26725">(&#167;7.5.2)</a>
<a name="32492"></a>
<li>To the left of the "<code>.</code>" in a qualified <i>PackageName</i>
<a name="32494"></a>
<li>To the left of the "<code>.</code>" in a qualified <i>TypeName</i>
</ul><a name="32149"></a>
A name is syntactically classified as a <i>TypeName</i> in these contexts:
<p><ul><a name="32174"></a>
<li>In a single-type-import declaration <a href="7.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="8.doc.html#21723">(&#167;8.1.3)</a>
<a name="32182"></a>
<li>In an <code>implements</code> clause in a class declaration <a href="8.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="9.doc.html#78598">(&#167;9.1.3)</a>
<a name="32290"></a>
<li>As a <i>Type</i> (or the part of a <i>Type</i> 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="8.doc.html#40898">&#167;8.3</a>, <a href="9.doc.html#78642">&#167;9.3</a>)
<a name="32322"></a>
<li>As the result type of a method (<a href="8.doc.html#40420">&#167;8.4</a>, <a href="9.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="8.doc.html#38698">&#167;8.4.1</a>, <a href="8.doc.html#29488">&#167;8.6.1</a>, <a href="9.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="8.doc.html#78323">&#167;8.4.4</a>, <a href="8.doc.html#244611">&#167;8.6.4</a>, <a href="9.doc.html#78651">&#167;9.4</a>)
<a name="32224"></a>
<li>As the type of a local variable <a href="14.doc.html#5920">(&#167;14.3)</a>
<a name="32225"></a>
<li>As the type of an exception parameter in a <code>catch</code> clause of a <code>try</code> statement <a href="14.doc.html#79311">(&#167;14.18)</a>
<a name="32233"></a>
<li>As the class type of an instance that is to be created in a class instance creation expression <a href="15.doc.html#41147">(&#167;15.8)</a>
<a name="32240"></a>
<li>As the element type of an array to be created in an array creation expression <a href="15.doc.html#46168">(&#167;15.9)</a>
<a name="32244"></a>
<li>As the type mentioned in the cast operator of a cast expression <a href="15.doc.html#238146">(&#167;15.15)</a>
<a name="32248"></a>
<li>As the type that follows the <code>instanceof</code> relational operator <a href="15.doc.html#80289">(&#167;15.19.2)</a>
</ul>
</ul><a name="32435"></a>
A name is syntactically classified as an <i>ExpressionName</i> in these contexts:
<p><ul><a name="32464"></a>
<li>As the array reference expression in an array access expression <a href="15.doc.html#239587">(&#167;15.12)</a>
<a name="32459"></a>
<li>As a <i>PostfixExpression</i> <a href="15.doc.html#36254">(&#167;15.13)</a>
<a name="32477"></a>
<li>As the left-hand operand of an assignment operator <a href="15.doc.html#5281">(&#167;15.25)</a>
</ul><a name="32437"></a>
A name is syntactically classified as a <i>MethodName</i> in this context:
<p><ul><a name="32480"></a>
<li>Before the "<code>(</code>" in a method invocation expression <a href="15.doc.html#20448">(&#167;15.11)</a>
</ul><a name="32439"></a>
A name is syntactically classified as an <i>AmbiguousName</i> in these contexts:
<p><ul><a name="32496"></a>
<li>To the left of the "<code>.</code>" in a qualified <i>ExpressionName</i>
<a name="32499"></a>
<li>To the left of the "<code>.</code>" in a qualified <i>MethodName</i>
<a name="32501"></a>
<li>To the left of the "<code>.</code>" in a qualified <i>AmbiguousName</i>
</ul><a name="32725"></a>
<h3>6.5.2 Reclassification of Contextually Ambiguous Names</h3>
<a name="32133"></a>
An <i>AmbiguousName</i> is then reclassified as follows:
<p><ul><a name="32505"></a>
<li>If the <i>AmbiguousName</i> is a simple name, consisting of a single <i>Identifier</i>:
<ul>
<a name="32544"></a>
<li>If the <i>Identifier</i> appears within the scope <a href="6.doc.html#33623">(&#167;6.3)</a> of a local variable declaration <a href="14.doc.html#5920">(&#167;14.3)</a> or parameter declaration (<a href="8.doc.html#38698">&#167;8.4.1</a>, <a href="8.doc.html#29488">&#167;8.6.1</a>, <a href="14.doc.html#79311">&#167;14.18</a>) with that name, then the <i>AmbiguousName</i> is reclassified as an <i>ExpressionName</i>.
<a name="32569"></a>
<li>Otherwise, consider the class or interface <i>C</i> within whose declaration the <i>Identifier</i> occurs. If <i>C</i> has one or more fields with that name, which may be either declared within it or inherited, then the <i>AmbiguousName</i> is reclassified as an <i>ExpressionName</i>.
<a name="32843"></a>
<li>Otherwise, if a type of that name is declared in the compilation unit <a href="7.doc.html#40031">(&#167;7.3)</a> containing the <i>Identifier</i>, either by a single-type-import declaration <a href="7.doc.html#26699">(&#167;7.5.1)</a> or by a class or interface type declaration <a href="7.doc.html#26783">(&#167;7.6)</a>, then the <i>AmbiguousName</i> is reclassified as a <i>TypeName</i>.
<a name="32853"></a>
<li>Otherwise, if a type of that name is declared in another compilation unit <a href="7.doc.html#40031">(&#167;7.3)</a> of the package <a href="7.doc.html#26535">(&#167;7.1)</a> of the compilation unit containing the <i>Identifier</i>, &#32;then the <i>AmbiguousName</i> is reclassified as a <i>TypeName</i>.
<a name="32860"></a>
<li>Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration <a href="7.doc.html#26725">(&#167;7.5.2)</a> of the compilation unit containing the <i>Identifier</i>, &#32;then the <i>AmbiguousName</i> is reclassified as a <i>TypeName</i>.
<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 <i>Identifier</i>, then a compile-time error results.
<a name="32535"></a>
<li>Otherwise, the <i>AmbiguousName</i> is reclassified as a <i>PackageName</i>. A later step determines whether or not a package of that name actually exists.
</ul>
<a name="32506"></a>
<li>If the <i>AmbiguousName</i> is a qualified name, consisting of a name, a "<code>.</code>", and an <i>Identifier</i>, then the name to the left of the "<code>.</code>" is first reclassified, for it is itself an <i>AmbiguousName</i>. 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 <i>PackageName</i>, then there is a further choice:
<ul>
<a name="32700"></a>
<li>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 <i>Identifier</i>, then this <i>AmbiguousName</i> is reclassified as a <i>TypeName</i>.
<a name="32713"></a>
<li>Otherwise, this <i>AmbiguousName</i> is reclassified as a <i>PackageName</i>. A later step determines whether or not a package of that name actually exists.
</ul>
<a name="32511"></a>
<li>If the name to the left of the "<code>.</code>" is reclassified as a <i>TypeName</i>, then this <i>AmbiguousName</i> is reclassified as an <i>ExpressionName</i>.
<a name="32513"></a>
<li>If the name to the left of the "<code>.</code>" is reclassified as an <i>ExpressionName</i>, then this <i>AmbiguousName</i> is reclassified as an <i>ExpressionName</i>.
</ul>
</ul><a name="60456"></a>
As an example, consider the following contrived "library code":<p>
<pre><br><a name="60457"></a>package ORG.rpgpoet;
<br><br><a name="60459"></a>import java.util.Random;
<br><a name="60458"></a>interface Music { Random[] wizards = new Random[4]; }
</pre><a name="60464"></a>
and then consider this example code in another package:
<p><pre><br><a name="60521"></a>package bazola;
<br></pre><pre><a name="60467"></a>
class Gabriel {
<a name="60466"></a> static int n = ORG.rpgpoet.Music.wizards.length;
<a name="60465"></a>}
</pre><a name="60483"></a>
First of all, the name <code>ORG.rpgpoet.Music.wizards.length</code> is classified as an
<i>ExpressionName</i> because it functions as a <i>PostfixExpression</i>. Therefore, each of
the names:
<p><pre><a name="60488"></a>
ORG.rpgpoet.Music.wizards
<a name="60490"></a>ORG.rpgpoet.Music
<a name="60492"></a>ORG.rpgpoet
<a name="60494"></a>ORG
</pre><a name="60515"></a>
is initially classified as an <i>AmbiguousName</i>. These are then reclassified:
<p><ul><a name="60526"></a>
<li>Assuming that there is no class or interface named <code>ORG</code> in any other compilation unit of package <code>bazola</code>, then the simple name <code>ORG</code> is reclassified as a <i>PackageName</i>.
<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 <i>PackageName</i>.
<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 <i>TypeName</i>.
<a name="60540"></a>
<li>Finally, because the name <code>ORG.rpgpoet.Music</code> is a <i>TypeName</i>, the qualified name <code>ORG.rpgpoet.Music.wizards</code> is reclassified as an <i>ExpressionName</i>.
</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 <i>PackageName</i> 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 <i>Identifier</i>, then this identifier denotes a top-
level package named by that identifier. If no package of that name is accessible, as
determined by the host system <a href="7.doc.html#13180">(&#167;7.4.3)</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 accessible package or <i>Id</i> does not
name an accessible subpackage of that package, then a compile-time error occurs.
<p><a name="21721"></a>
<h3>6.5.4 Meaning of Type Names</h3>
<a name="32763"></a>
The meaning of a name classified as a <i>TypeName</i> is determined as follows.
<p><a name="21810"></a>
<h4>6.5.4.1 Simple Type Names</h4>
<a name="32799"></a>
If a type name consists of a single <i>Identifier</i>, then the identifier must occur in the
scope of a declaration of a type with this name, or a compile-time error occurs. 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 a type with that name is declared in the current compilation unit <a href="7.doc.html#40031">(&#167;7.3)</a>, either by a single-type-import declaration <a href="7.doc.html#26699">(&#167;7.5.1)</a> or by a declaration of a class or interface &#32;type <a href="7.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="7.doc.html#40031">(&#167;7.3)</a> of the package <a href="7.doc.html#26535">(&#167;7.1)</a> containing the identifier, then the identifier denotes that type. Note that, in systems that store compilation units in a file system, such a compilation unit must have a file name that is the name of the type <a href="7.doc.html#26783">(&#167;7.6)</a>.
<a name="21758"></a>
<li>Otherwise, if a type of that name is declared by exactly one type-import-on-demand declaration <a href="7.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="32933"></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.4.2 Qualified Type Names</h4>
<a name="32818"></a>
If a type name is of the form <i>Q</i><code>.</code><i>Id</i>, then <i>Q</i> must be a package name. The type
name <i>Q</i><code>.</code><i>Id</i> names a type that is the member named <i>Id</i> within the package named
by <i>Q</i>. If <i>Q</i> does not name an accessible package, or <i>Id</i> does not name a type within
that package, or the type named <i>Id</i> within that package is not accessible <a href="6.doc.html#33916">(&#167;6.6)</a>,
then a compile-time error occurs.
<p><a name="32816"></a>
The example:<p>
<pre><a name="21789"></a>package wnj.test;
</pre><pre><a name="21790"></a>
class Test {
<a name="21791"></a> public static void main(String[] args) {
<a name="21792"></a> java.util.Date date =
<a name="21793"></a> new java.util.Date(System.currentTimeMillis());
<a name="21794"></a> System.out.println(date.toLocaleString());
<a name="21795"></a> }
<a name="21796"></a>}
</pre><a name="21797"></a>
produced the following output the first time it was run:
<p><pre><a name="21798"></a>Sun Jan 21 22:56:29 1996
</pre><a name="21799"></a>
In this example:
<p><ul><a name="21800"></a>
<li>The name <code>wnj.test</code> must name a package on the host system. It is resolved by first looking for the package <code>wnj</code>, using the procedure described in <a href="6.doc.html#22481">&#167;6.5.3.1</a>, and then making sure that the subpackage <code>test</code> of this package is accessible.
<a name="21807"></a>
<li>The name <code>java.util.Date</code> <a href="javautil.doc3.html#7433">(&#167;21.3)</a> must denote a type, so we first use the procedure recursively to determine if <code>java.util</code> is an accessible package, which it is, and then look to see if the type <code>Date</code> is accessible in this package.
</ul><a name="21650"></a>
<h3>6.5.5 Meaning of Expression Names</h3>
<a name="32767"></a>
The meaning of a name classified as an <i>ExpressionName</i> is determined as follows.
<p><a name="22022"></a>
<h4>6.5.5.1 Simple Expression Names</h4>
<a name="22023"></a>
If an expression name consists of a single <i>Identifier</i>, then:
<p><ul><a name="22030"></a>
<li>If the <i>Identifier</i> appears within the scope <a href="6.doc.html#33623">(&#167;6.3)</a> of a local variable declaration <a href="14.doc.html#5920">(&#167;14.3)</a> or parameter declaration (<a href="8.doc.html#38698">&#167;8.4.1</a>, <a href="8.doc.html#29488">&#167;8.6.1</a>, <a href="14.doc.html#79311">&#167;14.18</a>) with that name, then the expression name denotes a variable, that is, that local variable or parameter. Local variables and parameters are never hidden (<a href="6.doc.html#33623">&#167;6.3</a>, <a href="6.doc.html#34133">&#167;6.3.1</a>, <a href="14.doc.html#5920">&#167;14.3</a>), so 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 <i>Identifier</i> appears within a class declaration <a href="8.doc.html#3857">(&#167;8)</a>:
<ul>
<a name="22062"></a>
<li>If there is not exactly one member of that class <a href="8.doc.html#21831">(&#167;8.2)</a> 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="8.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><a name="60351"></a>
<br><br>If the field is an instance variable <a href="8.doc.html#37544">(&#167;8.3.1.1)</a>, the expression name must appear within the declaration of an instance method <a href="8.doc.html#40420">(&#167;8.4)</a>, constructor <a href="8.doc.html#41652">(&#167;8.6)</a>, or instance variable initializer <a href="8.doc.html#38013">(&#167;8.3.2.2)</a>. If it appears within a <code>static</code> method <a href="8.doc.html#229128">(&#167;8.4.3.2)</a>, static initializer <a href="8.doc.html#39245">(&#167;8.5)</a>, or initializer for a <code>static</code> variable (<a href="8.doc.html#37544">&#167;8.3.1.1</a>, <a href="12.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="9.doc.html#238678">(&#167;9)</a>:
<ul>
<a name="60380"></a>
<li>If there is not exactly one member of that interface <a href="9.doc.html#32392">(&#167;9.2)</a> 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="22118"></a>
In the example:
<p><pre><a name="22119"></a>
class Test {
<br><a name="22120"></a> static int v;
<br><br><a name="61612"></a> static final int f = 3;
<br><a name="61613"></a>
public static void main(String[] args) {
<a name="61614"></a> int i;
<a name="22124"></a> i = 1;
<a name="22125"></a> v = 2;
<a name="22126"></a> f = 33; // compile-time error
<a name="22127"></a> System.out.println(i + " " + v + " " + f);
<a name="22128"></a> }
<br><a name="22129"></a>}
</pre><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><pre><a name="22131"></a>1 2 3
</pre><a name="22133"></a>
<h4>6.5.5.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="8.doc.html#3857">(&#167;8)</a>, then:
<ul>
<a name="22298"></a>
<li>If there is not exactly one accessible <a href="6.doc.html#33916">(&#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="9.doc.html#238678">(&#167;9)</a>, then:
<ul>
<a name="33167"></a>
<li>If there is not exactly one accessible <a href="6.doc.html#33916">(&#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="6.doc.html#33916">(&#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
</ul>
<a name="33211"></a>
<li>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.
<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
</ul>
</ul><a name="62391"></a>
The example:
<p><pre><a name="22175"></a>
class Point {
<a name="22176"></a> int x, y;
<a name="22177"></a> static int nPoints;
<a name="22178"></a>}
<a name="22179"></a>
class Test {
<a name="22180"></a> public static void main(String[] args) {
<a name="22181"></a> int i = 0;
<a name="22182"></a> i.x++; // compile-time error
<a name="22183"></a> Point p = new Point();
<a name="22184"></a> p.nPoints(); // compile-time error
<a name="22185"></a> }
<a name="22186"></a>}
</pre><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.6 Meaning of Method Names</h3>
<a name="32771"></a>
A <i>MethodName</i> can appear only in a method invocation expression <a href="15.doc.html#20448">(&#167;15.11)</a>. The
meaning of a name classified as a <i>MethodName</i> is determined as follows.
<p><a name="54512"></a>
<h4>6.5.6.1 Simple Method Names</h4>
<a name="54513"></a>
If a method name consists of a single <i>Identifier</i>, then <i>Identifier</i> is the method name
to be used for method invocation. The <i>Identifier</i> must name at least one method of
the class or interface within whose declaration the <i>Identifier</i> appears. See <a href="15.doc.html#20448">&#167;15.11</a>
for further discussion of the interpretation of simple method names in method
invocation expressions.
<p><a name="54547"></a>
<h4>6.5.6.2 Qualified Method Names</h4>
<a name="33243"></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="15.doc.html#20448">&#167;15.11</a> for further
discussion of the interpretation of qualified method names in method invocation
expressions.
<p><a name="33916"></a>
<h2>6.6 Qualified Names and Access Control</h2>
<a name="33917"></a>
Qualified names are a means of access to members of packages and reference
types; related means of access include field access expressions <a href="15.doc.html#41267">(&#167;15.10)</a> and
method invocation expressions <a href="15.doc.html#20448">(&#167;15.11)</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 <i>Identifier</i> that names a member of the package
or type. These are collectively known as constructs for <i>qualified access</i>.
<p><a name="33924"></a>
Java provides mechanisms for <i>access control</i>, to prevent the users of a package or class from depending on unnecessary details of the implementation of that package or class. Access control applies to qualified access and to the invocation of constructors by class instance creation expressions <a href="15.doc.html#41147">(&#167;15.8)</a>, explicit constructor invocations <a href="8.doc.html#78435">(&#167;8.6.5)</a>, and the method <code>newInstance</code> of class <code>Class</code> <a href="javalang.doc2.html#15088">(&#167;20.3.6)</a>.<p>
<a name="62634"></a>
If access is permitted, then the accessed entity is said to be <i>accessible</i>.<p>
<a name="62395"></a>
<h3>6.6.1 Determining Accessibility</h3>
<ul><a name="33934"></a>
<li>Whether a package is accessible is determined by the host system <a href="7.doc.html#37758">(&#167;7.2)</a>.
<a name="62409"></a>
<li>If a class or interface type is declared <code>public</code>, then it may be accessed by any Java code that can access the package in which it is declared. If a 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="62410"></a>
<li>A member (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 is declared.
<a name="62452"></a>
<li>Access occurs within a subclass of the class in which the <code>protected</code> member is declared, and the access is correct as described in <a href="6.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 only when it occurs from within the class in which it is declared.
<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</code> Access</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. Let <i>C</i> be the class in which a <code>protected</code> member or constructor
is declared and let <i>S</i> be the subclass of <i>C</i> in whose declaration the use of
the <code>protected</code> member or constructor occurs. Then:
<p><ul><a name="60602"></a>
<li>If an access is of a <code>protected</code> member (field or method), let <i>Id</i> be its name. Consider then the means of qualified access:
<ul>
<a name="33943"></a>
<li>If the access is by a field access expression of the form <code>super.</code><i>Id</i>, then the access is permitted.
<a name="33945"></a>
<li>If the access is by a qualified name <i>Q</i><code>.</code><i>Id</i>, where <i>Q</i> is a <i>TypeName</i>, then the access is permitted if and only if <i>Q</i> is <i>S</i> or a subclass of <i>S</i>.
<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 <i>ExpressionName</i>, 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="33947"></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 <i>Primary</i> 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 <i>Primary</i> 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="60590"></a>
<li>Otherwise, if an access is of a <code>protected</code> constructor:
<ul>
<a name="60601"></a>
<li>If the access is by a superclass constructor invocation <code>super(</code>. . .<code>)</code>, then the access is permitted.
<a name="62811"></a>
<li>If the access is by a class instance creation expression <code>new</code> <i>T</i><code>(</code>. . .<code>)</code>, then the access is not permitted. (A <code>protected</code> constructor can be accessed by a class instance creation expression only from within the package in which it is defined.)
<a name="62828"></a>
<li>If the access is by an invocation of the method <code>newInstance</code> of class <code>Class</code> <a href="javalang.doc2.html#15088">(&#167;20.3.6)</a>, then the access is not permitted.
</ul>
</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><pre><br><a name="33958"></a>package points;
<br><a name="33959"></a>class PointVec { Point[] vec; }
</pre><a name="33960"></a>
and:
<p><pre><br><a name="33961"></a>package points;
<br></pre><pre><a name="33962"></a>
public class Point {
<a name="33963"></a> protected int x, y;
<a name="33964"></a> public void move(int dx, int dy) { x += dx; y += dy; }
<a name="33965"></a> public int getX() { return x; }
<a name="33966"></a> public int getY() { return y; }
<a name="33967"></a>}
</pre><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 Java 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="6.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 Non-<code>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="6.doc.html#33916">(&#167;6.6)</a>. In the example:
<p><pre><br><a name="36076"></a>package points;
<br></pre><pre><a name="36077"></a>
public class Point {
<a name="36078"></a> public int x, y;
<a name="36079"></a> public void move(int dx, int dy) { x += dx; y += dy; }
<a name="36080"></a>}
<br><a name="36081"></a>
class PointList {
<a name="36082"></a> Point next, prev;
<a name="36083"></a>}
</pre><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. Thus a compilation unit in another package can access
<code>points.Point</code>, either by using its fully qualified name:
<p><pre><br><a name="36085"></a>package pointsUser;
<br></pre><pre><a name="36086"></a>
class Test {
<a name="36087"></a> public static void main(String[] args) {
<a name="36088"></a> points.Point p = new points.Point();
<a name="36089"></a> System.out.println(p.x + " " + p.y);
<a name="36090"></a> }
<a name="36091"></a>}
</pre><a name="36092"></a>
or by using a single-type-import declaration <a href="7.doc.html#26699">(&#167;7.5.1)</a> that mentions the fully
qualfied name, so that the simple name may be used thereafter:
<p><pre><br><a name="36096"></a>package pointsUser;
<br><br><a name="36097"></a>import points.Point;
<br></pre><pre><a name="36098"></a>
class Test {
<a name="36099"></a> public static void main(String[] args) {
<a name="36100"></a> Point p = new Point();
<a name="36101"></a> System.out.println(p.x + " " + p.y);
<a name="36102"></a> }
<a name="36103"></a>}
</pre><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. 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.
<p><a name="60607"></a>
For example, if we have:<p>
<pre><br><a name="36156"></a>package points;
<br></pre><pre><a name="36157"></a>
public class Point {
<a name="36158"></a> public int x, y;
<a name="36159"></a> void move(int dx, int dy) { x += dx; y += dy; }
<a name="61627"></a> public void moveAlso(int dx, int dy) { move(dx, dy); }
<a name="36160"></a>}
</pre><a name="36161"></a>
then a subclass in another package may declare an unrelated <code>move</code> method, with
the same signature <a href="8.doc.html#38649">(&#167;8.4.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><pre><br><a name="36165"></a>package morepoints;
<br></pre><pre><a name="36166"></a>
public class PlusPoint extends points.Point {
<a name="36167"></a> public void move(int dx, int dy) {
<a name="61624"></a> super.move(dx, dy); // compile-time error
<a name="36170"></a> moveAlso(dx, dy);
<a name="61628"></a> }
<a name="36171"></a>}
</pre><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:<p>
<pre><a name="61642"></a>
import points.Point;
<a name="61643"></a>
import morepoints.PlusPoint;
<a name="61644"></a>
class Test {
<a name="61645"></a>
public static void main(String[] args) {
<a name="61646"></a> PlusPoint pp = new PlusPoint();
<a name="61647"></a> pp.move(1, 1);
<a name="61648"></a> }
<br><a name="61649"></a>}
</pre><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 that has access to the package in
which it is declared <a href="7.doc.html#13194">(&#167;7.4.4)</a>. For example, in the compilation unit:
<p><pre><br><a name="36180"></a>package points;
<br></pre><pre><a name="36181"></a>
public class Point {
<br><a name="36182"></a> int x, y;
<br><a name="36183"></a>
public void move(int dx, int dy) {
<a name="36184"></a> x += dx; y += dy;
<a name="36185"></a> moves++;
<a name="36186"></a> }
<br><br><a name="36187"></a> public static int moves = 0;
<br><a name="36188"></a>}
</pre><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>point</code> package declares:
<p><pre><br><a name="36202"></a>package points;
<br></pre><pre><a name="36203"></a>
public class Point {
<br><a name="36322"></a> protected int x, y;
<br><a name="36324"></a>
void warp(threePoint.Point3d a) {
<a name="61672"></a> if (a.z &gt; 0) // compile-time error: cannot access a.z
<a name="61670"></a> a.delta(this);
<a name="36332"></a> }
<br><a name="36323"></a>}
</pre><a name="36204"></a>
and the <code>threePoint</code> package declares:
<p><pre><br><a name="36331"></a>package threePoint;
<br><br><a name="36205"></a>import points.Point;
<br></pre><pre><a name="36206"></a>
public class Point3d extends Point {
<br><a name="36315"></a> protected int z;
<br><a name="36207"></a>
public void delta(Point p) {
<a name="36295"></a> p.x += this.x; // compile-time error: cannot access p.x
<a name="36296"></a> p.y += this.y; // compile-time error: cannot access p.y
<a name="36297"></a> }
<br><a name="36208"></a>
public void delta3d(Point3d q) {
<a name="36300"></a> q.x += this.x;
<a name="36317"></a> q.y += this.y;
<a name="36319"></a> q.z += this.z;
<a name="36302"></a> }
<br><a name="36209"></a>}
</pre><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="5.doc.html#176921">&#167;5.4</a>, <a href="15.doc.html#238146">&#167;15.15</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>.<p>
<a name="61715"></a>
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>Point</code> (the type of the parameter a), it is not a subclass of <code>Point</code> (the class in which <code>z</code> is declared). <p>
<a name="36233"></a>
<h3>6.6.8 Example: <code>private</code> Fields, Methods, and Constructors</h3>
<a name="36235"></a>
<code>A</code> <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><pre><a name="36237"></a>
class Point {
<br><a name="36344"></a> Point() { setMasterID(); }
<br><a name="36238"></a>
int x, y;
<a name="36239"></a> private int ID;
<a name="36240"></a> private static int masterID = 0;
<br><a name="36241"></a> private void setMasterID() { ID = masterID++; }
<br><a name="36242"></a>}
</pre><a name="36243"></a>
the <code>private</code> members <code>ID,</code> m<code>asterID</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="8.doc.html#16830">&#167;8.6.8</a> for an example that uses a <code>private</code> constructor.<p>
<a name="25430"></a>
<h2>6.7 Fully Qualified Names</h2>
<a name="24074"></a>
Every package, class, interface, array type, and primitive type has a fully qualified
name. It follows that every type except the null 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 class or 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 class or 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="9454"></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="11162"></a>
Examples:
<p><ul><a name="12348"></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 standard 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><pre><a name="12353"></a>package points;
</pre><pre><a name="12362"></a>
class Point { int x, y; }
<a name="12354"></a>
class PointVec {
<a name="12355"></a> Point[] vec;
<a name="56765"></a>}
</pre><a name="56766"></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="11186"></a>
<h2>6.8 Naming Conventions</h2>
<a name="9218"></a>
The Java system and standard classes 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 Java programs. 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 Java convention because they are short and are not verbs.<p>
<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="7.doc.html#40169">&#167;7.7</a>. Such names are always qualified names whose first identifier
consists of two or three uppercase 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><pre><a name="9241"></a>
COM.JavaSoft.jag.Oak
<a name="9242"></a>ORG.NPR.pledge.driver
<a name="9252"></a>UK.ac.city.rugby.game
</pre><a name="32841"></a>
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 to JavaSoft for naming standard Java packages.<p>
<a name="29469"></a>
When package names occur in expressions:<p>
<ul><a name="12971"></a>
<li>If a package name is hidden by a field declaration, then <code>import</code> declarations <a href="7.doc.html#26656">(&#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 hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java code.
<a name="34365"></a>
<li>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 language does not actually rely on case distinctions to determine whether a name is a package name or a type name. It is not possible for a type name to hide a package 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><pre><a name="9292"></a>
<code>ClassLoader
</code><a name="9298"></a><code>SecurityManager
</code><a name="9309"></a><code>Thread
</code><a name="9299"></a><code>Dictionary
</code><a name="9316"></a>BufferedInputStream
</pre><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>java.lang.Runnable</code> and <code>java.lang.Cloneable</code>.<p>
<a name="12992"></a>
Hiding involving class and interface type names is rare. Names of fields, parameters, and local variables normally do not hide type names because they conventionally begin with a lowercase letter whereas type names conventionally begin with an uppercase letter.<p>
<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><i>V</i> and <code>set</code><i>V</i>. An example is the methods <code>getPriority</code> <a href="javalang.doc18.html#2819">(&#167;20.20.22)</a> and <code>setPriority</code> <a href="javalang.doc18.html#14175">(&#167;20.20.23)</a> of class <code>java.lang.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>java.lang.String</code> <a href="javalang.doc11.html#13985">(&#167;20.12.11)</a>.
<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><i>V</i>. An example is the method <code>isInterrupted</code> of class <code>java.lang.Thread</code> <a href="javalang.doc18.html#29183">(&#167;20.20.32)</a>.
<a name="34650"></a>
<li>A method that converts its object to a particular format <i>F</i> should be named <code>to</code><i>F</i>. Examples are the method <code>toString</code> of class <code>java.lang.Object</code> <a href="javalang.doc1.html#1152">(&#167;20.1.2)</a> and the methods <code>toLocaleString</code> <a href="javautil.doc3.html#7495">(&#167;21.3.27)</a> and <code>toGMTString</code> <a href="javautil.doc3.html#7496">(&#167;21.3.28)</a> 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 standard
Java Application Programming Interface classes, will make it easier to use.
<p><a name="9384"></a>
Method names cannot hide or be hidden by other names <a href="6.doc.html#21652">(&#167;6.5.6)</a>.<p>
<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
Java 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="6.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> <a href="javaio.doc6.html#28355">(&#167;22.6)</a> and the field <code>bytesTransferred</code> of the class <code>java.io.InterruptedIOException</code> <a href="javaio.doc30.html#30212">(&#167;22.30.1)</a>.<p>
<a name="13055"></a>
Hiding involving field names is rare.<p>
<ul><a name="29526"></a>
<li>If a field name hides a package name, then an <code>import</code> declaration <a href="7.doc.html#26656">(&#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 hides a type name, then a fully qualified name for the type can be used.
<a name="29539"></a>
<li>Field names cannot hide method names.
<a name="9539"></a>
<li>If a field name is hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java 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>java.lang.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:<p>
<pre><a name="9564"></a>
interface ProcessStates {
<a name="9565"></a> int PS_RUNNING = 0;
<a name="9566"></a> int PS_SUSPENDED = 1;
<a name="9568"></a>}
</pre><a name="13087"></a>
Hiding involving constant names is rare:
<p><ul><a name="9569"></a>
<li>Constant names should be longer than three letters, so that they do not hide the initial component of a unique package name.
<a name="62840"></a>
<li>Constant names normally have no lowercase letters, so they will not normally hide names of packages, types, or fields, whose names normally contain at least one lowercase letter.
<a name="62841"></a>
<li>Constant names cannot hide method names, because they are distinguished syntactically.
</ul><a name="62552"></a>
<h3>6.8.6 Local Variable and Parameter Names</h3>
<a name="9381"></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="12405"></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>java.lang.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>
</ul>
</ul><a name="12367"></a>
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:<p>
<ul><a name="9148"></a>
<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
</ul><a name="34406"></a>
Local variable or parameter names that consist of only two or three uppercase letters should be avoided to avoid potential conflicts with the initial country codes and domain names that are the first component of unique package names <a href="7.doc.html#40169">(&#167;7.7)</a>.<p>
<a name="65318"></a>
<p>
<hr>
<!-- This inserts footnotes-->
<table border="0" width="100%">
<tr>
<td><a href="index.html">Contents</a> | <a href="5.doc.html">Prev</a> | <a href="7.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">First Edition</font></td></tr></table>
<p>
<font size=-1>Java Language Specification (HTML generated by Suzette Pelouch on April 03, 1998)<br>
<i><a href="jcopyright.doc.html">Copyright &#169 1996 Sun Microsystems, Inc.</a>
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>
<meta name="collection" content="exclude">
<title>The Java Language Specification
Packages</title>
</head>
<body BGCOLOR=#eeeeff text=#000000 LINK=#0000ff VLINK=#000077 ALINK=#ff0000>
<table border="0" width="100%">
<tr>
<td><a href="index.html">Contents</a> | <a href="6.doc.html">Prev</a> | <a href="8.doc.html">Next</a> | <a href="j.index.doc1.html">Index</a></td>
<td align=right><i>Java Language Specification</i><br>
<font size="-1">First 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>
Java programs are organized as sets of packages. Each package has its own set
of names for types, which helps to prevent name conflicts. A type is accessible
<a href="6.doc.html#33916">(&#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="7.doc.html#26535">(&#167;7.1)</a>. The members of a package are class and interface types <a href="7.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="7.doc.html#37546">(&#167;7.2.1)</a> or in a database <a href="7.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. In either case, the set of packages available to a Java program is determined by the host system, but must always include at least the three standard packages <code>java.lang</code>, <code>java.util</code>, and <code>java.io</code> as specified in Chapters <a href="javalang.doc.html#">20</a>, <a href="javautil.doc.html#">21</a>, and <a href="javaio.doc16.html#29544">22</a>. In most host environments, the standard packages <code>java.applet</code>, <code>java.awt</code>, and <code>java.net</code>, which are not described in this specification, are also available to Java programs.<p>
<a name="26522"></a>
A package consists of a number of compilation units <a href="7.doc.html#40031">(&#167;7.3)</a>. A compilation unit automatically has access to all types declared in its package and also automatically imports<i> </i>each of the types declared in the predefined package<i> </i><code>java.lang</code>.<p>
<a name="35454"></a>
A compilation unit has three parts, each of which is optional:<p>
<ul><a name="13571"></a>
<li>A <code>package</code> declaration <a href="7.doc.html#26619">(&#167;7.4)</a>, giving the fully qualified name <a href="6.doc.html#25430">(&#167;6.7)</a> of the package to which the compilation unit belongs
<a name="13599"></a>
<li><code>import</code> declarations <a href="7.doc.html#26656">(&#167;7.5)</a> that allow types from other packages to be referred to using their simple names
<a name="13606"></a>
<li>Type declarations <a href="7.doc.html#26783">(&#167;7.6)</a> of class and interface types
</ul><a name="26526"></a>
For small programs and casual development, a package can be unnamed <a href="7.doc.html#26639">(&#167;7.4.2)</a> or have a simple name, but if Java code is to be widely distributed, unique package names should be chosen <a href="7.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.<p>
<a name="26535"></a>
<h2>7.1 Package Members</h2>
<a name="37172"></a>
A<i> package</i> can have members of either or both of the following kinds:
<p><ul><a name="29038"></a>
<li>Subpackages of the package
<a name="29031"></a>
<li>Types declared in the compilation units <a href="7.doc.html#40031">(&#167;7.3)</a> of the package
</ul><a name="37558"></a>
For example, in the standard 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="6.doc.html#25430">(&#167;6.7)</a> of a package is <i>P</i><i></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="37562"></a>
The subpackages of package <code>java</code> named <code>lang</code>, <code>util</code>, and <code>io</code> (whose fully qualified package names are therefore <code>java.lang</code>, <code>java.util</code>, and <code>java.io</code>) are a standard part of every Java implementation and are specified in Chapters <a href="javalang.doc.html#">20</a>, <a href="javautil.doc.html#">21</a>, and <a href="javaio.doc11.html#28749">22</a>. Many Java implementations will include the entire set of <code>java</code> packages defined in the series of books <i>The Java Application Programming Interface</i>.<p>
<a name="37573"></a>
A package may not contain a type declaration and a subpackage of the same name, or a compile-time error results. Here are some examples:<p>
<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="37576"></a>
<li>If there is a package named <code>mouse</code> and a 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="61007"></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>.
</ul><a name="61009"></a>
The hierarchical naming structure for packages is intended to be convenient for organizing related packages in a conventional manner, but has no significance in the Java language itself other than the prohibition against a package having a subpackage with the same simple name as a type declared in that package. There is no special access relationship in the Java language 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.<p>
<a name="37758"></a>
<h2>7.2 Host Support for Packages</h2>
<a name="37780"></a>
Each Java host determines how packages, compilation units, and subpackages are
created and stored; which top-level package names are in scope in a particular
compilation; and which packages are accessible.
<p><a name="37759"></a>
The packages may be stored in a local file system in simple implementations of Java. Other implementations may use a distributed file system or some form of database to store Java source and/or binary code.<p>
<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 Java 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><pre><a name="37473"></a>
COM
<a name="13211"></a>gls
<a name="13212"></a>jag
<a name="13213"></a>java
<a name="13214"></a>wnj
</pre><a name="37477"></a>
where directory <code>java</code> would contain the standard Java Application Programming
Interface packages that are part of every standard Java system; the directories <code>jag</code>,
<code>gls</code>, and <code>wnj</code> might contain packages that the three 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="7.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 probably contain at least the following subdirectories:<p>
<pre><a name="37481"></a>
applet
<a name="13215"></a>awt
<a name="13216"></a>io
<a name="13217"></a>lang
<a name="13218"></a>net
<a name="13219"></a>util
</pre><a name="37490"></a>
corresponding to the standard 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 standard
Java Application Programming Interface.
<p><a name="37491"