Thinking in Java, 3rd ed. Revision 4.0

A package is what becomes available when you use the import keyword to bring in an entire library, such as

import java.util.*;

This brings in the entire utility library that's part of the standard Java distribution. For instance, there's a class called ArrayList in java.util, so you can now either specify the full name java.util.ArrayList (which you can do without the import statement), or you can simply say ArrayList (because of the import).

If you want to bring in a single class, you can name that class in the import statement

import java.util.ArrayList;

Now you can use ArrayList with no qualification. However, none of the other classes in java.util are available.

The reason for all this importing is to provide a mechanism to manage name spaces. The names of all your class members are insulated from each other. A method f( ) inside a class A will not clash with an f( ) that has the same signature (argument list) in class B. But what about the class names? Suppose you create a Stack class that is installed on a machine that already has a Stack class that's written by someone else? This potential clashing of names is why it's important to have complete control over the name spaces in Java, and to be able to create a completely unique name regardless of the constraints of the Internet.

Most of the examples thus far in this book have existed in a single file and have been designed for local use, so they haven't bothered with package names. (In this case the class name is placed in the "default package.") This is certainly an option, and for simplicity's sake this approach will be used whenever possible throughout the rest of this book. However, if you're planning to create libraries or programs that are friendly to other Java programs on the same machine, you must think about preventing class name clashes.

When you create a source-code file for Java, it's commonly called a compilation unit (sometimes a translation unit). Each compilation unit must have a name ending in .java, and inside the compilation unit there can be a public class that must have the same name as the file (including capitalization, but excluding the .java filename extension). There can be only one public class in each compilation unit, otherwise the compiler will complain. If there are additional classes in that compilation unit, they are hidden from the world outside that package because they're not public, and they comprise "support" classes for the main public class.

