A nested class or interface that is declared as a static member of its enclosing class or interface acts just like any non-nested, or top-level, class or interface, except that its name and accessibility are defined by its enclosing type. The name of a nested type is expressed as EnclosingName.NestedName. The nested type is accessible only if the enclosing type is accessible.

Static nested types serve as a structuring and scoping mechanism for logically related types. However, static nested types are members of their enclosing type and as such can access all other members of the enclosing type including private ones—through an appropriate object reference of course. This gives the nested type a special, privileged relationship with the enclosing type.

Because static nested types are members of their enclosing type, the same accessibility rules apply to them as for other members. For classes this means that a static nested class or interface can have private, package, protected, or public access, while for interfaces, nested types are implicitly public.

public class BankAccount {
    private long number;    // account number
    private long balance;   // current balance (in cents)

    public static class Permissions {
        public boolean canDeposit,
                       canWithdraw,
                       canClose;
    }
    // ...
}

BankAccount.Permissions perm = acct.permissionsFor(owner);

Non-static nested classes are called inner classes. Non-static class members are associated with instances of a class—non-static fields are instance variables and non-static methods operate on an instance. Similarly, an inner class is also (usually) associated with an instance of a class, or more specifically an instance of an inner class is associated with an instance of its enclosing class—the enclosing instance or enclosing object.

You often need to closely tie a nested class object to a particular object of the enclosing class. Consider, for example, a method for the BankAccount class that lets you see the last action performed on the account, such as a deposit or withdrawal:

public class BankAccount {
    private long number;    // account number
    private long balance;   // current balance (in cents)
    private Action lastAct; // last action performed

    public class Action {
        private String act;
        private long amount;
        Action(String act, long amount) {
            this.act = act;
            this.amount = amount;
        }
        public String toString() {
            // identify our enclosing account
            return number + ": " + act + " " + amount;
        }
    }

    public void deposit(long amount) {
        balance += amount;
        lastAct = new Action("deposit", amount);
    }

    public void withdraw(long amount) {
        balance -= amount;
        lastAct = new Action("withdraw", amount);
    }
    // ...
}

The class Action records a single action on the account. It is not declared static, and that means its objects exist relative to an object of the enclosing class.

The relationship between an Action object and its BankAccount object is established when the Action object is created, as shown in the deposit and withdraw methods. When an inner class object is created, it must be associated with an object of its enclosing class. Usually, inner class objects are created inside instance methods of the enclosing class, as in deposit and withdraw. When that occurs the current object this is associated with the inner object by default. The creation code in deposit is the same as the more explicit

lastAct = this.new Action("deposit", amount);

Any BankAccount object could be substituted for this. For example, suppose we add a transfer operation that takes a specified amount from one account and places it in the current account—such an action needs to update the lastAct field of both account objects:

public void transfer(BankAccount other, long amount) {
    other.withdraw(amount);
    deposit(amount);
    lastAct = this.new Action("transfer", amount);
    other.lastAct = other.new Action("transfer", amount);
}

In this case we bind the second Action object to the otherBankAccount object and store it as the last action of the other account. Each BankAccount object should only refer to Action objects for which that BankAccount object is the enclosing instance. It would make no sense above, for example, to store the same Action object in both the current lastAct field and other.lastAct.

An inner class declaration is just like a top-level class declaration except for one restriction—inner classes cannot have static members (including static nested types), except for final static fields that are initialized to constants or expressions built up from constants. The rationale for allowing constants to be declared in an inner class is the same as that for allowing them in interfaces—it can be convenient to define constants within the type that uses them.

As with top-level classes, inner classes can extend any other class—including its enclosing class^[2] —implement any interface and be extended by any other class. An inner class can be declared final or abstract, and can have annotations applied to it.

Exercise 5.2: Create a version of BankAccount that records the last ten actions on the account. Add a history method that returns a History object that will return Action objects one at a time via a next method, returning null at the end of the list. Should History be a nested class? If so, should it be static or not?

return BankAccount.this.number + ": " + act + " " + amount;

class Outer {
    class Inner { }
}

class ExtendedOuter extends Outer {
    class ExtendedInner extends Inner { }
    Inner ref = new ExtendedInner();
}

class Unrelated extends Outer.Inner {
    Unrelated(Outer ref) {
        ref.super();
    }
}

Outer ref = new Outer();
Unrelated u = ref.new Unrelated(); // INVALID

class Host {
    int x;

    class Helper extends Unknown {
        void increment() { x++; }    // Not what you think!
    }
}

class Outer {
    void print() { }
    void print(int val) { }

    class Inner {
        void print() { }
        void show() {
            print();
            Outer.this.print();
            print(1);    // INVALID: no Inner.print(int)
        }
    }
}

You can define inner classes in code blocks, such as a method body, constructor, or initialization block. These local inner classes are not members of the class of which the code is a part but are local to that block, just as a local variable is. Such classes are completely inaccessible outside the block in which they are defined—there is simply no way to refer to them. But instances of such classes are normal objects that can be passed as arguments and returned from methods, and they exist until they are no longer referenced. Because local inner classes are inaccessible, they can't have access modifiers, nor can they be declared static because, well, they are local inner classes. All of the other class modifiers, including annotations, can be applied, though only strictfp and annotations have practical applications.

