Packages, JAR Files, and CLASSPATH

You can find the Sun tutorial on packages at http://java.sun.com/docs/books/tutorial/java/interpack/packages.html
The sun tutorial on jar files is located at http://java.sun.com/docs/books/tutorial/jar/basics/index.html
A good CLASSPATH tutorial is available at http://mindprod.com/jgloss/classpath.html

Java Packages

Packages are used to organize your classes. They resemble file folders, and in fact there is a correspondance between the two, which we will see later in this document. There are three basic uses for packages in Java:

Organize classes into categories, e.g. a package for data-manipulation classes, another package for user-interface classes, etc.
Avoid class naming conflicts. In other words, you can have two classes that are named the same as long as they are in different packages. In fact, you can think of the true name for a class as being the package and the class name combined.
Access control: the protected and package-level access modifiers allow access to methods and attributes of classes in the same package

The package that a Java class is in must be specified at the top of the .java file, e.g.

package com.acme.gadgets

public class Anvil {

}

Given the above example, the Anvil.java file should be in a the com\acme\gadgets subdirectory relative to the start of the project, e.g. C:\JavaProject\com\acme\gadgets\Anvil.java. When you compile this class, the .class must also use the same directory structure. There are two options here: Keep the source (.java) and .class files together in the same directory, or put the .class files in the separate directory, e.g.

C:\JavaProject\com\acme\gadgets\Anvil.class
C:\JavaProject\classes\com\acme\gadgets\Anvil.class

The second option allows you to package up classes together in one place, so you can conveniently distribute your application separately from the source code. I will show you in class how to do this using eclipse.

JAR Files

Jar files are a convenient way to distribute applications or libraries. The basic idea is that you can put a bunch of .class files into a single jar file archive. If you are familiar with zip files, jar files are the same idea. In fact, a jar file is a zip file behind the scenes! To collect a directory tree of .class files into a jar file, just use the convenient jar tool provided with the sun SDK (IDEs usually have a nice non-command line way of doing this too; and the 'ant' tool can help you to build jar files as well).

CLASSPATH

In order for javac to be able to compile .java files, and for java (the runtime) to execute .class files, these files must be searchable using the CLASSPATH environment variable. This variable must point to the folder that represents the start of any packages you wish to use. If the .class files are located on the disk as individual files, then CLASSPATH must point to the directory where the package structure starts. If the .class files are located in a JAR file, then the CLASSPATH variable must point to the directory where the jar file is located.

Exercise: Start off by creating the following class in C:\CatProject\com\acme\cats\Cat.java:

package com.acme.cats

public class Cat {
    public void chase {
        System.out.println("meow!");
    }
}

Next, create the following class in C:\DogProject\com\acme\dogs\Dog.java

package com.acme.dogs

import com.acme.cats.Cat;

public class Dog {
    public void chaseCat(Cat cat) {
        System.out.println("I'm chasing a cat!");
        cat.chase();
    }

    public static void main(String[] args) {
        Dog dog = new Dog();
        Cat cat = new Cat();

        dog.chaseCat(cat);
    }
}

Set the CLASSPATH environment variable in Windows so that it points to C:\CatProject;C:\DogProject. Next, use javac on the command line to compile both the Cat and Dog classes. Finally, go to the C:\DogProject directory and execute "java Dog" to run the program!