When you compile a .java file, you get an output file for each class in the .java file. Each output file has the name of a class in the .java file, but with an extension of .class. Thus you can end up with quite a few .class files from a small number of .java files. If you've programmed with a compiled language, you might be used to the compiler spitting out an intermediate form (usually an "obj" file) that is then packaged together with others of its kind using a linker (to create an executable file) or a librarian (to create a library). That's not how Java works. A working program is a bunch of .class files, which can be packaged and compressed into a Java ARchive (JAR) file (using Java's jar archiver). The Java interpreter is responsible for finding, loading, and interpreting (26)

A library is a group of these class files. Each file has one class that is public (you're not forced to have a public class, but it's typical), so there's one component for each file. If you want to say that all these components (each in their own separate .java and .class files) belong together, that's where the package keyword comes in.

When you say:

package mypackage;

at the beginning of a file (if you use a package statement, it must appear as the first noncomment in the file), you're stating that this compilation unit is part of a library named mypackage. Or, put another way, you're saying that the public class name within this compilation unit is under the umbrella of the name mypackage, and anyone who wants to use the name must either fully specify the name or use the import keyword in combination with mypackage (using the choices given previously). Note that the convention for Java package names is to use all lowercase letters, even for intermediate words.

For example, suppose the name of the file is MyClass.java. This means there can be one and only one public class in that file, and the name of that class must be MyClass (including the capitalization):

package mypackage;
public class MyClass {
	// . . .

Now, if someone wants to use MyClass or, for that matter, any of the other public classes in mypackage, they must use the import keyword to make the name or names in mypackage available. The alternative is to give the fully qualified name:

mypackage.MyClass m = new mypackage.MyClass();

The import keyword can make this much cleaner:

import mypackage.*;
// . . . 
MyClass m = new MyClass();

It's worth keeping in mind that what the package and import keywords allow you to do, as a library designer, is to divide up the single global name space so you won't have clashing names, no matter how many people get on the Internet and start writing classes in Java.

5-1-1. Creating unique package names▲

package com.bruceeckel.simple;

//: com:bruceeckel:simple:Vector.java
// Creating a package.
package com.bruceeckel.simple;
 
public class Vector {
	public Vector() {
		System.out.println("com.bruceeckel.simple.Vector");
	}
} ///:~

//: com:bruceeckel:simple:List.java
// Creating a package.
package com.bruceeckel.simple;
 
public class List {
	public List() {
		System.out.println("com.bruceeckel.simple.List");
	}
} ///:~

C:\DOC\JavaT\com\bruceeckel\simple

CLASSPATH=.;D:\JAVA\LIB;C:\DOC\JavaT

CLASSPATH=.;D:\JAVA\LIB;C:\flavors\grape.jar

//: c05:LibTest.java
// Uses the library.
import com.bruceeckel.simpletest.*;
import com.bruceeckel.simple.*;
 
public class LibTest {
	static Test monitor = new Test();
	public static void main(String[] args) {
		Vector v = new Vector();
		List l = new List();
		monitor.expect(new String[] {
			"com.bruceeckel.simple.Vector",
			"com.bruceeckel.simple.List"
		});
	}
} ///:~

import com.bruceeckel.simple.*;
import java.util.*;

Vector v = new Vector();

java.util.Vector v = new java.util.Vector();

5-1-2. A custom tool library▲

//: com:bruceeckel:tools:P.java
// The P.rint & P.rintln shorthand.
package com.bruceeckel.tools;
 
public class P {
	public static void rint(String s) {
		System.out.print(s);
	}
	public static void rintln(String s) {
		System.out.println(s);
	}
} ///:~

//: c05:ToolTest.java
// Uses the tools library.
import com.bruceeckel.tools.*;
import com.bruceeckel.simpletest.*;
 
public class ToolTest {
	static Test monitor = new Test();
	public static void main(String[] args) {
		P.rintln("Available from now on!");
		P.rintln("" + 100); // Force it to be a String
		P.rintln("" + 100L);
		P.rintln("" + 3.14159);
		monitor.expect(new String[] {
			"Available from now on!",
			"100",
			"100",
			"3.14159"
		});
	}
} ///:~

5-1-3. Using imports to change behavior▲

5-1-4. Package caveat▲

When used, the Java access specifiers public, protected, and private are placed in front of each definition for each member in your class, whether it's a field or a method. Each access specifier controls the access for only that particular definition. This is a distinct contrast to C++, in which the access specifier controls all the definitions following it until another access specifier comes along.

One way or another, everything has some kind of access specified for it. In the following sections, you'll learn all about the various types of access, starting with the default access.

5-2-1. Package access▲

5-2-2. public : interface access▲

//: c05:dessert:Cookie.java
// Creates a library.
package c05.dessert;
 
public class Cookie {
	public Cookie() {
		System.out.println("Cookie constructor");
	}
	void bite() { System.out.println("bite"); }
} ///:~

//: c05:Dinner.java
// Uses the library.
import com.bruceeckel.simpletest.*;
import c05.dessert.*;
 
public class Dinner {
	static Test monitor = new Test();
	public Dinner() {
		System.out.println("Dinner constructor");
	}
	public static void main(String[] args) {
		Cookie x = new Cookie();
		//! x.bite(); // Can't access
		monitor.expect(new String[] {
			"Cookie constructor"
		});
	}
} ///:~

//: c05:Cake.java
// Accesses a class in a separate compilation unit.
import com.bruceeckel.simpletest.*;
 
class Cake {
	static Test monitor = new Test();
	public static void main(String[] args) {
		Pie x = new Pie();
		x.f();
		monitor.expect(new String[] {
			"Pie.f()"
		});
	}
} ///:~

//: c05:Pie.java
// The other class.
 
class Pie {
	void f() { System.out.println("Pie.f()"); }
} ///:~

5-2-3. private : you can't touch that!▲

//: c05:IceCream.java
// Demonstrates "private" keyword.
 
class Sundae {
	private Sundae() {}
	static Sundae makeASundae() {
		return new Sundae();
	}
}
 
public class IceCream {
	public static void main(String[] args) {
		//! Sundae x = new Sundae();
		Sundae x = Sundae.makeASundae();
	}
} ///:~

5-2-4. protected : inheritance access▲

class Foo extends Bar {

//: c05:ChocolateChip.java
// Can't use package-access member from another package.
import com.bruceeckel.simpletest.*;
import c05.dessert.*;
 
public class ChocolateChip extends Cookie {
	private static Test monitor = new Test();
	public ChocolateChip() {
		System.out.println("ChocolateChip constructor");
	}
	public static void main(String[] args) {
		ChocolateChip x = new ChocolateChip();
		//! x.bite(); // Can't access bite
		monitor.expect(new String[] {
			"Cookie constructor",
			"ChocolateChip constructor"
		});
	}
} ///:~

public class Cookie {
	public Cookie() { 
		System.out.println("Cookie constructor");
	}
	protected void bite() {
	System.out.println("bite"); 
	}
}

Access control is often referred to as implementation hiding. Wrapping data and methods within classes in combination with implementation hiding is often called encapsulation. (29) The result is a data type with characteristics and behaviors.

Access control puts boundaries within a data type for two important reasons. The first is to establish what the client programmers can and can't use. You can build your internal mechanisms into the structure without worrying that the client programmers will accidentally treat the internals as part of the interface that they should be using.

This feeds directly into the second reason, which is to separate the interface from the implementation. If the structure is used in a set of programs, but client programmers can't do anything but send messages to the public interface, then you are free to change anything that's not public (e.g., package access, protected, or private) without breaking client code.

We're now in the world of object-oriented programming, where a class is actually describing "a class of objects," as you would describe a class of fishes or a class of birds. Any object belonging to this class will share these characteristics and behaviors. The class is a description of the way all objects of this type will look and act.

In the original OOP language, Simula-67, the keyword class was used to describe a new data type. The same keyword has been used for most object-oriented languages. This is the focal point of the whole language: the creation of new data types that are more than just boxes containing data and methods.

The class is the fundamental OOP concept in Java. It is one of the keywords that will not be set in bold in this book-it becomes annoying with a word repeated as often as "class."

For clarity, you might prefer a style of creating classes that puts the public members at the beginning, followed by the protected, package access, and private members. The advantage is that the user of the class can then read down from the top and see first what's important to them (the public members, because they can be accessed outside the file), and stop reading when they encounter the non-public members, which are part of the internal implementation:

public class X {
	public void pub1() { /* . . . */ }
	public void pub2() { /* . . . */ }
	public void pub3() { /* . . . */ }
	private void priv1() { /* . . . */ }
	private void priv2() { /* . . . */ }
	private void priv3() { /* . . . */ }
	private int i;
	// . . .
}

This will make it only partially easier to read, because the interface and implementation are still mixed together. That is, you still see the source code-the implementation-because it's right there in the class. In addition, the comment documentation supported by javadoc (described in Chapter 2) lessens the importance of code readability by the client programmer. Displaying the interface to the consumer of a class is really the job of the class browser, a tool whose job is to look at all the available classes and show you what you can do with them (i.e., what members are available) in a useful fashion. Class browsers have become an expected part of any good Java development tool.

In Java, the access specifiers can also be used to determine which classes within a library will be available to the users of that library. If you want a class to be available to a client programmer, you use the public keyword on the entire classdefinition. This controls whether the client programmer can even create an object of the class.

To control the access of a class, the specifier must appear before the keyword class.Thus you can say:

public class Widget {

Now if the name of your library is mylib, any client programmer can access Widget by saying

import mylib.Widget;

or

import mylib.*;

However, there's an extra set of constraints:

• There can be only one public class per compilation unit (file). The idea is that each compilation unit has a single public interface represented by that public class. It can have as many supporting package-access classes as you want. If you have more than one public class inside a compilation unit, the compiler will give you an error message.
• The name of the public class must exactly match the name of the file containing the compilation unit, including capitalization. So for Widget, the name of the file must be Widget.java, not widget.java or WIDGET.java. Again, you'll get a compile-time error if they don't agree.
• It is possible, though not typical, to have a compilation unit with no public class at all. In this case, you can name the file whatever you like.

What if you've got a class inside mylib that you're just using to accomplish the tasks performed by Widget or some other public class in mylib? You don't want to go to the bother of creating documentation for the client programmer, and you think that sometime later you might want to completely change things and rip out your class altogether, substituting a different one. To give you this flexibility, you need to ensure that no client programmers become dependent on your particular implementation details hidden inside mylib. To accomplish this, you just leave the public keyword off the class, in which case it has package access. (That class can be used only within that package.)

When you create a package-access class, it still makes sense to make the fields of the class private-you should always make fields as private as possible-but it's generally reasonable to give the methods the same access as the class (package access). Since a package-access class is usually used only within the package, you only need to make the methods of such a class public if you're forced to, and in those cases, the compiler will tell you.

Note that a class cannot be private (that would make it accessible to no one but the class) or protected. (30) So you have only two choices for class access: package access or public. If you don't want anyone else to have access to that class, you can make all the constructors private, thereby preventing anyone but you, inside a static member of the class, from creating an object of that class. Here's an example:

//: c05:Lunch.java
// Demonstrates class access specifiers. Make a class
// effectively private with private constructors:
 
class Soup {
	private Soup() {}
	// (1) Allow creation via static method:
	public static Soup makeSoup() {
		return new Soup();
	}
	// (2) Create a static object and return a reference
	// upon request.(The "Singleton" pattern):
	private static Soup ps1 = new Soup();
	public static Soup access() {
		return ps1;
	}
	public void f() {}
}
 
class Sandwich { // Uses Lunch
	void f() { new Lunch(); }
}
 
// Only one public class allowed per file:
public class Lunch {
	void test() {
		// Can't do this! Private constructor:
		//! Soup priv1 = new Soup();
		Soup priv2 = Soup.makeSoup();
		Sandwich f1 = new Sandwich();
		Soup.access().f();
	}
} ///:~

Up to now, most of the methods have been returning either void or a primitive type, so the definition:

public static Soup access() {
	return ps1;
}

might look a little confusing at first. The word before the method name (access) tells what the method returns. So far, this has most often been void, which means it returns nothing. But you can also return a reference to an object, which is what happens here. This method returns a reference to an object of class Soup.

The class Soup shows how to prevent direct creation of a class by making all the constructors private. Remember that if you don't explicitly create at least one constructor, the default constructor (a constructor with no arguments) will be created for you. By writing the default constructor, it won't be created automatically. By making it private, no one can create an object of that class. But now how does anyone use this class? The preceding example shows two options. First, a static method is created that creates a new Soup and returns a reference to it. This could be useful if you want to do some extra operations on the Soup before returning it, or if you want to keep count of how many Soup objects to create (perhaps to restrict their population).

The second option uses what's called a design pattern, which is covered in Thinking in Patterns (with Java) at www.BruceEckel.com. This particular pattern is called a "singleton" because it allows only a single object to ever be created. The object of class Soup is created as a static private member of Soup, so there's one and only one, and you can't get at it except through the public method access( ).

As previously mentioned, if you don't put an access specifier for class access, it defaults to package access. This means that an object of that class can be created by any other class in the package, but not outside the package. (Remember, all the files within the same directory that don't have explicit package declarations are implicitly part of the default package for that directory.) However, if a static member of that class is public, the client programmer can still access that static member even though they cannot create an object of that class.

In any relationship it's important to have boundaries that are respected by all parties involved. When you create a library, you establish a relationship with the user of that library-the client programmer-who is another programmer, but one putting together an application or using your library to build a bigger library.

Without rules, client programmers can do anything they want with all the members of a class, even if you might prefer they don't directly manipulate some of the members. Everything's naked to the world.

This chapter looked at how classes are built to form libraries: first, the way a group of classes is packaged within a library, and second, the way the class controls access to its members.

It is estimated that a C programming project begins to break down somewhere between 50K and 100K lines of code because C has a single "name space": names begin to collide, causing an extra management overhead. In Java, the package keyword, the package naming scheme, and the import keyword give you complete control over names, so the issue of name collision is easily avoided.

There are two reasons for controlling access to members. The first is to keep users' hands off tools that they shouldn't touch: tools that are necessary for the internal operations of the data type, but not part of the interface that users need to solve their particular problems. So making methods and fields private is a service to users, because they can easily see what's important to them and what they can ignore. It simplifies their understanding of the class.

The second and most important reason for access control is to allow the library designer to change the internal workings of the class without worrying about how it will affect the client programmer. You might build a class one way at first, and then discover that restructuring your code will provide much greater speed. If the interface and implementation are clearly separated and protected, you can accomplish this without forcing users to rewrite their code.

Access specifiers in Java give valuable control to the creator of a class. The users of the class can clearly see exactly what they can use and what to ignore. More important, though, is the ability to ensure that no user becomes dependent on any part of the underlying implementation of a class. If you know this as the creator of the class, you can change the underlying implementation at will, because you know that no client programmer will be affected by the changes; they can't access that part of the class.

When you have the ability to change the underlying implementation, you can freely improve your design. You also have the freedom to make mistakes. No matter how carefully you plan and design, you'll make mistakes. Knowing that it's relatively safe to make these mistakes means you'll be more experimental, you'll learn more quickly, and you'll finish your project sooner.

The public interface to a class is what the user does see, so that is the most important part of the class to get "right" during analysis and design. Even that allows you some leeway for change. If you don't get the interface right the first time, you can add more methods, as long as you don't remove any that client programmers have already used in their code.

Solutions to selected exercises can be found in the electronic document The Thinking in Java Annotated Solution Guide, available for a small fee from www.BruceEckel.com.

1. Write a program that creates an ArrayList object without explicitly importing java.util.*.
2. In the section labeled "package: the library unit," turn the code fragments concerning mypackage into a compiling and running set of Java files.
3. In the section labeled "Collisions," take the code fragments and turn them into a program and verify that collisions do in fact occur.
4. Generalize the class P defined in this chapter by adding all the overloaded versions of rint( ) and rintln( ) necessary to handle all the different basic Java types.
5. Create a class with public, private, protected, and package-access fields and method members. Create an object of this class and see what kind of compiler messages you get when you try to access all the class members. Be aware that classes in the same directory are part of the "default" package.
6. Create a class with protected data. Create a second class in the same file with a method that manipulates the protected data in the first class.
7. Change the class Cookie as specified in the section labeled "protected: inheritance access." Verify that bite( ) is not public.
8. In the section titled "Class access" you'll find code fragments describing mylib and Widget. Create this library, then create a Widget in a class that is not part of the mylib package.
9. Create a new directory and edit your CLASSPATH to include that new directory. Copy the P.class file (produced by compiling com.bruceeckel.tools.P.java)to your new directory and then change the names of the file, the P class inside, and the method names. (You might also want to add additional output to watch how it works.) Create another program in a different directory that uses your new class.
10. Following the form of the example Lunch.java, create a class called ConnectionManager that manages a fixed array of Connection objects. The client programmer must not be able to explicitly create Connection objects, but can only get them via a static method in ConnectionManager. When the ConnectionManager runs out of objects, it returns a null reference. Test the classes in main( ).
11. Create the following file in the c05/local directory (presumably in your CLASSPATH):

// c05:local:PackagedClass.java
package c05.local;
class PackagedClass {
	public PackagedClass() {
		System.out.println("Creating a packaged class");
	}
}

Then create the following file in a directory other than c05:

// c05:foreign:Foreign.java
package c05.foreign;
import c05.local.*;
public class Foreign {
	public static void main (String[] args) {
		PackagedClass pc = new PackagedClass();
	}
}

Explain why the compiler generates an error. Would making the Foreign class part of the c05.local package change anything?