Creating a Package in Java

A package is a unique namespace for class names. It prevents collisions between programs and between libraries.

For instance, if you make a class called Spreadsheet and several other people also make a class called Spreadsheet, and for some reason all of those classes are available at runtime, only one can be loaded. (Actually it’s more complicated than that, but my statement is true for the most common cases.)

But if your class is named com.kataria.Spreadsheet, it is unlikely to collide with any other classes, since it’s unlikely they that have that package name.

The package name is part of the class name. Java does not have a class named List, but Java does have a class named java.util.List. An import statement is just compiler shorthand; import java.util.List; tells the compiler, “every time I write List, I actually mean java.util.List.”

Since the last part (known as the simple name) of a class name is only a shorthand, the two classes java.util.List and java.awt.List are different classes. There is no conflict between them. (However, if for some reason you wanted to import both, that would be a problem, because the compiler wouldn’t know whether List by itself in the code is supposed to be shorthand for java.util.List or java.awt.List.)

To enforce consistency, Java requires that every (public, top-level) class is in a file which exactly matches its name and package:

• java.util.List must be defined in a file called java/util/List.java
• com.kataria.Spreadsheet must be defined in a file called com/kataria/Spreadsheet.java
• com.example.ai.wopr.Brain must be defined in a file called com/example/ai/wopr/Brain.java
• etc.

Similarly, .class files must have the same naming and directory structure:

• The java.util.List class must be compiled to a file called java/util/List.class
• The com.kataria.Spreadsheet class must be compiled to a file called com/kataria/Spreadsheet.class
• The com.example.ai.wopr.Brain class must be compiled to a file called com/example/ai/wopr/Brain.class
• etc.

A search path is a very old operating system concept, far older than Java. All Windows and Unix systems use it for locating programs on the command line, and for locating loadable software libraries.

A search path is an ordered list of directories. When you enter a command, the terminal environment (shell) looks in each directory in the search path for that command.

Similarly, a Java classpath was originally a list of directories. If you enter the command java com.kataria.Spreadsheet, it would look in each directory specified in the classpath for a com/kataria/Spreadsheet.class file.

Not long after that, a Java classpath entry was allowed to be a .zip file or .jar file. Although they are single archive files and not directories, the entries in such an archive has to obey the same rules: to go back to the previous example, the first .jar file in the classpath which has a com/kataria/Spreadsheet.class entry will be the source from which the class is loaded at runtime.

A .jar file is actually a zip file which a different extension and a few special Java-specific entries. It is simply an easier way to deliver a Java program or library than copying around a bunch of files. (Also it is compressed, so it uses less space and can be loaded from disk faster.)

When you want to run a Java program, you normally set the classpath on the command line:

java -cp /home/kataria/my-spreadsheet.jar:/opt/javafx/lib/javafx.base.jar com.kataria.Spreadsheet 

You can also set an environment variable named CLASSPATH; this is based on the fact that the original system search paths have used (and continue to use) environment variables like “PATH” and “LD_LIBRARY_PATH”. I do not recommend setting CLASSPATH, since it will result in your program only running in one particular environment. The program would not run on any other computer unless that user also remembers to set their CLASSPATH variable.