A Rough Guide to James Development Using Eclipse

Follow these steps to develop James code using the Eclipse IDE. Use the Eclipse Help and Tutorials to more fully understand the Eclipse concepts and actions described here.

Download and Install Eclipse

Eclipse can be obtained from http://www.eclipse.org/. Follow the installation instructions that come with the download.

Connect to the Apache CVS repository

• Open the CVS perspective and create a new Repository Location with these properties:
  • Host: cvs.apache.org
  • Repository Path: /home/cvspublic
  • User: anoncvs
  • Password: anoncvs
  • Connection type: pserver
  • Use default port: true

Check Out James from the Apache CVS repository

• In the CVS perspective expand the Apache CVS hierarchy to show HEAD/james-server.
  • From the pop-up menu, select "Check Out As..."
  • From the "New Project Wizard", select Java as the project type and click the "Next" button.
  • Specify a project name and location and click the "Next" button.
  • Click the "Finish" button to proceed.

Verify Checkout

Before attempting to configure Eclipse, verify that you have everything you need by running a build of James outside of Eclipse. This will fetch, or prompt you to fetch, any missing components.

• Open a shell and switch to the directory into which James was checked out.
• Run the 'build' script without arguments.
• When this completes cleanly, the checkout is verified.

Customize Project Settings

• Open the Java perspective and select the project.
• From the pop-up menu, select "Properties".
  • Select "Java Build Path"
    • Select the "Source" tab.
    • * Select "Use source folders contained in the project".
    • * Click "Add Existing Folders" and select folder "src/java".
    • * Click "OK" and accept the build output folder of "bin".
    • Select the "Libraries" tab.
    • * Ensure exactly one "rt.jar" file is listed and that it is for Java 1.3.1. See the Eclipse help for how to import and specify JVMs with Eclipse.
    • * Click "Add Jars..." and add every .jar in the James project's "lib" and "phoenix-bin" directories and subdirectories.
    • Click "OK" and Eclipse should recompile James without errors.

You are now ready to develop James in Eclipse.

Build, Test and Debug Code

As James is a server application I prefer to transfer my updated files to a remote machine, run James' Ant build script (build.bat or build.sh) on the remote machine to update the distribution and then use the Eclipse remote debugger to test. This means that the build, deployment and execution are being tested as they will be used and any changes validated. You can use another session on your local machine as the 'remote machine', the JVM is still 'remote' from the one used by Eclipse. The JVM pointed to by the JAVA_HOME environment variable for the session used to build and run James must be v1.4.0 or above. To debug remotely:

• Uncomment the DEBUG property in the James start-up script (run.bat or run.sh). Now, when you run the script the JVM will pause waiting for a debugger to attach.

• In Eclipse select Run>Debug... to open the Launch Configuration widget.

  • Select 'Remote Java Application' as the configuration type and click the 'New' button.
  • Fill in the configuration properties so that they match those specified in the James start-up script and click the 'Apply' button.
• If you have not already done so, run the James start-up script so that it is waiting for a connection.
• In Eclipse, select the appropriate Launch Configuration and click the 'Debug' button to proceed. James will now start and you will see all of its threads, as they are created, displayed in the Eclipse debugger.

Read the Eclipse Help to understand the many facilities now at your fingertips.

Release patches

Eclipse is able to build patches against the code stored in the CVS repository. This makes patch creation very easy. Still, remember that the code in the repository may have changed since you imported it. Use the CVS Perspectives Synchronisation feature to ensure you are up-to-date before creating a patch. Eclipse offers the ability to generate a patch that includes new files. This does not work when the new file is in a new directory! It is safest to work in the more conventional manner, building a patch for changed files and submitting new files separately.

To create a patch:

• Select the item or items you wish to create a patch for.

• From the pop-up menu, select "Team>Create Patch...".

• Select "Save In File System", "Browse" to select a target file and click the "Next" button.
• Select "Recurse into sub-folders", unselect "Include new files in patch", select the Diff output format of "Unified" and Click the "Finish" button.

You have created a patch!