7.4. Setting Up Eclipse and WAF

The following sections describes how to set up a WAF development and debugging environment within Eclipse, an open source Integrated Development Environment (IDE).

7.4.1. Installing Eclipse

  1. Install WAF — install as normal, using the RPM's and WAF Autobuild system. For more information, see the Red Hat Web Application Framework Installation Guide:.

  2. Install EclipseEclipse can be obtained from http://www.eclipse.org. Install using RPM, if possible.

    In order to take advantage of the anti-aliased fonts within Eclipse, use a build of Eclipse designed for the GTK in Red Hat Linux 8.0 and later.

  3. You may also wish to install the Perforce, Resin, and JavaCC plugins for Eclipse, which can be found at:

  4. To install the Perforce and Resin plugins, use the Eclipse Update Manager by selecting Help => Software Updates => Update Manager. Next, add bookmarks for the download URLs listed by the plugins' Web sites. The Update Manager can then automatically download and install the Perforce and Resin plugins.

    To install the JavaCC plugin, download the plugin and unzip it in Eclipse's plugin directory. Then, follow the instructions in the plugin's README file.

  5. Install Resin — if you are using the Resin application server. You may download Resin at Caucho's website: http://caucho.com. You may also want to download the source code for Resin in order to trace through its code when debugging.

7.4.2. Eclipse Preferences Configuration

To set preferences within Eclipse, go to Window => Preferences. Noteworthy preferences include:

7.4.3. Eclipse Project Configuration

This section covers adding and configuring projects to Eclipse for developing with WAF.

7.4.3.1. Adding Projects

WAF
  1. In Eclipse, go to File => New => Project.

  2. Select Java Project.

  3. Name the project, e.g. webapp and select your existing WAF core-platform directory as the project directory.

  4. In the source tab, make sure that Eclipse lists the WAF source directory, src/. If it is not there, click Add Existing Folders... to add it. You may also want to add the directory for the Junit test code, test/src/.

    After adding the existing source folders, click on Create New Folder... and name the folder _generated. This is where Eclipse will store its JavaCC-generated source files.

  5. Select the Libraries tab once you are presented with the Java Settings dialog box.

  6. Click on Add JARs and select all the JARs under your WAF Project (typically under lib and etc/lib).

  7. Click on Add External JARs and add the following JARs:

    • $ORACLE_HOME/jdbc/lib/classes12.zip

    • $RESIN_HOME/lib/jta-spec JAR

    • $RESIN_HOME/lib/resin.jar

  8. Click on the Order and Export tab. Select All.

  9. Create a build folder for Eclipse on your file system. Then, enter the path to that build folder in the Build output folder input box.

  10. Click on the Finish button.

CMS and Other Projects

To add CMS or other projects to Eclipse, follow the same steps as for adding WAF, with the following exceptions:

  • For CMS and other projects that depend on WAF, you do not need to add external JARs. Eclipse will pick up these libraries from WAF.

  • When you reach the Java Settings dialog box, select the Projects tab. For CMS, add a dependency upon WAF. For projects that use both WAF and CMS, add a dependency upon both WAF and CMS.

  • Create build folders for the respective projects.

7.4.3.2. Configuring Eclipse for Perforce

For each project that you have added, go to the Package Explorer and right-click on it. Then, select Team => Share Project. Select the options for Perforce. Now, you should see a Perforce menu and Perforce options for your source files.

7.4.3.3. Building and Deploying with Eclipse

Eclipse uses its own build directories for compiling your source files. However, you will probably still want to use the WAF build system for building and deploying your application. Therefore, you should create a shell script that will do this for you. Then, you may call this shell script to build and deploy WAF from within Eclipse when you are ready to run your application.

Here is an example shell-script, which should be modified appropriately to fit the target environment.

#!/bin/bash

#setup environment
. /etc/profile.d/ccm-config.sh
. /etc/profile.d/ccm-devel.sh
. /etc/profile.d/ccm-scripts.sh

CCM_HOME=/var/ccm-devel/dev/user/cms_dev
ORACLE_HOME="/opt/oracle/product/9.2.0"
JAVA_HOME=/opt/IBMJava2-131

CLASSPATH=$CCM_HOME/core-platform/lib/jaas.jar
CLASSPATH=$CLASSPATH:$CCM_HOME/core-platform/lib/jce.jar
CLASSPATH=$CLASSPATH:$CCM_HOME/core-platform/lib/sunjce_provider.jar
CLASSPATH=$CLASSPATH:$CLASSPATH:$ORACLE_HOME/jdbc/lib/classes12.zip
CLASSPATH=$CLASSPATH:$CCM_HOME/core-platform/etc/lib/iDoclet.jar
export CLASSPATH

export ANT_OPTS="-Xms128m -Xmx128m"

##########
#build
##########

#uncomment to make enterprise.init
#cd $CCM_HOME
#ant make-config
#ant make-init

#clean
cd $CCM_HOME
ant clean

#build
cd $CCM_HOME
ant deploy

#javadoc
cd $CCM_HOME
ant javadoc
ant deploy-api

Example 7-1. Shell-script to build and deploy from within Eclipse

In your ant.properties file, make sure that you have set compile.debug=on. Once you have created this shell script, in Eclipse go to Run => External Tools => Configure. A dialog box will appear for configuring external tools. Select New and in the Tool Location input box, select your shell script for deploying WAF. Select the options:

  • Block until tool terminates

  • Show execution log on console

Then, select OK. Now, in Eclipse, your shell script will appear under Run => External Tools. Use that to build and deploy WAF from within Eclipse.

7.4.4. Eclipse Debugging Configuration

To do runtime debugging of WAF within Eclipse, you will need to add a new Resin launch configuration for running WAF and a new Remote Java Application debug configuration for attaching to WAF.

WAF Execution Setup

To be able to run WAF from Eclipse, select Run => Run. Select Resin and then click on New. Then, enter information for the following tabs:

  • Main Tab

    To set your project, select the highest-level project, which is the project no other projects are dependent on. This is where you select your resin.conf.

  • Arguments Tab

    In the VM arguments text box, enter the following, all in one line — this line is broken for printing purposes with a "\":

    -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=\
    dt_socket, server=y, suspend=n,address=8000 -Xms128m -Xmx128m

    You may allocate more memory than 128 MB to the server if you wish.

  • Classpath Tab

    Add all the external JARs under $RESIN_HOME/lib to your user classes.

  • Common Tab

    At the bottom of the dialog box, select Display in favorites menu: Run.

    You are now finished and may close the dialog box.

WAF Debugging Setup

In Eclipse, select Run => Debug. In the dialog box, select Remote Java Application and then click on New. Then enter information for the following tabs:

  • Connect Tab

    Enter a name for your debug configuration, such as webapp-debug. Select the same project previously selected as the main project. Enter the host name (localhost should be fine). Use 8000 as your connection port. Also, select Allow termination of remote VM.

  • Source Tab

    Add all the external JARs under $RESIN_HOME/lib to your source lookup path.

  • Common Tab

    At the bottom of the dialog box, select Display in favorites menu: Debug.

You are now finished and may close the dialog box.

7.4.5. Eclipse Setup Validation

Your Eclipse setup should now be complete. To test this:

  1. Select Run => External Tools => [Deploy Script].

  2. Select Run => Run and pick the WAF configuration. The server's log output should become visible in the Console. Wait for the server to finish initializing.

  3. Select Run => Debug and pick the debug configuration. This opens the Debug perspective. Open a source file, set a breakpoint, and request a page from the server.

If everything is setup correctly, you can now develop with Eclipse and use it to step through your WAF code.