The Java Language Specification

James Gosling
Bill Joy
Guy Steele

Version 1.0
(Converted from the printed book, August 1996, first printing)

1.1 Example Programs 5

1.2 References 6

2.1 Context-Free Grammars 7

2.2 The Lexical Grammar 7

2.3 The Syntactic Grammar 8

2.4 Grammar Notation 8

3.1 Unicode 11

3.2 Lexical Translations 12

3.3 Unicode Escapes 12

3.4 Line Terminators 13

3.5 Input Elements and Tokens 14

3.6 White Space 15

3.7 Comments 15

3.8 Identifiers 17

3.9 Keywords 18

3.10 Literals 19

3.10.1 Integer Literals 19

3.10.2 Floating-Point Literals 22

3.10.3 Boolean Literals 23

3.10.4 Character Literals 24

3.10.5 String Literals 25

3.10.6 Escape Sequences for Character and String Literals 26

3.10.7 The Null Literal 27

3.11 Separators 27

3.12 Operators 28

4.1 The Kinds of Types and Values 30

4.2 Primitive Types and Values 30

4.2.1 Integral Types and Values 31

4.2.2 Integer Operations 31

4.2.3 Floating-Point Types and Values 33

4.2.4 Floating-Point Operations 34

4.2.5 The boolean Type and boolean Values 36

4.3 Reference Types and Values 37

4.3.1 Objects 38

4.3.2 The Class Object 40

4.3.3 The Class String 41

4.3.4 When Reference Types Are the Same 42

4.4 Where Types Are Used 42

4.5 Variables 43

4.5.1 Variables of Primitive Type 44

4.5.2 Variables of Reference Type 44

4.5.3 Kinds of Variables 44

4.5.4 Initial Values of Variables 46

4.5.5 Variables Have Types, Objects Have Classes 47

5.1 Kinds of Conversion 54

5.1.1 Identity Conversions 54

5.1.2 Widening Primitive Conversions 54

5.1.3 Narrowing Primitive Conversions 55

5.1.4 Widening Reference Conversions 58

5.1.5 Narrowing Reference Conversions 59

5.1.6 String Conversions 60

5.1.7 Forbidden Conversions 60

5.2 Assignment Conversion 61

5.3 Method Invocation Conversion 66

5.4 String Conversion 67

5.5 Casting Conversion 67

5.6 Numeric Promotions 72

5.6.1 Unary Numeric Promotion 73

5.6.2 Binary Numeric Promotion 74

6.1 Declarations 78

6.2 Names and Identifiers 79

6.3 Scope of a Simple Name 81

6.3.1 Hiding Names 83

6.4 Members and Inheritance 85

6.4.1 The Members of a Package 85

6.4.2 The Members of a Class Type 86

6.4.3 The Members of an Interface Type 87

6.4.4 The Members of an Array Type 88

6.5 Determining the Meaning of a Name 89

6.5.1 Syntactic Classification of a Name According to Context 90

6.5.2 Reclassification of Contextually Ambiguous Names 91

6.5.3 Meaning of Package Names 93

6.5.3.1 Simple Package Names 93

6.5.3.2 Qualified Package Names 93

6.5.4 Meaning of Type Names 93

6.5.4.1 Simple Type Names 93

6.5.4.2 Qualified Type Names 94

6.5.5 Meaning of Expression Names 95

6.5.5.1 Simple Expression Names 95

6.5.5.2 Qualified Expression Names 96

6.5.6 Meaning of Method Names 98

6.5.6.1 Simple Method Names 98

6.5.6.2 Qualified Method Names 98

6.6 Qualified Names and Access Control 99

6.6.1 Determining Accessibility 99

6.6.2 Details on protected Access 100

6.6.3 An Example of Access Control 100

6.6.4 Example: Access to public and Non-public Classes 101

6.6.5 Example: Default-Access Fields, Methods, and Constructors 102

