XNAT Development

Best Practices for Development


Other topics

[Edit Nav]

XNAT Codebase: Eclipse Integration

Eclipse is a powerful Java IDE and the prefered development environment for XNAT.

Recommend Plugins

There are a number of extremely useful plugins for XNAT development in Eclipse.

The update sites can be added at: Help > Install New Software > Add

Importing a Mercurial Project

We will use the MercurialEclipse and M2Eclipse project to import the xdat_core module from
http://bitbucket.org/nrg/xdat_core_1_4/. This method will also work well for other Maven 2 projects like DicomUtils, UploadAssistant, etc.. Note that you could also clone the project from the command line or with TortoiseHg, then simply import as existing project.

File > Import ...

Mercurial > Clone Existing Mercurial Repository > Next

Enter the URL (in this case, http://bitbucket.org/nrg/xdat_core_1_4/) > Next

Click Next

Click Finish

Our project is cloned and imported into the workspace. If the project uses Maven 2 (as xdat_core does), it will likely take a few minutes to download all the dependencies into ~/.m2/repository.

Importing xnat_builder

The xdat_release module, the primary XNAT project, is currently more complex to import into Eclipse than some of the other projects (we plan on address this complexity in the future).

To get xdat_release into Eclipse, we will not use Eclipse to clone the repository as we did previously, instead we will follow the the XNAT Build from Source instructions, install the code, then register the project in Eclipse.

1) Clone xdat_core (xdat_core_1_4)

As show above , import the xdat_core (xdat_core_1_4) project. xdat_core is a dependency for the xnat_builder project.

2) Clone xdat_release and pipeline

Follow the XNAT Build from Source guide to clone the xdat_release and pipeline repositories.

3) Install XNAT

The Eclipse xdat_release project requires that the setup script has already been run once to generate a handful of classes. To run the setup script, follow the XNAT Installation Guide.

4) Prepare the Eclipse Project

We distribute sample eclipse configuration settings, sample.project and sample.classpath (checking the real .project and .classpath files into the Mercurial repositories is currently too brittle for xdat_release).

From the Windows command line, in the xnat folder:
copy sample.classpath .classpath
copy sample.project .project
Use "cp" instead of "copy" for other operating systems.

5) Import the Eclipse Project

We are now ready to import the existing project into Eclipse.

File > Import...

Existing Projects into Workspace > Next

Browse > Select xnat > Ok

Click Finish

Your Eclipse should look like below, with no build errors.


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