Looking for a desktop environment to develop and test commercial-quality Java code, JSP's and Servlets? Prefer not to spend a small fortune for the software?

Here's a great alternative to high-priced, commercial software and you just can't beat the price! It's all either free and open source (or just free) and available for downloading on the internet (for commercial work or for provider support, some of the components may have a price tag). Just to make it easy, the table below has the links you will need. The friendly folks who wrote Core Servlets and Javaserver Pages: Advanced Technologies, Vol. 2 (2nd Edition), have put together a Preconfigured Tomcat Version that saves time by including many of the changes you probably will want. After it's all set up you'll be able to make changes to your JSP's and see the effects in a browser. You'll also have many of the debugging features of the Eclipse environment available and the console will be live along with the Tomcat logs for bug tracing.

You can easily develop WAR files (Java Web Archive files) which can be dropped into the webapps folder of a Tomcat server. Tomcat will magically “explode” the WAR file into the appropriate folders. This makes transferring your website between servers a snap. If you select the option to include the java files you can also pass your WAR file to other developers who can unzip the WAR into a project inside Eclipse for further development.

This tutorial covers the basics of a JSP development environment. It is recommended you learn these basics before moving on to Struts, Tiles, Validation and the other frameworks.

The following are the steps to load Java, a Tomcat JSP container which works as a server, the Eclipse IDE, and a MySQL database server. The versions were generally up-to-date as of Spring, 2008. Newer versions may be available but remember to confirm all the components will work together (especially important: make sure the Sysdeo plugin is compatible with Eclipse and the MySQL JDBC driver works with the version of MySQL). After the downloads are unzipped, installed and setup you will have eaten 600+ mb's. Even more as you begin to set up the workspaces and databases for development -- plan on a gigabyte of hard-drive space.

I suggest at least 512 mb's of RAM an XP computer. Eclipse really flies with a gigabyte of RAM and Windows XP. In my experience, Vista requires a dual-core processor and 2 gigabytes of RAM to equal the less powerful XP machine -- but, hey, that's progress (and why nerds like us are taking another long look at Ubuntu)!

Download: java.sun.com/javase/downloads/index.jsp

Download and install your chosen version of the Java JDK (Java Development Kit). You must install the JDK version -- which includes the javac compiler -- not just the JRE (Java Runtime Environment). In fact, the JDK includes a JRE in its directory structure and installs another copy in the main Java directory (see the screen capture at right). Download the JDK Version 6u6 by choosing one of the jdk-6u6-windows-i586-p versions on the download page.

• Offline version: jdk-6u6-windows-i586-p.exe
• Online version: jdk-6u6-windows-i586-p-iftw.exe

The offline version will download the entire package first so you can save it and install it locally. Using the Sun Download Manager is optional. It is helpful if you need to interrupt and restart the download. The online version installs Java directly off the Sun Java website.

Accept the defaults and install it at C:\Program Files\Java\jdk1.6.0_06. Make the changes in the System environment variables (described in the next paragraph) to point to this installation. You can install it elsewhere but you must adjust your JAVA_HOME and Classpath variables to accurately reflect the actual location. Multiple versions of the JDK can be on the same workstation -- what counts is the directory pointed to by the environment variables.

JAVA_HOME

After installing Java go to the Control Panel --> System --> Advanced --> Environment Variables. Enter a new system variable in the bottom half of the pane named "JAVA_HOME" and set the value to the drive location (C:\Program Files\Java\jdk1.6.0_06 in this example). While you've got the environment window open update the PATH variable to include the C:\Program Files\Java\jdk1.6.0_06\bin location. Remember to add a semi-colon to the current path before making the addition. You should restart the workstation for environment variable changes to take effect.

Quick Test

Test your setup by opening a command prompt (Start Program --> Run --> enter “cmd”). In the DOS command box that comes up, type in “java -version” and check for an obvious good result and not an error message saying it couldn't be found. Then type in javac -help and check again. If one or both of these don't work check your JAVA_HOME variable and PATH settings.