A local inner class can access all the variables that are in scope where the class is defined—local variables, method parameters, instance variables (assuming it is a non-static block), and static variables. The only restriction is that a local variable or method parameter can be accessed only if it is declared final. The reason for this restriction relates mainly to multithreading issues (see Chapter 14) and ensures that all such variables have well-defined values when accessed from the inner class. Given that the method accessing the local variable or parameter could be invoked after the completion of the method in which the local class was defined—and hence the local variables and parameters no longer exist—the value of those variables must be frozen before the local class object is created. If needed, you can copy a non-final variable into a final one that is subsequently accessed by the local inner class.

Consider the standard interface Iterator defined in the java.util package. This interface defines a way to iterate through a group of objects. It is commonly used to provide access to the elements in a container object but can be used for any general-purpose iteration:

package java.util;

public interface Iterator<E> {
    boolean hasNext();
    E next() throws NoSuchElementException;
    void remove() throws UnsupportedOperationException,
                         IllegalStateException;
}

The hasNext method returns true if next has more elements to return. The remove method removes from the collection the last element returned by next. But remove is optional, which means an implementation is allowed to throw UnsupportedOperationException. If remove is invoked before next, or is invoked multiple times after a single call to next, then IllegalStateException is thrown. NoSuchElementException—also part of the java.util package—is thrown if next is invoked when there are no more elements. See “Iteration” on page 571 for more details.

Here is a simple method that returns an Iterator to walk through an array of Object instances:

public static Iterator<Object>
    walkThrough(final Object[] objs) {

    class Iter implements Iterator<Object> {
        private int pos = 0;
        public boolean hasNext() {
            return (pos < objs.length);
        }
        public Object next() throws NoSuchElementException {
            if (pos >= objs.length)
                throw new NoSuchElementException();
            return objs[pos++];
        }
        public void remove() {
            throw new UnsupportedOperationException();
        }
    }
    return new Iter();
}

The Iter class is local to the walkThrough method; it is not a member of the enclosing class. Because Iter is local to the method, it has access to all the final variables of the method—in particular the parameter objs. It defines a pos field to keep track of where it is in the objs array. (This code assumes that Iterator and NoSuchElementException are imported from java.util in the source that contains walkThrough.)

Members of local inner classes can hide the local variables and parameters of the block they are declared in, just as they can hide instance fields and methods. The rules discussed on page 140 apply in all cases. The only difference is that once a local variable or parameter has been hidden it is impossible to refer to it.

When a local inner class seems too much for your needs, you can declare anonymous classes that extend a class or implement an interface. These classes are defined at the same time they are instantiated with new. For example, consider the walkThrough method. The class Iter is fairly lightweight and is not needed outside the method. The name Iter doesn't add much value to the code—what is important is that it is an Iterator object. The walkThrough method could use an anonymous inner class instead:

public static Iterator<Object>
    walkThrough(final Object[] objs) {

    return new Iterator<Object>() {
        private int pos = 0;
        public boolean hasNext() {
            return (pos < objs.length);
        }
        public Object next() throws NoSuchElementException {
            if (pos >= objs.length)
                throw new NoSuchElementException();
            return objs[pos++];
        }
        public void remove() {
            throw new UnsupportedOperationException();
        }
    };
}

Anonymous classes are defined in the new expression itself, as part of a statement. The type specified to new is the supertype of the anonymous class. Because Iterator is an interface, the anonymous class in walkThrough implicitly extends Object and implements Iterator. An anonymous class cannot have an explicit extends or implements clause, nor can it have any modifiers, including annotations.

Anonymous inner classes cannot have explicit constructors declared because they have no name to give the constructor. If an anonymous inner class is complex enough that it needs explicit constructors then it should probably be a local inner class. In practice, many anonymous inner classes need little or no initialization. In either case, an anonymous inner class can have initializers and initialization blocks that can access the values that would logically have been passed as a constructor argument. The only construction problem that remains is the need to invoke an explicit superclass constructor. To solve this problem the new expression is written as if a superclass instance were being constructed, and that constructor is invoked as the superclass constructor. For example, the following anonymous subclass of Attr (see page 76) invokes the single-argument Attr constructor and overrides setValue to print out the new value each time it is changed:

Attr name = new Attr("Name") {
    public Object setValue(Object nv) {
        System.out.println("Name set to " + nv);
        return super.setValue(nv);
    }
};

In the Iterator example we invoked the no-arg superclass constructor for Object—the only constructor that can ever be used when an anonymous inner class has an interface type.

Anonymous classes are simple and direct but can easily become very hard to read. The further they nest, the harder they are to understand. The nesting of the anonymous class code that will execute in the future inside the method code that is executing now adds to the potential for confusion. You should probably avoid anonymous classes that are longer than about six lines, and you should use them in only the simplest of expressions. We stretch this rule in the walkThrough example because the sole purpose of the method is to return that object, but when a method does more, anonymous classes must be kept quite small or the code becomes illegible. When anonymous classes are used properly, they are a good tool for keeping simple classes simple. When misused, they create impenetrable inscrutability.

