Packages - A set of rules to keep your compiler and interpreter happy happy.

Many people in comp.lang.java.programmer have problems compiling when they first enter the dizzy world of packages. There are various ways you can get everything to work, and this is just one of them - but I believe it's one of the easiest ways to get things to work.

Setting the scene

I'll assume for the moment that you're working on Windows, using a compiler that takes the standard javac options (jikes does). If you're on Unix, I'm sure you can work out what the equivalent would be.
Let's say you have two packages, com.mycompanypackage containing classes CompanyApp and BusinessLogic; and org.mypersonalpackages.util containing classes Semaphore and HandyBits. BusinessLogic needs access to HandyBits (and your boss has waived rights to your personal code so long as you don't mind putting it in the product!)

Coding and compiling

First things first: source organisation. You need to choose a "root" directory for your source tree. (I'll just call this the root from here onwards.) I'll use c:\java for my examples.
You should have four files for your source code:
- c:\java\com\mycompanypackage\CompanyApp.java
- c:\java\com\mycompanypackage\BusinessLogic.java
- c:\java\org\mypersonalpacakges\util\Semaphore.java
- c:\java\org\mypersonalpacakges\util\HandyUtil.java
Note that the source files are organised in the same way as the package structure. This is very important, as it helps to tell the compiler where to find things - as well as making it much easier for you to find your source code later on.
At the top of each of your source files (before any imports or anything else other than comments), you should have a package declaration. For example, CompanyApp.java would start with:
```
package com.mycompanypackage;
```
If your class needs to import anything from other packages, it can do it after that. For instance, BusinessLogic.java could start:
```
package com.mycompanypackage;
import org.mypersonalpackages.util.*;
```
or possibly
```
package com.mycompanypackage;
import org.mypersonalpackages.util.HandyUtil;
```
Some people like using import-on-demand (the first version), others don't. To be honest, it's mainly a matter of laziness. I use import-on-demand because I'm lazy. I realise that it could create incompatibilities if names clash later on, but within the standard Java packages that I use that's not likely to happen very often. (This is partly because I don't do much GUI work. If I were using the java.awt and java.util packages in the same class, I'd be more careful. I'll try to keep my publicly available source a bit cleaner though. (Don't look yet - I haven't done the cleaning!)
Time to compile the classes. I usually compile everything, just to make sure I'll get the most recent version of all classes. There are some non-obvious dependencies in Java, such as constants from one class being embedded in another (eg if HandyUtil refers to Semaphore.SOME_CONSTANT which is a static final primitive/literal String, the value will be embedded in HandyUtil.class.) There are two ways you could compile everything. Either specify it explicitly:
```
c:\java> javac -d . com\mycompanypackage\*.java org\mypersonalpackage\util\*.java
```
or create a list of files and pass that to javac:
```
c:\java> dir /s /b *.java > srcfiles.txt
c:\java> javac -d . @srcfiles.txt
```
Note that you compile from the root directory, and you specify -d . to tell the compiler to put the classes in a package structure starting at the root too. Some people don't like keeping class and source files together - in that case, you could use -d classes, although you need to create the classes directory first. (You'll also need to either compile everything each time or put classes on the classpath for the compiler with the -classpath option.) Unless you really know what you're doing, I suggest you use the above and make sure you don't have a classpath set. If you must use a classpath for some reason (see my notes on the extension mechanism for ways to avoid this), make sure that . (the current directory) is on the classpath.

Running the application

Many people "accidentally" end up with their classes in the right place, etc, just by luck, but then run into errors like:

java.lang.NoClassDefFoundError: MyCompanyApp (wrong name:
com/mycompanypackage/MyCompanyApp

. Hopefully, if you've understood everything above, you won't run into this. It happens if you try to run your code using something like this:

c:\java\com\mycompanypackage> java MyCompanyApp

Here's how to avoid it:

Stay in your "root" directory, eg c:\java
Always use the fully qualified classname. So, for example:
```
c:\java> java com.mycompanypackage.MyCompanyApp
```
The JVM knows to find that class file in the directory com\mycompanypackage (note, this is a VM-specific convention, it's just that almost all VMs use it - there's nothing in the language specification to say that packages have to be stored that way; the VM just has to know how to find and load a class), but there's something in the class file which says what its fully qualified name is - and the VM uses that to check that the class its been asked to load is actually the one it's found. That's why you get the error above - if you can understand that error, you're a long way towards understanding how packages work.

Back to the main page.