Setting Up

This section focuses on what you'll need to do in order to get started.

Software You'll Need

IDE or Programmer's Editor

Programming in Java means that you will need to be able to enter source code into your system, compile the source code, and execute the resulting application classes. There are two primary modes of accomplishing this work:

• You can use what is known as an integrated development environment (IDE). An IDE supplies just about everything you'll need to develop in Java in one application. Examples of IDEs include IntelliJ IDEA, Eclipse, Borland JBuilder, and NetBeans.

I'm currently rebuilding the examples for this book using IntelliJ IDEA, available from JetBrains (http://www.jetbrains.com). IDEA does a great job with respect to letting you “work the way you want to work.” Its complete support for J2SE 5.0 also arrived sooner than the other IDEs mentioned.

• You can use a programmer's editor. A programmer's editor is an application that allows you to type in code and save it to the file system. It will allow you to configure external tools, such as the Java compiler and VM, that you can execute from within the editor. A programmer's editor typically provides additional support to make the task of programming easier. For example, most programmer's editors recognize other languages enough to provide you with meaningful color schemes (a feature known as syntax highlighting).

Some of the more popular programmer's editors include emacs, vi, TextPad, UltraEdit, and SlickEdit. My personal choice is TextPad, a $27 editor that you can download from http://www.textpad.com. While you could use Windows Notepad (or WordPad) as an editor, you will find that the lack of programming features makes it an ineffective programming tool.

So what is the difference between a programmer's editor and an IDE?

An IDE is often, but not always, limited to a single language. IntelliJ IDEA, JBuilder, and NetBeans specifically target Java, but Microsoft's Visual Studio and Eclipse both provide support for other languages. Modern IDEs know a lot about languages and their class libraries. This knowledge allows the IDEs to provide advanced programming aids such as auto-completion (you type a few letters and the IDE completes what it thought you wanted to type). Modern IDEs also contain sophisticated navigation tools that understand how all your code weaves together. Finally, modern IDEs typically contain a debugger. A debugger is a tool you can use to step through code as it executes. By using a debugger, you can gain a better understanding of what the code does.

In contrast, a programmer's editor is a general-purpose tool that supports editing virtually any kind of program or file. In recent years, programmer's editors have been enhanced to understand more and more about specific languages. However, the level of sophistication remains much lower than an IDE. In order to navigate through code using a programmer's editor, you will typically have to execute text searches. In contrast, IDEs make navigation as simple as a single keystroke. While I know of no programmer's editor that includes a debugger, you can configure most programmer's tools to execute a debugger as an external tool.

Some people find IDEs constricting—you have to work the way the IDE wants you to work. Most IDEs are highly configurable, but you will probably always find something that doesn't work the way you want it to. On the flip side, once you've gotten accustomed to the advanced features that an IDE provides, you'll miss them if you go back to a programmer's editor.

Most of the code in this book was originally constructed under TextPad, since the IDEs generally take a while to support new language versions. You may also find that the IDE you intended to use does not yet support J2SE 5.0. It can take up to a year for vendors to bring their product up to date with the latest Java version.

Agile Java does not assume you use any specific IDE or editor. The few examples in Agile Java that discuss compilation specifics are based upon command-line execution.

If you are using IntelliJ IDEA, Appendix C shows you how to get started with the “Hello World” example shown in this chapter. Appendix C also shows you how to build and run the test-driven examples from Lesson 1. If you're using any other IDE, consult its help documentation for information on configuring it.

Java

You need version 5.0 of the Java 2 SDK (Software Development Kit) in order to run all the examples in Agile Java. If you are running an IDE, it may already include the SDK. I still recommend installing the SDK, as it is wise to learn how to build and execute Java programs exclusive of an IDE.

You can download the SDK from http://java.sun.com. You will also want to download the corresponding documentation from the same site. There are installation instructions located at the site to install the SDK that you will want to follow.

Note that you will have the option of downloading either the SDK or the JRE (Java Runtime Environment). You want to download the SDK (which includes the JRE).

The JRE is in essence the JVM. You might download and install the VM if you are interested only in executing Java applications on your system, not in building Java applications. The JVM is supplied separately so that you can ship a minimal set of components with your application when you deploy it to other machines.

After you install the SDK, you will want to extract the documentation, which is a voluminous set of web pages stored in a subdirectory named doc. The best place to extract these is into the directory in which you installed the SDK (under Windows, this might be c:Program FilesJavajdk1.5.0). Once you have extracted the docs, you may want to create a shortcut in your web browser to the various index.html files located within. Minimally, you will want to be able to pull up the API documentation, located in the api folder (sub-directory), which is contained directly within the doc folder.

Finally, if you intend to compile and execute Java programs from the command line, you will need to update your path to include the bin directory located directly within the JDK install directory. You will also want to create an environment variable named JAVA_HOME that points to the installation directory of the JDK (if one was not already created by installation of the JDK). Refer to an operating system guide for information on how to set the path and environment variables.

Checking Your Java Installation

You can do a quick sanity check of your installation and configuration. From the command line, execute the command:

java -version

You should seem something similar to:

java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-12345)
Java HotSpot(TM) Client VM (build 1.5.0-12345, mixed mode, sharing)

If you instead see something like:

'java' is not recognized as an internal or external command, operable program or batch file.

Or:

java: command not found

then you have not set your path correctly. To view the path under Windows, enter the command:

path

Under Unix, enter:

echo $PATH

You should see the directory in which you installed Java appear on the path. If you do not, try restarting the shell or command prompt.

If you see a different version of Java, perhaps 1.3 or 1.4, another version of Java appears in the path before the 1.5 version. Try moving your 1.5 install directory to the head of the path.¹

