With some exceptions that are beyond the scope of this web page, each Java class is defined in a separate source code file. The name of the file should be the same as the class name with a .java suffix. Thus the definition for a class named Comparators should be in a file named Comparators.java. If the operating system uses case-sensitive file names then the .java suffix should be all lower case and the case of the rest of the file name should match the case of the class name.

It is a good programming practice to group source code files into packages of related classes, with each package in a separate directory. For compatibility with Java development software, the directories should be arranged as one or more hierarchies, each with the name classes. To enable development software to accesss the packages, you need to set a CLASSPATH environmental variable in your login startup script (the .personal file for UNIX machines here at UMD). For example, I have most of my classes rooted in my subdirectory public/lib. To allow development software to access the classes, I have added the following line to my .personal file:

    setenv CLASSPATH .:$HOME/myjava/lib
      

In general, the CLASSPATH variable is set to a list of directories separated by colons. In the above command, the list contains two directories: my classes directory and the current directory (using the UNIX period abbreviation). The current directory is added to allow access to classes in the current directory that do not have package statements.

For import statements, described in the next section, it is important to know how packages are named in Java. By way of example, my classes directory contains a subdirectory named gshute/util. Each class in this subdirectory has the following package statement:

    package gshute.util;
      

that is, the package name is the path name of the subdirectory, relative to my CLASSPATH variable, with periods replacing the slashes.

A Java source code file normally has the following structure:

    package statement

    import statements

    class definition
      

If the name of the class defined in the file is A then the file must be named A.java.

When you are writing code for a class, it will often play the role of a client for another class, which plays the role of a server class. In Java, the server class and any classes appearing in its interface must be imported by the client. This includes the server class itself and any classes used to define method parameter types or returned value types for server methods. Classes that are part of the package that contains the client class or part of the java.lang standard library package do not need import statements.

Server classes are imported with import statements. These statements should appear near the beginning of a Java source code file, immediately after the package statement. An import statement has the following syntax:

    import fully-qualified-class-name;
      

A fully-qualified-class-namehas the form

    package-name.class-name
      

For example, if I want to import my Comparators class, which is defined in the gshute/util subdirectory then I use the following import statement.

    import gshute.util.Comparators;
      

It is a common practice to import a complete package. This can be done with the wild card "*" replacing the class name. For example, the following import imports the entire java.util package.

    import java.util.*;