Section 3.3. Using (and Making) Java APIs

3.3. Using (and Making) Java APIs

With every class you write, you define a namethe name of the class. But what if someone else has already used that name? Java programming should encourage reuse of existing code, so how do you keep straight which names are available?

This is a namespace issuewho can use which names. A classic way to solve a namespace issue is to divide the namespace up into domains. On the Internet, host names are sectioned off into domains, so that I can have a host named Pluto or www and so can lots of othersbecause each host is qualified by its domain (e.g., myco.com). Thus www.myco.com isn't confused with www.otherco.com or www.hisgroup.org. Each host is named www, but each is unique because of the qualifying domain.

Java solves the problem in much the same way, but with the names in the reverse order. Think of the "host" as the class name; the "domain" name, used to sort out identical host names, is, in Java parlance, the package name. When you see a name like com.myco.finapp.Account, that can be a Java package com.myco.finapp qualifying a class named Account.

Beyond just keeping the namespace clean, Java packages serve another important function. They let you group together similar classes and interfaces to control access to them. Classes within the same package can access each others' members and methods even when they are not declared public, provided they are not declared to be private. This level of intimacy, sometimes called package protection, means that you should group classes together that are related, but avoid grouping too many classes together. It's tempting just to put all your classes for a project into the same package, for example, com.myco.ourproject, but you will provide better safety and perhaps promote better reuse by grouping them into several smaller packages, for example, com.myco.util, com.myco.financial, and com.myco.gui.

3.3.1. The package Statement

So how do you make a Java class part of a package? It's easyyou just put, as the first (noncomment) line of the file, the package statement, naming the package to which you want this class to belong. So if you want your Account class to be part of the com.myco.financial package, your Java code would look as shown in Example 3.23.

Example 3.23. Use of a package statement

 package com.myco.financial; public class Account {   // ... } 

Making a class part of a package is easy. What's tricky is putting the class file in the right location so that Java can find it.

Think of the current directory as the root of your package tree. Each part of a package name represents a directory from that point on down. So if you have a package named com.myco.financial then you'll need a directory named com and within that a directory named myco and within that a directory named financial. Inside that financial directory you can put your Account.class file.

When Java runs a class file, it will look in all the directories named in the CLASSPATH environment variable. Check its current value:

 $ echo $CLASSPATH $ 

If it's empty, as in this example, then the only place where it will look for your classes will be the current directory. That's a handy default, because it is just what you want when your class file has no package statement in it. With no package statement, your class becomes part of the unnamed package. That's fine for simple sample programs, but for serious application development you'll want to use packages.

Let's assume that you're in your home directory, /home/joeuser, and beneath that you have a com directory and beneath that a myco directory with two subdirectories financial and util. Then with your classes in those lower level directories, you can run your Java program from the home directory. If you want to run it from any arbitrary directory (e.g., /tmp or /home/joeuser/alt) then you need to set CLASSPATH so it can find this package tree. Try:

 $ export CLASSPATH="/home/joeuser" $ 

Now Java knows where to look to find classes of the com.myco.financial and com.myco.util packages.

3.3.2. The import Statement

Once we have put our classes into packages, we have to use that package's name when we refer to those classesunless we use the import statement.

Continuing our example, if we want to declare a reference to an Account object, but Account is now part of com.myco.financial, then we could refer to it with its full name, as in:

 com.myco.financial.Account =     new com.myco.financial.Account(user, number); 

which admittedly is a lot more cumbersome than just:

 Account = new Account(user, number); 

To avoid the unnecessarily long names, Java has import statements. They are put at the beginning of the class file, outside the class definition, just after any package statement. In an import statement, you can name a class with its full name, to avoid having to use the full name all the time. So our example becomes:

 import com.myco.financial.Account; // ... Account = new Account(user, number); 

If you have several classes from that package that you want to reference, you can name them all with a "*", and you can have multiple different import statements, as in:

 import java.util.*; import com.myco.financial.*; // ... Account = new Account(user, number); 

Here are a few things to remember about import statements. First, they don't bring in any new code into the class. While their syntax and placement is reminiscent of the C/C++ include preprocessor directive, their function is not the same. An import statement does not include any new code; it only aids name resolution. Secondly, the "*" can only be used at the end of the package name; it is not a true wildcard in the regular expression sense of the word. Thirdly, every class has what is in effect an implicit import java.lang.* so that you don't need to put one there. References to String or System or other core language classes can be made without the need for either the import statement or the fully qualified name (except as described in the next paragraph).

If you need to use two different classes that have the same name but come from different packages, you will still need to refer to them by their full names; import can't help you here. As an example of this, consider the two classes java.util.Date and java.sql.Date (though with any luck you won't need to refer to both of them within the same class).