Static Member Classes

A static member class is astatic member of an enclosing class. Although enclosed, it doesn’t have an enclosing instance of that class and cannot access the enclosing class’s instance fields and invoke its instance methods. However, it can access the enclosing class’s static fields and invoke its static methods, even those members that are declared private. Listing 5-1 presents a static member class declaration.

Listing 5-1. Declaring a Static Member Class

class EnclosingClass
{
   private static int i;
 
   private static void m1()
   {
      System.out.println(i);
   }
 
   static void m2()
   {
      EnclosedClass.accessEnclosingClass();
   }
 
   static class EnclosedClass
   {
      static void accessEnclosingClass()
      {
         i = 1;
         m1();
      }
 
      void accessEnclosingClass2()
      {
         m2();
      }
   }
}

Listing 5-1 declares a top-level class named EnclosingClass with class field i, class methods m1() and m2(), and static member class EnclosedClass. Also, EnclosedClass declares class method accessEnclosingClass() and instance method accessEnclosingClass2().

Because accessEnclosingClass() is declared static, m2() must be prefixed with EnclosedClass and the member access operator to call this method.

Listing 5-2 presents the source code to an application class that demonstrates how to invoke EnclosedClass’s accessEnclosingClass() class method and instantiate EnclosedClass and invoke its accessEnclosingClass2() instance method.

Listing 5-2. Invoking a Static Member Class’s Class and Instance Methods

public class SMCDemo
{
   public static void main(String[] args)
   {
      EnclosingClass.EnclosedClass.accessEnclosingClass(); // Output: 1
      EnclosingClass.EnclosedClass ec = new EnclosingClass.EnclosedClass();
      ec.accessEnclosingClass2(); // Output: 1
   }
}

Listing 5-2’s main() method reveals that you must prefix the name of an enclosed class with the name of its enclosing class to invoke a class method, for example, EnclosingClass.EnclosedClass.accessEnclosingClass();.

This listing also reveals that you must prefix the name of the enclosed class with the name of its enclosing class when instantiating the enclosed class, for example, EnclosingClass.EnclosedClass ec = new EnclosingClass.EnclosedClass();. You can then invoke the instance method in the normal manner, for example, ec.accessEnclosingClass2();.

Static member classes have their uses. For example, Listing 5-3’s Double and Float static member classes provide different implementations of their enclosing Rectangle class. The Float version occupies less memory because of its 32-bit float fields, and the Double version provides greater accuracy because of its 64-bit double fields.

Listing 5-3. Using Static Member Classes to Declare Multiple Implementations of Their Enclosing Class

abstract class Rectangle
{
   abstract double getX();
   abstract double getY();
   abstract double getWidth();
   abstract double getHeight();
 
   static class Double extends Rectangle
   {
      private double x, y, width, height;
 
      Double(double x, double y, double width, double height)
      {
         this.x = x;
         this.y = y;
         this.width = width;
         this.height = height;
      }
 
      double getX() { return x; }
      double getY() { return y; }
      double getWidth() { return width; }
      double getHeight() { return height; }
   }
 
   static class Float extends Rectangle
   {
      private float x, y, width, height;
 
      Float(float x, float y, float width, float height)
      {
         this.x = x;
         this.y = y;
         this.width = width;
         this.height = height;
      }
 
      double getX() { return x; }
      double getY() { return y; }
      double getWidth() { return width; }
      double getHeight() { return height; }
   }
 
   // Prevent subclassing. Use the type-specific Double and Float
   // implementation subclass classes to instantiate.
   private Rectangle() {}
 
   boolean contains(double x, double y)
   {
      return (x >= getX() && x < getX() + getWidth()) &&
             (y >= getY() && y < getY() + getHeight());
   }
}

Listing 5-3’s Rectangle class demonstrates nested subclasses. Each of the Double and Float static member classes subclass the abstract Rectangle class, providing private floating-point or double precision floating-point fields and overriding Rectangle’s abstract methods to return these fields’ values as doubles.

Rectangle is abstract because it makes no sense to instantiate this class. Because it also makes no sense to directly extend Rectangle with new implementations (the Double and Float nested subclasses should be sufficient), its default constructor is declared private. Instead, you must instantiate Rectangle.Float (to save memory) or Rectangle.Double (when accuracy is required), as demonstrated by Listing 5-4.

Listing 5-4. Creating and Using Different Rectangle Implementations

public class SMCDemo
{
   public static void main(String[] args)
   {
      Rectangle r = new Rectangle.Double(10.0, 10.0, 20.0, 30.0);
      System.out.println("x = " + r.getX());
      System.out.println("y = " + r.getY());
      System.out.println("width = " + r.getWidth());
      System.out.println("height = " + r.getHeight());
      System.out.println("contains(15.0, 15.0) = " + r.contains(15.0, 15.0));
      System.out.println("contains(0.0, 0.0) = " + r.contains(0.0, 0.0));
      System.out.println();
      r = new Rectangle.Float(10.0f, 10.0f, 20.0f, 30.0f);
      System.out.println("x = " + r.getX());
      System.out.println("y = " + r.getY());
      System.out.println("width = " + r.getWidth());
      System.out.println("height = " + r.getHeight());
      System.out.println("contains(15.0, 15.0) = " + r.contains(15.0, 15.0));
      System.out.println("contains(0.0, 0.0) = " + r.contains(0.0, 0.0));
   }
}

Listing 5-4 first instantiates Rectangle’s Double subclass via new Rectangle.Double(10.0, 10.0, 20.0, 30.0) and then invokes its various methods. Continuing, Listing 5-4 instantiates Rectangle’s Float subclass via new Rectangle.Float(10.0f, 10.0f, 20.0f, 30.0f) before invoking Rectangle methods on this instance.

Compile both listings (javac SMCDemo.java or javac *.java) and run the application (java SMCDemo). You will then observe the following output:

x = 10.0
y = 10.0
width = 20.0
height = 30.0
contains(15.0, 15.0) = true
contains(0.0, 0.0) = false
 
