ePDoc Page

Configuring Eclipse for Servlet and Flex Development

During the past few months I've been doing Flex and Servlet development in Eclipse on a WinXP machine and simultaneously on a Macbook Pro running Mac OS 10.4. The tools and set up are pretty much the same on Win and Mac.

For newbies, figuring out the correct tools to use and how to configure them can take a bit of time and a bit of guess work. It isn't always obvious from searches on the web which are the best options, and what information is up to date. I started capturing configuration details on an internal wiki, because we have a few people on my project at Adobe that have needed to simultaneously come up to speed on these procedures. I've publicly posted this information here to help others that may be in the same situation that I was a few months ago. This information dates from September 2007.

To post comments, please visit the blog entry for this article.

Installing Eclipse

Install the latest version of Eclipse from http://www.eclipse.org/downloads/. Eclipse SDK 3.3 is the current version. I use Eclipse Classic, which is equivalent to what the setup you used to get in v3.2.

Win - Unzip to your favourite location (eg. c:\usr)
Mac OS X - Uncompress to /Applications or your favourite location.

A nice thing about Eclipse is that the eclipse folder is self-contained. So, if you bugger up an installation with various plug-ins or you need to run a different instance with a particular set of plug-ins, just unzip a new Eclipse folder instance. Of course on Mac most apps already have this nice characteristic :-).

Installing Java

If you are on Windows, install the latest version of Java SE (JDK 6 Update 2) from http://java.sun.com/javase/downloads/index.jsp. I let the Sun installer install this to the default location under Program Files.

My Macbook Pro came with Java pre-installed, so I haven't done a Java installation here yet. It also came with Perl pre-installed. And bash. And a terminal. And an assortment of unix command line tools.

Installing Perforce

We use Perforce at Adobe and I like running the perforce plug-in for Eclipse (called P4WSAD). Before installing the plug-in you will need to install the Perforce client tools including the command line tool (details not covered here). To then install the plug-in:

Open Eclipse menu Help > Software Updates > Find and Install... > Search for New Features to Install > New Remote Site
Create a New Remote Site with the name Perforce and the following URL: http://www.perforce.com/downloads/http/p4-wsad/install/

Once you have the plug-in installed you will have access to Perforce Help, under menu Help > Help Contents there will be an entry Perforce SCM, and a Perforce Perspective.

I will mention that I have had problems with the Perforce plug-ins that have caused Eclipse to quit on launch. Removing the Perforce plug-ins fixed the problem. Perforce is aware of this issue (I should add more details here on this issue when I can find the support email thread).

Another general hint for Perforce on a Mac laptop that roams on DHCP is to leave the Host field blank for your workspace.

Installing Flex

The Flex development environment for Eclipse is useful if you are doing Flex or AIR development and want an IDE with debug support, but it isn't free. You can get a trial version of the Flex 3 beta from http://labs.adobe.com.

The Flex installer walks you through the installation process (win or mac). There are two downloads that you can choose, the standalone installer, and the Eclipse plug-in installer. Get the Eclipse plug-in installer, as it includes the standalone installer. It's a 200M+ download because it includes a complete copy of Eclipse but, since you've already installed Eclipse, you can choose to just add the plug-ins to your existing Eclipse installation.

Setup for Tomcat Servlet Development

The preferred way to use Eclipse and Tomcat together is with the sysdeo tomcat plug-in. This allows you to control and debug the tomcat server from within Eclipse. Stay away from the Web Standard Tools (WST) Project (v1.5.4). It's big and possibly a source of out-of-memory crashes. I had particulary bad luck trying to use this package, and was later advised by a more experienced servlet developer at Adobe to use sysdeo.

To understand Java servlets I recommend you get your hands on O'Reilly's Java Servlet Programming, Second Edition by Jason Hunter. Even though the 2nd edition dates back to 2001, it is still very relevant.

Installation

Install the latest version (6.0.13) of Tomcat from http://tomcat.apache.org/download-60.cgi and unzip (eg. to c:\usr on Windows or /usr/local on Mac OS X). Apple has a good document describing how to install tomcat on a Mac OS X.

Install the sysdeo Tomcat plugin for Eclipse from http://www.eclipsetotale.com/tomcatPlugin.html. Version 3.2.1 of these plug-ins works with Eclipse 3.2 and 3.3, as well as Tomcat 6.x. Follow the online instructions at this site, which will cause you to do no more then extract com.sysdeo.eclipse.tomcat_3.2.1 into your eclipse/plugins folder.

Configuration

