The Java Environment

Jim's Pages => Java Pages => The Java Environment

Ok, that's a lousy name for this page. Mail me a better one.

Here we explore how to set up directories, path, classpath and all that tricky stuff to get your first programs running. These seem to be common stumbling blocks for people just starting in Java; maybe this page will help. After I wrote this I found Sun had a neat page on the subject, too. I'd suggest you start with Sun's Setting the Class Path and then pick up here.

The zip file javaenvironment.zip contains sample programs that match the first 5 sections of this page.

Unzip, creating a directory called javaenvironment.
Open a command window and navigate to the javaenvironment directory.
Set your path to include the bin directory of the JDK.
Run cleanup.bat to remove any residue from prior runs.
Change directory to bob and run go.bat. This is section 6 in the page, but we need the results right away.
Change to directory 1 through 5 and read and run go.bat

This is all based on Windows XP experience. If you'd like to customize it for *nix please send me an update!

1. Simplest Program

One source file
No package statement
No import statements except for the Java libraries

Let's start a simple one-class project, perhaps some homework for a class, a quick and dirty utility, or an experiment with something new in the JDK. For this discussion, our java file does not have a package statement at the top. It can import Java classes like java.io.InputStream but nothing that doesn't come with the JDK.

Editing

We'll make a directory for the project, and put our source file there. We can edit the source file with Notepad or any text editor we like.

	Project1
	TestOne.java

Compiling

To compile we'll open a command window along with the editor. We have to make sure Windows can find the compiler, JavaC.exe. The path is a list of directories where Windows looks for programs and we want it to include the bin directory of the JDK. Your location may vary depending on where you installed the JDK.

X:\> set path="C:\Program Files\j2sejdk500\bin"
X:\> java -version

The "java -version" command is a quick way to see if the path is good. It should display something like "java version 1.5.0" and more.

If you already have useful things in your path, you can preserve the old settings and add java. %path% in this command represents the existing path.

X:\> set path=%path%;"C:\Program Files\j2sejdk500\bin"

If you're going to do this all the time, you can set the path permanently. From the Start Menu in XP: Start / Settings / Control Panel / System / Advanced / Environment Variables.

Now we'll navigate to the Project1 directory and run the compiler. Say we start on some other drive:

X:\> C:
C:\> CD \Project1
C:\Project1> javac TestOne.java

If that worked, we'll now have a new class file.

	Project1
	TestOne.java
	TestOne.class

Running

The Java command starts the JVM. We tell the JVM what class to run and the JVM tries to call the main() method. There's nothing magical about main() except that the JVM looks for it. This ought to run your program:

C:>\Project1> java TestOne

2. Import & Classpath

One source file
No package statement
Import from a jar

Let's say our friend, Bob, gave us a jar file with utility classes. We put it in the project directory.

	Project2
	TestTwo.java
	TestTwo.class
	BobsUtilities.jar

We'd like to use the StringThing that Bob wrote. We add a line to our source file to import the class:

import com.bob.utility.strings.StringThing;

The compiler complains that it cannot find StringThing. The solution is to set the classpath, which is a list of directories where Java should look for classes. Note that we use the same technique as before to preserve whatever was already in the classpath.

C:\Project2> set classpath=.;%classpath%;BobsUtilities.jar

That dot semi-colon in there is important to include the current directory. That's where TestTwo.class is so we have to have it. If you already have a classpath, it might have the dot in there. Check by displaying the current classpath:

C:\Project2> echo %classpath%

The compiler (Java.exe) and the runtime (JavaC.exe) can both find the utility jar. You can use jars from any directory on your system by specifying the path. Later on we'll talk about keeping special folder for third party jars.

3. Using Packages

Multiple source files
Using import
Using packages

We can think of Java packages as being just like folder structures on our disk drives. Packages give you a way to organize code. You might make it easier to find files by grouping all your file-handling classes in a "fileio" package and all your string utilities in "strings".