Nested types, whether static classes, interfaces, or inner classes, are inherited the same way that fields are inherited. A declaration of a nested type with the same name as that of an inherited nested type hides the definition of the inherited type. The actual type referred to is determined by the type of the reference used. Within a given class, the actual nested type referred to is the one defined in the current class or inherited in the current class.

Consider a framework that models devices that can be connected by different ports. The class Device is an abstract class that captures some common behavior of all devices. A port also has some common generic behavior so it is also modeled as an abstract class and, because ports exist only within devices, the Port class is made an inner class of Device. A concrete device class defines the state for the device and the concrete inner port classes for that device. During construction of a concrete device class, references to the concrete ports of that class are initialized:

abstract class Device {
    abstract class Port {
        // ...
    }
    // ...
}
class Printer extends Device {
    class SerialPort extends Port {
        // ...
    }
    Port serial = new SerialPort();
}

A concrete device can itself be extended, as can the concrete inner port classes, to specialize their behavior.

class HighSpeedPrinter extends Printer {
    class SerialPort extends Printer.SerialPort {
        // ...
    }
}

The intent is that the class HighSpeedPrinter.SerialPort overrides the class Printer.SerialPort so that serial is set to refer to the correct type of object. But the class Printer is not affected by the new subclass of SerialPort defined inside HighSpeedPrinter, even though the new subclass seems to have the same name.

One solution to this design problem is to abstract construction of the inner class objects into a factory method which can then be overridden in a subclass to construct the right kind of inner class. For example:

class Printer extends Device {
    class SerialPort extends Port {
        // ...
    }
    Port serial = createSerialPort();
    protected Port createSerialPort() {
        return new SerialPort();
    }
}

The HighSpeedPrinter class now defines its specialized inner class and overrides the factory method to construct an instance of that class. Now that we realize that nested type definitions hide and don't override, we aren't tempted to use the same name for the inner class, for we know that hiding is usually a bad thing.

class HighSpeedPrinter extends Printer {
    class EnhancedSerialPort extends SerialPort {
        // ...
    }
    protected Port createSerialPort() {
        return new EnhancedSerialPort();
    }
}

Now when a HighSpeedPrinter is constructed and the initializers in Printer execute, we invoke the overriding createSerialPort method that returns an instance of EnhancedSerialPort.

This is one example of a situation in which a method of the subclass is invoked before the subclass object has been fully constructed and so care must be taken to ensure that things work correctly. For example, if EnhancedSerialPort initializes a field using a field from the enclosing HighSpeedPrinter instance, then at the time the EnhancedSerialPort object is constructed, the fields of the enclosing object will have the default “zero” values for their type.

An alternative design would have the constructor for HighSpeedPrinter simply reassign serial to refer to an EnhancedSerialPort object. However, that approach causes the unnecessary construction of the original SerialPort object, and that construction may be non-trivial and undesirable—in this example it may involve configuring hardware.

You declare nested classes and interfaces in an interface for the same reason that you declare nested classes and interfaces in a class: nested classes and interfaces allow you to associate types that are strongly related to an interface inside that interface. For example, a class that was used only to return multiple values from an interface's method could be represented as a nested class in that interface:

interface Changeable {
    class Record {
        public Object changer;
        public String changeDesc;
    }

    Record getLastChange();
    // ...
}

The method getLastChange returns a Changeable.Record object that contains the object that made the change and a string describing the change. This class has meaning relative only to the Changeable interface, so making a top-level class not only is unnecessary but would also separate it from the context of its use. As a nested class it is tightly bound to its origin and context, but it is a normal class in every other regard.

Another use for a nested class within an interface is to define a (partial or complete) default implementation for that interface. A class that implements the interface could then choose to extend the default implementation class or to forward method invocations to an instance of that class.

Any class or interface nested inside an interface is public and static.

interface SharedData {
    class Data {
        private int x = 0;
        public int getX() { return x; }
        public void setX(int newX) { x = newX; }
    }
    Data data = new Data();
}

How the compiler and runtime system deal with nested types would ideally be transparent to the programmer. Unfortunately, this is not quite the case. Nested types were added as a language extension, and that extension had to maintain compatibility with older Java virtual machines. Consequently, nested types are implemented in terms of a source code transformation that the compiler applies.

As a programmer, the only thing you should need to know about this process is the naming conventions that are used. Consider a static, or non-local, nested type defined as Outer.Inner. This is the source name for the class. At the virtual machine level the class is renamed as Outer$Inner—in essence, dots in a nested name are converted to dollar signs. For local inner classes, the transformation is less specific because these classes are inaccessible, hence their name is less important—such classes are named Outer$NInner, where Inner is the name of the local class and N is a sequence of one or more digits. For anonymous inner classes the names have the form Outer$N, where N is a sequence of one or more digits.

These issues have to be dealt with in two main cases. First, when bundling the class files for your applications you have to recognize all the strange files with $ in their name. Second, if you use the reflection mechanism discussed in Chapter 16 to create nested class instances, you'll need to know the transformed name. But in most programming the transformed name is something you can blissfully ignore.