x = 10.0
y = 10.0
width = 20.0
height = 30.0
contains(15.0, 15.0) = true
contains(0.0, 0.0) = false

Java’s class library contains many static member classes. For example, the java.lang.Character class encloses a static member class named Subset whose instances represent subsets of the Unicode character set. Additional examples include java.util.AbstractMap.SimpleEntry and java.io.ObjectInputStream.GetField.

Nonstatic Member Classes

A nonstatic member class is a non-static member of an enclosing class. Each instance of the nonstatic member class implicitly associates with an instance of the enclosing class. The nonstatic member class’s instance methods can call instance methods in the enclosing class and access the enclosing class instance’s nonstatic fields. Listing 5-5 presents a nonstatic member class declaration.

Listing 5-5. Declaring a Nonstatic Member Class

class EnclosingClass
{
   private int i;
 
   private void m()
   {
      System.out.println(i);
   }
 
   class EnclosedClass
   {
      void accessEnclosingClass()
      {
         i = 1;
         m();
      }
   }
}

Listing 5-5 declares a top-level class named EnclosingClass with instance field i, instance method m1(), and nonstatic member class EnclosedClass. Furthermore, EnclosedClass declares instance method accessEnclosingClass().

Because accessEnclosingClass() is nonstatic, EnclosedClass must be instantiated before this method can be called. This instantiation must take place via an instance of EnclosingClass. Listing 5-6 accomplishes these tasks.

Listing 5-6. Calling a Nonstatic Member Class’s Instance Method

public class NSMCDemo
{
   public static void main(String[] args)
   {
      EnclosingClass ec = new EnclosingClass();
      ec.new EnclosedClass().accessEnclosingClass(); // Output: 1
   }
}

Listing 5-6’s main() method first instantiates EnclosingClass and saves its reference in local variable ec. Then, main() uses this reference as a prefix to the new operator to instantiate EnclosedClass, whose reference is then used to call accessEnclosingClass(), which outputs 1.

Suppose you need to maintain a to-do list of items, where each item consists of a name and a description. After some thought, you create Listing 5-7’s ToDo class to implement these items.

Listing 5-7. Implementing To-Do Items as Name-Description Pairs

class ToDo
{
   private String name;
   private String desc;
 
   ToDo(String name, String desc)
   {
      this.name = name;
      this.desc = desc;
   }
 
   String getName()
   {
      return name;
   }
 
   String getDesc()
   {
      return desc;
   }
 
   @Override
   public String toString()
   {
      return "Name = " + getName() + ", Desc = " + getDesc();
   }
}

You next create a ToDoList class to store ToDo instances. ToDoList uses its ToDoArray nonstatic member class to store ToDo instances in a growable array; you don’t know how many instances will be stored, and Java arrays have fixed lengths. See Listing 5-8.

Listing 5-8. Storing a Maximum of Two ToDo Instances in a ToDoArray Instance

class ToDoList
{
   private ToDoArray toDoArray;
   private int index = 0;
 
   ToDoList()
   {
      toDoArray = new ToDoArray(2);
   }
 
   boolean hasMoreElements()
   {
      return index < toDoArray.size();
   }
 
   ToDo nextElement()
   {
      return toDoArray.get(index++);
   }
 
   void add(ToDo item)
   {
      toDoArray.add(item);
   }
 
   private class ToDoArray
   {
      private ToDo[] toDoArray;
      private int index = 0;
 
      ToDoArray(int initSize)
      {
         toDoArray = new ToDo[initSize];
      }
 
      void add(ToDo item)
      {
         if (index >= toDoArray.length)
         {
            ToDo[] temp = new ToDo[toDoArray.length*2];
            for (int i = 0; i < toDoArray.length; i++)
               temp[i] = toDoArray[i];
            toDoArray = temp;
         }
         toDoArray[index++] = item;
      }
 
      ToDo get(int i)
      {
         return toDoArray[i];
      }
 
      int size()
      {
         return index;
      }
   }
}

As well as providing an add() method to store ToDo instances in the ToDoArray instance, ToDoList provides hasMoreElements() and nextElement() methods to iterate over and return the stored instances. Listing 5-9 demonstrates these methods.

Listing 5-9. Creating and Iterating Over a ToDoList of ToDo Instances

public class NSMCDemo
{
   public static void main(String[] args)
   {
      ToDoList toDoList = new ToDoList();
      toDoList.add(new ToDo("#1", "Do laundry."));
      toDoList.add(new ToDo("#2", "Buy groceries."));
      toDoList.add(new ToDo("#3", "Vacuum apartment."));
      toDoList.add(new ToDo("#4", "Write report."));
      toDoList.add(new ToDo("#5", "Wash car."));
      while (toDoList.hasMoreElements())
         System.out.println(toDoList.nextElement());
   }
}

Compile all three listings (javac NSMCDemo.java or javac *.java) and run the application (java NSMCDemo). You will then observe the following output:

Name = #1, Desc = Do laundry.
Name = #2, Desc = Buy groceries.
Name = #3, Desc = Vacuum apartment.
Name = #4, Desc = Write report.
Name = #5, Desc = Wash car.

Java’s class library presents many examples of nonstatic member classes. For example, the java.util package’s HashMap class declares private HashIterator, ValueIterator, KeyIterator, and EntryIterator classes for iterating over a hashmap’s values, keys, and entries. (I will discuss HashMap in Chapter 9.)

Anonymous Classes

An anonymous class is a class without a name. Furthermore, it is not a member of its enclosing class. Instead, an anonymous class is simultaneously declared (as an anonymous extension of a class or as an anonymous implementation of an interface) and instantiated any place where it is legal to specify an expression. Listing 5-10 demonstrates an anonymous class declaration and instantiation.

Listing 5-10. Declaring and Instantiating an Anonymous Class That Extends a Class

abstract class Speaker
{
   abstract void speak();
}
 