6.6.6 Example: public Fields, Methods, and Constructors 103

6.6.7 Example: protected Fields, Methods, and Constructors 104

6.6.8 Example: private Fields, Methods, and Constructors 105

6.7 Fully Qualified Names 105

6.8 Naming Conventions 106

6.8.1 Package Names 107

6.8.2 Class and Interface Type Names 108

6.8.3 Method Names 108

6.8.4 Field Names 109

6.8.5 Constant Names 109

6.8.6 Local Variable and Parameter Names 110

7.1 Package Members 114

7.2 Host Support for Packages 115

7.2.1 Storing Packages in a File System 115

7.2.2 Storing Packages in a Database 117

7.3 Compilation Units 117

7.4 Package Declarations 118

7.4.1 Named Packages 118

7.4.2 Unnamed Packages 119

7.4.3 Scope and Hiding of a Package Name 120

7.4.4 Access to Members of a Package 120

7.5 Import Declarations 120

7.5.1 Single-Type-Import Declaration 121

7.5.2 Type-Import-on-Demand Declaration 122

7.5.3 Automatic Imports 122

7.5.4 A Strange Example 123

7.6 Type Declarations 124

7.7 Unique Package Names 125

8.1 Class Declaration 128

8.1.1 Scope of a Class Type Name 130

8.1.2 Class Modifiers 130

8.1.2.1 abstract Classes 131

8.1.2.2 final Classes 133

8.1.3 Superclasses and Subclasses 133

8.1.4 Superinterfaces 135

8.1.5 Class Body and Member Declarations 138

8.2 Class Members 138

8.2.1 Examples of Inheritance 139

8.2.1.1 Example: Inheritance with Default Access 140

8.2.1.2 Inheritance with public and protected 141

8.2.1.3 Inheritance with private 141

8.2.1.4 Accessing Members of Inaccessible Classes 142

8.3 Field Declarations 143

8.3.1 Field Modifiers 144

8.3.1.1 static Fields 145

8.3.1.2 final Fields 146

8.3.1.3 transient Fields 147

8.3.1.4 volatile Fields 147

8.3.2 Initialization of Fields 149

8.3.2.1 Initializers for Class Variables 149

8.3.2.2 Initializers for Instance Variables 150

8.3.3 Examples of Field Declarations 151

8.3.3.1 Example: Hiding of Class Variables 151

8.3.3.2 Example: Hiding of Instance Variables 152

8.3.3.3 Example: Multiply Inherited Fields 153

8.3.3.4 Example: Re-inheritance of Fields 154

8.4 Method Declarations 155

8.4.1 Formal Parameters 156

8.4.2 Method Signature 157

8.4.3 Method Modifiers 157

8.4.3.1 abstract Methods 158

8.4.3.2 static Methods 160

8.4.3.3 final Methods 160

8.4.3.4 native Methods 161

8.4.3.5 synchronized Methods 161

8.4.4 Method Throws 163

8.4.5 Method Body 164

8.4.6 Inheritance, Overriding, and Hiding 165

8.4.6.1 Overriding (By Instance Methods) 165

8.4.6.2 Hiding (By Class Methods) 165

8.4.6.3 Requirements in Overriding and Hiding 166

8.4.6.4 Inheriting Methods with the Same Signature 166

8.4.7 Overloading 167

8.4.8 Examples of Method Declarations 168

8.4.8.1 Example: Overriding 168

8.4.8.2 Example: Overloading, Overriding, and Hiding 168

8.4.8.3 Example: Incorrect Overriding 169

8.4.8.4 Example: Overriding versus Hiding 170

8.4.8.5 Example: Invocation of Hidden Class Methods 171

8.4.8.6 Large Example of Overriding 172

8.4.8.7 Example: Incorrect Overriding because of Throws 174

8.5 Static Initializers 175

8.6 Constructor Declarations 176

8.6.1 Formal Parameters 177

8.6.2 Constructor Signature 177