Download: www.coreservlets.com/Apache-Tomcat-Tutorial/Preconfigured-Tomcat-5.5-Version.html

The easiest way to install Tomcat is to use the preconfigured version available at the link above.

After downloading, right click on the zip file and choose Extract All. Browse to “C:\Program Files”; the extraction process will create the “apache-tomcat-5.5.17” folder. If you extract the files to the default folder (which will be the folder where the zip file is located) just move the files to C:\Program Files\apache-tomcat-5.5.17 (some versions will be “Jakarta-Tomcat”).

By default, your browser will be watching port 80 rather than 8080 which means you would have to type http://localhost:8080/ rather than http://localhost/ to check your work. The pre-configured version linked above includes the following change. You can change the port number from 8080 to 80 easily. Navigate to C:\Program Files\apache-tomcat-5.5.17\conf\ and open server.xml in a text editor (NotePad or WordPad). Do a search for “8080”. There will be some comments that will catch the search first but following the comments you will find the actual instruction pointing to 8080. Changing it to “80” will match it to your browser's default.

Create or change the system's Classpath variable to include the Tomcat jsp and servlet api's under the Control Panel --> System --> Advanced --> Environmental Variables. If a Classpath variable doesn't already exist, click on New and enter "CLASSPATH" in the variable name line. The Variable Value box should include the following:

.;C:\Program Files\apache-tomcat-5.5.17\common\lib\servlet-api.jar;C:\Program Files\apache-tomcat-5.5.17\common\lib\jsp-api.jar;

The variable value above should begin with a period followed by a semi-colon.

While you have the Environment Variable screen open, add C:\Program Files\apache-tomcat-5.5.17\bin to the Path variable. Add another environment variable called "CATALINA_HOME" and point it to the Tomcat directory -- in my case it is C:\Program Files\apache-tomcat-5.5.17\bin.

Restart the workstation for environment variable changes to take effect.

Test your setup as follows: Click on C:\Program Files\apache-tomcat-5.5.17\bin\startup.bat and see if a DOS window opens up and the server starts. You can right click on the startup.bat file and drag it to the desktop to create a shortcut (be careful not to move the actual file -- just create a desktop shortcut). Do the same with the shutdown.bat file also in the bin directory. This will make starting and stopping the Tomcat server much easier until you get the plugin working inside Eclipse. You should see a screen similar to this after a successful startup (some of the version numbers may have changed since this screen capture was created).