A common package naming scheme for classes you might share outside your own projects is "com", a company name, a project name and a category name. We saw Bob put his StringThing in the package com.bob.utility.strings.

Let's say TestThree uses our own version of StringThing. We could organize our code like this:

Project3
	com
		myname
			myproject
				main
				TestThree.java
				other
				StringThing.java

We add a package statement to each java file that matches the path from Project3. For example, TestThree has this statement at the top:

package com.myname.myproject.main;

TestThree must import any other classes that it uses. We give their fully qualified names:

import com.myname.myproject.other.StringThing;

With the same path and classpath as before, we compile the main program. Note that we start in Project3 and give the relative path to TestThree, which matches the package with slashes instead of dots.

c:\Project3> javac com/myname/myproject/main/TestThree.java

The compiler notices that TestThree imports StringThing, so it explores the classpath to find the java and class files for StringThing. It finds only a java file the first time through, so it compiles StringThing. A single compile command on our part conveniently compiles both classes. When the compiler is done, the two leaf folders contain a class file along with the java file.

To run TestThree, we give the fully qualified classname, including the package.

C:\Project3> java com.myname.myproject.main.TestThree

4. Separating Source & Binaries

Most developers don't like to mix their java files and their class files. I like to ZIP my java files now and then for archival and backup, so it's handy to have them in a folder of their own. We often want to put our class files into a jar. A jar is little more than a ZIP file so it's good to have the classes in their folder, too.

The following is typical or even a kind of standard. It may seem to be a lot of folders the first time through, but it's a worthwhile organization:

Project4
	src
		com
			myname
				myproject
					main
					TestFour.java
					other
					StringThing.java
	bin
		com
			myname
				myproject
					main
					TestFour.class
					other
					StringThing.class

To compile, we navigate to the src directory so all the package names work out relative to the current directory. We add the -d compiler option to put the class files in the bin directory: I couldn't seem to make it compile both files at once so I have to compile commands.

c:\Project4> cd src
c:\Project4\src> javac -d ..\bin com/myname/myproject/main/TestFour.java
c:\Project4\src> javac -d ..\bin com/myname/myproject/other/StringThing.java

To execute, we navigate to the bin directory and give the fully qualified classname again.

c:\Project4\src> cd ..\bin
C:\Project4\bin> java com.myname.myproject.main.TestFour

This might be reason enough to keep two command windows open: one in src and one in bin.

5. Multiple Projects

So far we have put all the files for one program in one project folder. This might be perfect for school assignments where we have to turn everything in together. As we get more advanced, though, we'll find we've written some classes we'd like to use again without copying them to every new project. Say we decide that StringThing is worth having outside the MainProject. So we start up a utility package, just like Bob did.

MainProject
	src
	bin
OtherProject
	src
		com
			myname
				other
				StringThing.java
	bin

We change MyProgram to import StringSplitter from the new location.

import com.myname.other.StringThing;

We have to compile the two projects separately.

cd MainProject\src
javac com\myname\myproject\main\TestFour.java -d ..\bin
cd ..\..

cd OtherProject\src
javac com\myname\myproject\other\StringThing.java -d ..\bin
cd ..\..

But when we navigate to MainProject/bin to execute, the utilities package is not in the folder structure. The compiler cannot find it. We have to resort to classpath again.

C:\MainProject\bin> set classpath=.;..\..\OtherProject\bin

6. Making Jars

Let's say the Utilities project is very stable, meaning we very rarely if ever change any of those classes. We can bundle it up for safety, easy reuse and easy distribution to our friends with the jar utility. Here are the commands Bob might have used to make his jar:

javac com\bob\utility\strings\StringThing.java
jar cvf BobsUtilities.jar com/

7. A Library of Jars

It's common to make a special folder to hold the jars you use, often named lib, short for library. Some people have a lib-ext folder for "external" jars, meaning things they didn't build.

Let's add a higher level directory to hold all of our java work and a lib directory for jars. We can use the jars in lib from any project.

	java
		Project7
		Utilities
		lib
		BobsUtilities.jar