¹ Windows puts the latest version of Java in the Windows SYSTEM32 directory. You might consider (carefully) deleting this version.

You will also want to test that you properly set the JAVA_HOME environment variable. Try executing (under Windows):

"%JAVA_HOME%"injava -version

You should see the same version as before. Under Unix:

"$JAVA_HOME/bin/java" -version

The quotes handle the possibility that there are spaces in the path name. If you don't get a good result, view the value of the JAVA_HOME environment variable. Unix:

echo $JAVA_HOME

Windows:

echo %JAVA_HOME%

If you can't get past these steps, go no farther! Seek assistance (see the section Still Stuck? at the end of this chapter).

JUnit

You may need to download and install JUnit in order to get started. JUnit is a simple unit-testing framework that you will need in order to do TDD.

Most major IDEs provide direct or indirect support for JUnit. Many IDEs ship with the JUnit product already built in. If you are building and executing Java applications from the command line or as an external tool from a programmer's editor, you will need to install JUnit.

You can download JUnit for free from http://www.junit.org. Installation is a matter of extracting the contents of the downloaded zip file onto your hard drive.

Most important, the JUnit zip file contains a file named junit.jar. This file contains the JUnit class libraries to which your code will need to refer in order for you to write tests for your programs.

I built the tests in this book using JUnit version 3.8.1.

Ant

You may also need to download and install Ant. Ant is an XML-based build utility that has become the standard for building and deploying Java projects.

Most major IDEs provide direct or indirect support for Ant. Many IDEs ship with the Ant product already built in. If you are building and executing Java applications from the command line or as an external tool from a programmer's editor, you will want to install Ant.

Ant is available for download at http://ant.apache.org. As with JUnit, installation is a matter of extracting the contents of the downloaded zip file onto your hard drive.

You can choose to defer the installation of Ant until you reach Lesson 3, the first use of Ant. This lesson includes a brief introduction to Ant.

If you are not using an IDE with built-in Ant support: You will want to include a reference to the bin directory of your Ant installation in your path statement. Refer to an operating system guide for information on how to set the path. You will also need to create an environment variable named ANT_HOME that points to the installation directory of Ant. Refer to an operating system guide for information on how to set the path and environment variables.

I built the examples in this book using Ant version 1.6.

Does It Work?

To get started, you will code the “Hello World” program. The hello world program is the prototypical first Java program. When executed, it prints the text “hello world” onto your console. Many programmers venturing into new languages create a hello world program to demonstrate the basic ability to compile and execute code in that new language environment.

I include “hello world” here solely as a quick means of feedback. Many of the concepts in it are more advanced topics that you will learn later in the book. This exercise exists to ensure you are able to compile and execute Java programs. For now, type the code below, exactly as it appears, into your IDE or editor.

class Hello {
   public static void main(String[] args) {
      System.out.println("hello world");
   }
}

Save this using the filename Hello.java. Case is important in Java. If you save it as hello.java, you may not be able to compile or execute the code.²

² Windows is a little less picky about case. You may find that Windows doesn't always complain about case when it should.

Compiling Hello World

Either use your IDE to compile Hello (if your IDE requires explicit compilation³) or compile it from the command line:

³ Some IDEs require you to explicitly trigger a build. Other IDEs, such as Eclipse, automatically compile the necessary source files each time you save an edit change.

javac Hello.java

See the sidebar for more information about the javac command.

You should be in the directory where you saved Hello.java. If all went well, you will see no messages from the compiler. If you mistyped something, you will likely receive compilation errors. For example, you might see:

Hello.java:4: ';' expected
   }
   ^
1 error

This specific error means that you forget to type the semicolon (;) at the end of the third line of text.

You might see multiple errors, depending on what you mistyped. Correct any errors and try to compile the file again. If you still have problems, make sure your code looks exactly as it appears above. Finally, see the section Still Stuck? at the end of this chapter.

A successful compilation of Hello.java will produce the file Hello.class. Execute a dir or ls command to produce a directory listing and ensure that Hello.class exists. Hello.class is the binary compiled version of the source code—the class file. Hello.class is what the Java VM will read and interpret in order to execute the code you typed in Hello.java.

Executing Hello World

To execute the Hello application from the command line, enter:

java Hello

Make sure that Hello is capitalized as shown.

If you entered the command correctly, you should see the output:

hello world

Each time you compile the source file, the Java compiler will replace any associated class file that already exists.

Only where pertinent in this book (for example, when I discuss classpath) do I demonstrate use of the javac and java commands. I highly recommend that you familiarize yourself with command-line compilation and execution. The Java compiler and VM work virtually the same across all platforms. If you have difficulty compiling and executing code within your IDE, you will have to refer to the documentation for your IDE.

Still Stuck?

Getting your first Java program compiled and executed can be frustrating, as there are many things that can go wrong. Unfortunately, I can't cover all possibilities in this book. If you are still having trouble, there are wonderful places to go on the web that will provide you with all the help you need. Sun's official Java web site (http://java.sun.com) provides you with a wealth of information right from the source.

Another great place to find assistance is the JavaRanch web site at http://www.javaranch.com. You'll need to register with a real name in order to use this service. Most of the moderators of the site are particularly helpful and friendly to Java novices. Look for the forum named “Java in General (beginner)” and post your messages there.

As with any public forum, first read the JavaRanch guidelines on posting. The link http://www.faqs.org/faqs/usenet/primer/part1/ contains a document on etiquette for posting to Usenet. Most of this etiquette applies to virtually any public forum, including JavaRanch. Asking for help in the right way elicits a much better response.

If you're still stuck, I apologize. Please send an email to me at [email protected].