Package and Document

Packaging and Documenting Your Classes

Now that you know just about everything there is to know about creating classes, this chapter shows you what to do with the classes you create. Specifically, I show you how to organize your classes into neat packages. Packages enable you to keep your classes separate from classes in the Java API, allow you to reuse your classes in other applications, and even let you distribute your classes to others, assuming other people might be interested in your classes.

If that's the case, you probably won't want to just send those people all your separate class files. Instead, you want to bundle them into a single file called a JAR file. That's covered in this chapter too.

Finally, you find out how to use a feature called JavaDocs that lets you add documentation comments to your classes. With JavaDocs, you can build professional-looking documentation pages automatically. Your friends will think you're a real Java guru when you post your JavaDoc pages to your Web site.

Working with Packages

A package is a group of classes that belong together. Without packages, the entire universe of Java classes would be a huge unorganized mess. Imagine the thousands of classes that are available in the Java API combined with millions of Java classes created by Java programmers throughout the world, all thrown into one big pot. Packages let you organize this pot into smaller, manageable collections of related classes.

Importing classes and packages

When you use import statements at the beginning of a Java source file, you make classes from the packages mentioned in the import statements available throughout the file. (I cover import statements in Book II, Chapter 1, but it doesn't hurt to repeat it here.)

An import statement can import all the classes in a package by using an asterisk wildcard:

import java.util.*;

Here all the classes in the java.util package are imported.

Alternatively, you can import classes one at a time:

import java.util.ArrayList;

Here just the ArrayList class is imported.

Note

You don't have to use an import statement to use a class from a package. But if you don't use an import statement, you must fully qualify any references to the class. For example, you can use the ArrayList class without importing java.util: java.util.ArrayList = new java.util.ArrayList();

Because fully qualified names are a pain to always spell out, you should always use import statements to import the packages or individual classes your application uses.

You never have to explicitly import two packages:

• java.lang: This package contains classes that are so commonly used that the Java compiler makes them available to every program. Examples of the classes in this package are String, Exception, and the various wrapper classes, such as Integer and Boolean.

• The default package: This package contains classes that aren't specifically put in some other package. All the programs I show in this book up to this point rely on the default package.

For simple program development and experimentation, using the default package is acceptable. However, if you start work on a serious Java application, create a separate package for it and place all the application's classes there. You find out how to do that in the next section.

TECHNICAL STAUFF

You can't import the default package, even if you want to. Suppose you have two packages-the default package and the com.lowewriter.util package. The default package's code contains the statement import com.lowewriter.util.*. That's okay. But the default package doesn't have a name-at least it has no name that you can use inside a program. The com.lowewriter.util package's code can't contain a statement like import that_default_package.you_know.the_one_with_no_name.

Creating your own packages

Creating your own packages to hold your classes is easy. Well, relatively easy anyway. You must go through a few steps:

1. Pick a name for your package.

   You can use any name you wish, but I recommend you follow the established convention of using your Internet domain name (if you have one), only backwards. I own a domain called http://www.LoweWriter.com, so I use the name com.lowewriter for all my packages. (Using your domain name backwards ensures that your package names are unique.)

   Notice that package names are in all-lowercase letters. That's not an absolute requirement, but it's a Java convention that you ought to stick to. If you start using capital letters in your package names, you'll be branded a rebel for sure.

   Tip

   You can add additional levels beyond the domain name if you want. For example, I put my utility classes in a package named com.lowewriter. util.

   If you don't have a domain all to yourself, try using your e-mail address backwards. For example, if your e-mail address is SomeBody@SomeCompany.com, use com.somecompany.somebody for your package names. That way they are still unique. (If you ever want to distribute your Java packages, you should register a domain name. Nothing says "Amateur" like a package name that starts with com.aol.)

2. Choose a directory on your hard drive to be the root of your class library.

   You need a place on your hard drive to store your classes. I suggest you create a directory such as c:\javaclasses.

   This folder becomes the root directory for your Java packages.

3. Create subdirectories within the root directory for your package name.

   For example, for the package named com.lowewriter.util, create a directory named com in the c:\javaclasses directory (assuming that's the name of your root). Then, in the com directory, create a directory named lowewriter. Then, in lowewriter, create a directory named util. Thus, the complete path to the directory that contains the classes for the com.lowewriter.util package is c:\javaclasses\ com\lowewriter\util.

4. Add the root directory for your package to the ClassPath environment variable.

   The exact procedure for doing this depends on your operating system. In Windows XP and Vista, you can set the ClassPath by double-clicking System from the Control Panel. Click the Advanced tab, and then click Environment Variables.

   Be careful not to disturb any directories already listed in the ClassPath. To add your root directory to the ClassPath, add a semicolon followed by the path to your root directory to the end of the ClassPath value. For example, suppose your ClassPath is already set to this:

        .;c:\util\classes
   

   Then you modify it to look like this:

        .;c:\util\classes;c:\javaclasses
   

   Here I added ;c:\javaclasses to the end of the ClassPath value.

5. Save the files for any classes you want to be in a particular package in the directory for that package.

   For example, save the files for a class that belongs to the com.lowewriter.util package in c:\javaclasses\com\ lowewriter\util.

6. Add a package statement to the beginning of each source file that belongs in a package.

   The package statement simply provides the name for the package that any class in the file is placed in. For example:

        package com.lowewriter.util;
   

   REMEMBER

   The package statement must be the first non-comment statement in the file.

An example

Suppose you've developed a utility class named Console that has a bunch of handy static methods for getting user input from the console. For example, this class has a static method named askYorN that gets a Y or N from the user and returns a boolean value to indicate which value the user entered. You decide to make this class available in a package named com.lowewriter.util so you and other like-minded programmers can use it in their programs.

Here's the source file for the Console class:

package com.lowewriter.util;

import java.util.Scanner;

public class Console
{

    static Scanner sc = new Scanner(System.in);

    public static boolean askYorN(String prompt)
    {
    while (true)
    {
       String answer;
       System.out.print("\n" + prompt
          + " (Y or N) ");
       answer = sc.next();
       if (answer.equalsIgnoreCase("Y"))
           return true;
       else if (answer.equalsIgnoreCase("N"))
           return false;
    }
    }
}

Okay, so far this class has just the one method (askYorN), but one of these days you'll add a bunch of other useful methods to it. In the meantime, you want to get it set up in a package so you can start using it right away.

So you create a directory named c:\javaclasses\com\lowewriter\util (as described in the preceding section) and save the source file to this directory. Then you compile the program so the Console.class file is stored in that directory too. And you add c:\javaclasses to your ClassPath environment variable.

Now you can use the following program to test that your package is alive and well:

import com.lowewriter.util.*;

public class PackageTest
{
  public static void main(String[] args)
  {
      while (Console.askYorN("Keep going?"))
      {
          System.out.println("D'oh!");

      }
  }
}

Here the import statement imports all the classes in the com.lowewriter. util package. Then, the while loop in the main method repeatedly asks the user if he or she wants to keep going.