public class ACDemo
{
   public static void main(final String[] args)
   {
      new Speaker()
      {
         String msg = (args.length == 1) ? args[0] : "nothing to say";
  
        @Override
         void speak()
         {
            System.out.println(msg);
         }
      }
      .speak();
   }
}

Listing 5-10 introduces an abstract class named Speaker and a concrete class named ACDemo. The latter class’s main() method declares an anonymous class that extends Speaker and overrides its speak() method. When this method is called, it outputs main()’s first command-line argument or a default message when there are no arguments.

An anonymous class doesn’t have a constructor (because the anonymous class doesn’t have a name). However, its classfile does contain an <init>() method that performs instance initialization. This method calls the superclass’s noargument constructor (prior to any other initialization), which is the reason for specifying Speaker() after new.

Anonymous class instances should be able to access the surrounding scope’s local variables and parameters. However, an instance might outlive the method in which it was conceived (as a result of storing the instance’s reference in a field), and try to access local variables and parameters that no longer exist after the method returns.

Because Java cannot allow this illegal access, which would most likely crash the virtual machine, it lets an anonymous class instance only access local variables and parameters that are declared final (see Listing 5-10). On encountering a final local variable/parameter name in an anonymous class instance, the compiler does one of two things:

• If the variable’s type is primitive (int or double, for example), the compiler replaces its name with the variable’s read-only value.
• If the variable’s type is reference (String, for example), the compiler introduces, into the classfile, a synthetic variable (a manufactured variable) and code that stores the local variable’s/parameter’s reference in the synthetic variable.

Listing 5-11 demonstrates an alternative anonymous class declaration and instantiation.

Listing 5-11. Declaring and Instantiating an Anonymous Class That Implements an Interface

interface Speakable
{
   void speak();
}
 
public class ACDemo
{
   public static void main(final String[] args)
   {
      new Speakable()
      {
         String msg = (args.length == 1) ? args[0] : "nothing to say";
 
         @Override
         public void speak()
         {
            System.out.println(msg);
         }
      }
      .speak();
   }
}

Listing 5-11 is very similar to Listing 5-10. However, instead of subclassing a Speaker class, this listing’s anonymous class implements an interface named Speakable. Apart from the <init>() method calling java.lang.Object() (interfaces have no constructors), Listing 5-11 behaves like Listing 5-10.

Although an anonymous class doesn’t have a constructor, you can provide an instance initializer to handle complex initialization. For example, new Office() {{addEmployee(new Employee("John Doe"));}}; instantiates an anonymous subclass of Office and adds one Employee object to this instance by calling Office’s addEmployee() method.

You will often find yourself creating and instantiating anonymous classes for their convenience. For example, suppose you need to return a list of all filenames having the .java suffix. The following example shows you how an anonymous class simplifies using the java.io package’s File and FilenameFilter classes to achieve this objective:

String[] list = new File(directory).list(new FilenameFilter()
                {
                   @Override
                   public boolean accept(File f, String s)
                   {
                      return s.endsWith(".java");
                   }
                });

However, keep in mind that there is a downside to using anonymous classes. Because they are anonymous, you cannot reuse anonymous classes in other parts of your applications.

Local Classes

A local class is a class that is declared anywhere that a local variable is declared. Furthermore, it has the same scope as a local variable. Unlike an anonymous class, a local class has a name and can be reused. Like anonymous classes, local classes only have enclosing instances when used in nonstatic contexts.

A local class instance can access the surrounding scope’s local variables and parameters. However, the local variables and parameters that are accessed must be declared final. For example, Listing 5-12’s local class declaration accesses a final parameter and a final local variable.

Listing 5-12. Declaring a Local Class

class EnclosingClass
{
   void m(final int x)
   {
      final int y = x * 2;
      class LocalClass
      {
         int a = x;
         int b = y;
      }
      LocalClass lc = new LocalClass();
      System.out.println(lc.a);
      System.out.println(lc.b);
   }
}

Listing 5-12 declares EnclosingClass with its instance method m() declaring a local class named LocalClass. This local class declares a pair of instance fields (a and b) that are initialized to the values of final parameter x and final local variable y when LocalClass is instantiated: new EnclosingClass().m(10);, for example. Listing 5-13 demonstrates this local class.

Listing 5-13. Demonstrating a Local Class

public class LCDemo
{
   public static void main(String[] args)
   {
      EnclosingClass ec = new EnclosingClass();
      ec.m(10);
   }
}

After instantiating EnclosingClass, Listing 5-13’s main() method invokes m(10). The called m() method multiplies this argument by 2, instantiates LocalClass, whose <init>() method assigns the argument and the doubled value to its pair of instance fields (in lieu of using a constructor to perform this task); and outputs the LocalClass instance fields. The following output results:

10
20

Local classes help improve code clarity because they can be moved closer to where they are needed. For example, Listing 5-14 declares an Iterator interface and a ToDoList class whose iterator() method returns an instance of its local Iter class as an Iterator instance (because Iter implements Iterator).

Listing 5-14. The Iterator Interface and the ToDoList Class

interface Iterator
{
   boolean hasMoreElements();
   Object nextElement();
}
 
class ToDoList
{
   private ToDo[] toDoList;
   private int index = 0;
 
   ToDoList(int size)
   {
      toDoList = new ToDo[size];
   }
 
   Iterator iterator()
   {
      class Iter implements Iterator
      {
         int index = 0;
 
         @Override
         public boolean hasMoreElements()
         {
            return index < toDoList.length;
         }
 
         @Override
         public Object nextElement()
         {
            return toDoList[index++];
         }
      }
      return new Iter();
   }
 
   void add(ToDo item)
   {
      toDoList[index++] = item;
   }
}

Listing 5-15 demonstrates Iterator, the refactored ToDoList class, and Listing 5-7’s ToDo class.

Listing 5-15. Creating and Iterating Over a ToDoList of ToDo Instances with a Reusable Iterator

