The Essence of OOP using Java, Local Classes

Baldwin explains the various relationships that exist among local classes and their enclosing classes.

Published:  November 4, 2003
By Richard G. Baldwin

Java Programming Notes # 1638

• Preface
• Preview
• Discussion and Sample Code
• Run the Program
  
• Summary
• What's Next
• Complete Program Listing
  

This series of lessons is designed to teach you about the essence of Object-Oriented Programming (OOP) using Java.

The first lesson in the series was entitled The Essence of OOP Using Java, Objects, and Encapsulation.  The previous lesson was entitled The Essence of OOP using Java, Member Classes.

You may find it useful to open another copy of this lesson in a separate browser window.  That will make it easier for you to scroll back and forth among the different figures and listings while you are reading about them.

For further reading, see my extensive collection of online Java tutorials at Gamelan.com. A consolidated index is available at www.DickBaldwin.com.

What can you include in a class definition?

There are several different kinds of items that can be included in a class definition.  As you learned in the earlier lessons in this series, the list includes:

• Static variables
• Instance variables
• Static methods
• Instance methods
• Constructors
• Static initializer blocks
• Instance initializers
  

Can also contain other class definitions

As you learned in the previous lesson, a class definition can also contain the following four kinds of inner classes:

• Member classes
• Local classes
• Anonymous classes
• Nested top-level classes and interfaces

The previous lesson explained member classes.  This lesson will explain local classes.  Subsequent lessons will explain the other two types of inner classes.

(Note that it is questionable whether a nested top-level class or interface should be referred to as an inner class, because an object of a nested top-level class can exist in the absence of an object of the enclosing class.  Regardless of whether the term inner class applies, a nested top-level class is defined within the definition of another class, so its definition is internal to the definition of another class.)

What is a local class?

A local class is a class that is defined within a block of Java code.  While local classes are probably most frequently defined within methods and constructors, they can also be defined inside static initializer blocks and instance initializers.

As is the case for an object of a member class (discussed in the previous lesson), an object of a local class must be internally linked to an object of the enclosing class.  I will often refer to that object as the containing object, and make comments about the containment hierarchy.

Thus, a local class is truly an inner class, because an object of the local class cannot exist in the absence of an object of the enclosing class.

What about a local interface?

Interfaces defined within classes are implicitly static.  This means that they are always top-level.  There is no such thing as a member interface, a local interface, or an anonymous interface.

Why use local classes?

Objects instantiated from local classes share many of the characteristics of objects instantiated from member classes.  However, in some cases, a local class can be defined closer to its point of use than would be possible with a member class, leading to improved code readability.

Probably the most important benefit of local classes has to do with accessing the members of enclosing classes.  Just like with member classes, methods of a local class have direct access to all the members of the enclosing classes, including private members.  Thus the use of local classes can sometimes eliminate the requirement to connect objects together via constructor parameters.

(We will also see in the example program in this lesson that methods of a local class have direct access to protected members of the superclass of the enclosing class.)

Can be particularly useful when ...

A local class can be particularly useful in those cases where

• There is no reason for an object of the local class to exist in the absence of an object of the enclosing class
• There is no reason for an object of the local class to exist outside a method of the enclosing class
• Methods of the object of the local class need access to members of the object of the enclosing class
• Methods of the object of the local class need access to final local variables and method parameters belonging to the method in which the local class is defined
  

This lesson approaches local classes from a somewhat theoretical viewpoint.  The next lesson will approach local classes from a more practical viewpoint, including a comparison between local classes and anonymous classes.

Local classes versus member classes

A local class has approximately the same relationship to a member class that a local variable in a method has to an instance variable of the class containing the method.

The scope of a local class

As is the case with local variables, the name of a local class is visible and usable only within the block of code in which it is defined (and blocks nested within that block).  Further, the name of the local class is visible and usable only to code following the class definition within that block.

The methods of a local class can use any final local variables or method parameters that are visible from the scope in which the local class is defined.

Similar to member classes

As mentioned earlier, local classes have many characteristics in common with member classes.  This includes access to private fields and methods in the containing class.  The thing that separates local classes from member classes is the fact that local classes have access to local variables in the scope in which the local class is defined.

A big restriction

There is a big restriction, however, on the ability of methods of the local class to access local variables and method parameters.  The methods in a local class can access local variables and method parameters only if they are declared final.

What does Flanagan have to say?

