Chapter 8. Classes
A class declaration defines a new class and describes how it is implemented (§8.1).
A top level class (§7.6) is a class declared directly in a compilation unit.
A nested class is any class whose declaration occurs within the body of another class or interface declaration. A nested class may be a member class (§8.5, §9.5), a local class (§14.3), or an anonymous class (§15.9.5).
Some kinds of nested class are an inner class (§8.1.3), which is a class that can refer to enclosing class instances, local variables, and type variables.
An enum class (§8.9) is a class declared with abbreviated syntax that defines a small set of named class instances.
A record class (§8.10) is a class declared with abbreviated syntax that defines a simple aggregate of values.
This chapter discusses the common semantics of all classes. Details that are specific to particular kinds of classes are discussed in the sections dedicated to these constructs.
A class may be declared public (§8.1.1) so it can be referred to from code in any package of its module and potentially from code in other modules.
A class may be declared abstract (§8.1.1.1), and must be declared abstract if it is incompletely implemented; such a class cannot be instantiated, but can be extended by subclasses. The degree to which a class can be extended can be controlled explicitly (§8.1.1.2): it may be declared sealed to limit its subclasses, or it may be declared final to ensure no subclasses. Each class except Object is an extension of (that is, a subclass of) a single existing class (§8.1.4) and may implement interfaces (§8.1.5).
A class may be generic (§8.1.2), that is, its declaration may introduce type variables whose bindings differ among different instances of the class.
Class declarations may be decorated with annotations (§9.7) just like any other kind of declaration.
The body of a class declares members (fields, methods, classes, and interfaces), instance and static initializers, and constructors (§8.1.7). The scope (§6.3) of a member (§8.2) is the entire body of the declaration of the class to which the member belongs. Field, method, member class, member interface, and constructor declarations may include the access modifiers public , protected , or private (§6.6). The members of a class include both declared and inherited members (§8.2). Newly declared fields can hide fields declared in a superclass or superinterface. Newly declared member classes and member interfaces can hide member classes and member interfaces declared in a superclass or superinterface. Newly declared methods can hide, implement, or override methods declared in a superclass or superinterface.
Field declarations (§8.3) describe class variables, which are incarnated once, and instance variables, which are freshly incarnated for each instance of the class. A field may be declared final (§8.3.1.2), in which case it can be assigned to only once. Any field declaration may include an initializer.
Member class declarations (§8.5) describe nested classes that are members of the surrounding class. Member classes may be static , in which case they have no access to the instance variables of the surrounding class; or they may be inner classes.
Member interface declarations (§8.5) describe nested interfaces that are members of the surrounding class.
Method declarations (§8.4) describe code that may be invoked by method invocation expressions (§15.12). A class method is invoked relative to the class; an instance method is invoked with respect to some particular object that is an instance of a class. A method whose declaration does not indicate how it is implemented must be declared abstract . A method may be declared final (§8.4.3.3), in which case it cannot be hidden or overridden. A method may be implemented by platform-dependent native code (§8.4.3.4). A synchronized method (§8.4.3.6) automatically locks an object before executing its body and automatically unlocks the object on return, as if by use of a synchronized statement (§14.19), thus allowing its activities to be synchronized with those of other threads (§17 (Threads and Locks)).
Method names may be overloaded (§8.4.9).
Instance initializers (§8.6) are blocks of executable code that may be used to help initialize an instance when it is created (§15.9).
Static initializers (§8.7) are blocks of executable code that may be used to help initialize a class.
Constructors (§8.8) are similar to methods, but cannot be invoked directly by a method call; they are used to initialize new class instances. Like methods, they may be overloaded (§8.8.8).
Nested Classes
The Java programming language allows you to define a class within another class. Such a class is called a nested class and is illustrated here:
Terminology: Nested classes are divided into two categories: non-static and static. Non-static nested classes are called inner classes. Nested classes that are declared static are called static nested classes.
class OuterClass < . class InnerClass < . >static class StaticNestedClass < . >>
A nested class is a member of its enclosing class. Non-static nested classes (inner classes) have access to other members of the enclosing class, even if they are declared private. Static nested classes do not have access to other members of the enclosing class. As a member of the OuterClass , a nested class can be declared private , public , protected , or package private. (Recall that outer classes can only be declared public or package private.)
Why Use Nested Classes?
Compelling reasons for using nested classes include the following:
- It is a way of logically grouping classes that are only used in one place: If a class is useful to only one other class, then it is logical to embed it in that class and keep the two together. Nesting such «helper classes» makes their package more streamlined.
- It increases encapsulation: Consider two top-level classes, A and B, where B needs access to members of A that would otherwise be declared private . By hiding class B within class A, A’s members can be declared private and B can access them. In addition, B itself can be hidden from the outside world.
- It can lead to more readable and maintainable code: Nesting small classes within top-level classes places the code closer to where it is used.
Inner Classes
As with instance methods and variables, an inner class is associated with an instance of its enclosing class and has direct access to that object’s methods and fields. Also, because an inner class is associated with an instance, it cannot define any static members itself.
Objects that are instances of an inner class exist within an instance of the outer class. Consider the following classes:
An instance of InnerClass can exist only within an instance of OuterClass and has direct access to the methods and fields of its enclosing instance.
To instantiate an inner class, you must first instantiate the outer class. Then, create the inner object within the outer object with this syntax:
OuterClass outerObject = new OuterClass(); OuterClass.InnerClass innerObject = outerObject.new InnerClass();
There are two special kinds of inner classes: local classes and anonymous classes.
Static Nested Classes
As with class methods and variables, a static nested class is associated with its outer class. And like static class methods, a static nested class cannot refer directly to instance variables or methods defined in its enclosing class: it can use them only through an object reference. Inner Class and Nested Static Class Example demonstrates this.
Note: A static nested class interacts with the instance members of its outer class (and other classes) just like any other top-level class. In effect, a static nested class is behaviorally a top-level class that has been nested in another top-level class for packaging convenience. Inner Class and Nested Static Class Example also demonstrates this.
You instantiate a static nested class the same way as a top-level class:
StaticNestedClass staticNestedObject = new StaticNestedClass();
Inner Class and Nested Static Class Example
The following example, OuterClass , along with TopLevelClass , demonstrates which class members of OuterClass an inner class ( InnerClass ), a nested static class ( StaticNestedClass ), and a top-level class ( TopLevelClass ) can access:
OuterClass.java
public class OuterClass < String outerField = "Outer field"; static String staticOuterField = "Static outer field"; class InnerClass < void accessMembers() < System.out.println(outerField); System.out.println(staticOuterField); >> static class StaticNestedClass < void accessMembers(OuterClass outer) < // Compiler error: Cannot make a static reference to the non-static // field outerField // System.out.println(outerField); System.out.println(outer.outerField); System.out.println(staticOuterField); >> public static void main(String[] args) < System.out.println("Inner class:"); System.out.println("------------"); OuterClass outerObject = new OuterClass(); OuterClass.InnerClass innerObject = outerObject.new InnerClass(); innerObject.accessMembers(); System.out.println("\nStatic nested class:"); System.out.println("--------------------"); StaticNestedClass staticNestedObject = new StaticNestedClass(); staticNestedObject.accessMembers(outerObject); System.out.println("\nTop-level class:"); System.out.println("--------------------"); TopLevelClass topLevelObject = new TopLevelClass(); topLevelObject.accessMembers(outerObject); >> TopLevelClass.java
public class TopLevelClass < void accessMembers(OuterClass outer) < // Compiler error: Cannot make a static reference to the non-static // field OuterClass.outerField // System.out.println(OuterClass.outerField); System.out.println(outer.outerField); System.out.println(OuterClass.staticOuterField); >>
This example prints the following output:
Inner class: ------------ Outer field Static outer field Static nested class: -------------------- Outer field Static outer field Top-level class: -------------------- Outer field Static outer field
Note that a static nested class interacts with the instance members of its outer class just like any other top-level class. The static nested class StaticNestedClass can’t directly access outerField because it’s an instance variable of the enclosing class, OuterClass . The Java compiler generates an error at the highlighted statement:
static class StaticNestedClass < void accessMembers(OuterClass outer) < // Compiler error: Cannot make a static reference to the non-static // field outerField System.out.println(outerField); > >
To fix this error, access outerField through an object reference:
System.out.println(outer.outerField);
Similarly, the top-level class TopLevelClass can’t directly access outerField either.
Note: For more information about the taxonomy of the different kinds of classes in the Java programming language (which can be tricky to describe concisely, clearly, and correctly), see Joseph Darcy’s blog: Nested, Inner, Member, and Top-Level Classes.
Shadowing
If a declaration of a type (such as a member variable or a parameter name) in a particular scope (such as an inner class or a method definition) has the same name as another declaration in the enclosing scope, then the declaration shadows the declaration of the enclosing scope. You cannot refer to a shadowed declaration by its name alone. The following example, ShadowTest , demonstrates this:
public class ShadowTest < public int x = 0; class FirstLevel < public int x = 1; void methodInFirstLevel(int x) < System.out.println("x = " + x); System.out.println("this.x = " + this.x); System.out.println("ShadowTest.this.x = " + ShadowTest.this.x); >> public static void main(String. args) < ShadowTest st = new ShadowTest(); ShadowTest.FirstLevel fl = st.new FirstLevel(); fl.methodInFirstLevel(23); >> The following is the output of this example:
x = 23 this.x = 1 ShadowTest.this.x = 0
This example defines three variables named x : the member variable of the class ShadowTest , the member variable of the inner class FirstLevel , and the parameter in the method methodInFirstLevel . The variable x defined as a parameter of the method methodInFirstLevel shadows the variable of the inner class FirstLevel . Consequently, when you use the variable x in the method methodInFirstLevel , it refers to the method parameter. To refer to the member variable of the inner class FirstLevel , use the keyword this to represent the enclosing scope:
Serialization of inner classes, including local and anonymous classes, is strongly discouraged. When the Java compiler compiles certain constructs, such as inner classes, it creates synthetic constructs; these are classes, methods, fields, and other constructs that do not have a corresponding construct in the source code. Synthetic constructs enable Java compilers to implement new Java language features without changes to the JVM. However, synthetic constructs can vary among different Java compiler implementations, which means that .class files can vary among different implementations as well. Consequently, you may have compatibility issues if you serialize an inner class and then deserialize it with a different JRE implementation. See the section Implicit and Synthetic Parameters in the section Obtaining Names of Method Parameters for more information about the synthetic constructs generated when an inner class is compiled.