public class LCDemo
{
   public static void main(String[] args)
   {
      ToDoList toDoList = new ToDoList(5);
      toDoList.add(new ToDo("#1", "Do laundry."));
      toDoList.add(new ToDo("#2", "Buy groceries."));
      toDoList.add(new ToDo("#3", "Vacuum apartment."));
      toDoList.add(new ToDo("#4", "Write report."));
      toDoList.add(new ToDo("#5", "Wash car."));
      Iterator iter = toDoList.iterator();
      while (iter.hasMoreElements())
         System.out.println(iter.nextElement());
   }
}

The Iterator instance that is returned from iterator() returns ToDo items in the same order as when they were added to the list. Although you can only use the returned Iterator object once, you can call iterator() whenever you need a new Iterator object. This capability is a big improvement over the one-shot iterator presented in Listing 5-9.

Inner Classes and Memory Leaks

Instances of inner classes contain implicit references to their outer classes. Prolonging the existence of an inner class instance (such as storing its reference in a static variable) can result in a memory leak in which the outer instance may be referencing a large graph of objects that cannot be garbage collected because of the prolonged inner class reference. Consider Listing 5-16’s example.

Listing 5-16. Demonstrating a Memory Leak in the Context of a Local Class

public class InnerLeakDemo
{
   public static void main(String[] args)
   {
      class Outer
      {
         String s = "outer string";
 
         class Inner
         {
            String s = "inner string";
 
            void print()
            {
               System.out.println(s);
               System.out.println(Outer.this.s);
            }
         }
      }
      Outer o = new Outer();
      Outer.Inner oi = o.new Inner();
      oi.print();
   }
}

Listing 5-16’s main() method declares a local class named Outer, which declares a nonstatic member class named Inner. Each of Outer and Inner declares a String instance field named s, and Inner also declares a print() method.

After declaring Outer, main() instantiates this local class and then instantiates its nested Inner member. Finally, it invokes Inner’s print() method.

Compile Listing 5-16 (javac InnerLeakDemo.java) and run this application (java InnerLeakDemo). You should observe the following output:

inner string
outer string

This output reveals that Outer’s s field is present for as long as the reference to its Inner class exists. This is an example of a memory leak.

Although this example is trivial, you’ll find it more profoundly demonstrated in an Android context, in which the inner class can outlive its activity outer class and delay the activity from being garbage collected and its resources released. To learn more about this problem, check out Alex Lockwood’s “How to Leak a Context: Handlers & Inner Classes” blog post (www.androiddesignpatterns.com/2013/01/inner-class-handler-memory-leak.html).

Interfaces within Classes and Classes within Interfaces

Interfaces can be nested within classes. Once declared, an interface is considered to be static even when it is not declared static. For example, Listing 5-17 declares an enclosing class named X along with two nested static interfaces named A and B.

Listing 5-17. Declaring a Pair of Interfaces Within a Class

class X
{
   interface A
   {
   }
 
   static interface B
   {
   }
}

You would access Listing 5-17’s interfaces in the same way. For example, you would specify class C implements X.A {} or class D implements X.B {}.

As with nested classes, nested interfaces help to implement top-level class architecture by being implemented by nested classes. Collectively, these types are nested because they cannot (as in Listing 5-14’s Iter local class) or need not appear at the same level as a top-level class and pollute its package namespace. The java.util.Map.Entry interface and HashMap class is a good example.

Classes can be nested within interfaces. Once declared, a class is considered to be static even when it is not declared static. Although nowhere near as common as nesting an interface within a class, nested classes have a potential use, which Listing 5-18 demonstrates.

Listing 5-18. Tightly Binding a Class to an Interface

public interface Addressable
{
   class Address
   {
      private String boxNumber;
      private String street;
      private String city;
 
      public Address(String boxNumber, String street, String city)
      {
         this.boxNumber = boxNumber;
         this.street = street;
         this.city = city;
      }
 
      public String getBoxNumber()
      {
         return boxNumber;
      }
 
      public String getStreet()
      {
         return street;
      }
 
      public String getCity()
      {
         return city;
      }
 
      @Override
      public String toString()
      {
         return boxNumber+" - "+street+" - "+city;
      }
   }
 
   Address getAddress();
}

Listing 5-18 declares an Addressable interface that describes any entity associated with an address, such as a letter, parcel, or postcard. This interface declares an Address class to store the address components, and an Address getAddress() method that returns the address.

Assuming the existence of Letter, Parcel, and Postcard classes whose constructors take Address arguments, the following code fragment shows you how you could construct an array of addressables and then iterate over it, obtaining and printing each address:

Addressable[] addressables =
{
   new Letter(new Addressable.Address("10", "AnyStreet", "AnyTown")),
   new Parcel(new Addressable.Address("20", "Doe Street", "NewTown")),
   new Postcard(new Addressable.Address("30", "Ender Avenue", "AnyCity"))
};
 
for (int i = 0; i < addressables.length; i++)
   System.out.println(addressables[i].getAddress());

Notice that you must specify Addressable.Address to access the nested Address class. (You can use the static imports feature discussed in Chapter 6 to save yourself from typing the Addressable. prefix.)

Why nest Address instead of making it a separate top-level class? The idea here is that there exists a tight relationship between Addressable and Address, and you want to capture this relationship. Also, you might have a different top-level Address class and want to prevent a name conflict.

Nesting a class in an interface is considered by many to be a bad practice, because it goes against the ideas of object-oriented programming and the notion of an interface. However, you should be aware of this capability because you may encounter it in practice.

What Are Packages?

A package is a unique namespace that can contain a combination of top-level classes, other top-level types, and subpackages. Only types that are declared public can be accessed from outside the package. Furthermore, the constants, constructors, methods, and nested types that describe a class’s interface must be declared public to be accessible from beyond the package.

Every package has a name, which must be a nonreserved identifier. The member access operator separates a package name from a subpackage name and separates a package or subpackage name from a type name. For example, the two member access operators in graphics.shapes.Circle separate package name graphics from the shapes subpackage name and separate subpackage name shapes from the Circle type name.

