Installing and Using Java Tools

Java development environments have two basic approaches. On the one hand, you can use a sophisticated Integrated Development Environment (IDE) such as Sun's Java Studio Creator, IntelliJ IDEA, or Eclipse. These tools combine a full-featured source editor that lets you edit your Java program files with integrated development tools, including visual development tools that let you create applications by dragging and dropping visual components onto a design surface.

At the other extreme, you can use just the basic command-line tools that are available free from Sun's Java Web site (http://www.java.sun.com). Then you can use any text editor you wish to create the text files that contain your Java programs (called source files), and compile and run your programs by typing commands at a command prompt.

Tip 

As a compromise, you may want to use a simple development environment, such as TextPad. TextPad is an inexpensive text editor that provides some nice features for editing Java programs (such as automatic indentation) and shortcuts for compiling and running programs. However, it doesn't generate any code for you or provide any type of visual design aids. TextPad is the tool I used to develop all the examples shown in this book. For information about downloading and using TextPad, refer to Book I, Chapter 3. Eclipse is a free, open-source development environment that's gaining popularity. I describe it in Book I, Chapter 4.

Downloading and Installing the Java Development Kit

Before you can start writing Java programs, you have to download and install the correct version of the Java Development Kit (JDK) for the computer system you're using. Sun's Java Web site provides versions for Windows, Solaris, and Unix. The following sections show you how to download and install the JDK.

Downloading the JDK

To get to the download page, point your browser to java.sun.com/javase/downloads. Then follow the appropriate links to download the JDK 6 for your operating system.

TECHNICAL STAUFF 

Presently a menu of Popular Downloads is on the right side of Java's home page at http://www.java.sun.com. At the top of that menu is a link to the download site for the current version of Java. So, if you don't want to type an entire link, you can just go to http://www.java.sun.com and then use the Popular Downloads list to navigate quickly to the appropriate download page.

When you get to the Java download page, you find links to download the JDK or the JRE. Follow the JDK link; the JRE link gets you only the Java Runtime Environment, not the complete Java Development Kit.

The JDK download comes in two versions: an online version that requires an active Internet connection to install the JDK, and an offline version that lets you download the JDK installation file to your disk, then install it later. I recommend you use the offline version. That way you can reinstall the JDK if you need to, without having to download it again.

The exact size of the offline version depends on the platform, but most of them are between 50MB and 60MB. As a result, the download takes a few hours if you don't have a high-speed Internet connection. With a cable, DSL, or T1 connection, the download takes less than five minutes.

Installing the JDK

After you download the JDK file, you can install it by running the executable file you downloaded. The procedure varies slightly depending on your operating system, but basically you just run the JDK installation program file after you download it:

• On a Windows system, open the folder to which you saved the installation program and double-click the installation program's icon.
• For a Linux or Solaris system, use console commands to change to the directory to which you downloaded the file, and then run the program.

Legal mumbo jumbo