8.6.3 Constructor Modifiers 177

8.6.4 Constructor Throws 178

8.6.5 Constructor Body 178

8.6.6 Constructor Overloading 180

8.6.7 Default Constructor 180

8.6.8 Preventing Instantiation of a Class 180

9.1 Interface Declarations 184

9.1.1 Scope of an Interface Type Name 184

9.1.2 Interface Modifiers 184

9.1.2.1 abstract Interfaces 184

9.1.3 Superinterfaces 185

9.1.4 Interface Body and Member Declarations 185

9.1.5 Access to Interface Member Names 186

9.2 Interface Members 186

9.3 Field (Constant) Declarations 186

9.3.1 Initialization of Fields in Interfaces 187

9.3.2 Examples of Field Declarations 188

9.3.2.1 Ambiguous Inherited Fields 188

9.3.2.2 Multiply Inherited Fields 188

9.4 Abstract Method Declarations 189

9.4.1 Inheritance and Overriding 189

9.4.2 Overloading 190

9.4.3 Examples of Abstract Method Declarations 190

9.4.3.1 Example: Overriding 190

9.4.3.2 Example: Overloading 191

10.1 Array Types 194

10.2 Array Variables 194

10.3 Array Creation 195

10.4 Array Access 195

10.5 Arrays: A Simple Example 196

10.6 Arrays Initializers 196

10.7 Array Members 197

10.8 Class Objects for Arrays 199

10.9 An Array of Characters is Not a String 199

10.10 Array Store Exception 199

11.1 The Causes of Exceptions 202

11.2 Compile-Time Checking of Exceptions 203

11.2.1 Why Errors are Not Checked 203

11.2.2 Why Runtime Exceptions are Not Checked 203

11.3 Handling of an Exception 204

11.3.1 Exceptions are Precise 205

11.3.2 Handling Asynchronous Exceptions 205

11.4 An Example of Exceptions 206

11.5 The Exception Hierarchy 208

11.5.1 The Classes Exception and RuntimeException 208

11.5.1.1 Standard Runtime Exceptions 208

11.5.1.2 Standard Checked Exceptions 210

11.5.2 The Class Error 211

11.5.2.1 Loading and Linkage Errors 211

11.5.2.2 Virtual Machine Errors 212

12.1 Virtual Machine Start-Up 215

12.1.1 Load the Class Test 216

12.1.2 Link Test: Verify, Prepare, (Optionally) Resolve 216

12.1.3 Initialize Test: Execute Initializers 217

12.1.4 Invoke Test.main 218

12.2 Loading of Classes and Interfaces 218

12.2.1 The Loading Process 219

12.2.2 Loading: Implications for Code Generation 219

12.3 Linking of Classes and Interfaces 220

12.3.1 Verification of the Binary Representation 220

12.3.2 Preparation of a Class or Interface Type 221

12.3.3 Resolution of Symbolic References 221

12.3.4 Linking: Implications for Code Generation 222

12.4 Initialization of Classes and Interfaces 223

12.4.1 When Initialization Occurs 223

12.4.2 Detailed Initialization Procedure 225

12.4.3 Initialization: Implications for Code Generation 227

12.5 Creation of New Class Instances 228

12.6 Finalization of Class Instances 231

12.6.1 Implementing Finalization 232

12.6.2 Finalizer Invocations are Not Ordered 234

12.7 Finalization of Classes 235

12.8 Unloading of Classes and Interfaces 235

12.9 Virtual Machine Exit 235

13.1 The Form of a Java Binary 238

13.2 What Binary Compatibility Is and Is Not 240

13.3 Evolution of Packages 242

13.4 Evolution of Classes 242

13.4.1 abstract Classes 242

13.4.2 final Classes 242

13.4.3 public Classes 243

13.4.4 Superclasses and Superinterfaces 243

13.4.5 Class Body and Member Declarations 245

13.4.6 Access to Members and Constructors 248

