7.2.1 Storing Packages in a File System

7.2.1 Storing Packages in a File System

As an extremely simple example, all the Java packages and source and binary code on a system might be stored in a single directory and its subdirectories. Each immediate subdirectory of this directory would represent a top-level package, that is, one whose fully qualified name consists of a single simple name. The directory might contain the following immediate subdirectories:

COM
gls
jag
java
wnj

where directory java would contain the standard Java Application Programming Interface packages that are part of every standard Java system; the directories jag, gls, and wnj might contain packages that the three authors of this specification created for their personal use and to share with each other within this small group; and the directory COM would contain packages procured from companies that used the conventions described in §7.7 to generate unique names for their packages.

Continuing the example, the directory java would probably contain at least the following subdirectories:

applet  
awt
io
lang
net
util

corresponding to the standard packages java.applet, java.awt, java.io, java.lang, java.net, and java.util that are defined as part of the standard Java Application Programming Interface.

Still continuing the example, if we were to look inside the directory util, we might see the following files:

BitSet.java                                     Observable.java
BitSet.class                                        Observable.class
Date.java                                       Observer.java
Date.class                                      Observer.class
Dictionary.java                                     Properties.java
Dictionary.class                                        Properties.class
EmptyStackException.java                                        Random.java
EmptyStackException.class                                       Random.class
Enumeration.java                                        Stack.java
Enumeration.class                                       Stack.class
Hashtable.java                                      StringTokenizer.java
Hashtable.class                                     StringTokenizer.class
NoSuchElementException.java                                     Vector.java
NoSuchElementException.class                                        Vector.class

where each of the .java files contains the source for a compilation unit (§7.3) that contains the definition of a class or interface whose binary compiled form is contained in the corresponding .class file.

Under this simple organization of packages, an implementation of Java would transform a package name into a pathname by concatenating the components of the package name, placing a file name separator (directory indicator) between adjacent components. For example, if this simple organization were used on a UNIX system, where the file name separator is /, the package name:

jag.scrabble.board

would be transformed into the directory name:

jag/scrabble/board

and:

COM.Sun.sunsoft.DOE

would be transformed to the directory name:

COM/Sun/sunsoft/DOE

In fact, the standard JavaSoft Java Developer's Kit on UNIX differs from the very simple discipline described here only in that it provides a CLASSPATH environment variable that specifies a set of directories, each of which is treated like the single directory described here. These directories are searched in order for definitions of named packages and types.

A package name component or class name might contain a character that cannot correctly appear in a host file system's ordinary directory name, such as a Unicode character on a system that allows only ASCII characters in file names. As a convention, the character can be escaped by using, say, the @ character followed by four hexadecimal digits giving the numeric value of the character, as in the \uxxxx escape (§3.3), so that the package name:

children.activities.crafts.papierM\u00e2ch\u00e9

which can also be written using full Unicode as:

children.activities.crafts.papierMache;

might be mapped to the directory name:

children/activities/crafts/papierM@00e2ch@00e9

If the @ character is not a valid character in a file name for some given host file system, then some other character that is not valid in a Java identifier could be used instead.