Eclipse Tools: Prerequisite Installation

...

Obviously, to do this you will need to have Eclipse Installed: http://www.eclipse.org/^{Image Removed}

This HOW-TO has been written using Eclipse 3.4 (Ganymede), but it is also known to work in Eclipse 3.3 as well. The information here probably works with other versions of Eclipse, but no guarantees are made.

...

After you have installed all of these plugins, or in-between each one, you will need to restart the Eclipse workspace

SVN Plugins (required)

to restart the Eclipse workspace

Install the SVN Plugin

Subversion (SVN) enables you to checkout the DSpace source code and keep up-to-date with the latest changes to the platform from DSpace Repository.

Eclipse >= 3.5:

In Eclipse select "Help --> Install New Software...". 
Image Added
In the drop down list select "Helios - http://download.eclipse.org/release/helios."
Image Added
From the list select "Collaboration --> Subversive SVN Team Provider"
Image Added
Click the "Next >" button and follow the dialogs to install the plugins.

Restart Eclipse.

Eclipse ask you which Subversive Connector you want to use. Choose SVN Kit or JavaHL.

Eclipse < 3.5:

There are 2 popular SVN plugins for Eclipse. You only need to install one of them:

• SubVersive Install Instructions: http://www.eclipse.org/subversive/downloads.php^{Image Removed}

• SubClipse Install Instructions: http://subclipse.tigris.org/install.html^{Image Removed}

You should install the most recent version of your preferred client. The recommendation is SubVersive (as it is an Eclipse Incubation project), and the remainder of this tutorial assumes that this is the one you are using.

...

Install the most recent version of the plugin, which is available for download from:

http://www.eclipsetotale.com/tomcatPlugin.html^{Image Removed}

Unfortunately, there is no remote URL location for the sysdeo plugin. You will have to manually download the plugin and unzip it into the [eclipse]/plugins directory. Also, you will need to have Tomcat installed locally. Obtain the latest version of Tomcat from: http://jakarta.apache.org/tomcat^{Image Removed}

Maven 2 Plugin (required for DSpace 1.5)

...

Prerequisite: Before installing the Maven 2 Plugin for Eclipse, you must install Apache Maven from http://maven.apache.org/^{Image Removed}

Install the most recent version of the plugin using the below remote URL.

Remote URL: http://m2eclipse.sonatype.org/update/^{Image Removed}/

The remote URL for the m2eclipse project has moved to: http://m2eclipse.sonatype.org/sites/m2e

Web Standard Tools (optional)

...

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.

Code Formatting

Java Perspective.

Code Formatting

1. Download the DSpace's Coding Conventions config file: dspace-eclipse-format.xml|IDE Integration - DSpace, Eclipse and Tomcat^dspace-eclipse-format.xml|||^Dspace-eclipse-format.xml|^DspaceDownload the DSpace's Coding Conventions config file: dspace-eclipse-format.xml|\Install either as workspace default or for your individual DSpace project(s).
2. #* (Workspace Default) Select Window -> Preferences in Eclipse. Go to the Java -> Code Style -> Formatter. Click the "Import..." button and select the file.
   • (Individual Project) Right click on the DSpace project, select Properties. Go to the Java -> Code Style -> Formatter. Click the "Import..." button and select the file.

...

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 Note: If you are using Mac OS X, the tools.jar library does not exist on the platform. Instead using classes.jar found at: /System/Library/Frameworks/JavaVM.framework/Versions/${JAVA_VERSION}/Classes/classes.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)

...

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: https://dspace.svn.sourceforge.net/svnroot/dspace^{Image Removed}

"Access restriction: The type DataSource is not accessible due to restriction on required library <jre_path>/lib/rt.jar"

...

(If you are working with DSpace 1.5 see the Working with DSpace 1.5 section after this)

Wiki Markup_NEEDS UPDATING -- – Not sure this actually works! \ [15 Apr 2008\]_

Checking out DSpace as a Tomcat Project

...

The installation path you give should be:

  dspace.dir = <workspace>/dspace/working-copy