According to one of my favorite authors, David Flanagan, author of Java in a Nutshell, the methods in a local class don't really have access to local variables and method parameters.  Rather, when an object of the local class is instantiated, copies of the final local variables and method parameters referred to by the object's methods are stored as instance variables in the object.  The methods in the object of the local class really access those hidden instance variables.  (See the later section entitled Smoke and mirrors.)

Thus, the local variables and method parameters accessed by the methods of the local class must be declared final to prevent their values from changing after the object is instantiated.

Restrictions on local classes

As with member classes, local classes cannot contain static members.

As with local variables, local classes cannot be declared public, protected, private, or static. 

A local class cannot have the same name as any of its enclosing classes.

Smoke and mirrors

As I mentioned in the previous lesson, every class definition in a Java program, including nested top-level classes, member classes, local classes, and anonymous classes, produces a class file when the program is compiled.  According to Flanagan,

"The Java Virtual Machine knows nothing about nested top-level classes and interfaces or the various types of inner classes.  Therefore, the Java compiler must convert these new types into standard non-nested class files that the Java interpreter can understand.  This is done through source code transformations that insert $ characters into nested class names.  These source code transformations may also insert hidden fields, methods, and constructor arguments into the affected classes."

A reference to the containing object

For example, the compiler automatically inserts a private instance variable in the local class to hold a reference to the containing object.  It also inserts a hidden argument in all constructors for the local class, and passes the containing object's reference to the constructor for the local class.  The modified constructor saves that reference in the private instance variable of the object of the local class.  Thus each object instantiated from the local class contains a private reference to the containing object.

Accessing private members

In those cases where it is necessary for an object of the local class to access private members of the containing object, the compiler automatically creates and uses accessor methods that make such access possible.

Similar to your code

The bottom line is that the code that is automatically produced by the compiler is probably very similar to code that you would write if you were writing the program using only top-level classes.  The good news is that you don't have to write that extra code, and you don't have to maintain it.  The extra code is written for you, and if you modify your class structure, the extra code is automatically modified accordingly.

Enough talk, let's see some code

The paragraphs that follow will explain a program named InnerClasses07, which is designed specifically to illustrate various characteristics of local classes.  I will discuss the program in fragments.  A complete listing is shown in Listing 17 near the end of the lesson.

• Top-level classes named InnerClasses07, A, X, and Y
• A local class named B.

A$1$B.class
A.class
InnerClasses07.class
X.class
Y.class

Figure 1

(Note that while the containment hierarchy of local classes is independent of the inheritance hierarchy, it is technically possible to establish an inheritance relationship between a local class and one of its enclosing classes.  For example, by making a couple of minor modifications, it is possible to cause the local class B in this program to extend the enclosing class A instead of the top-level class Y.)

public class InnerClasses07{

  static long baseTime = new Date().getTime();

  public static void main(String[] args){
    new A().meth();
  }//end main
}//end class InnerClasses07

Listing 1

class X{
  protected int xVar = 1000;
}//end class X


Listing 2

(Somewhat surprisingly, you will also see later that this protected instance variable belonging to the superclass of the enclosing class A is also accessible by methods belonging to an object of the local class via the containment hierarchy.)

class Y{
  protected int yVar = 2000;

  public String toString(){
    return "toString in class Y, yVar = " + yVar;
  }//end overridden toString
}//end class Y
Listing 3

class A extends X{
  private long aTime = new Date().getTime() -
                         InnerClasses07.baseTime;

  A(){//constructor
    System.out.println(
              "In xstr for A, aTime = " + aTime);
  }//end constructor

Listing 4

In xstr for A, aTime = 10

Figure 2

(Note that the relative time output value on your system may be different, depending on the speed of your system and the impact of other applications that may be running concurrently.)

• The relative time that the object was instantiated.
• The value of the instance variable named xVar, which is an instance variable of the superclass of class A.
• The name of the class file that represents the class named A.

  private void showA(){
    System.out.println(
                   "In showA, aTime = " + aTime);
    System.out.println(
                     "In showA, xVar = " + xVar);
    System.out.println("In showA, class name = "
                         + getClass().getName());
  }//end showA

Listing 5

  void delay(){
    try{
      Thread.currentThread().sleep(30);
    }catch(InterruptedException e){
      System.out.println(e);
    }//end catch
  }//end delay

Listing 6