Configure tomcat development for Eclipse using Window > Preference > Tomcat on Windows, or Eclipse > Preferences on the Mac.

Set the version to 6.x and the Tomcat home (called TOMCAT_HOME here) to the Tomcat install folder, for example /usr/local/apache-tomcat-6.0.13 which contains bin, webapp, conf subdirectories.
Set the Context declaration mode to Context files. This will result in configuration files later being written to TOMCAT_HOME/conf/Catalina/localhost (more on this below).
On Windows I set the JVM settings to point to a JDK install, rather then a jre install. On Mac I just set this to " JVM 1.5.0 (MacOS X Default)".
Consider increasing Eclipse's memory limits by modifying eclipse.ini in the eclipse root directory as follows. You may only want to do this if you run into problems.
```
         -vmargs
         -Xms80m
         -Xmx512m
```

Creating a Servlet Project

Create an Eclipse servlet project (eg. MyProject) using File > New > Project and selecting Java > Tomcat Project.

In the wizard, give your context a name (eg. MyContext). This is case sensitive and will be used in the URL that accesses your servlet.
When you create the servlet project, an xml file called MyContext.xml will be created for you in the tomcat folder TOMCAT_HOME/conf/Catalina/localhost. This will point to your projects root directory PROJECT_ROOT. This XML file represents a context. You can have multiple contexts running on one Tomcat server (see further below).

Context XML files look like this:

    <Context path="/MyContext"
    reloadable="true" 
    docBase="PROJECT_ROOT" 
    workDir="PROJECT_ROOT\work" />

Associated with this new context, you must hand edit your PROJECT_ROOT/WEB-INF/web.xml file. You can add all your servlets from MyProject to this file. If you want to know anything more about web.xml files, check out the O'Reilly book mentioned above.

Sample web.xml file:

<?xml version="1.0" encoding="UTF-8" ?>
<web-app id="WebApp_ID" version="2.4"   xmlns="http://java.sun.com/xml/ns/j2ee"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee   http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>My Demo Server</display-name>
<servlet>
  <servlet-name>MyServlet</servlet-name>
  <servlet-class>com.example.MyServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>MyServlet</servlet-name>
  <url-pattern>/servlet</url-pattern>
</servlet-mapping>
</web-app>

For existing tomcat projects, you can determine the context name by right-clicking on the project from the Eclipse Package Explorer window, opening Properties > Tomcat and reading the Context name. I've gotten into the habit of editing context XML files by hand.

Note that a PROJECT_ROOT/work folder is required to exist, even if empty. It is needed in order for the project to compile, and it is referenced from MyContext.xml. Built files are sometimes output into this folder (eg. when using JSTL with servlets).

Adding Libraries to your Servlet Project

Libraries (i.e. jar files) will need to be added to your Eclipse project to allow it to compile and they will also need to be somewhere where they can be loaded by the tomcat server. One set up setp does not appear to cover both needs.

Adding libraries to an Eclipse project:

Right-clicking on the project, then Properties > Java Build Path > Libaries
Add jar files using variables by clicking Add Variable, select a variable (or configure a new one), click Extend and browse to the location of the jar file
Add jar files without using variables by clicking Add External JAR and browsing to the jar file

Exposing libaries to tomcat when not deployed as a WAR file:

Tomcat loads libraries that it finds within it's own directory. It also loads content from PROJECT_ROOT/WEB-INF. Here it looks for compiled class files and jar files.
My current understanding is that PROJECT_ROOT/WEB-INF/lib must contain all dependent jar files. This means you must make a copy of your jar files and put them in this folder. It seems that this would be a good candidate for a build.xml Ant file operation, but I have not explored this possibility yet.

Exposing libraries to tomcat when deploying a WAR file

I don't have experience with this yet.

More on Apache Tomcat Server Contexts

In my current research activity I have five different context files under the TOMCAT_HOME/conf/Catalina/localhost directory. Three of these are for individual servlet applications which run independently of each other. Another one I use for the debug convenience of serving Flash SWF files that are referenced by one of my servlet projects. This context file points to my FLEX_PROJECT/bin directory where my SWF files are output. The fifth context points to a documentation tree that I also serve from my Apache Tomcat server (I've recently switched to using Dreamweaver to write my documentation, as Framemaker doesn't run natively on the Mac).

I included a sample MyContext.xml file for servlets above. Here are sample context xml files for serving bin/SWF files (Win) and documentation (Mac). I'm not sure what role, if any, the workDir serves in this situation.

Revision History

Created 3 September 2007 by Jim Pravetz from material collected internally at Adobe since June.

ePDoc