Before you can download the JDK, you have to approve of the Java license agreement, all 2,463 words of it including the thereupons, whereases, and hithertos all finely crafted by Sun's legal department. I'm not a lawyer (and I don't play one on TV), but I'll try to summarize the license agreement for you:

• Sun grants you the right to use Java as is, and doesn't promise that it will do anything at all.
• The party of the second part (that's you) in turn promises to use Java only to write programs. You're not allowed to try to figure out how Java works and sell your secrets to Microsoft.
• You can't use Java to run a nuclear power plant. (I'm not making that up. It's actually in the license agreement.)

After you start the installation program, it asks any questions it needs to know to properly install the JDK. You're prompted for information such as which features you want to install and what folder you want to install the JDK to. You can safely choose the default answers for each of the options.

Perusing the JDK folders

When the JDK installs itself, it creates several folders on your hard drive. The locations of these folders vary depending on your system, but in Windows the JDK root folder is found under Program FilesJava on your boot drive. The name of the JDK root folder also varies, depending on the exact Java version you've installed. For version 1.6, the root folder is named jdk1.6.0 (or something similar, such as jdk1.6.0_02).

Table 2-1 lists the subfolders created in the JDK root folder. As you work with Java, you'll frequently refer to these folders.

Table 2-1: Folders in the JDK Root Folder
Open table as spreadsheet

Folder	Description
bin	The compiler and other Java development tools.
demo	Demo programs you can study to learn how to use various Java features.
docs	The Java API documentation. (For instructions on how to create this folder, see the section "Using Java Documentation" later in this chapter.)
include	This library contains files needed to integrate Java with programs written in other languages.
jre	The Runtime Environment files.
lib	Library files, including the Java API class library.
src	The source code for the Java API classes. This folder is only created if you unpack the src.zip file (this file may be named src.jar). After you get your feet wet with Java, looking at these source files can be a great way to learn more about how the API classes work.

In addition to these folders, the JDK installs several files into the JDK root folder. I list these files in Table 2-2.

Table 2-2: Files in the JDK Root Folder
Open table as spreadsheet

File	Description
README.html	The Java readme file in HTML format.
README.txt	The readme file again, this time in text format.
LICENSE	The Java license that you agreed to when you downloaded the JDK, on the outside chance you enjoyed it so much the first time you want to read it again. (If you work for Microsoft, you probably should read it again, at least twice.)
LICENSE.rtf	The license file once again, this time in RTF format. (RTF is a document format that can be understood by most word processing programs.)
COPYRIGHT	Most companies are happy to just say (c) 2007 Sun Microsystems, Inc. at the bottom of the readme file or in the license file. But not Sun. It puts the copyright notice in a separate text file, along with information about all the copyright and export laws that apply.

Warning 

I guess the Java license you have to agree to at least twice-once when you download the JDK, and again when you install it-isn't clear enough about what you're not allowed to use Java for. The license says you can't use it for nuclear power applications. But the copyright notice (in the COPYRIGHT file) also prohibits you from using it in missile systems or chemical or biological weapons systems. If you work for the Defense Department, you'd better read the copyright notice!

Setting the path

After you install the JDK, you need to configure your operating system so that it can find the JDK command-line tools. To do that, you must set the Path environment variable. This variable is a list of folders that the operating system uses to locate executable programs. To do this on a Windows XP or Windows Vista system, follow these steps:

1. Open the Control Panel and click the Performance and Maintenance link (in Windows XP) or the System and Maintenance link (in Windows Vista).
2. Click the System link.

   The System Properties dialog box comes up.

3. Click the Advanced tab (in Windows XP) or the Advanced System Settings link (in Windows Vista). Then click the Environment Variables button.

   The Environment Variables dialog box, as shown in Figure 2-1, appears.

   
   Figure 2-1: The Environment Variables dialog box.

4. In the System Variables list, select Path, and then click the Edit button.

   A little dialog box comes up to let you edit the value of the Path variable.

5. Add the JDK bin folder to the beginning of the Path value.

   Use a semicolon to separate the bin folder from the rest of the information that may already be in the path.Note: The exact name of the bin folder may vary on your system. For example:

    c:Program FilesJavajdk1.6.0in;other directories...
   

6. Click OK three times to exit.

   The first OK gets you back to the Environment Variables dialog box. The second OK gets you back to the System Properties dialog box. And the third OK closes the System Properties dialog box.

For earlier versions of Windows (such as ancient Windows 98 or Me), you set the path by adding a Path statement to the AutoExec.bat file in the root directory of your C drive. Here's an example:

path c:Program FilesJavajdk1.6.0in;other directories...

For Linux or Solaris, the procedure depends on which shell you're using. Consult the documentation for the shell you're using for more information.

Using Java s Command Line Tools

Java comes with several command-line tools you can run directly from a command prompt. The two most important are javac, the Java compiler used to compile a program, and java, the runtime command used to run a Java program. These tools work essentially the same no matter what operating system you're using. (The examples in this section are all for Windows XP and Windows Vista.)

Compiling a program

You can compile a program from a command prompt by using the javac command. Before you can do that, however, you need a program to compile. Using any text editor, type the following text into a file and save it as HelloApp.java:

public class HelloApp
{
 public static void main(String[] args)
 {
 System.out.println("Hello, World!");
 }
}

Save the file in any directory you wish. Pay special attention to capitalization. For example, if you type Public instead of public, the program won't work. (If you don't want to bother with the typing, you can download the sample programs from this book's Web site.)

Open a command prompt and use a cd command to change to the directory you saved the program file in. Then enter the command javac HelloApp. java. This command compiles the program (javac) and creates a class file named HelloApp.class.

Assuming you typed the program exactly right, the javac command doesn't display any messages at all. If the program contains any errors, one or more error messages appear on-screen. For example, if you type Public instead of public, the compiler displays the following error message:

C:javasamples>javac HelloApp.java
HelloApp.java:1: 'class' or 'interface' expected
Public class HelloApp
^
1 error

C:javasamples>

The compiler error message indicates that an error is in line 1 of the HelloApp.java file. If the compiler reports an error message like this one, that means your program contains a coding mistake. You need to find the mistake, correct it, and then compile the program again.

Compiling more than one file

Normally the javac command compiles only the file that you specify on the command line. However, you can coax javac into compiling more than one file at a time by using any of the techniques I describe in the following paragraphs:

• If the Java file you specify on the command line contains a reference to another Java class that's defined by a java file in the same folder, the Java compiler automatically compiles that class too.

  For example, suppose you have a java program named TestProgram, and that program refers to a class called TestClass, and the TestClass.java file is located in the same folder as the TestProgram.java file. Then, when you use the javac command to compile the TestProgram.java file, the compiler automatically compiles the TestClass.java file, too.

• You can list more than one filename on the javac command. For example, the following command compiles three files:

   javac TestProgram1.java TestProgram2.java
   TestProgram3.java
  

• You can use a wildcard to compile all the files in a folder, like this:

   javac *.java
  
  

• If you need to compile a lot of files at once, but don't want to use a wild-card (perhaps you want to compile a large number of files, but not all the files in a folder), you can create an argument file that lists the files to compile. In the argument file, you can type as many filenames as you want. You can use spaces or line breaks to separate the files. For example, here's an argument file named TestPrograms that lists three files to compile:

   TestProgram1.java
   TestProgram2.java
   TestProgram3.java
  

  Then you can compile all the programs in this file by using an @ character followed by the name of the argument file on the javac command line, like this:

   javac @TestPrograms
  

Using Java compiler options

The javac command has a gaggle of options you can use to influence the way it compiles your programs. For your reference, I list these options in Table 2-3. To use one or more of these options, type the option either before or after the source filename. For example, either of the following commands compiles the HelloApp.java file with the -verbose and -deprecation options enabled:

 javac HelloWorld.java -verbose -deprecation
 javac -verbose -deprecation HelloWorld.java

Table 2-3: Java Compiler Options
Open table as spreadsheet

Folder	Description
-g	Generate all debugging info
-g:none	Generate no debugging info
-g:{lines, vars, source}	Generate only some debugging info
-nowarn	Generate no warnings
-verbose	Output messages about what the compiler is doing
-deprecation	Output source locations where deprecated APIs are used
-classpath	Specify where to find user class files
-cp	Specify where to find user class files
-sourcepath	Specify where to find input source files
-bootclasspath	Override location of bootstrap class files
-extdirs	Override location of installed extensions
-endorseddirs	Override location of endorsed standards path
-d	Specify where to place generated class files
-encoding	Specify character encoding used by source files
-source	Provide source compatibility with specified release
-target	Generate class files for specific VM version
-version	Version information
-help	Print a synopsis of standard options
-X	Print a synopsis of nonstandard options
-J	Pass directly to the runtime system

Don't get all discombobulated if you don't understand what all these options do. Most of them are useful only in unusual situations. The options you'll use the most are

• -classpath or -cp: Use this option if your program makes use of class files that you've stored in a separate folder.
• -deprecation: Use this option if you want the compiler to warn you whenever you use API methods that have been deprecated. (Deprecated methods are older methods that were once a part of the Java standard API but are now on the road to obsolescence. They still work, but may not in future versions of Java.)
• -source: Use this option to limit the compiler to previous versions of Java. Note, however, that this option only applies to features of the Java language itself, not to the API class libraries. For example, if you specify -source 1.4, the compiler won't allow you to use new Java language features that were introduced with Java 1.5, such as generics or enhanced for loops. However, you can still use the new API features that were added with version 1.5, such as the Scanner class.
• -help: Use this option to list the options that are available for the javac command.

Running a Java program

When you successfully compile a Java program, you can then run the program by typing the java command followed by the name of the class that contains the program's main method. The Java Runtime Environment loads, along with the class you specify, and then runs the main method in that class. For example, to run the HelloApp program, type this command:

C:javasamples>java HelloApp

The program responds by displaying the message “Hello, World!”.

The class must be contained in a file with the same name as the class, and its filename must have the extension .class. You don't usually have to worry about the name of the class file because it's created automatically when you compile the program with the javac command. Thus, if you compile a program in a file named HelloApp.java, the compiler creates a class named HelloApp and saves it in a file named HelloApp.class.

If Java can't find a filename that corresponds to the class, you get a simple error message that indicates the class can't be found. For example, here's what you get if you type JelloApp instead of HelloApp:

C:javasamples>java JelloApp
Exception in thread "main" java.lang.NoClassDefFoundError:
 JelloApp

This error message simply means that Java couldn't find a class named JelloApp.

However, if you get the class name right but capitalize it incorrectly, you get a slew of error messages. Ponder this example:

C:javasamples>java helloapp
Exception in thread "main" java.lang. NoClassDefFoundError:
 helloapp (wrong name: HelloApp)
 at java.lang.ClassLoader.defineClass1(Native Method)
 at
 java.lang.ClassLoader.defineClass(ClassLoader.java:620)
 at java.security.SecureClassLoader.defineClass
 (SecureClassLoader.java:124)
 at java.net.URLClassLoader.defineClass
 (URLClassLoader.java:260)
 at java.net.URLClassLoader.access$100
 (URLClassLoader.java:56)
 at java.net.URLClassLoader$1.run
 (URLClassLoader.java:195)
 at java.security.AccessController.doPrivileged
 (Native Method)
 at java.net.URLClassLoader.findClass
 (URLClassLoader.java:188)
 at java.lang.ClassLoader.loadClass
 (ClassLoader.java:306)
 at sun.misc.Launcher$AppClassLoader.loadClass
 (Launcher.java:268)
 at java.lang.ClassLoader.loadClass
 (ClassLoader.java:251)
 at java.lang.ClassLoader.loadClassInternal
 (ClassLoader.java:319)

Wow, that's a pretty serious-looking set of error messages-considering that the only problem is that I forgot to capitalize HelloApp. Java isn't just case-sensitive, it's case-hypersensitive.

Like the Java compiler, the Java runtime command lets you specify options that can influence its behavior. Table 2-4 lists the most commonly used options.

Table 2-4: Commonly Used Java Command Options
Open table as spreadsheet

Folder	Description
-client	Runs the client VM
-server	Runs the server VM, which is optimized for server systems
-classpath adirectories	A list of directories or JAR or Zip archive and archives files used to search for class files
-cp	Same as -classpath
-D name=value	Sets a system property
-verbose	Enables verbose output
-version	Displays the JRE version number, then stops
-showversion	Displays the JRE version number, then continues
-? or -help	Lists the standard options
-X	Lists nonstandard options
-ea or -enableassertions	Enables the assert command
-ea classes or packages	Enables assertions for the specified classes or packages
-esa or -enablesystemassertions	Enables system assertions
-dsa or -disablesystemassertions	Disables system assertions

Using the javap command

The javap command is called the Java disassembler because it takes apart class files and tells you what's inside them. It's not a command you'll use often, but using it to find out how a particular Java statement works is sometimes fun. You can also use it to find out what methods are available for a class if you don't have the source code that was used to create the class.

For example, here's the information you get when you run the javap HelloApp command:

 C:javasamples>javap HelloApp
 Compiled from "HelloApp.java"
 public class HelloApp extends java.lang.Object{
 public HelloApp();
 public static void main(java.lang.String[]);
 }

As you can see, the javap command indicates that the HelloApp class was compiled from the HelloApp.java file and that it consists of a HelloApp public class and a main public method.

TECHNICAL STAUFF 

You may want to use two options with the javap command. If you use the -c option, the javap command displays the actual Java bytecodes created by the compiler for the class. And if you use the -verbose option, the bytecodes plus a ton of other fascinating information about the innards of the class are displayed. For example, here's the -c output for the HelloApp class:

C:javasamples>javap HelloApp -c
Compiled from "HelloApp.java"
public class HelloApp extends java.lang.Object{
public HelloApp();
 Code:
 0: aload_0
 1: invokespecial #1; //Method
 java/lang/Object."":()V
 4: return

public static void main(java.lang.String[]);
 Code:
 0: getstatic #2; //Field
 java/lang/System.out:Ljava/io/PrintStream;
 3: ldc #3; //String Hello, World!
 5: invokevirtual #4; //Method
 java/io/PrintStream.println:(Ljava/lang/String;)V
 8: return

}

If you become a big-time Java guru, you can use this type of information to find out exactly how certain Java features work. Until then, you should probably leave the javap command alone, except for those rare occasions when you want to impress your friends with your in-depth knowledge of Java. (Just hope that when you do, they don't ask you what the aload or invokevirtual instruction does.)

Other Java command line tools

Java has many other command-line tools that might come in handy from time to time. You can find a complete list of command-line tools at the following Web site:

java.sun.com/javase/6/docs/technotes/tools/index.html#basic

I describe three of these additional tools elsewhere in this book:

• applet viewer: Runs a Web applet application. For more information, see Book VII, Chapter 1.
• javadoc: Automatically creates HTML documentation for your Java classes. For more information, see Book III, Chapter 8.
• jar: Creates Java archive files, which store classes in a compressed file that's similar to a Zip file. I cover this command in Book III, Chapter 8.

Using Java Documentation

Before you get too far into learning Java, don't be surprised if you find yourself wondering whether some class has some other method that I don't describe in this book-or whether some other class may be more appropriate for an application you're working on. When that time comes, you'll need to consult the Java help pages.

Complete documentation for Java is available from the Sun Java Web site at java.sun.com/javase/reference. Although this page contains many links to documentation pages, the two you'll use the most are the Java SE API documentation pages and the Java Language Specification pages. The following sections describe these two links.

Tip 

If you don't have a reliable high-speed Internet connection, you can download Java's documentation by using the download links on the main java.sun.com/javase/reference page. Then, you can access the documentation pages directly from your computer.

Java SE API Docs

The APIs & Documentation links on the java.sun.com/javase/reference page take you to the complete documentation for all currently supported versions of the Java API, in English as well as Japanese. Figure 2-2 shows the English Java SE 6 API documentation page.

Figure 2-2: The documentation page for Java SE API 6 (English version).

You can use this page to find complete information for any class in the API. By default, all the Java classes are listed in the frame that appears at the bottom left of the page. You can limit this display to just the classes in a particular package by selecting the package from the menu at the upper-left side of the page. (If you don't know what a Java "package" is, don't worry. You find out about packages in Book I, Chapter 4.)

Click the class you're looking for in the class list to call up its documentation page. For example, Figure 2-3 shows the documentation page for the String class. If you scroll down this page, you find complete information about everything you can do with this class, including an in-depth discussion of what the class does, a list of the various methods it provides, and a detailed description of what each method does. In addition, you find links to other similar classes.

Figure 2-3: The documentation page for the String class.

Java Language Specification

If you're interested in learning details about some element of the Java language itself (rather than the information about a class in the API class library), click the Java Language Specification link near the bottom of the page. That takes you to a set of pages that describe-in sometimes-excruciating and obscure detail-exactly how each element of the Java language works.

Frankly, this documentation isn't that much help for beginning programmers. It was written by computer scientists for computer scientists. You can tell just by looking at the table of contents that it isn't for novices. The first chapter is called Introduction (that's not so bad), but then Chapters 2 and 3 are titled "Grammars" and "Lexical Structure." And it just gets more arcane from there.

That's why you're reading this book, after all. You won't even find a single sentence more about Lexical Structure in this book (other than this one, of course). Even so, at some time in your Java journeys you may want to get to the bottom of the rules that govern such strange Java features as anonymous inner classes. When that day arrives, grab a six pack of Jolt Cola, roll up your sleeves, and open the Java Language Specification pages.