  void meth(){
    final long methTime;
Listing 7

• Inserts a delay
• Sets a value for the final local variable named methTime
• Displays the value that was set in methTime
• Inserts an additional delay before continuing

    delay();
    methTime = new Date().getTime() -
                         InnerClasses07.baseTime;
    System.out.println(
              "In meth, methTime = " + methTime);
    delay();

Listing 8

In meth, methTime = 40

Figure 3

    class B extends Y{
      private long bTime;

      B(){//constructor
        bTime = new Date().getTime() -
                         InnerClasses07.baseTime;
        System.out.println(
              "In xstr for B, bTime = " + bTime);
      }//end constructor

Listing 9

    System.out.println("----------------------");
    System.out.println(
                   "Instantiate first B-object");
    final B obj1 = new B();
    System.out.println(
        "Delay and instantiate second B-object");
    delay();
    final B obj2 = new B();

Listing 10

----------------------
Instantiate first B-object
In xstr for B, bTime = 70
Delay and instantiate second B-object
In xstr for B, bTime = 100

Figure 4

    System.out.println("----------------------");
    System.out.println("Display first B-Object");
    obj1.showB();

Listing 11

//Continuing with local class B definition
      void showB(){
        System.out.println("-1-");
        System.out.println(
           "In showB, private bTime = " + bTime);
        System.out.println(
           "In showB, private aTime = " + aTime);
        System.out.println(
                  "In showB, final methTime = " +
                                       methTime);
        System.out.println(
           "In showB, protected xVar = " + xVar);
        System.out.println(
           "In showB, protected yVar = " + yVar);
        System.out.println(
                      "In showB, class name = " +
                           getClass().getName());

Listing 12

(Note that code in this method has direct access to xVar, which is a protected member variable of the superclass of the class named A.)

• A visual line separator, -1-
• A private instance variable, bTime, belonging to the object instantiated from local class B
• A private instance variable, aTime, belonging to the containing object instantiated from the top-level class A
• A final local variable, methTime, belonging to the method named meth, in which the local class B is defined
• A protected instance variable, xVar, of the superclass of the class A, from which the containing object was instantiated.
• A protected instance variable, yVar, of the superclass of the local class B
• The name of the class file that represents the local class B

----------------------
Display first B-Object
-1-
In showB, private bTime = 70
In showB, private aTime = 10
In showB, final methTime = 40
In showB, protected xVar = 1000
In showB, protected yVar = 2000
In showB, class name = A$1$B

Figure 5

(In this case, an object of the local class B has only one containing class, an object instantiated from the top-level class A.)

        System.out.println("-2-");
        showA();

Listing 13

-2-
In showA, aTime = 10
In showA, xVar = 1000
In showA, class name = A

Figure 6

• The relative time that the containing object of the class A was instantiated
• A protected instance variable in the superclass of the class from which the containing object was instantiated
• The name of the class file that represents the top-level class named A

        System.out.println("-3-");
        System.out.println(
              "In showB, bTime = " + this.bTime);
        System.out.println(
            "In showB, aTime = " + A.this.aTime);
Listing 14

-3-
In showB, bTime = 70
In showB, aTime = 10

Figure 7

• Invoking the overridden toString method belonging to the local class B
• Using the super keyword to invoke the overridden toString method belonging to the class Y, which is the superclass of the local class B

        System.out.println("-4-");
        System.out.println(toString());
        System.out.println(super.toString());
      }//end showB
      //---------------------------------------//

      //Overridden toString method
      public String toString(){
        return
         "toString in class B, bTime = " + bTime;
      }//end overridden toString
    }//end local class B

Listing 15

-4-
toString in class B, bTime = 70
toString in class Y, yVar = 2000

Figure 8

    System.out.println("----------------------");
    System.out.println(
                      "Display second B-Object");
    obj2.showB();

  }// end meth
}//end class A

Listing 16

----------------------
Display second B-Object
-1-
In showB, private bTime = 100
In showB, private aTime = 10
In showB, final methTime = 40
In showB, protected xVar = 1000
In showB, protected yVar = 2000
In showB, class name = A$1$B
-2-
In showA, aTime = 10
In showA, xVar = 1000
In showA, class name = A
-3-
In showB, bTime = 100
In showB, aTime = 10
-4-
toString in class B, bTime = 100
toString in class Y, yVar = 2000

Figure 9