If you have problems, one way to discover their nature is to start Tomcat from a Command box by entering "startup.bat" (or C:\Program Files\apache-tomcat-5.5.17\bin\startup.bat if you didn't set the Path environmental variable above). The rather friendly error messages may provide an insight into the specific problem causing Tomcat to fail to start.

Open a browser and type in a URL of http://localhost/. If everything's working you should see the Apache-Jakarta Tomcat welcome page.

If the correct page doesn't open in the browser go back through and check all of the environment variables in the Control Panel for typos and omissions. Although you are operating in a Windows environment, the Java and Tomcat directories need only be present and pointed to correctly in the environment variables in either location. There aren't any other “hidden” connectors as you might expect in standard Windows components.

Congratulations if you see the Tomcat sample page! You're halfway to a great development environment! Take some time to check the sample JSP and Servlet pages provided by Tomcat in the C:\Program Files\apache-tomcat-5.5.17\webapps\ directory. You can see the source code and the resulting web page for each example. For example, enter http://localhost/jsp-examples/num/numguess.jsp in the address bar of a browser and play their simple number game.

PATH versus CLASSPATH

If you're not confused by the distinction between the environmental variables “PATH” and “CLASSPATH” you probably don't need to be reading this tutorial.

PATH is where the operating system (XP or Vista in our case) goes to find executables (EXE's). Thus you (or sometimes the program installer) will put the “bin” directories of Java, Tomcat, and MySQL in the PATH. You should confirm the only path to a Java bin is the one pointing to the JDK you are using. The system will accept the first one and ignore any conflicting bin's that follow but you want to keep your environment variables as clean as possible. You can check the Path variable by bringing up a Command Prompt (Start Programs --> Accessories --> Command Prompt) and type in "Path". This should bring up the path variable in the command box.

CLASSPATH is where Java (the JVM) will look for jar files (i.e., compiled classes) when it's running programs. So your CLASSPATH environmental variable will have paths to two jar files for Tomcat and one for MySQL -- and probably others if you have other Java programs on your computer.

Tomcat and Vista Security

Vista with User Account Control (UAC) running causes a problem. Vista normally runs everybody -- including administrators -- in a non-administrative role. This provides additional security and makes it more difficult for intruders to run programs requiring administrative privileges. You can right click on the Tomcat desktop shortcut if you made one and chose “Run As Administrator”. Do this for both Tomcat Startup and Shutdown shortcuts. You will also need to run Eclipse in administrator mode.

For a more permanent solution, right-click on the shortcut and chose “Properties / General / Advanced” and check the box to run the program as administrator. Do this for both the Tomcat Startup and Shutdown shortcuts.

Tomcat overwrites an xml file when it starts up. This will fail if run on a Vista computer without administrator privileges. The command line box will show some errors but it will also finish with the Server startup message so you may get the impression you have a good Tomcat startup.

Download: www.eclipse.org/downloads/index.php

Download: www.eclipsetotale.com/tomcatPlugin.html

Download and install Tomcat before installing the Sysdeo plugin. After downloading the Sysdeo plugin from the link above, extract it to C:\Program Files\eclipse\plugins\. As before, if you extract it to the wrong directory simply move it to the correct one. The end result should be similar to C:\Program Files\eclipse\plugins\com.sysdeo.eclipse.tomcat_3.2.0. The Sysdeo plugin is a directory containing jar files, html, and property files. Stop and relaunch Eclipse if it's running so it will pick up the new plug-in. Activate the plugin in the following location in Eclipse: Window --> Customize Perspective --> Commands and select the checkbox for Tomcat. It may be necessary to force Eclipse to see the new plug-in. Right-click on the Eclipse icon (either in Start --> Programs or on your desktop) and select Properties in the drop-down list. Select the Shortcut tab and add “-clean” in the Target box to make Eclipse check for new plug-ins. The result should be similar to “C:\Program Files\eclipse\eclipse.exe” -clean. Set the Tomcat preferences in Window --> Preferences --> Tomcat. Highlight Tomcat in the list and select the correct version of Tomcat and browse to C:\Program Files\apache-tomcat-5.5.17. See the screen capture on the right. On the same screen, select the Context Declaration Mode --> Context Files and enter C:\Program Files\apache-tomcat-5.5.17\conf\Catalina\localhost or the location you originally installed Tomcat. In the Advanced section under Tomcat browse to C:\Program Files\apache-tomcat-5.5.17 for the entry pointing to the Tomcat base.

Next, in the JVM Settings window, at the top of the screen select the JRE you added previously (actually a JDK). The possible choices will be included in the dropdown. Leaving it as the default eclipse JRE will prevent the Tomcat connector from working properly. Add a reference to the C:\Program Files\Java\jdk1.6.0_06\lib\tools.jar in the Classpath window in the middle of the screen as the jpg at the left illustrates. Add C:\Program Files\Java\jdk1.6.0_06\jre\lib\rt.jar in the Boot Classpath window at the bottom of the page. The plugin has created three new buttons on your Eclipse toolbar (see the small image below). Click on the first icon and watch Tomcat start up in the console (the plugin redirects Tomcat messages to the Eclipse console). Now when you start a project in Eclipse select “Tomcat Project” under Java in the New Project window. Your workstation is set up to run Tomcat while working in Eclipse. You should see your index page in a browser set to http://localhost/<context>.

Download: dev.mysql.com/downloads/mysql/5.0.html

Online Reference Manual: dev.mysql.com/doc/mysql/en/index.html

MySQL will be installed as a service which will start up with Windows. It is recommended you accept most of the defaults although I did check in the "Include Bin Directory in Windows Path" checkbox (which allows Windows to find executables from the command line if you choose to run it that way occasionally) and you should add a password when given the opportunity. You should configure your firewall to accept the port(usually port 3306).

Grab your favorite MySQL manual and create a database and some tables from the command line. If you're not in love with command line programming give the MySQL Administrator below a try.

Download: dev.mysql.com/downloads/connector/j/5.0.html

The Java-MySQL Connector allows standard Java JDBC commands to access the database. As of Spring, 2007, the current connector is 5.0.5.

Download and unzip the file linked above. Copy the mysql-connector-java-5.0.5-bin.jar to the following folder in the Java home directory: C:Program Files\Java\jdk1.6.0_06\jre\lib\ext. Then add the jar to the “Classpath” variable in the System environmental variables (Control Panel --> System --> Advanced --> Environmental Variables). Your addition should read something similar to: C:\Program Files\java\jdk1.6.0_06\jre\lib\ext\mysql-connector-java-5.0.5-bin.jar

Download: dev.mysql.com/downloads/gui-tools/5.0.html

Online documentation for the tools: dev.mysql.com/doc/

To properly administer a MySQL database you can download or buy the 800+ page manual (listed under MySQL above) or you download and use the MySQL Administrator. The Administrator works on MySQL versions above 4.0. With the Administrator's GUI interface you can create databases, tables and columns much faster than entering arcane SQL commands in a DOS command box. You can also use it to export databases to other team members on a project. The MySQL Query Browser is also very handy for checking changes to your database during code testing. Once you create a database query you can retrieve it from the history and run it as needed.

The interfaces are pretty intuitive but the online instructions are easy to follow if you need some help.

These GUI tools will be set up in a sub-directory call MySQL TOOLS within the MySQL directory. If you're desktop-oriented as I am, right-click the various EXE's and create short-cuts on the desktop.

It's time to start writing code. I'm working on a simple project sample to include on this page later this summer. A great book to use in setting up a first project is Murach's Java Servlets and JSP. It contains a couple of relatively easy projects (complete with code) including a mailing list program that makes a perfect beginner's project.

Tomcat has also provided several sample jsp files in the webapps directory. Navigate to C:\Program Files\apache-tomcat-5.5.17\webapps\jsp-examples to get some ideas. In the C:\Program Files\apache-tomcat-5.5.17\webapps\ROOT directory take a look at index.jsp. It's the page that came up when you originally set up the Tomcat directory above (which you reach with http://localhost/ in the address of your browser).

You could copy files to the Tomcat Root directory like the Tomcat samples, however, this would put unnecessary files in that important folder. There are several better ways to create a development environment for testing JSP's. Two are described below; one using a context XML files to link your files to Tomcat and one using a WAR file to quickly move your files to the webapps directory. Either way, the JSP page should display in your browser using an address such as this: http://localhost/‹context name›/.

Please send any comments or suggestions to webmaster@sipages.com. It would be a huge help if you report errors in the instructions or just point out hard-to-understand sections. Several hundred Java/Tomcat beginners are using these instructions every day -- so any corrections would help us all.

The Murach book, “Java Servlets & JSP (2nd Edition)”, is highly recommended for developers learning the basics of JSP's and servlets. It will help you develop a strong foundation before venturing into Struts, Tiles, Validation, etc. The Hall, Brown, and Chaikin book, “Core Servlets and JavaServer Pages (2nd Edition)” is excellent and includes the Struts, Tiles and Validation frameworks. Both are readable by beginners. There are Amazon links to both books on the left column of this page. Using these Amazon links is paying for this site -- thank you very much.

This page was last updated May 10, 2008. The screen captures are from a Vista computer and may differ slightly from the XP look. Some captures may also indicate earlier application versions, i.e., C:\Program Files\Java\jdk1.6.0_01 whereas the current version is actually C:\Program Files\Java\jdk1.6.0_06.

I added a forum for questions. Several thousand "newbies" visit this site every month. Quite possibly one of them had the same problem you're having and can provide an answer.