How to Setup Eclipse, Tomcat, and DSpace for Development
This is an updated guide describing how I configure Eclipse, Tomcat, and DSpace for my development. A previous version of this guide was written for Eclipse 3.4 and this version has been updated for the latest versions of both Eclipse and DSpace. One of my motivations forcing my move to the newer version of Eclipse is the ability to handle Java 1.6. Apple has decided to stop shipping both 32bit and 64bit versions, instead they are only providing 64bit Java binaries. Eclipse 3.5 is the first version to support 64bit on OS X.
Versions:
1) Download Eclipse
Obtain a fresh version of Eclipse from the official download site, from which there are several variants. You can choose either “Eclipse for Java EE Developers” or “Eclipse for Java Developers”. Once you’ve selected the variant, choose the distribution that is appropriate for you (Mac, Windows, Linux, and 32bit vs 64bit). Once downloaded, unpack the software where you would like it to be installed, however it’s best if you do not try start Eclipse until after step #2.
2) Install the Sysdeo Tomcat plugin
The Sysdeo Tomcat plugin allows you to start, stop, and restart Tomcat from within Eclipse. The plugin also allows you to debug a running web application by setting break points, stepping through the code line by line, and examining memory locations through the standard Eclipse debugger. Download the latest version of the Sysdeo Tomcat plugin and un-compress the software into Eclipse’s plugin directory. Next start Eclipse for the first and the plugin will be recognized. If you have previously started Eclipse then it will not immediately recognize the new plugin. In this case you need to start Eclipse with the “-clean” option from the command line.
http://www.eclipsetotale.com/tomcatPlugin.html
3) Install the SVN & Maven plugins
Fortunately for the other plugins the process is easier than the Tomcat plugin, you will be able to use the built-in updating mechanism. There are two more plugins that you need: Subversive and M2Eclipse. Subversive enables you to checkout the DSpace source code and keep up-to-date with the latest changes to the platform from DSpace’s SVN Repository. Maven’s M2Eciplse plugin is used to support DSpace’s new Maven-based build system. Begin by selecting “Help -> Install New Software…” from the main menu.
Near the top of the Install New Software dialog box there is a button labeled “Add…”, this lets you add a new site the list of places where Eclipse will look to get software from. We need to add a new site for M2Eclipse’s plugin. Click the “Add…” button and enter the information blow into the Add Site dialog box.:
Name: M2Eclipse
Location: http://m2eclipse.sonatype.org/update
Add new M2Eclipse site.
Click “OK” to add the new site. You will be returned to the Install New Software dialog box, change select field labeled “Work With” to “–All Available Sites–”. This will bring up a big list of all the available software you can install from all knows sources, including the one you just added.
Select the "--All Available Sites--" option.
From the large list of Eclipse plugins and other components select the three components listed below for SVN and Maven:
- Collaboration
- Subversive SVN Team Provider (Incubation)
- Maven Integration
- Maven Embedder
- Maven Integration for Eclipse (Required)
Once the plugins are selected, click the “Next >” button and follow the dialogs to install the plugins. After they are installed you will be prompted to restart Eclipse which you should agree too. When Eclipse restarts there should be a dialog box waiting for you to select which SVN implementation to use. You can either choose to use JavaHL which uses your local system implementation or SVNKit which is a pure Java implementation. If you clicked the window away, or it did not appear, then switch to the “SVN Repository Exploring” perspective and the dialog box will appear.
Select which type of SVN implementation to us, either JavaHL to use your OS's local binaries or SVN Kit for a pure Java implementation.
4) Check out the DSpace source code
The next step is to check out the DSpace source code from the DSpace SVN Repository. If the “Welcome” tab is displayed when you start eclipse, click that away to return to the workbench. In the Project Explorer panel, left hand side, select “New -> Project…” from the context menu.
Project Explorer -> New -> Project...
This will bring up a “Select a wizard” dialog box, select entry the “Project from SVN” wizard and click the next button.You will then be asked to configure an SVN Repository to check out code from. In the URL field put DSpace’s repository URL and leave all other fields at their defaults. Then click next.
URL: http://scm.dspace.org/svn/repo/
Enter the Root DSpace SVN Repository
You may be asked to accept a certificate from the repository, if so, accept it.
The next step will ask you to select a specific version of DSpace to checkout. You can choose a specific taged version such as 1.5.1 or 1.5.2. These tags will never change, they have already been released. Alternatively you can choose to check out a branch or mainline trunk these versions will continue to change over time as new features and bug fixes are added. Click the “Browse…” button to select the version of DSpace you want to work with. When you are done, click the “OK” button followed by the “Finished” button.
Select which version of DSpace to check out, either a tag, branch or the main line trunk.
The final step will ask you where to place DSpace within your Eclipse workspace. Select the last option “Check out as a project with the name specified:” and enter any name you choose.
5) Configure Maven
After checking out DSpace’s source code the next step is to compile. DSpace uses Maven as its build system but before you can start to compile you’ll need to configure Maven. Locate the project you just checked out in the Project Explorer on the left hand side of you Eclipse workbench. Right clicking on the project will bring up a context menu. There will be a Maven submenu with several options, you need to enable dependency management and nested modules. After ensuring those two options are turned on use Maven to update the project’s configuration. Between each of these steps Eclipse may need to rebuild its workspace, however after it is finished you should not see any compilation errors.
- Maven -> Enable Dependency Management
- Maven -> Enable Nested Modules
- Maven -> Update Project Configuration
Next you need to create a “Run Configuration” to compile DSpace. From Eclipse’s top tool bar select “the green arrow -> Run Configurations…” as shown below:
The Green Arrow -> Run Configurations...
Next the “Run Configuration” dialog box will appear. Locate “Maven” on the list, and right click to select the “New” option from the context menu.
Create a new Maven-based run configuration.
This will change the right hand side of the dialog box displaying the details for a maven command. Fill out the following parameters as shown below in the picture.
Name: MVN Package
Base Directory: ${project_loc}
Goals: package
Next add a new parameter “dspace.config” that points to the full path to you dspace.cfg.
Detailed view of the completed run configuration
When you are finished click the “Run” button to compile DSpace. I suggest you also create another Run Configuration for the Maven “clean” goal.
6) Configure Tomcat
The last component needing configuration is the Tomcat Sysdeo Plugin. This plugin enables you to start and stop Tomcat from within Eclipse and run web applications in the debugger. However the plugin needs to know where your Tomcat is installed and where to run the web application. First, start with general Tomcat configuration. Select the main Eclipse preferences, “Eclipse -> Preferences” from the main menu (under windows this may be located in the File menu).
Select the appropriate Tomcat version and path.
Inside the “Preferences” dialog box expand the “Tomcat” option from the left hand hierarchy. At this screen select the correct version of Tomcat that you are using, and enter the full path to the Tomcat directory. Next select the “Tomcat Manager App” from the left hand hierarchy and enter your Tomcat username and password. If you have not set up a Tomcat manager account then use the “Add user to tomcat-users.xml” button to create one. When you are finished click “OK”.
Provide a username and password to authenticate with Tomcat's manager application.
The next step is to configure the DSpace project to use Tomcat. In the main menu select the project’s properties by “Project -> properties”, and select “Tomcat” from the left hand hierarchy. Enter the following fields and click “OK”.
Is a Tomcat Project: Check
Context Name: dspace
Subdirectory: dspace-xmlui/dspace-xmlui-webapp/
target/dspace-xmlui-webapp-1.5.2/
You need to change the sub-directory to point to a complete Webapplication ARchive (WAR) file or directory. This directory will change if you want to check out the JSPUI or the XMLUI, and it also changes slighly for each different version of DSpace. Below are some examples you can use to extrapolate where which directory to use.
DSpace JSPUI 1.5.2: dspace-jspui/dspace-jspui-webapp/target/dspace-jspui-webapp-1.5.2/
DSpace XMLUI 1.5 branch: dspace-xmlui/dspace-xmlui-webapp/target/dspace-xmlui-webapp-1.5.2-SNAPSHOT/
Declare the project as a Tomcat Project, set a context name, and provide the path to the web-application.
9) Deploy the web application
Congratulations your done! To test that everything work start Tomcat, then use the Update and Reload commands to publish DSpace’s web-application into Tomcat. Use you’re web browser to check that DSpace is running.