Section 8.7 Packages
Subsection 8.7.1 Packages
A Java package is a bundle of related classes and other types that are collected under a single name. The package name works like a scope in the sense that types in a package may be accessed using the package name with dot-notation. In large programs there are several good reasons to organize types into packages. These include:
- Types collected in a single package suggest they are related.
- Packaging types avoids name conflicts with types having the same name in other packages because a type name can be disambiguated using the package name as its scope.
- Packages have scoping rules that allow members of a single package unrestricted access to other members of the package, while restricting access to package members from outside the package. This is called package scoping with private visibility, often shortened to package-private.
To both define a package and place a class into the package, simply add a
package statement as the first line in any file naming the package. For example,package doodlepad;
If you refer to the DoodlePad 1 source code repository, you will find this line at the top of every source code file. This puts all classes into the
doodlepad package, and is the reason why we add a line like import doodlepad.*; to the top of our graphics programs. This statement imports all types from the doodlepad package into your program. The package name is doodlepad and the * is a wildcard matching all public types in the package. You are free to create your own packages using a similar syntax.Using the
doodlepad package name helps to disambiguate classes defined in that package from classes having the same name in other packages. For example, the DoodlePad Rectangle class has the same name as Java’s Rectangle class defined in its Abstract Window Toolkit (AWT) package. These classes don’t conflict because their fully-qualified names are different. Namely, the DoodlePad class has a fully-qualified name of doodlepad.Rectangle and the Java AWT class has the fully-qualified name java.awt.Rectangle.Subsection 8.7.2 The Default Package
Even if you don’t specify a package name for your program, Java puts your classes into a package. The default package is the one named
"", in other words, the default package has no name. All the classes that we have created thus far have no package statement, therefore they have been placed into the default package, automatically.Subsection 8.7.3 Subpackages and Package Organization
It is a best practice to organize your source code files into a subfolder structure that matches the names and structure of your package organization scheme. Package names are usually chosen to be lowercase, in order to distinguish them from class names, which usually start with a capital letter.
We often see these best practices at play when working with commercial software. Companies that produce Java packages tend to use the reversed components of their Internet domain name as their package structure. This helps to make their packages globally unique because only they own their domain name. If you started a consulting company named "Java Maniac" and purchased the domain name javamaniac.com, you might organize your Java classes with a
com.javamaniac package scheme, and arrange your source code in a "com/javamaniac/" subfolder structure. Note how this specifies both the folder named "com" and a further subfolder named "javamaniac" to contain your types. This avoids the name conflict that would occur with types from the Java Charmer company with the domain name "javacharmer.com." They organize their classes in the "com/javacharmer/" subfolder structure. When you add the statement import com.javamaniac.*; to your program, the Java compiler will look in "com/javamaniac/" to find these compiled files and check that the way you use them matches their definitions.Let’s consider another example. Let’s assume you have defined two classes named "Hammer" and "Drill" and declared them to be grouped in a package named "toolbox." You could define the two classes as in Listing 8.7.1 and Listing 8.7.2, and place them in a subfolder of your project named "toolbox". Let’s assume that your main driver class is named "Construction" which is added to the folder above your "toolbox" subfolder (See Listing 8.7.3).
// Hammer.java
package toolbox;
public class Hammer {
// Hammer fields
private String sound;
// Hammer Constructor
public Hammer() {
this.sound = "Bang!";
}
// String representation of a Hammer
public String toString() {
return this.sound;
}
}
toolbox/Hammer.java// Drill.java
package toolbox;
public class Drill {
// Drill fields
private String sound;
// Drill Constructor
public Drill() {
this.sound = "Bzzz!";
}
// String representation of a Drill
public String toString() {
return this.sound;
}
}
toolbox/Drill.java// Construction.java
public class Construction {
public static void main(String[] args) {
// Get tools from the toolbox
toolbox.Hammer tool1 = new toolbox.Hammer();
toolbox.Drill tool2 = new toolbox.Drill();
// Sounds of the construction project.
System.out.println( tool1 + " " + tool2 );;
}
}
Construction.javaTo compile this multi-file program we can use commands like those in the following shell session. Note how we are not required to specify all files in the "toolbox" subfolder by name. We can make use of the wildcard character (
*) as in toolbox/*.java, which will compile all files in the "toolbox" subfolder with any name that has a .java extension. As expected, the output from running the Construction driver class is the sounds of all tools used on the construction project.javac Construction.java toolbox/*.java java Construction Bang! Bzzz!
Because all of our toolbox classes are in the "toolbox" package, we accessed them using the package name. For example, see the
toolbox. prefix in the following two lines from Listing 8.7.3.toolbox.Hammer tool1 = new toolbox.Hammer();
toolbox.Drill tool2 = new toolbox.Drill();
A more convenient option, especially when we intend to use most or all classes from a package, is to use the
import statement and the wildcard character (*) to import all accessible type names in the current package, which we have seen many times when importing DoodlePad classes with import doodlepad.*. Listing 8.7.4 is an alternative implementation if the Construction driver class that imports all tool classes from the "toolbox" package at the top of the program file. This allows us to avoid the repeated explicit scoping of classes to the toolbox package. After an import, the class names are now known.// Construction.java
import toolbox.*; // Import all tools
public class Construction {
public static void main(String[] args) {
// Get tools from the toolbox
Hammer tool1 = new Hammer(); // No package needed
Drill tool2 = new Drill();
// Sounds of the construction project.
System.out.println( tool1 + " " + tool2 );;
}
}
Construction.javaPackages are extremely convenient for organizing the classes and other types in your larger projects and for avoiding name conflicts. Some developers use packages as a matter of course, and some programming editors will create them for you. We use packages only for larger examples. Otherwise, we rely on the default package in order to make our examples more readable and less cluttered.
Subsection 8.7.4 Core Library Packages
It is no surprise that the Java Core Library organizes its types into packages. Most core library types are located in the
java. top level package, but the core library organization changes on occasion and depends on your version of Java. It is best to refer to the Java API documentation 2 when in doubt.Under the
java. package in the Core Library, types are further divided into subpackages. For example, we’ve used many classes that are found in the java.util subpackage, such as java.util.Random and java.util.Scanner. When we start working with files we’ll use several classes in the java.io subpackage. Its worth noting that all types in the java.lang subpackage are imported automatically. That is were we find classes like String, and why we do not need to import java.lang.String in order to use the String class.Subsection 8.7.5 Package Scope
It should be obvious by now that packages (and subpackages) form a space of names that are grouped together (namespace). A Java scope provides this namespace for us. We now have the complete set of Java scope definitions within which names can exist. These also let us know when we may have to use explicit scoping to reach a name defined in a different scope, or how to address a type in a different package when importing.
- package scope (limited to a Java package).
- class scope (accessible throughout a class), and
- object (instance) scope (limited to a specific object),
- method scope (limited to a specific method),
- block scope (limited to a specific block of code),
Recall the Most Narrow Scope Feasible principle. We’ve learned how packages help us avoid name conflicts by grouping types in more narrow namespaces provided by a package scope.
github.com/russomf/doodlepad/tree/master/src/doodlepaddocs.oracle.com/en/java/javase/index.html
