From DSpace Wiki

[edit] Prerequisite Installation

1. Install Eclipse 3.2.2 from http://www.eclipse.org/

   (Eclipse 3.2.2 is specified because this is the version that this HOWTO was written using. It probably works with older versions and newer versions too, but no promises that it is the same)

2. We need to install a variety of plugins to allow us to interact with DSpace and Tomcat in a fully integrated way. To install plugins into Eclipse you should use Help -> Software Updates -> Find and Install ... -> Search for new features to install. On this page you will find a couple of pre-set install sites. For the plugins that we need we also need to add 2 new sites to this list, which is done by clicking "New Remote Site" on the right. URLs are given below.
   1. SubClipse (this is assumed for this tutorial, but you may also wish to use SubVersive). Remote URL: http://subclipse.tigris.org/update_1.2.x

      Install the most recent version of the client

   2. SysDeo Tomcat Plugin. Remote URL: http://www.sysdeo.com/eclipse/tomcatplugin

      Install the most recent version of the plugin

   3. Web Standard Tools. This uses a pre-configured plugin site. Go to: Callisto Discovery Site -> Web & J2EE Development -> Web Standard Tools and select the checkbox on the left. This will alert you to required dependencies. Click "Select Required" on the right and this will resolve those dependencies.
   4. Database Tools: This also uses the pre-configured plugin site. Go to: Callisto Discovery Site -> Database Development and select the checkbox on the left (this will also select all the packages underneath that directory). Click "Select Required" to resolve the dependencies before installing
3. After you have installed all of these plugins, or in-between each one, you will need to restart the Eclipse workspace
4. You will need to have tomcat installed locally. Obtain the latest version of tomcat from: http://jakarta.apache.org/tomcat

[edit] Configuring your working environment

Obviously it's really up to you how you want your Eclipse to look, but this section details how to configure the tomcat plugin in general, and which views you will find useful to have included in your main Java Perspective.

[edit] Preparing the Tomcat Plugin

1. Open the tomcat preferences pane: Window -> Preferences -> Tomcat
2. Select your installed Tomcat version, and its home page (hit Apply when finished). For example:

   Tomcat Version: 6.x

   Tomcat Home: /opt/tomcat6

3. Under Tomcat -> Advanced, enter the Tomcat Base (hit Apply when finished). This should generally be the same as the Tomcat Home:

   Tomcat Base: /opt/tomcat6

4. Under Tomcat -> JVM Settings, you need to enter the JDK's tools.jar file for the "Classpath (before generated classpath)". You should find this in the directory [installed jdk]/lib/tools.jar
5. Under Tomcat -> Tomcat Manager App, enter a username and password for the desired manager user. If this user doesn't already exist hit "Add user to tomcat-users.xml" (hit Apply when finished)

[edit] Visual Configuration of Eclipse

To add a new View to the current Perspective, use: Window -> Show View -> Other (in general). From here you can select the view to open from a list of available categories.

1. Add the Console View (General -> Console)
2. Add the Database Explorer View (Data -> Database Exporer)
3. Activate line numbering: Window -> Preferences -> General -> Editors -> Text Editors and select "Show line numbers"

[edit] Checking out DSpace as a Tomcat Project

1. Open the SVN Repository Exploring Perspective by using Window -> Open Perspective -> Other -> SVN Repository Exploring
2. Right click in the "SVN Repository" View on the left, and use: New -> Repository Location
3. Enter the location of the DSpace SVN repository: http://scm.dspace.org/svn/repo/dspace
4. Open up the location with the arrow on the left, and drill down to find trunk/dspace
5. Right click on trunk/dspace and select "Checkout..."; leave "Check out as a project configured using the New Project Wizard" selected and hit "Finish". Note: some implementations appear to have a "Checkout" and a "Find/Checkout as..."; if you have this setup, you want to select the second option.
6. You will be given a list of project types to check out as. Select Java -> Tomcat Project and hit "Next"
7. Insert a name for the project. For example dspace-svn. Then hit "Next".
8. Leave the context name as-is (this is the url path that dspace will become available under), and leave "can update context definition" checked. In the box marked "Subdirectory to set as application root" enter "/jsp". Then hit "Finish".
9. Follow the on-screen instructions, and see the source code get checked out into your eclipse workspace. You should now have a new project called dspace-svn, which will contain some additional things to the contents of the SVN repository, including now a directory named "work", and two files: .cvsignore and .tomcatplugin
10. Configure the fine details of this Tomcat Project by right clicking on the project name and selecting Properties -> Java Build Path
    1. Java Build Path -> Source: "Add Folder" on the right, and select the "src" directory in the root of the project (you may notice your project being compiled in the background)
    2. Java Build Path -> Source: select the folder dspace-svn/jsp/WEB-INF/src and hit "Remove" on the right
    3. Java Build Path -> Libraries: "Add JARs" on the right, and select all of the files in dspace-svn/lib and hit "OK". This tells Eclipse to use these as part of your classpath, and your deployed application.

Now we have DSpace set up as a tomcat project, although it won't work yet until we've installed DSpace into the Eclipse Workspace ...

[edit] Installing DSpace into the Eclipse Workspace

This section is principally the same as the standard DSpace installation, so assumes that you are familiar with that process, and doesn't dwell on potential difficulties.

