Jan K. Labanowski, Computational Chemistry List, Ltd.

Click on images to see them in the natural size

Eclipse and Tomcat installation on Windows 7

For serious programming with Java Core or Java EE you need Eclipse. Eclipse (check the Wiki for some overview and history: http://en.wikipedia.org/wiki/Eclipse_%28software%29) is the most popular IDE (Integrated Development Environment) on the Planet (at least on Earth). Frankly, even being the emacs guy, I do not imagine how I could develop Java code, especially for popular Java frameworks, web applications and web services, without Eclipse. That being said, I also use NetBeans (http://en.wikipedia.org/wiki/NetBeans) especially when I deal with the latest and greatest (and often experimental) from Java and JavaEE (say the latest Glassfish and JEE7), since it comes from Oracle and usually supports new stuff sooner than Eclipse. Also, I think that NetBeans has a more natural support for Maven (http://en.wikipedia.org/wiki/Apache_Maven) which is a convenient tool for automating deployment and maintaining consistency of your builds. But of course, Maven is also very well supported by Eclipse.

Due to the popularity of Windoz, you are often forced to use Eclipse under Windoz, though the software that you develop will usually run on a production quality operating system, i.e., some Unix (usually Linux). So I wanted to share how I usually install Eclipse on Windoz platform.

I started to use Eclipse when it was nicknamed Ganymede (v. 3.4). They name them alphabetically, usually using some astronomical (astrological?) names. The current Eclipse that I use is nicknamed Luna (v.4.4) and the next stable release (Mars) is planned for mid 2015. The Luna has now full support for Java8. In this brain dump I will start from the fresh copy of Eclipse. Actually, it is prudent to start from fresh copy for each major project that you are developing, since I know from experience that if you accumulate too many plugins that have no relation to the project at hand, you will have problems. The wisdom here is to have in your Eclipse only the stuff that you need. Otherwise, you may have conflicts and strange interactions that are hard to debug. I also start from downloading the JEE version of Eclipse rather than the smaller Java version. The JEE Eclipse packs most stuff that I need (I usually do some kind of enterprise stuff, including the Web stuff). Eclipse comes to you as a zip file and is completely relocatable. You can install it anywhere you want. You also need Java before you can use it, since it is written in Java. You can look at my write-up on installing Java under Windows. It is important that your JDK is installed well, or you will have problems down the road. Default Java installation may place Java in the directory that contains spaces in its name. While spaces are legal in the file and directory names, they require that you quote such paths on the command line and inside the scripts. This is often the headache, since some scripts created with Unix in mind do not quote command line parameters or environment variables. For example, if your environment variable MY_JAVA_HOME is set C:\Program Files\Java, the Cygwin command:

$ ls -l $MY_JAVA_HOME
ls: cannot access C:\Program: No such file or directory
ls: cannot access Files\Java: No such file or directory

will fail, and only the

$ ls -l "$MY_JAVA_HOME"
total 323
drwxr-xr-x 1 jkl None      0 Feb  2 22:35 bin
-rw-r--r-- 1 jkl None   3244 Feb  2 22:35 COPYRIGHT
drwxr-xr-x 1 jkl None      0 Feb  2 22:35 lib
-rw-r--r-- 1 jkl None     40 Feb  2 22:35 LICENSE
-rw-r--r-- 1 jkl None     46 Feb  2 22:35 README.txt
-rw-r--r-- 1 jkl None    527 Feb  2 22:35 release
-rw-r--r-- 1 jkl None 178400 Feb  2 22:35 THIRDPARTYLICENSEREADME.txt
-rw-r--r-- 1 jkl None 110114 Feb  2 22:35 THIRDPARTYLICENSEREADME-JAVAFX.txt
-rw-r--r-- 1 jkl None    955 Feb  2 22:35 Welcome.html

will work.

To get Eclipse go to https://eclipse.org/downloads/ and download the Eclipse IDE for Java EE Developers for Windows 64 bit -- I assume you are running the 64-bit windows. It is a zip file about 260MB in size. Unpack it in the directory that does not have spaces in the path/name. If you have to have spaces, I describe a few tricks how to deal with this in my Cygwin installation notes. Hint: you can always make links or junctions as they call it, say: C:/With Space to C:/With_No_Space. Once you unzip this file your Eclipse is ready to run under eclipse subdirectory:

When you click on it, you will get a Welcome thing... But in my case I did not get a nice welcome... I will tell you why...

There maybe several reasons for this. I get it sometimes when my Java environment is messed up. But we covered this. You do have Java installed well. Sometimes file permissions will mess you up. But in this case, the reason was that I unzipped the distribution file under Unix environment (in this case by using unzip under Cygwin). When you use a Cygwin's unzip to extract files from the Windoz Eclipse distribution, your Eclipse will not usually work. The problem is that Cygwin's unzip, unzips files in a Unix convention, i.e., using slashes / rather than backslashes \. It usually does not matter, but for Eclipse it does, for some reason. Since Eclipse runs on Windows, it needs backslashes. Note that everything under Cygwin runs under Windows. The Cygwin is just a convenience, a Linux like interface. But the stuff there is still Windoz. So do not use Cygwin's unzip to unpack Eclipse's archive. You can either right click on the Eclipse zip archive in your Windows Explorer dialog (and internal Windows unzipper will do the extraction after a few random clicks), or use some Windows aware achiever software (like WinZip). I love the 7-zip (you can download and install it from http://www.7-zip.org/) and use it under Windoz. It is free and open-source. Once you install it, it will create an entry under [Start] button and it is easy to use.

In this case, I used 7-zip, using a file browser at the top:

Selected the zip file and clicked on the [Extract] icon.

The thing suggested the subdirectory directory for extraction that included the full name of the zip file, but I changed to the directory where the zip file is located knowing the top directory in this zip file is eclipse. I then clicked [OK]:

And 7-zip went its way:

Then I clicked on the [x] and looked at the target directory in my Windows Browser:

I double-clicked on the eclipse executable and saw the the nice logo that Eclipse displays when it loads:

Then a dialog appears that asks you to enter (or accept) the default workspace. It is a place where your projects and files are saved. You can place it anywhere, but I usually have the workspace in the same directory where I keep the original Eclipse zip file rather than a directory under my Windoz %USERPROFILE%, that is C:\Users\jkl in my case. First, I create lots of workspaces. Second, some projects will only work with the particular version of Eclipse, and the plugins that were included. So in my case, I clicked on [Browse] button on the right and by clicking zillions times got to Computer \C:\cygwin64\home\jkl\eclipse_jee2 and requested that the workspace directory is created there:

and clicked [OK] twice. Eclipse came with the Welcome screen that provide you to the links to tutorials, overviews, samples, etc. It is an obligatory reading if you are new. It is also not the easy reading since they developed their strange lingo that you need to learn.

I usually skip this screen by clicking on the [x] on the left Welcome tab, or by clicking on the icon in the upper right corner. Once you do this you will see a virgin Eclipse with no projects. You can see several panes and lots of icons on the top and you can see that you are in the Java EE perspective in the upper right corner:

I will not go into any detail here, since it would take a book. Learning Eclipse is an iterative and always ongoing process. One reason for it is that Eclipse evolves and changes constantly its User Interface from one Planet to Another Planet or Moon. There are many tutorials on the Web. Type Eclipse Tutorial into Google and you will get some of those. I do not want to suggest anything since I did not look at these things lately, but I remember that Lars Vogel did a through job on teaching Eclipse at his http://www.vogella.com/tutorials/Eclipse/article.html. Also, you will gain a lot from the Mark Dexter Eclipse Tutorials Source Forge or http://zenit.senecac.on.ca/~jordan.anastasiade/Eclipse/basics/Beginner/Beginner-DexterTutorial.html that unfortunately get quite old. Start from some simple Hello World in Java to learn the keystrokes. Remember one thing, that for most selections there is the Other menu option. There is so much stuff there that you cannot have a single level menus. I will show you, however, how to associate Tomcat (the popular Web server written in Java that is also a servlet and JSP container).

Installing Tomcat

First, you need to go to the Apache Tomcat download site. Just type Apache Tomcat 8 Download into Google. As an example I used the http://tomcat.apache.org/download-80.cgi page but there are many ways to get it. The 8.0.18 is the latest one as of this writing. Under Binary Distributions section grab the 64-bit Windows zip and save it on your computer (it is relatively short, about 10Mbytes). Unpack it in the directory that you can remember and where you can find it. You will probably use it with other things beside Eclipse, so some top level directory: C:\Tomcat seems sensible. Note that the zip archive's top directory is apache-tomcat-8.0.18 so your resulting path will be C:\Tomcat\apache-tomcat-8.0.18. If you do not have Admin privileges, you can create the C:\Users\YourId\Tomcat that the security people usually leave open. Use your friend 7-zip to unpack the archive under this directory. In my case, when I click on [Extract] icon of my 7-zip, the dialog looks like:

After zip archive was unpacked, I could see the following under the Tomcat Home Directory (the associated environment variable is called CATALINA_HOME):

In the bin subdirectory you will have lots of stuff, but there are also simple .bat scripts to start and stop Tomcat under Windoz. If you double-click on startup.bat:

the Tomcat should start, but the Windoz will ask you for permission if it runs in the directory that is usually associated with Admin:

Also, you will see that the Java opens a Console window with a trace log of the Tomcat startup:

When you type http://127.0.0.1:8080 into the Location field of your browser window, you should get the Tomcat welcome page:

Now, after you clicked on buttons and read all the docs {:-)}, go to your Windows Explorer where you started the Tomcat and double-click on shutdown.bat script.

You should see the Java Console closed, and when you try to refresh your Browser (or start the http://127.0.0.1:8080 page) it will bark:

Now... What if it does not work... I am not sure what to tell you, since there maybe a number of reasons. Try to repeat the exercise by actually typing the startup.bat in your DOS Command Prompt. This is how it should look like if everything is fine:

If the Java Console window does not show up or it bitches about Java not found or something, then you need to check if it your Java installation is fine. For example:

When it complains that it cannot bind to the TCP port, you probably have something else running on this port. The ports that Tomcat uses are listed in the %CATALINA_HOME%\conf\server.xml, namely, in our case C:\Tomcat\apache-tomcat-8.0.18\conf\server.xml. Look for XML elements in this file that list TCP ports and are not commented (i.e., not within <-- . . . -->), and you will find that Tomcat uses a number of ports. The default values may be:

• 8005 -- Shutdown port),
• 8080 -- HTTP Port where it serves pages,
• 8443 -- HTTPS Port where it serves secure pages,
• 8009 -- port that Tomcat uses when serving as a worker for Apache server through the coyote connector,

These can be modified, and you can avoid conflicts (but for God sake, keep the backup of original file before you start messing with it). It may also happen that you installed the Tomcat as an Admin, and you try to run it as a regular user and the directory for logs does not have the write permission, or some read permissions are messed up. BTW, the logs directory (C:\Tomcat\apache-tomcat-8.0.18\logs) should have logs, and if it is writable, you should check it and it may even list your real problems and the time of your unavoidable demise. As always, possibilities of a screw up are endless, but there is usually only a few choices for the stuff to run well.

Tomcat and Eclipse

Now, back to Eclipse. In case you minimized it, and do not know how to get it back, notice that Eclipse added an icon to your Windoz task bar at the bottom (you have it at the bottom, don't you?). Click on it to Minimize or Maximize Eclipse since it takes a lot of your screen acreage. I usually work with Eclipse with dual monitors. With the current mobile madness, I wonder when they will create the Eclipse for iOS, Android or God forbid, Windows-CE. Now you need to add the Tomcat Server to Eclipse. Go to: [Window] -> [Show View] and click on [Servers]. You should see a new tab in the bottom pane:

Click on the underlined link No servers are available... and the Define a New Server window will pop off:

Unfold the Apache folder and click on the Tomcat v8.0 Server at the end of choices and then click on [Next].

The next Window appears (Tomcat Server) where you will [Browse] to the Tomcat Home Directory (known as CATALINA_HOME if you need to ever set it as an environment variable) that in my case is C:\Tomcat\Apache-tomcat-8.0.18

Click on [OK] and it should now appear in the Tomcat Server server dialog. Click on [Finish] and you should now have a server defined both in the Servers tab under Project Explorer in the left pane, and under the Servers tab in the bottom pane.

Now, let us create a Hello World project. Click on File, [New] and [Dynamic Web Project]

When you click on [Next] you will see a screen that allows you to modify your project directory layout and the Build Path (which is Eclipse's generic name for the Java CLASSPATH in this case). Do not modify anything here AND CLICK {Next]:

On the Web Module dialog that shows up, select the Generate web.xml deployment descriptor and only then you can click on [Finish]

Note that under the Project Explorer tab you have the new Project. You can click on the triangle by the the HelloCCL-NET and unfold the intricate web of Dynamic Web Project:

Now, we will create a Hello CCL.NET JSP page. Right-click on WebContent directory and select [New] [JSP File] and click on it.

New dialog appears. Choose the name as: index.jsp

and Click on [Finish]. Of course, you are welcome to go through the intermediate configuration files by clicking on [Next]. The Eclipse will create a skeleton of primitive JSP page for us.

I changed it a bit, but you can change it a bit too. Click on the diskettes (3rd icon on the top bar from the left) to save it.

Now right click on the Project Name (HelloCCL-NET) and select Run as and click on Run on Server

The Run on Server dialog appears. Check if the right server is selected (here Tomcat v8.0) and click [Next]

The next dialog shows you which project is configured to run on the server. Make sure that there is only one project (HelloCCL-NET). If there were more than 1, you would usually select them, and click on the [Remove] button, otherwise you may have unpredictable results. Now you can click on [Finish].

And if everything worked, you should have gotten the following thing in Eclipse. You should also be able to access the http://localhost:8080/HelloCCL-NET/ URL in any browser that you have installed on this machine.

Now you know enough to be dangerous. I could write a book about it, but you would not read it anyhow. There is tons of good stuff on the Internet about it, and since I took away your fear to try things, you are now a free woman (or a man, or both, or none...).

If you think it is useful, share it with your buddies. If you found some trash, let me know about it, and I will correct it.

Jan Labanowski
jkl at ccl dot net