The Package Statement

The package statement identifies the package in which a source file’s types are located. This statement consists of reserved word package, followed by a member access operator-separated list of package and subpackage names, followed by a semicolon.

For example, package graphics; specifies that the source file’s types locate in a package named graphics, and package graphics.shapes; specifies that the source file’s types locate in the graphics package’s shapes subpackage.

By convention, a package name is expressed in lowercase. When the name consists of multiple words, each word except for the first word is capitalized.

Only one package statement can appear in a source file. When it is present, nothing apart from comments must precede this statement.

Java implementations map package and subpackage names to same-named directories. For example, an implementation would map graphics to a directory named graphics and would map graphics.shapes to a shapes subdirectory of graphics. The Java compiler stores the classfiles that implement the package’s types in the corresponding directory.

The Import Statement

Imagine having to repeatedly specify ca.tutortutor.graphics.shapes.Circle or some other lengthy package-qualified type name for each occurrence of that type in source code. Java provides an alternative that lets you avoid having to specify package details. This alternative is the import statement.

The import statement imports types from a package by telling the compiler where to look for unqualified type names during compilation. This statement consists of reserved word import, followed by a member access operator-separated list of package and subpackage names, followed by a type name or * (asterisk), followed by a semicolon.

The * symbol is a wildcard that represents all unqualified type names. It tells the compiler to look for such names in the import statement’s specified package, unless the type name is found in a previously searched package. (Using the wildcard doesn’t have a performance penalty or lead to code bloat but can lead to name conflicts, as you will see.)

For example, import ca.tutortutor.graphics.shapes.Circle; tells the compiler that an unqualified Circle class exists in the ca.tutortutor.graphics.shapes package. Similarly, import ca.tutortutor.graphics.shapes.*; tells the compiler to look in this package when it encounters a Circle class, a Rectangle class, or even an Employee class (if Employee hasn’t already been found).

Because Java is case sensitive, package and subpackage names specified in an import statement must be expressed in the same case as that used in the package statement.

When import statements are present in source code, only a package statement and comments can precede them.

You can run into name conflicts when using the wildcard version of the import statement because any unqualified type name matches the wildcard. For example, you have graphics.shapes and geometry packages that each contain a Circle class, the source code begins with import geometry.*; and import graphics.shape.*; statements, and it also contains an unqualified occurrence of Circle. Because the compiler doesn’t know if Circle refers to geometry’s Circle class or graphics.shape’s Circle class, it reports an error. You can fix this problem by qualifying Circle with the correct package name.

Searching for Packages and Types

Newcomers to Java who first start to work with packages often become frustrated by “no class definition found” and other errors. This frustration can be partly avoided by understanding how the virtual machine searches for packages and types.

This section explains how the search process works. To understand this process, you need to realize that the compiler is a special Java application that runs under the control of the virtual machine. Furthermore, there are two different forms of search.

Playing with Packages

Suppose your application needs to log messages to the console, to a file, or to another destination. It can accomplish this task with the help of a logging library. My implementation of this library consists of an interface named Logger, an abstract class named LoggerFactory, and a pair of package-private classes named Console and File.

Listing 5-19 presents the Logger interface, which describes objects that log messages.

Listing 5-19. Describing Objects That Log Messages via the Logger Interface

package logging;
 
public interface Logger
{
   boolean connect();
   boolean disconnect();
   boolean log(String msg);
}

Each of the connect(), disconnect(), and log() methods returns true upon success and false upon failure. (Later in this chapter, you will discover a better technique for dealing with failure.) These methods are not declared public explicitly because an interface’s methods are implicitly public.

Listing 5-20 presents the LoggerFactory abstract class.

Listing 5-20. Obtaining a Logger for Logging Messages to a Specific Destination

package logging;
 
public abstract class LoggerFactory
{
   public final static int CONSOLE = 0;
   public final static int FILE = 1;
 
   public static Logger newLogger(int dstType, String... dstName)
   {
      switch (dstType)
      {
         case CONSOLE: return new Console(dstName.length == 0 ? null
                                                              : dstName[0]);
         case FILE   : return new File(dstName.length == 0 ? null
                                                           : dstName[0]);
         default     : return null;
      }
   }
}

newLogger() returns a Logger object for logging messages to an appropriate destination. It uses the varargs (variable arguments) feature (see Chapter 3) to optionally accept an extra String argument for those destination types that require the argument. For example, FILE requires a filename.

Listing 5-21 presents the package-private Console class; this class is not accessible beyond the classes in the logging package because reserved word class is not preceded by reserved word public.

Listing 5-21. Logging Messages to the Console

package logging;
 
class Console implements Logger
{
   private String dstName;
 
   Console(String dstName)
   {
      this.dstName = dstName;
   }
 
   @Override
   public boolean connect()
   {
      return true;
   }
 
   @Override
   public boolean disconnect()
   {
      return true;
   }
 
   @Override
   public boolean log(String msg)
   {
      System.out.println(msg);
      return true;
   }
}

Console’s package-private constructor saves its argument, which most likely will be null because there is no need for a String argument. Perhaps a future version of Console will use this argument to identify one of multiple console windows.

Listing 5-22 presents the package-private File class.

Listing 5-22. Logging Messages to a File (Eventually)

package logging;
 
class File implements Logger
{
   private String dstName;
 
   File(String dstName)
   {
      this.dstName = dstName;
   }
 
   @Override
   public boolean connect()
   {
      if (dstName == null)
         return false;
      System.out.println("opening file " + dstName);
      return true;
   }
 
   @Override
   public boolean disconnect()
   {
      if (dstName == null)
         return false;
      System.out.println("closing file " + dstName);
      return true;
   }
 
   @Override
   public boolean log(String msg)
   {
      if (dstName == null)
         return false;
      System.out.println("writing "+msg+" to file " + dstName);
      return true;
   }
}