1. Obtain the PostgreSQL JDBC driver, and drop it into dspace-svn/lib
2. Create a directory dspace-svn/jsp/WEB-INF/lib
3. Copy all of the jar files from dspace-svn/lib into dspace-svn/jsp/WEB-INF/lib
4. Open up the project Preferences, and go to Preferences -> Java Build Path -> Libraries, and use "Add JARs" to add the new JAR file for postgres
5. create a directory under dspace-svn into which you want to install the application. For example dspace-svn/dspace-install
6. copy dspace-svn/config/dspace.cfg into dspace-svn/dspace-install with the file name dspace.cfg.initial
7. Prepare the configuration for installation in the Eclipse Workspace. The configuration does not need to be heavily modified, but the following points should be set correctly:

 dspace.dir = /home/user/workspace/dspace-svn/dspace-install
 dspace.url = http://localhost:8090/dspace-svn
 db.url = jdbc:postgresql://localhost:5432/dspace-svn

Here we have assumed that you will also call your database dspace-svn (we will deal with this in a moment)

1. Create the database that will back this up. The most basic version of this command is just:

 createdb dspace-svn

1. Now we can perform the install inside the Eclipse workspace. To keep everything nice and eclipse-centric, we will build it inside Eclipse using Ant. Right click on the build.xml file, and select Run As -> Ant Build... (note that there are two Ant Build options, and you want the second one, with the trailing dots)
2. Targets Tag: uncheck "compile" and check "fresh_install"
3. Main Tag: In the Arguments box, insert -Dconfig=/home/user/workspace/dspace-svn/dspace-install/dspace.cfg.initial
4. Hit "Run" at the bottom of the page. If you have the Console view open you will see Ant building the DSpace application inside Eclipse. This will produce the usual output of a DSpace fresh_install. If you right click your project and hit "Refresh" you will see the changes it has made to your workspace. There will be a new directory called build which will contain the compiled classes, the built WAR files, and the dspace-web.xml and oai-web.xml files. Unfortunately, this method of working with DSpace will only support the main DSpace application (you can adapt this methodology to work with OAI in a different Tomcat Project). Your "dspace-install" directory will also contain the fully installed application, including the assetstore, logs and so forth, which is very useful.
5. Open the directory dspace-svn/build and copy the file dspace-web.xml into dspace-svn/jsp/WEB-INF with the name web.xml.
6. Open the directory dspace-svn/build/classes and copy the file Messages.properties into dspace-svn/jsp/WEB-INF/classes
7. Restart the tomcat web server through the Eclipse interface. This is done by clicking the right-most of the three tomcat buttons that are in the Eclipse toolbar courtesy of the SysDeo plugin. (In reality, you can restart the context without restarting tomcat, which can be done by right clicking on the project name and selecting Tomcat project -> Reload this context; furthermore, Eclipse will regularly auto-deploy the context while you are making changes). You can see the results of these actions reflected in the Console View if you have it open.
8. Go to your web browser and enter the URL: http://localhost:8080/dspace-svn And Hey Presto! One DSpace application running inside Eclipse.

[edit] Viewing the Database in Eclipse

1. Go to the Database Explorer View and select "New Connection" from the right.
2. Use the following details to create a new database connection: Generic JDBC -> 1.0. Enter the database name dspace-svn; The JDBC driver: org.postgresql.Driver; The location of the driver will be the postgres JAR file, in dspace-svn/lib; The connection URL should be as specified in your dspace.cfg: jdbc:postgresql://localhost:5432/dspace-svn. To check that this is working hit "Test Connection". Once it is hit "Finish".
3. Browse your database using the Database Explorer View: Connections -> dspace-svn -> dspace-svn -> Schemas -> public -> Tables will show you a list of the tables that Ant created during install, for example

There are lots of things you can do with the database connection, including issuing queries, so it's worth playing around with.

[edit] So what use is this really?

Well, aside from the obvious benefits of having everything compiled in the background while you are working, and having everything, including database browsing and querying integrated into your development environment, consider the following exercise:

1. Open the file dspace-svn/src/org/dspace/app/webui/servlet/DSpaceServlet.java
2. Scroll down to the method:

private void processRequest(HttpServletRequest request,
           HttpServletResponse response) throws ServletException, IOException

and find the line of code which reads:

 // Are we resuming a previous request that was interrupted for
 // authentication?
 request = Authenticate.getRealRequest(request);

around line 136.

1. Once you have found this line, right click in the margin on the left side of the line numbers, and select "Toggle Breakpoint". A blue circle, with a tick in it, will appear.
2. Go to your web browser, and select any link appart from the home page. For example, browse by title.
3. Did you see what happened? Eclipse should have intervened in your web browsing, offering to open the debug mode for the application. If you agree to the request, you are flipped back into Eclipse in the Debug Perspective. You should find that the file DSpaceServlet is open, and execution of the code has ceased at the line where we set the breakpoint. From this point you can step through the code, line-by-line if you like, and see the state of all the variables and your position in the stack at whatever point you like. Now that's useful!

There are plenty of opportunities for this sort of integration to be useful, and I would encourage people to add their tips and tricks to this page.

[edit] SVN Ignore

The following resources will be needed to be set to SVN Ignore, to ensure that unwanted resources are not committed to the repository:

.cvsignore
.tomcatproject
build/
jsp/local
jsp/WEB-INF/lib
jsp/WEB-INF/web.xml
work
dspace-install

To set these to be ignored, right click on the resource and go: Team -> Add to svn:ignore then select "Resource(s) by name"