13.4.7 Field Declarations 249

13.4.8 final Fields and Constants 250

13.4.9 static Fields 253

13.4.10 transient Fields 253

13.4.11 volatile Fields 253

13.4.12 Method and Constructor Declarations 253

13.4.13 Method and Constructor Parameters 254

13.4.14 Method Result Type 254

13.4.15 abstract Methods 254

13.4.16 final Methods 255

13.4.17 native Methods 256

13.4.18 static Methods 256

13.4.19 synchronized Methods 256

13.4.20 Method and Constructor Throws 256

13.4.21 Method and Constructor Body 257

13.4.22 Method and Constructor Overloading 257

13.4.23 Method Overriding 258

13.4.24 Static Initializers 259

13.5 Evolution of Interfaces 259

13.5.1 public Interfaces 259

13.5.2 Superinterfaces 260

13.5.3 The Interface Members 260

13.5.4 Field Declarations 260

13.5.5 Abstract Method Declarations 261

14.1 Normal and Abrupt Completion of Statements 264

14.2 Blocks 265

14.3 Local Variable Declaration Statements 265

14.3.1 Local Variable Declarators and Types 266

14.3.2 Scope of Local Variable Declarations 267

14.3.3 Hiding of Names by Local Variables 268

14.3.4 Execution of Local Variable Declarations 269

14.4 Statements 269

14.5 The Empty Statement 271

14.6 Labeled Statements 271

14.7 Expression Statements 272

14.8 The if Statement 273

14.8.1 The if-then Statement 273

14.8.2 The if-then-else Statement 273

14.9 The switch Statement 274

14.10 The while Statement 277

14.10.1 Abrupt Completion 278

14.11 The do Statement 278

14.11.1 Abrupt Completion 279

14.11.2 Example of do statement 280

14.12 The for Statement 280

14.12.1 Initialization of for statement 281

14.12.2 Iteration of for statement 281

14.12.3 Abrupt Completion of for statement 282

14.13 The break Statement 283

14.14 The continue Statement 285

14.15 The return Statement 286

14.16 The throw Statement 287

14.17 The synchronized Statement 289

14.18 The try statement 290

14.18.1 Execution of try-catch 291

14.18.2 Execution of try-catch-finally 292

14.19 Unreachable Statements 295

15.1 Evaluation, Denotation, and Result 301

15.2 Variables as Values 302

15.3 Type of an Expression 302

15.4 Expressions and Run-Time Checks 302

15.5 Normal and Abrupt Completion of Evaluation 304

15.6 Evaluation Order 305

15.6.1 Evaluate Left-Hand Operand First 305

15.6.2 Evaluate Operands before Operation 307

15.6.3 Evaluation Respects Parentheses and Precedence 308

15.6.4 Argument Lists are Evaluated Left-to-Right 309

15.6.5 Evaluation Order for Other Expressions 310

15.7 Primary Expressions 311

15.7.1 Literals 312

15.7.2 this 313

15.7.3 Parenthesized Expressions 313

15.8 Class Instance Creation Expressions 314

15.8.1 Run-time Evaluation of Class Instance Creation Expressions 314

15.8.2 Example: Evaluation Order and Out-of-Memory Detection 315

15.9 Array Creation Expressions 315

15.9.1 Run-time Evaluation of Array Creation Expressions 316

15.9.2 Example: Array Creation Evaluation Order 318

15.9.3 Example: Array Creation and Out-of-Memory Detection 319

15.10 Field Access Expressions 319

15.10.1 Field Access Using a Primary 320

15.10.2 Accessing Superclass Members using super 322

15.11 Method Invocation Expressions 323

15.11.1 Compile-Time Step 1: Determine Class or Interface to Search 324

15.11.2 Compile-Time Step 2: Determine Method Signature 325

15.11.2.1 Find Methods that are Applicable and Accessible 325

15.11.2.2 Choose the Most Specific Method 327

