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
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.