The Java® Language Specification Java SE 16 Edition James Gosling Bill Joy Guy Steele Gilad Bracha Alex Buckley Daniel Smith Gavin Bierman 2021-02-12 Specification: JSR-391 Java SE 16 Version: 16 Status: Final Release Release: March 2021 Copyright © 1997, 2021, Oracle America, Inc. All rights reserved. The Specification provided herein is provided to you only under the Limited License Grant included herein as Appendix A. Please see Appendix A, Limited License Grant. Table of Contents 1 Introduction 1 1.1 Organization of the Specification 2 1.2 Example Programs 6 1.3 Notation 6 1.4 Relationship to Predefined Classes and Interfaces 7 1.5 Preview Features 7 1.6 Feedback 9 1.7 References 10 2 Grammars 11 2.1 Context-Free Grammars 11 2.2 The Lexical Grammar 11 2.3 The Syntactic Grammar 12 2.4 Grammar Notation 12 3 Lexical Structure 17 3.1 Unicode 17 3.2 Lexical Translations 18 3.3 Unicode Escapes 19 3.4 Line Terminators 21 3.5 Input Elements and Tokens 21 3.6 White Space 23 3.7 Comments 23 3.8 Identifiers 24 3.9 Keywords 26 3.10 Literals 28 3.10.1 Integer Literals 28 3.10.2 Floating-Point Literals 35 3.10.3 Boolean Literals 38 3.10.4 Character Literals 39 3.10.5 String Literals 40 3.10.6 Text Blocks 42 3.10.7 Escape Sequences 48 3.10.8 The Null Literal 49 3.11 Separators 49 3.12 Operators 49 4 Types, Values, and Variables 51 4.1 The Kinds of Types and Values 51 iii The Java® Language Specification 4.2 Primitive Types and Values 52 4.2.1 Integral Types and Values 53 4.2.2 Integer Operations 53 4.2.3 Floating-Point Types, Formats, and Values 55 4.2.4 Floating-Point Operations 58 4.2.5 The boolean Type and boolean Values 62 4.3 Reference Types and Values 63 4.3.1 Objects 64 4.3.2 The Class Object 67 4.3.3 The Class String 67 4.3.4 When Reference Types Are the Same 68 4.4 Type Variables 68 4.5 Parameterized Types 70 4.5.1 Type Arguments of Parameterized Types 71 4.5.2 Members and Constructors of Parameterized Types 74 4.6 Type Erasure 75 4.7 Reifiable Types 76 4.8 Raw Types 77 4.9 Intersection Types 81 4.10 Subtyping 82 4.10.1 Subtyping among Primitive Types 82 4.10.2 Subtyping among Class and Interface Types 83 4.10.3 Subtyping among Array Types 84 4.10.4 Least Upper Bound 84 4.10.5 Type Projections 87 4.11 Where Types Are Used 89 4.12 Variables 94 4.12.1 Variables of Primitive Type 94 4.12.2 Variables of Reference Type 95 4.12.3 Kinds of Variables 97 4.12.4 final Variables 99 4.12.5 Initial Values of Variables 101 4.12.6 Types, Classes, and Interfaces 102 5 Conversions and Contexts 107 5.1 Kinds of Conversion 110 5.1.1 Identity Conversion 110 5.1.2 Widening Primitive Conversion 111 5.1.3 Narrowing Primitive Conversion 112 5.1.4 Widening and Narrowing Primitive Conversion 115 5.1.5 Widening Reference Conversion 115 5.1.6 Narrowing Reference Conversion 115 5.1.6.1 Allowed Narrowing Reference Conversion 116 5.1.6.2 Checked and Unchecked Narrowing Reference Conversions 117 5.1.6.3 Narrowing Reference Conversions at Run Time 118 5.1.7 Boxing Conversion 121 iv The Java® Language Specification 5.1.8 Unboxing Conversion 122 5.1.9 Unchecked Conversion 124 5.1.10 Capture Conversion 124 5.1.11 String Conversion 126 5.1.12 Forbidden Conversions 127 5.1.13 Value Set Conversion 127 5.2 Assignment Contexts 128 5.3 Invocation Contexts 133 5.4 String Contexts 135 5.5 Casting Contexts 135 5.6 Numeric Contexts 142 6 Names 147 6.1 Declarations 148 6.2 Names and Identifiers 156 6.3 Scope of a Declaration 158 6.3.1 Scope for Pattern Variables in Expressions 162 6.3.1.1 Conditional-And Operator && 162 6.3.1.2 Conditional-Or Operator || 162 6.3.1.3 Logical Complement Operator ! 163 6.3.1.4 Conditional Operator ? : 163 6.3.1.5 Pattern Match Operator instanceof 164 6.3.1.6 switch Expressions 165 6.3.1.7 Parenthesized Expressions 165 6.3.2 Scope for Pattern Variables in Statements 165 6.3.2.1 Blocks 166 6.3.2.2 if Statements 166 6.3.2.3 while Statements 168 6.3.2.4 do Statements 168 6.3.2.5 for Statements 168 6.3.2.6 switch Statements 169 6.3.2.7 Labeled Statements 169 6.4 Shadowing and Obscuring 169 6.4.1 Shadowing 172 6.4.2 Obscuring 175 6.5 Determining the Meaning of a Name 177 6.5.1 Syntactic Classification of a Name According to Context 178 6.5.2 Reclassification of Contextually Ambiguous Names 182 6.5.3 Meaning of Module Names and Package Names 184 6.5.3.1 Simple Package Names 184 6.5.3.2 Qualified Package Names 184 6.5.4 Meaning of PackageOrTypeNames 184 6.5.4.1 Simple PackageOrTypeNames 184 6.5.4.2 Qualified PackageOrTypeNames 185 6.5.5 Meaning of Type Names 185 6.5.5.1 Simple Type Names 185 6.5.5.2 Qualified Type Names 186 v The Java® Language Specification 6.5.6 Meaning of Expression Names 187 6.5.6.1 Simple Expression Names 187 6.5.6.2 Qualified Expression Names 191 6.5.7 Meaning of Method Names 193 6.5.7.1 Simple Method Names 193 6.6 Access Control 195 6.6.1 Determining Accessibility 196 6.6.2 Details on protected Access 200 6.6.2.1 Access to a protected Member 201 6.6.2.2 Access to a protected Constructor 201 6.7 Fully Qualified Names and Canonical Names 203 7 Packages and Modules 207 7.1 Package Members 208 7.2 Host Support for Modules and Packages 209 7.3 Compilation Units 212 7.4 Package Declarations 214 7.4.1 Named Packages 214 7.4.2 Unnamed Packages 215 7.4.3 Package Observability and Visibility 215 7.5 Import Declarations 216 7.5.1 Single-Type-Import Declarations 217 7.5.2 Type-Import-on-Demand Declarations 219 7.5.3 Single-Static-Import Declarations 220 7.5.4 Static-Import-on-Demand Declarations 221 7.6 Top Level Class and Interface Declarations 222 7.7 Module Declarations 225 7.7.1 Dependences 228 7.7.2 Exported and Opened Packages 230 7.7.3 Service Consumption 231 7.7.4 Service Provision 232 7.7.5 Unnamed Modules 233 7.7.6 Observability of a Module 233 8 Classes 235 8.1 Class Declarations 237 8.1.1 Class Modifiers 237 8.1.1.1 abstract Classes 238 8.1.1.2 final Classes 240 8.1.1.3 strictfp Classes 240 8.1.1.4 static Classes 240 8.1.2 Generic Classes and Type Parameters 241 8.1.3 Inner Classes and Enclosing Instances 243 8.1.4 Superclasses and Subclasses 248 8.1.5 Superinterfaces 250 8.1.6 Class Body and Member Declarations 254 8.2 Class Members 254 vi The Java® Language Specification 8.3 Field Declarations 259 8.3.1 Field Modifiers 264 8.3.1.1 static Fields 264 8.3.1.2 final Fields 267 8.3.1.3 transient Fields 268 8.3.1.4 volatile Fields 268 8.3.2 Field Initialization 269 8.3.3 Restrictions on Field References in Initializers 271 8.4 Method Declarations 274 8.4.1 Formal Parameters 276 8.4.2 Method Signature 279 8.4.3 Method Modifiers 280 8.4.3.1 abstract Methods 280 8.4.3.2 static Methods 282 8.4.3.3 final Methods 283 8.4.3.4 native Methods 284 8.4.3.5 strictfp Methods 284 8.4.3.6 synchronized Methods 284 8.4.4 Generic Methods 286 8.4.5 Method Result 286 8.4.6 Method Throws 287 8.4.7 Method Body 289 8.4.8 Inheritance, Overriding, and Hiding 289 8.4.8.1 Overriding (by Instance Methods) 291 8.4.8.2 Hiding (by Class Methods) 294 8.4.8.3 Requirements in Overriding and Hiding 295 8.4.8.4 Inheriting Methods with Override-Equivalent Signatures 299 8.4.9 Overloading 300 8.5 Member Class and Interface Declarations 303 8.6 Instance Initializers 305 8.7 Static Initializers 305 8.8 Constructor Declarations 306 8.8.1 Formal Parameters 307 8.8.2 Constructor Signature 308 8.8.3 Constructor Modifiers 308 8.8.4 Generic Constructors 309 8.8.5 Constructor Throws 309 8.8.6 The Type of a Constructor 309 8.8.7 Constructor Body 310 8.8.7.1 Explicit Constructor Invocations 311 8.8.8 Constructor Overloading 315 8.8.9 Default Constructor 315 8.8.10 Preventing Instantiation of a Class 317 8.9 Enum Classes 318 8.9.1 Enum Constants 319 8.9.2 Enum Body Declarations 320 8.9.3 Enum Members 322 vii The Java® Language Specification 8.10 Record Classes 326 8.10.1 Record Components 327 8.10.2 Record Body Declarations 329 8.10.3 Record Members 330 8.10.4 Record Constructor Declarations 334 8.10.4.1 Normal Canonical Constructors 335 8.10.4.2 Compact Canonical Constructors 336 9 Interfaces 339 9.1 Interface Declarations 340 9.1.1 Interface Modifiers 340 9.1.1.1 abstract Interfaces 341 9.1.1.2 strictfp Interfaces 341 9.1.1.3 static Interfaces 341 9.1.2 Generic Interfaces and Type Parameters 342 9.1.3 Superinterfaces and Subinterfaces 343 9.1.4 Interface Body and Member Declarations 344 9.2 Interface Members 344 9.3 Field (Constant) Declarations 345 9.3.1 Initialization of Fields in Interfaces 347 9.4 Method Declarations 348 9.4.1 Inheritance and Overriding 350 9.4.1.1 Overriding (by Instance Methods) 351 9.4.1.2 Requirements in Overriding 352 9.4.1.3 Inheriting Methods with Override-Equivalent Signatures 353 9.4.2 Overloading 354 9.4.3 Interface Method Body 354 9.5 Member Class and Interface Declarations 355 9.6 Annotation Interfaces 356 9.6.1 Annotation Interface Elements 357 9.6.2 Defaults for Annotation Interface Elements 361 9.6.3 Repeatable Annotation Interfaces 362 9.6.4 Predefined Annotation Interfaces 367 9.6.4.1 @Target 367 9.6.4.2 @Retention 368 9.6.4.3 @Inherited 369 9.6.4.4 @Override 369 9.6.4.5 @SuppressWarnings 371 9.6.4.6 @Deprecated 372 9.6.4.7 @SafeVarargs 374 9.6.4.8 @Repeatable 375 9.6.4.9 @FunctionalInterface 375 9.7 Annotations 375 9.7.1 Normal Annotations 376 9.7.2 Marker Annotations 379 9.7.3 Single-Element Annotations 379 viii The Java® Language Specification 9.7.4 Where Annotations May Appear 380 9.7.5 Multiple Annotations of the Same Interface 385 9.8 Functional Interfaces 386 9.9 Function Types 390 10 Arrays 395 10.1 Array Types 396 10.2 Array Variables 396 10.3 Array Creation 399 10.4 Array Access 399 10.5 Array Store Exception 400 10.6 Array