where <workspace> is the absolute path to your Eclipse workspace, and "working-copy" is the name of the directory into which we will install the DSpace application. Other configuration that you should ensure are set correctly are as follows (assuming installation on the local machine):

  # DSpace base URL.  Include port number etc., but NOT trailing slash
  dspace.url = http://localhost:8080/dspace-svn

  # DSpace host name - should match base URL.  Do not include port number
  dspace.hostname = localhost

  # Name of the site
  dspace.name = DSpace 1.4.x in Eclipse

...

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
working-copy

...

You should now find the DSpace deployed; try the following URL to see if it is working correctly:

http://localhost:8080/dspace-svn^{Image Removed}

Note that due to the limitations of the 1.4.x source structure, it is only possible to view one web application at a time from the same project when deployed within Eclipse. To work on the web interface and the OAI interface simultaneously you must use DSpace 1.5 and follow the instructions below. Otherwise, it is possible to modify this HOW-TO so that the OAI interface is deployed in Tomcat rather than the usual web interface.

...

• dspace - The root module, which builds all of DSpace and holds the DSpace configurations
• dspace-api - The DSpace API module, which contains all the primary business logic (Java code)
• dspace-jspui - The JSP-based User Interface for DSpace
• dspace-xmlui - The XML-based User Interface for DSpace (also known as Manakin)
  • dspace-xmlui-api - The primary API for the XML-UI for DSpace (including all Aspect Java code)
  • dspace-xmlui-wing - The Digital Repository Interface (DRI) API for XML-UI
  • dspace-xmlui-webapp - The XML-UI web application configurations (including all Aspect & Theme definitions)
• dspace-oai - The OAI-PMH interface for DSpace
• dspace-lni - The Lightweight Network Interface (LNI) for DSpace
  • dspace-lni-core - The primary API for LNI
  • dspace-lni-client - The client API for LNI (along with a simple sample client)
  • dspace-lni-webapp - The LNI web application configurations