Unlike Console, File requires a nonnull argument. Each method first verifies that this argument is not null. If the argument is null, the method returns false to signify failure. (In Chapter 11, I refactor File to incorporate appropriate file-writing code.)

The logging library allows us to introduce portable logging code into an application. Apart from a call to newLogger(), this code will remain the same regardless of the logging destination. Listing 5-23 presents an application that tests this library.

Listing 5-23. Testing the Logging Library

import logging.Logger;
import logging.LoggerFactory;
 
public class TestLogger
{
   public static void main(String[] args)
   {
      Logger logger = LoggerFactory.newLogger(LoggerFactory.CONSOLE);
      if (logger.connect())
      {
         logger.log("test message #1");
         logger.disconnect();
      }
      else
         System.out.println("cannot connect to console-based logger");
      logger = LoggerFactory.newLogger(LoggerFactory.FILE, "x.txt");
      if (logger.connect())
      {
         logger.log("test message #2");
         logger.disconnect();
      }
      else
         System.out.println("cannot connect to file-based logger");
      logger = LoggerFactory.newLogger(LoggerFactory.FILE);
      if (logger.connect())
      {
         logger.log("test message #3");
         logger.disconnect();
      }
      else
         System.out.println("cannot connect to file-based logger");
   }
}

Follow the steps (which assume that the JDK has been installed) to create the logging package and TestLogger application, and to run this application.

1. Create a new directory and make this directory current.
2. Create a logging directory in the current directory.
3. Copy Listing 5-19 to a file named Logger.java in the logging directory.
4. Copy Listing 5-20 to a file named LoggerFactory.java in the logging directory.
5. Copy Listing 5-21 to a file named Console.java in the logging directory.
6. Copy Listing 5-22 to a file named File.java in the logging directory.
7. Copy Listing 5-23 to a file named TestLogger.java in the current directory.
8. Execute javac TestLogger.java, which also compiles logger’s source files.
9. Execute java TestLogger.

After completing these steps, you should observe the following output from the TestLogger application:

test message #1
opening file x.txt
writing test message #2 to file x.txt
closing file x.txt
cannot connect to file-based logger

What happens when logging is moved to another location? For example, move logging to the root directory and run TestLogger. You will now observe an error message about the virtual machine not finding the logging package and its LoggerFactory classfile.

You can solve this problem by specifying -classpath/-cp when running the java tool or by adding the location of the logging package to the CLASSPATH environment variable. For example, I chose to use -classpath (which I find more convenient) in the following Windows-specific command line:

java -classpath ;. TestLogger

The backslash represents the root directory in Windows. (I could have specified a forward slash as an alternative.) Also, the period represents the current directory. If it is missing, the virtual machine complains about not finding the TestLogger classfile.

Packages and JAR Files

The JDK provides a jar tool that is used to archive classfiles in JAR (Java ARchive) files and is also used to extract a JAR file’s classfiles. It probably comes as no surprise that you can store packages in JAR files, which greatly simplify the distribution of your package-based class libraries.

To show you how easy it is to store a package in a JAR file, you will create a logger.jar file that contains the logging package’s four classfiles (Logger.class, LoggerFactory.class, Console.class, and File.class). Complete the following steps to accomplish this task:

