Java programs are organized as sets of packages. There are two possible kinds of members in a package. The first type are called "compilation units". A compilation unit is a Java class or interface. Each class or interface has a name and the organization of these various named classes and interfaces into packages helps to prevent name conflicts. The second type of member is called a subpackage and may contain compilation units and subpackages of its own.

The naming structure for packages is hierarchical, with the hierarchy being separated by the '.' character. Example packages that are found in the Java Development Kit (JDK) are:

java
java.lang
java.awt
java.awt.event

Note however that the relationship between packages is not hierarchical. There is no implicit relationship between the package java.awt and java.awt.event. The package java.awt.event is a subpackage of java.awt in name only. The compilation units in java.awt have no special access to the compilation units of java.awt.event, and vice versa. All packages should be thought of as being independent of one another. The only exception to this is that all packages automatically import all of the public types declared in the predefined package java.lang.

Since the comilation units of packages are independent of one another, there are rules that allow them to access each other. A compilation unit in a package is accessible outside the package that declares it only if the it is declared public. If a compilation unit in a package is not declared public then it is not accesible from outside the package. Thus you can control access to your classes and interfaces by placing them in packages.

To declare that your Java class or interface is part of a package, you use a package statement. For example:

package hello.world;


public class HelloWorld {
}

In the above example, the class HelloWorld has been declared to be part of the package hello.world.

To use classes or interfaces from a another package in your Java class or interface, you add an import statement for the package that you want to import. For example:

package hello.world;

import java.awt.Button;
import java.awt.event.*;

public class HelloWorld {
}

The first import statement in the above example imports a single class, while the second statement imports all classes and interfaces from package java.awt.event.

A package may consist of a number of compilation units. A compilation unit automatically has access to all types declared in its package and also automatically imports all of the public types declared in the predefined package java.lang. For example, the class java.awt.Button automatically imports all other classes and interfaces in the package java.awt so it is not necessary to put an import statement in class java.awt.Button for any classes in package java.awt.

A package can be stored in a file system or in a database. Packages that are stored in a file system, as with the code generated by JBuilder, have certain constraints on the organization of their compilation units to allow for a simple implementation to find classes easily. In the current implemenation of Java (JDK 1.3) packages are constrained in that package names on the file system are mirrored with directory names. An example follows:

Given a class named test.package.SampleClass which is defined in the file SampleClass.java:

• The package name is test.package
• The class name is SampleClass
• The package name is represented on the file system by the directory structure testpackage
• Thus, the source file SampleClass.java will be found at testpackageSampleClass.java

If no package name is specified in a class or interface then that class or interface is said to be part of the "default" or "unnamed" package. Note that if you place your class or interface in the default package then all other classes or interfaces in all other packages will have access to that class (unless it is declared private). For this reason it is considered good practice to put all classes and interfaces in packages.

Try creating a new class in JBuilder and giving it a package name. With a Project open, follow these steps to do this:

1. Click File | New Class. The Class Wizard appears.
2. In the Package name field type myFirstPackage.
3. In the Class name field type MyFirstPackageClass.
4. Click OK. The Class Wizard exits and JBuilder generates the source file for the new class.

Notice that JBuilder generates the following code:

package myFirstPackage;

/**
 * Title:
 * Description:
 * Copyright:    Copyright (c) 2001
 * Company:
 * @author
 * @version 1.0
 */

public class MyFirstPackageClass {

   public MyFirstPackageClass() {
   }
}

You now have a class called MyFirstPackageClass that is part of the package myFirstPackage. Also note that JBuilder created the new class file MyFirstPackageClass.java in a directory called myFirstPackage under your project Source directory. When JBuilder generates a java class it automatically creates that class in the appropriate location on the file system based on the package name.