15.11.2.3 Example: Overloading Ambiguity 327

15.11.2.4 Example: Return Type Not Considered 328

15.11.2.5 Example: Compile-Time Resolution 329

15.11.3 Compile-Time Step 3: Is the Chosen Method Appropriate? 332

15.11.4 Runtime Evaluation of Method Invocation 333

15.11.4.1 Compute Target Reference (If Necessary) 333

15.11.4.2 Evaluate Arguments 334

15.11.4.3 Check Accessibility of Type and Method 334

15.11.4.4 Locate Method to Invoke 335

15.11.4.5 Create Frame, Synchronize, Transfer Control 336

15.11.4.6 Implementation Note: Combining Frames 337

15.11.4.7 Example: Target Reference and Static Methods 337

15.11.4.8 Example: Evaluation Order 338

15.11.4.9 Example: Overriding 338

15.11.4.10 Example: Method Invocation using super 340

15.12 Array Access Expressions 341

15.12.1 Runtime Evaluation of Array Access 341

15.12.2 Examples: Array Access Evaluation Order 342

15.13 Postfix Expressions 344

15.13.1 Names 344

15.13.2 Postfix Increment Operator ++ 345

15.13.3 Postfix Decrement Operator -- 345

15.14 Unary Operators 346

15.14.1 Prefix Increment Operator ++ 347

15.14.2 Prefix Decrement Operator -- 348

15.14.3 Unary Plus Operator + 348

15.14.4 Unary Minus Operator - 349

15.14.5 Bitwise Complement Operator ~ 349

15.14.6 Logical Complement Operator ! 349

15.15 Cast Expressions 350

15.16 Multiplicative Operators 351

15.16.1 Multiplication Operator * 351

15.16.2 Division Operator / 352

15.16.3 Remainder Operator % 353

15.17 Additive Operators 355

15.17.1 String Concatenation Operator + 355

15.17.1.1 String Conversion 355

15.17.1.2 Optimization of String Concatenation 356

15.17.1.3 Examples of String Concatenation 356

15.17.2 Additive Operators (+ and -) for Numeric Types 358

15.18 Shift Operators 359

15.19 Relational Operators 360

15.19.1 Numerical Comparison Operators <, <=, >, and >= 361

15.19.2 Type Comparison Operator instanceof 361

15.20 Equality Operators 362

15.20.1 Numerical Equality Operators == and != 363

15.20.2 Boolean Equality Operators == and != 364

15.20.3 Reference Equality Operators == and != 364

15.21 Bitwise and Logical Operators 365

15.21.1 Integer Bitwise Operators &, ^, and | 365

15.21.2 Boolean Logical Operators &, ^, and | 365

15.22 Conditional-And Operator && 366

15.23 Conditional-Or Operator || 366

15.24 Conditional Operator ? : 367

15.25 Assignment Operators 369

15.25.1 Simple Assignment Operator = 369

15.25.2 Compound Assignment Operators 374

15.26 Expression 381

15.27 Constant Expression 381

16.1 Definite Assignment and Expressions 386

16.1.1 Boolean Constant Expressions 386

16.1.2 Boolean-valued Expressions 386

16.1.3 The Boolean Operator && 386

16.1.4 The Boolean Operator || 387

16.1.5 The Boolean Operator ! 387

16.1.6 The Boolean Operator & 387

16.1.7 The Boolean Operator | 388

16.1.8 The Boolean Operator ^ 388

16.1.9 The Boolean Operator == 389

16.1.10 The Boolean Operator != 389

16.1.11 The Boolean Operator ? : 389

16.1.12 The Conditional Operator ? : 390

16.1.13 Boolean Assignment Expressions 390

16.1.14 Other Assignment Expressions 391

16.1.15 Operators ++ and -- 392

16.1.16 Other Expressions 392

16.2 Definite Assignment and Statements 393

16.2.1 Empty Statements 393

16.2.2 Blocks 393