1. Make sure that the current directory contains the previously created logging directory with its four classfiles.
2. Execute the following command:

   jar cf logger.jar logging*.class

   The c option stands for “create new archive” and the f option stands for “specify archive filename.”

   You could alternatively execute the following command:

   jar cf logger.jar logging/*.class

You should now find a logger.jar file in the current directory. To prove to yourself that this file contains the four classfiles, execute the following command, where the t option stands for “list table of contents”:

jar tf logger.jar

You can run TestLogger.class by adding logger.jar to the classpath. For example, you can run TestLogger under Windows via the following command:

java -classpath logger.jar;. TestLogger

What Are Exceptions?

An exception is a divergence from an application’s normal behavior. For example, the application attempts to open a nonexistent file for reading. The normal behavior is to successfully open the file and begin reading its contents. However, the file cannot be read when the file doesn’t exist.

This example illustrates an exception that cannot be prevented. However, a workaround is possible. For example, the application can detect that the file doesn’t exist and take an alternate course of action, which might include telling the user about the problem. Unpreventable exceptions where workarounds are possible must not be ignored.

Exceptions can occur because of poorly written code. For example, an application might contain code that accesses each element in an array. Because of careless oversight, the array-access code might attempt to access a nonexistent array element, which leads to an exception. This kind of exception is preventable by writing correct code.

Finally, an exception might occur that cannot be prevented and for which there is no workaround. For example, the virtual machine might run out of memory, or perhaps it cannot find a classfile. This kind of exception, known as an error, is so serious that it’s impossible (or at least inadvisable) to work around; the application must terminate, presenting a message to the user that explains why it’s terminating.

Representing Exceptions in Source Code

An exception can be represented via error codes or objects. After discussing each kind of representation and explaining why objects are superior, I will introduce you to Java’s exception and error class hierarchy, emphasizing the difference between checked and runtime exceptions. I will close my discussion on representing exceptions in source code by discussing custom exception classes.

package media;
 
public class InvalidMediaFormatException extends Exception
{
   private String expectedFormat;
   private String existingFormat;
 
   public InvalidMediaFormatException(String expectedFormat,
                                      String existingFormat)
   {
      super("Expected format: " + expectedFormat + ", Existing format: " +
            existingFormat);
      this.expectedFormat = expectedFormat;
      this.existingFormat = existingFormat;
   }
 
   public String getExpectedFormat()
   {
      return expectedFormat;
   }
 
   public String getExistingFormat()
   {
      return existingFormat;
   }
}

Throwing Exceptions

Now that you have created an InvalidMediaFormatException class, you can declare the Media class and begin to code its convert() method. The initial version of this method validates its arguments and then verifies that the source file’s media format agrees with the format implied by its file extension. Check out Listing 5-27.

Listing 5-27. Throwing Exceptions from the convert() Method

package media;
 
import java.io.IOException;
 
public final class Media
{
   public static void convert(String srcName, String dstName)
      throws InvalidMediaFormatException, IOException
   {
      if (srcName == null)
         throw new NullPointerException(srcName + " is null");
      if (dstName == null)
         throw new NullPointerException(dstName + " is null");
      // Code to access source file and verify that its format matches the
      // format implied by its file extension.
      //
      // Assume that the source file's extension is RM (for Real Media) and
      // that the file's internal signature suggests that its format is
      // Microsoft WAVE.
      String expectedFormat = "RM";
      String existingFormat = "WAVE";
      throw new InvalidMediaFormatException(expectedFormat, existingFormat);
   }
}

Listing 5-27 declares the Media class to be final because this utility class will only consist of class methods and there’s no reason to extend it.

Media’s convert() method appends throws InvalidMediaFormatException, IOException to its header. A throws clause identifies all checked exceptions that are thrown out of the method and must be handled by some other method. It consists of reserved word throws followed by a comma-separated list of checked exception class names and is always appended to a method header. The convert() method’s throws clause indicates that this method is capable of throwing an InvalidMediaException or IOException instance to the virtual machine.

convert() also demonstrates the throw statement, which consists of reserved word throw followed by an instance of Throwable or a subclass. (You will typically instantiate an Exception subclass.) This statement throws the instance to the virtual machine, which then searches for a suitable handler to handle the exception.

The first use of the throw statement is to throw a java.lang.NullPointerException instance when a null reference is passed as the source or destination filename. This unchecked exception is commonly thrown to indicate that a contract has been violated via a passed null reference. For example, you cannot pass null filenames to convert().

The second use of the throw statement is to throw a media.InvalidMediaFormatException instance when the expected media format doesn’t match the existing format. In the contrived example, the exception is thrown because the expected format is RM and the existing format is WAVE.

Unlike InvalidMediaFormatException, NullPointerException is not listed in convert()’s throws clause because NullPointerException instances are unchecked. They can occur so frequently that it is too big a burden to force the developer to properly handle these exceptions. Instead, the developer should write code that minimizes their occurrences.

Although not thrown from convert(), IOException is listed in this method’s throws clause in preparation for refactoring this method to perform the conversion with the help of file-handling code.

NullPointerException is one kind of exception that is thrown when an argument proves to be invalid. The java.lang.IllegalArgumentException class generalizes the illegal argument scenario to include other kinds of illegal arguments. For example, the following method throws an IllegalArgumentException instance when a numeric argument is negative:

public static double sqrt(double x)
{
   if (x < 0)
      throw new IllegalArgumentException(x + " is negative");
   // Calculate the square root of x.
}

There are a few additional items to keep in mind when working with throws clauses and throw statements:

• You can append a throws clause to a constructor and throw an exception from the constructor when something goes wrong while the constructor is executing. The resulting object will not be created.
• When an exception is thrown out of an application’s main() method, the virtual machine terminates the application and calls the exception’s printStackTrace() method to print, to the console, the sequence of nested method calls that was awaiting completion when the exception was thrown.
• If a superclass method declares a throws clause, the overriding subclass method doesn’t have to declare a throws clause. However, if the subclass method does declare a throws clause, the clause must not include the names of checked exception classes that are not also included in the superclass method’s throws clause, unless they are the names of exception subclasses. For example, given superclass method void foo() throws IOException {}, the overriding subclass method could be declared as void foo() {}, void foo() throws IOException {}, or void foo() throws FileNotFoundException {}; the java.io.FileNotFoundException class subclasses IOException.
• A checked exception class name doesn’t need to appear in a throws clause when the name of its superclass appears.
• The compiler reports an error when a method throws a checked exception and doesn’t also handle the exception or list the exception in its throws clause.
• If at all possible, don’t include the names of unchecked exception classes in a throws clause. These names are not required because such exceptions should never occur. Furthermore, they only clutter source code and possibly confuse someone who is trying to understand that code.
• You can declare a checked exception class name in a method’s throws clause without throwing an instance of this class from the method. (Perhaps the method has yet to be fully coded.) However, Java requires that you provide code to handle this exception, even though it is not thrown.

Handling Exceptions

A method indicates its intention to handle one or more exceptions by specifying a try statement that includes one or more appropriate catch blocks. The try statement consists of reserved word try followed by a brace-delimited body. You place code that throws exceptions into this block.

A catch block consists of reserved word catch, followed by a round bracket-delimited single-parameter list that specifies an exception class name, followed by a brace-delimited body. You place code that handles exceptions whose types match the type of the catch block’s parameter list’s exception class parameter in this block.

A catch block is specified immediately after a try block. When an exception is thrown, the virtual machine will search for a handler. It first examines the catch block to see whether its parameter type matches or is the superclass type of the exception that has been thrown.

If the catch block is found, its body executes and the exception is handled. Otherwise, the virtual machine proceeds up the method-call stack, looking for the first method whose try statement contains an appropriate catch block. This process continues unless a catch block is found or execution leaves the main() method.

The following example illustrates try and catch:

try
{
   int x = 1 / 0;
}
catch (ArithmeticException ae)
{
   System.out.println("attempt to divide by zero");
}

When execution enters the try block, an attempt is made to divide integer 1 by integer 0. The virtual machine responds by instantiating ArithmeticException and throwing this exception. It then detects the catch block, which is capable of handling thrown ArithmeticException objects, and transfers execution to this block, which invokes System.out.println() to output a suitable message; the exception is handled.

Because ArithmeticException is an example of an unchecked exception type, and because unchecked exceptions represent coding mistakes that must be fixed, you typically don’t catch them, as demonstrated previously. Instead, you would fix the problem that led to the thrown exception.

import java.io.FileNotFoundException;
import java.io.IOException;
 
import media.InvalidMediaFormatException;
import media.Media;
 
public class Converter
{
   public static void main(String[] args)
   {
      if (args.length != 2)
      {
         System.err.println("usage: java Converter srcfile dstfile");
         return;
      }
      try
      {
         Media.convert(args[0], args[1]);
      }
      catch (InvalidMediaFormatException imfe)
      {
         System.out.println("Unable to convert " + args[0] + " to " + args[1]);
         System.out.println("Expecting " + args[0] + " to conform to " +
                            imfe.getExpectedFormat() + " format.");
         System.out.println("However, " + args[0] + " conformed to " +
                            imfe.getExistingFormat() + " format.");
      }
      catch (FileNotFoundException fnfe)
      {
      }
      catch (IOException ioe)
      {
      }
   }
}

Unable to convert A to B
Expecting A to conform to RM format.
However, A conformed to WAVE format.

catch (IOException ioe)
{
   throw new ReportCreationException(ioe);
}

catch (FileNotFoundException fnfe)
{
   logger.log(fnfe);
   throw fnfe; // Rethrow the exception here.
}

Performing Cleanup

In some situations, you might want to execute cleanup code before execution leaves a method following a thrown exception. For example, you might want to close a file that was opened, but could not be written, possibly because of insufficient disk space. Java provides the finally block for this situation.

The finally block consists of reserved word finally followed by a body, which provides the cleanup code. A finally block follows either a catch block or a try block. In the former case, the exception may be handled (and possibly rethrown) before finally executes. In the latter case, the exception is handled (and possibly rethrown) after finally executes.

Listing 5-29 demonstrates the first scenario in the context of a simulated file-copying application’s main() method.

Listing 5-29. Cleaning Up by Closing Files After Handling a Thrown Exception

import java.io.IOException;
 
public class Copy
{
   public static void main(String[] args)
   {
      if (args.length != 2)
      {
         System.err.println("usage: java Copy srcFile dstFile");
         return;
      }
 
      int fileHandleSrc = 0;
      int fileHandleDst = 1;
      try
      {
         fileHandleSrc = open(args[0]);
         fileHandleDst = create(args[1]);
         copy(fileHandleSrc, fileHandleDst);
      }
      catch (IOException ioe)
      {
         System.err.println("I/O error: " + ioe.getMessage());
         return;
      }
      finally
      {
         close(fileHandleSrc);
         close(fileHandleDst);
      }
   }
 
   static int open(String filename)
   {
      return 1; // Assume that filename is mapped to integer.
   }
 
   static int create(String filename)
   {
      return 2; // Assume that filename is mapped to integer.
   }
 
   static void close(int fileHandle)
   {
      System.out.println("closing file: " + fileHandle);
   }
 
   static void copy(int fileHandleSrc, int fileHandleDst) throws IOException
   {
      System.out.println("copying file " + fileHandleSrc + " to file " +
                         fileHandleDst);
      if (Math.random() < 0.5)
         throw new IOException("unable to copy file");
   }
}

Listing 5-29 presents a Copy application class that simulates the copying of bytes from a source file to a destination file. The try block invokes the open() method to open the source file and the create() method to create the destination file. Each method returns an integer-based file handle that uniquely identifies the file.

Next, this block calls the copy() method to perform the copy. After outputting a suitable message, copy() invokes the Math class’s random() method (officially discussed in Chapter 7) to return a random number between 0 and 1. When this method returns a value less than 0.5, which simulates a problem (perhaps the disk is full), the IOException class is instantiated and this instance is thrown.

The virtual machine locates the catch block that follows the try block and causes its handler to execute, which outputs a message. Then, the code in the finally block that follows the catch block is allowed to execute. Its purpose is to close both files by invoking the close() method on the passed file handle.

Compile this source code (javac Copy.java) and run the application with two arbitrary arguments (java Copy x.txt x.bak). You should observe the following output when there is no problem:

copying file 1 to file 2
closing file: 1
closing file: 2

When something goes wrong, you should observe the following output:

copying file 1 to file 2
I/O error: unable to copy file
closing file: 1
closing file: 2

Whether or not an I/O error occurs, notice that the finally block is the final code to execute. The finally block executes even though the catch block ends with a return statement.

This example illustrates finally block execution after a thrown exception is handled. However, you might want to perform cleanup before the exception is handled. Listing 5-30 presents a variation of the Copy application that demonstrates this alternative.

Listing 5-30. Cleaning Up by Closing Files Before Handling a Thrown Exception

import java.io.IOException;
 
public class Copy
{
   public static void main(String[] args) throws IOException
   {
      if (args.length != 2)
      {
         System.err.println("usage: java Copy srcFile dstFile");
         return;
      }
 
      int fileHandleSrc = 0;
      int fileHandleDst = 1;
      try
      {
         fileHandleSrc = open(args[0]);
         fileHandleDst = create(args[1]);
         copy(fileHandleSrc, fileHandleDst);
      }
      finally
      {
         close(fileHandleSrc);
         close(fileHandleDst);
      }
   }
 
   static int open(String filename)
   {
      return 1; // Assume that filename is mapped to integer.
   }
 
   static int create(String filename)
   {
      return 2; // Assume that filename is mapped to integer.
   }
 
   static void close(int fileHandle)
   {
      System.out.println("closing file: " + fileHandle);
   }
 
   static void copy(int fileHandleSrc, int fileHandleDst) throws IOException
   {
      System.out.println("copying file " + fileHandleSrc + " to file " +
                         fileHandleDst);
      if (Math.random() < 0.5)
         throw new IOException("unable to copy file");
   }
}

Listing 5-30 is nearly identical to Listing 5-29. The only difference is the throws clause appended to the main() method header and the removal of the catch block. When IOException is thrown, the finally block executes before execution leaves the main() method. This time, Java’s default exception handler executes printStackTrace() and you observe output similar to the following:

copying file 1 to file 2
closing file: 1
closing file: 2
Exception in thread "main" java.io.IOException: unable to copy file
        at Copy.copy(Copy.java:48)
        at Copy.main(Copy.java:19)