• The second object instantiated from local class B is definitely a different object from the first object instantiated from local class B, as evidenced by a different value for bTime.  (Compare the value of bTime in Figure 9 with the value of bTime in Figure 5.)  In other words, the second object was instantiated after the first object was instantiated.
• Even though the two objects instantiated from local class B are different objects, they both belong to the same containing object, as evidenced by the same values for aTime in Figure 9 and Figure 5.
• The two objects instantiated from local class B each access the same final local variable belonging to the method named meth, as evidenced by the same values for methTime in Figure 9 and Figure 5.
  

Run the Program

At this point, you may find it useful to compile and run the program shown in Listing 17 near the end of the lesson.

• Member classes
• Local classes
• Anonymous classes
• Nested top-level classes and interfaces

The next lesson in this series will explain and discuss anonymous classes, and will also compare anonymous classes to local classes.  Subsequent lessons will explain top-level nested classes.

Complete Program Listing

/*File InnerClasses07.java
Copyright 2003 R.G.Baldwin

Illustrates the use of local classes.

This program defines a local class named B inside
an instance method named meth.  The method named
meth is an instance method of a class named A.

The method named meth instantiates two separate
objects of the local class named B, and invokes
on each of them a method named showB, which
displays certain data values that illustrate the
characteristics of local classes, a well as the
relationships among objects of a local class and
an object to which that object is internally
associated.  In this case, objects of the class
named B are internally associated with an object
of the class named A.

This program produces the following class files
when compiled:

A$1$B.class
A.class
InnerClasses07.class
X.class
Y.class

The file named A$1$B.class represents the local
class named B.

This program produces the following output:

In xstr for A, aTime = 10
In meth, methTime = 40
----------------------
Instantiate first B-object
In xstr for B, bTime = 70
Delay and instantiate second B-object
In xstr for B, bTime = 100
----------------------
Display first B-Object
-1-
In showB, private bTime = 70
In showB, private aTime = 10
In showB, final methTime = 40
In showB, protected xVar = 1000
In showB, protected yVar = 2000
In showB, class name = A$1$B
-2-
In showA, aTime = 10
In showA, xVar = 1000
In showA, class name = A
-3-
In showB, bTime = 70
In showB, aTime = 10
-4-
toString in class B, bTime = 70
toString in class Y, yVar = 2000
----------------------
Display second B-Object
-1-
In showB, private bTime = 100
In showB, private aTime = 10
In showB, final methTime = 40
In showB, protected xVar = 1000
In showB, protected yVar = 2000
In showB, class name = A$1$B
-2-
In showA, aTime = 10
In showA, xVar = 1000
In showA, class name = A
-3-
In showB, bTime = 100
In showB, aTime = 10
-4-
toString in class B, bTime = 100
toString in class Y, yVar = 2000


Tested using SDK 1.4.1 under WinXP
************************************************/
import java.util.Date;

public class InnerClasses07{
  //The following static variable is used as a
  // base to establish the relative points in
  // time that certain activities occur during
  // the execution of the program.
  static long baseTime = new Date().getTime();

  public static void main(String[] args){
    //Instantiate a new object of the class named
    // A and invoke the method named meth on that
    // object.  This method will sequentially
    // instantiate two separate objects of a
    // local class named B that is defined inside
    // the method named meth.  Then it will
    // invoke a method named showB on each of
    // those objects to cause them to display
    // various data values that illustrate the
    // characteristics of local classes.
    new A().meth();
  }//end main
}//end class InnerClasses07
//=============================================//

//The class named A extends this class to
// illustrate the difference between the
// inheritance hierarchy and the containment
// hierarchy.
class X{
  protected int xVar = 1000;
}//end class X
//=============================================//

//The local class named B extends this class to
// illustrate the difference between the
// inheritance hierarchy and the containment
// hierarchy.
class Y{
  protected int yVar = 2000;

  //Overridden toString method
  public String toString(){
    return "toString in class Y, yVar = " + yVar;
  }//end overridden toString
}//end class Y
//=============================================//

class A extends X{
  //Establish the relative time that the object
  // of class A is instantiated.
  private long aTime = new Date().getTime() -
                         InnerClasses07.baseTime;

  A(){//constructor
    System.out.println(
              "In xstr for A, aTime = " + aTime);
  }//end constructor
  //-------------------------------------------//

  //Displays information about the object
  // instantiated from class A.
  private void showA(){
    System.out.println(
                   "In showA, aTime = " + aTime);
    System.out.println(
                     "In showA, xVar = " + xVar);
    System.out.println("In showA, class name = "
                         + getClass().getName());
  }//end showA
  //-------------------------------------------//