16.2.3 Local Variable Declaration Statements 393

16.2.4 Labeled Statements 394

16.2.5 Expression Statements 394

16.2.6 if Statements 394

16.2.7 switch Statements 395

16.2.8 while Statements 395

16.2.9 do Statements 395

16.2.10 for Statements 396

16.2.10.1 Initialization Part 396

16.2.10.2 Incrementation Part 397

16.2.11 break, continue, return, and throw Statements 397

16.2.12 synchronized Statements 397

16.2.13 try Statements 398

17.1 Terminology and Framework 401

17.2 Execution Order 403

17.3 Rules about Variables 404

17.4 Nonatomic Treatment of double and long 405

17.5 Rules about Locks 406

17.6 Rules about the Interaction of Locks and Variables 407

17.7 Rules for Volatile Variables 407

17.8 Prescient Store Actions 408

17.9 Discussion 408

17.10 Example: Possible Swap 409

17.11 Example: Out-of-Order Writes 413

17.12 Threads 415

17.13 Locks and Synchronization 415

17.14 Wait Sets and Notification 416

18.1 The Text of a Documentation Comment 419

18.2 HTML in a Documentation Comment 420

18.3 Summary Sentence and General Description 420

18.4 Tagged Paragraphs 420

18.4.1 The @see Tag 421

18.4.2 The @author Tag 421

18.4.3 The @version Tag 422

18.4.4 The @param Tag 422

18.4.5 The @return Tag 422

18.4.6 The @exception Tag 422

18.5 Example 423

19.1 Grammatical Difficulties 433

19.1.1 Problem #1: Names Too Specific 433

19.1.2 Problem #2: Modifiers Too Specific 435

19.1.3 Problem #3: Field Declaration versus Method Declaration 437

19.1.4 Problem #4: Array Type versus Array Access 438

19.1.5 Problem #5: Cast versus Parenthesized Expression 438

19.2 Productions from §2.3: The Syntactic Grammar 440

19.3 Productions from §3: Lexical Structure 440

19.4 Productions from §4: Types, Values, and Variables 440

19.5 Productions from §6: Names 441

19.6 Productions from §7: Packages 442

19.7 Productions Used Only in the LALR(1) Grammar 442

19.8 Productions from §8: Classes 443

19.8.1 Productions from §8.1: Class Declaration 443

19.8.2 Productions from §8.3: Field Declarations 443

19.8.3 Productions from §8.4: Method Declarations 444

19.8.4 Productions from §8.5: Static Initializers 444

19.8.5 Productions from §8.6: Constructor Declarations 445

19.9 Productions from §9: Interfaces 445

19.9.1 Productions from §9.1: Interface Declarations 445

19.10 Productions from §10: Arrays 446

19.11 Productions from §14: Blocks and Statements 446

19.12 Productions from §15: Expressions 450

20.1 The Class java.lang.Object 458

20.2 The Interface java.lang.Cloneable 465

20.3 The Class java.lang.Class 466

20.4 The Class java.lang.Boolean 469

20.5 The Class java.lang.Character 471

20.6 The Class java.lang.Number 487

20.7 The Class java.lang.Integer 488

20.8 The Class java.lang.Long 495

20.9 The Class java.lang.Float 503

20.10 The Class java.lang.Double 510

20.11 The Class java.lang.Math 517

20.12 The Class java.lang.String 531

20.13 The Class java.lang.StringBuffer 548

20.14 The Class java.lang.ClassLoader 558

20.15 The Class java.lang.Process 561

20.16 The Class java.lang.Runtime 563

20.17 The Class java.lang.SecurityManager 569

20.18 The Class java.lang.System 579

20.19 The Interface java.lang.Runnable 586

20.20 The Class java.lang.Thread 587

20.21 The Class java.lang.ThreadGroup 602

20.22 The Class java.lang.Throwable and its Subclasses 611

20.23 The Class java.lang.ExceptionInInitializerError 614