• dspace-sword - The SWORD [interface for DSpace
  • dspace-sword-api - The SWORD API
  • dspace-sword-webapp - The SWORD web application
• language-packs - The Internalization (I18N) language packs for DSpace (Currently JSP-UI only - the I18N for Manakin is in the dspace-xmlui-webapp module)
• pom.xml - The Maven module, which contains the primary Maven configurations to build DSpace

...

The One-Big-Project Approach

This is the simplest approach and therefore is highly recommended for any new/novice developers. This approach allows you to checkout DSpace 1.5 as a single Eclipse Project. However, it only allows you to define a single user interface to debug tools using the Eclipse Tomcat plugin.

1. Select File -> New... -> Project in Eclipse
2. Select SVN -> Projects from SVN and click "Next"
3. Select to "Use an existing repository" and choose the DSpace SourceForge repository (https://dspace.svn.sourceforge.net/svnroot/dspace^{Image Removed})
4. Select the version of DSpace you want to checkout, likely either under "tags" (e.g. tags -> dspace-1_5) or "branches" (e.g. branches -> dspace-1_5_x). Click "Next"
5. Choose "Check Out as Project with the name specified". Give it a name (e.g. dspace-1_5_x), and click "Finish". Eclipse will then checkout the DSpace 1.5 source code from SVN.
6. Return to the "Java Perspective" in Eclipse ("Window -> Open Perspective -> Java"). You should see your newly created project in the Package Explorer.
7. Right-Click on your project and select "Maven -> Enable Dependency Management". Eclipse will now read the Maven pom.xml configuration file and auto-configure your project as a "Java Project"!
8. Right-Click again, and select "Maven -> Enable Nested Modules". This tells Maven Eclipse plugin that your project contains several nested sub-modules within it.
9. Right-Click one last time, and select "Maven -> Update Source Folders" ("Maven -> Download Sources" for Eclipse 3.2.0). Eclipse will now automatically locate all the DSpace Java source code, as well as all the 3rd party JAR dependencies.

...

1. First, we will checkout DSpace 1.5 from SVN. You must perform the checkout into a location that is not under your Eclipse workspace folder. Therefore, if you perform an SVN checkout using Eclipse, you must move that folder to another location before you can proceed.
   • (e.g.) svn co https://dspace.svn.sourceforge.net/svnroot/dspace/branches/dspace-1_5_xImage Removed dspace-1_5_x-src
   • NOTE: Make sure that you checkout DSpace 1.5 to a "stable" location (i.e. not to a temporary directory like /tmp). During the next step (when you will import the DSpace modules into Eclipse), Eclipse will not copy the code into your Eclipse workspace. Rather, it will just reference the location where you have checked out DSpace 1.5 via SVN...so, this location will (in a sense) become your DSpace 1.5 "workspace".
   • ADDITIONAL NOTE: This requirement to checkout DSpace 1.5 to a folder not in your Eclipse workspace unfortunately seems to be a limitation of the m2eclipse Maven plugin for Eclipse. If you attempt to re-import Maven projects which already exist in your Eclipse workspace, you will end up with a bunch of empty project folders.
2. Next, we will point Eclipse at the location where you checked out DSpace 1.5 to, and tell Eclipse to import it as a series of Maven Projects
   • Select File -> Import in Eclipse
   • Select General -> Maven Projects as the type of source. Click "Next".
   • Browse to the location where you just checked out DSpace 1.5
   • Eclipse will automatically parse out all the various Maven projects which are located there (based on the location of the Maven pom.xml file in each DSpace module). It will display a list of all DSpace modules & sub-modules, and allow you to check which ones you wish to import. If you don't want to import all the modules at this time, you can always go back and repeat this same process to checkout additional modules.
   • It is*highly recommended to always select the top-level pom.xml, since this is the module which builds DSpace.
   • It is also*recommended to uncheck any sub-modules of dspace-xmlui or dspace-lni (e.g. dspace-xmlui-api is a submodule of dspace-xmlui). This will decrease the number of separate DSpace projects in your Eclipse workspace.
     • You may choose to uncheck any DSpace modules you are not planning on working with. For example, if you don't want to work with the DSpace LNI, then uncheck all of its modules (dspace-lni, dspace-lni-core, dspace-lni-client, dspace-lni-webapp). As mentioned, you can always repeat this process to import the DSpace LNI code if you need to, afterall.
   • After you have selected the DSpace modules you wish to work with, click "Next". Eclipse will now create the number of DSpace projects you selected, and auto-identify those projects which contain Java code as Java Projects. It will also locate all the 3rd party JAR dependencies for each project and add them automatically to your project's classpath.
3. You should now have separate Eclipse projects for your various DSpace modules. Important: You'll notice that Eclipse did not move this code into your normal Eclipse workspace. Rather, Eclipse is just referencing those folders whereever you originally checked them out via SVN.

...

If you are looking at the Console view in Eclipse, you will know the build has been successful when you see it terminate with a message similar to the following:

[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL org.dspace:dspace:pom:1.5-SNAPSHOT (  task-segment: [package] )
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 32 second
[INFO] Finished at: Tue Nov 27 14:17:56 CST 2007
[INFO] Memory 8M/63M
[INFO] ----------------------------------------------------------------------------

...

The installation path you give should be:

  dspace.dir = <dspace>

where <dspace> is the absolute path of the folder where you want DSpace to be installed. Other configuration that you should ensure are set correctly are as follows (assuming installation on the local machine):

  # DSpace base URL.  Include port number etc., but NOT trailing slash
  dspace.url = http://localhost:8080/dspace-jspui

  # DSpace host name - should match base URL.  Do not include port number
  dspace.hostname = localhost

  # Name of the site
  dspace.name = DSpace 1.5

...

Go back into each of the Maven build tasks you defined in the Defining Maven Tasks in Eclipse section above, and add the following parameter:

   dspace.config = <dspace>/config/dspace.cfg

...

You should now find the web interface deployed; try one of the following URLs to see if they are working:

http://localhost:8080/dspace-jspui^{Image Removed} (JSP-UI)

http://localhost:8080/dspace-oai/request?verb=Identify^{Image Removed} (OAI-PMH)

http://localhost:8080/dspace-xmlui^{Image Removed} (XML-UI)

Viewing the Database in Eclipse

...

• Open the file dspace-svn/src/org/dspace/app/webui/servlet/DSpaceServlet.java
• 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);

...

• Open the file <workspace>/dspace-api/src/main/java/org/dspace/browse/Browse.java
• Scroll down to the method:

public static BrowseInfo getItemsByTitle(BrowseScope scope)
            throws SQLException
{
        scope.setBrowseType(ITEMS_BY_TITLE_BROWSE);
        scope.setAscending(true);
        scope.setSortByTitle(null);

        return doBrowse(scope);
}

...