  //Method used to insert a time delay of 30
  // milliseconds.
  void delay(){
    try{
      Thread.currentThread().sleep(30);
    }catch(InterruptedException e){
      System.out.println(e);
    }//end catch
  }//end delay
  //-------------------------------------------//

  //This method contains a local class definition
  // for a class named B.  The method
  // instantiates two separate objects of class B
  // and invokes a method named showB on each of
  // the objects.  The method named showB
  // displays various data values that illustrate
  // the characteristics of local classes.
  void meth(){
    //The following local variable must be final
    // to be accessible from a local class.  This
    // is a blank final variable whose value can
    // be set once and never changed after that.
    final long methTime;

    //Delay and then set the value of the blank
    // final local variable to a relative time.
    // Then delay again before continuing.
    delay();
    methTime = new Date().getTime() -
                         InnerClasses07.baseTime;
    System.out.println(
              "In meth, methTime = " + methTime);
    delay();
  //-------------------------------------------//

    //This is the definition of a local class
    // named B.  Note that as with local
    // variables, the class definition must
    // appear before the code that attempts to
    // instantiate the class.  The class extends
    // class Y to illustrate that the inheritance
    // hierarchy is independent of the
    // containment hierarchy.
    class B extends Y{
      private long bTime;

      B(){//constructor
        //Establish the relative time that the
        // object is instantiated.
        bTime = new Date().getTime() -
                         InnerClasses07.baseTime;
        System.out.println(
              "In xstr for B, bTime = " + bTime);
      }//end constructor

      void showB(){
        //Display private and protected
        // variables, some of which belong to the
        // internally associated object
        // instantiated from the class named A.
        // Note that code in this method has
        // access to xVar, which is a protected
        // member variable of a superclass of the
        // class named A.
        System.out.println("-1-");
        System.out.println(
           "In showB, private bTime = " + bTime);
        System.out.println(
           "In showB, private aTime = " + aTime);
        System.out.println(
                  "In showB, final methTime = " +
                                       methTime);
        System.out.println(
           "In showB, protected xVar = " + xVar);
        System.out.println(
           "In showB, protected yVar = " + yVar);
        System.out.println(
                      "In showB, class name = " +
                           getClass().getName());

        System.out.println("-2-");
        //Invoke the private method named showA
        // in the internally associated object
        // instantiated from the class named A,
        // to illustrate the containment
        // hierarchy.
        showA();

        System.out.println("-3-");
        //Show how to access individual objects,
        // including the internally associated
        // object instantiated from the class
        // named A.
        System.out.println(
              "In showB, bTime = " + this.bTime);
        System.out.println(
            "In showB, aTime = " + A.this.aTime);

        System.out.println("-4-");
        //Illustrate the inheritance hierarchy by
        // invoking the overridden toString
        // methods belonging to the class named B
        // and its superclass named Y.
        System.out.println(toString());
        System.out.println(super.toString());
      }//end showB
      //---------------------------------------//

      //Overridden toString method
      public String toString(){
        return
         "toString in class B, bTime = " + bTime;
      }//end overridden toString
    }//end local class B

    //This is the code that is executed when this
    // method named meth is invoked.  Instantiate
    // two objects from the class named B and
    // invoke the method named showB on each of
    // them.  Those methods will, in turn invoke
    // the method named showA on the internally
    // associated object instantiated from the
    // class named A.  Insert a delay between the
    // instantiation of the two objects.
    System.out.println("----------------------");
    System.out.println(
                   "Instantiate first B-object");
    final B obj1 = new B();
    System.out.println(
        "Delay and instantiate second B-object");
    delay();
    final B obj2 = new B();

    System.out.println("----------------------");
    System.out.println("Display first B-Object");
    obj1.showB();
    System.out.println("----------------------");
    System.out.println(
                      "Display second B-Object");
    obj2.showB();

  }// end meth
}//end class A
//=============================================//

Listing 17

Copyright 2003, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.

About the author

Richard Baldwin is a college professor (at Austin Community College in Austin, Texas) and private consultant whose primary focus is a combination of Java, C#, and XML. In addition to the many platform and/or language independent benefits of Java and C# applications, he believes that a combination of Java, C#, and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects, and he frequently provides onsite training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Programming Tutorials, which has gained a worldwide following among experienced and aspiring programmers. He has also published articles in JavaPro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.

baldwin@DickBaldwin.com

-end-