XNAT Eclipse Integration

Eclipse is a powerful Java IDE and the prefered development environment for XNAT. SpringSource Tool Suite (also known as STS) is based on Eclipse, but includes a number of plugins already installed and configured. More information on installing and configuring developer tools, including various useful Eclipse plugins and information on using other IDEs with XNAT, can be found on the XNAT Developer Tools page. This page describes specific procedures for working with the XNAT builder code within Eclipse or STS.

1) Get the xdat source

xdat is a dependency of xnat_builder, and much of the source resides there.  You have a couple options here:

  1. Clone using the command line, and create the .project file (otherwise Eclipse won't be able to import the project):

    hg clone https://bitbucket.org/nrg/xdat_1_6dev xdat
    cd xdat
    copy sample.project .project

    Once this is done, import the project into Eclipse (File-->Import->General–>Existing Projects into Workspace, browse to the project).

  2. Clone using MercurialEclipse (use URL https://bitbucket.org/nrg/xdat_1_6dev, and name the folder "xdat")
Once the project is in Eclipse, right click on it and Configure–>Convert to Maven Project.  (You'll need to have m2eclipse plugged in for this option to be present.  It's included with STS.  See the  developer tools page for download links).

2) Get the xnat_builder source

You have a few options here:

  1. Clone using the command line
  2. Clone using MercurialEclipse
  3. Download the latest release, then unpack into the desired location

3) Clone pipeline repo (optional)

Follow the XNAT Build from Source guide.

4) Prepare the Eclipse project

Sample Eclipse project settings (sample.project and sample.classpath), are including in the xnat_builder source at root level.  They just need to be renamed so that Eclipse will recognize them.  From the Windows command line, in the xnat_builder folder:

copy sample.classpath .classpath
copy sample.project .project

Use "cp" instead of "copy" for other operating systems.

5) Import the project into Eclipse

This step is required unless you used MercurialEclipse in Step 2 (in which case the project will be imported automatically after it's cloned):

  1. File-->Import->General–>Existing Projects into Workspace.
  2. Browse to the project.

6) Configure build.properties

Instructions here.

7) Setup XNAT

In order to get full support for all the Java classes generated by the XNAT installer, it's best to run the setup script before attempting to debug in Eclipse.  Instructions here.  

After the script completes, refresh the xnat_builder project in Eclipse.


Eclipse includes a powerful debugger allowing the developer to set breakpoints and examine state. If Eclipse is managing the process, debugging is just as one would expect. However, due to the deployment structure of XNAT, Eclipse often can not manage the Tomcat process running XNAT. We therefore recommend using JPDA to connect to a running Tomcat instance (Debugging with Eclipse & JPDA)

Tips & Tricks

Keyboard Shortcuts

Eclipse includes a huge number of features that are often hidden deep within menus. Learning a handful of common keyboard shortcuts can dramatically speed up development. Ctrl+Shift+L will display a list of current shortcuts.

There are several articles with common and useful shortcuts:

Some personal favorites include:

  • Crtl+Space = Autocomplete
  • Crtl+Shift+R = Open resource (accepts wildcards)
  • Alt+Shift+R = Rename

Related Pages