Table of Contents:

Instruction Video for Version v13 on MacOS

Installing IDEA

This guide covers version 11.1 of IDEA, which you can get from here: http://www.jetbrains.com/idea/. Instructions for installing & running can be found on the website and in the readme file included with the download.

Creating a DSpace project from a GitHub clone

Once the source has been cloned, you will be asked whether you want to create a project (click "Yes").

Note: If you haven't already defined a JDK, you may not be able to do so at this point, despite being given the option. Instead, create the project without a JDK, then later open the Settings dialog, then go Project Settings -> JDKs and add your JDK here

Git/GitHub Hints & Tips

The following are a few hints/tips which you may want to utilize to ease your development processes with IDEA and GitHub:

  1. Fork your own Repo to store your local changes: As recommended above, you really should think about forking your own copy of the DSpace GitHub repository. As GitHub describes in their "Fork a Repo" guide, forking lets you create your own personal copy of the codebase. It not only provides you a place to put your local customizations. It also provides an easier way to contribute your work back to the DSpace community (via a GitHub Pull Request).
  2. For easier Fetch/Merge, setup an "upstream" repository location: This is only really relevant if you have your own personal "fork" (see #1). If you have forked the DSpace GitHub repository, then you may want to setup an "upstream" remote that points at the central DSpace GitHub repository. This is described in more detail in the GitHub "Fork a Repo" guide. Perform the following:

Fetch & Merge Example via IDEA

 

This assumes you've followed the #Git/GitHub Hints & Tips listed above, and have forked your own personal copy of DSpace's GitHub as well as setup an "upstream" remote link. This is just one example of how you can perform these tasks.

 

  1. Fetch changes from DSpace Main GitHub: You fetch (and later merge) changes that have occurred in the central DSpace GitHub Repository:
  2. Merge changes into your Local Git Repo: Remember, "fetching" changes just brings them into your local-machine's copy of the Git repository. You'll then need to merge those changes with yours and push the changes back to your personal public GitHub repository.
  3. Quick Status of Local Git Repo: If you want to see what happened, you can look at the "Status" information:
  4. Push Merged Code up to your Personal GitHub Repo: Finally, assuming all went well, you can push your changes back up to GitHub into your public personal repository:

Building and installing DSpace for the first time

Go to the command line, and go to the root of your new project. Run:

mvn package

These steps might take a while to download all the dependencies, but that should only happen once.

Note: you may notice, if you look in IDEA, that at this stage it will detect a number of web facets. Ignore this for the time being, we will come back to it. They will be available under the flashing cog on the bottom right of the screen for future reference.

After this completes:

One-click maven builds

Name

Parameters Tab

General Tab

Runner Tab

Once you have this configured, click "Apply" at the bottom and then click "OK".

You should also run it immediately, because the previous build will have the incorrect dspace.cfg built into it. You can do this using the quick launch from the IDEA tool bar: in the center of the toolbar at the top is a pull-down menu which contains all your pre-configured run tasks. Select the one you have named "mvn clean package", and hit the green arrow to the right of it. You should see maven building your project in a window at the bottom of IDEA, and the content will be similar to when you ran it from the command line earlier.

Web Facets

At some point during the above installation process, IDEA may notify you of new web facets detected. These correspond to the individual WAR files and thus web applications which we are working on. If you do not confirm the detection of these facets straight away, they will be available on the bottom left of the screen by clicking on the flashing gear/cog.

Each of these web facets represents a web application provided by DSpace. This will include, for example, the LNI, the JSP-UI, the XML-UI and the OAI interface.

In the dialog, select "Accept". If you ignored the dialog, they should be available under the flashing 'cog' icon at the bottom of your IDEA window.

Deploying DSpace

The next step in getting fully integrated with this IDE is to set it up with ant and tomcat.

Ant Integration

Tomcat Integration

Tomcat integration is only possible if you have IDEA Ultimate edition. The free community version does not offer this feature. If you are an official DSpace developer, you can contact one of the other Committer's to learn about how you can get ultimate edition.

For Tomcat integration, I chose to download and install tomcat 6 in /opt to keep it separate from the 5.5 release that I had previously installed with my package manager. There are a few reasons for this, but mostly it's because we need to assign pretty weak privileges to the tomcat directory because we will be deploying the webapp as a normal user (run something along the lines of chmod -R jim:tomcat /opt/apache-tomcat-6.0.14 ; chmod -R g+rwx /opt/apache-tomcat-6.0.14 as root).

Once you have ant and tomcat ready, you can create a new build configuration for these two.

Name

Server Tab

Deployment Tab

Once you have this set up, you can deploy DSpace, by selecting the tomcat deployment from the menu bar, and hitting the green play button next to it. Hit the play button on the opened dialog, and IDEA will deploy the applications at the context paths specified in this section.

DSpace 6 (Services) and debugging command line

Because I wanted to debug command-line main

Remove: <scope>provided</scope> from servlet-api in many pom.xml files.

<dependency>
   <groupId>javax.servlet</groupId>
   <artifactId>servlet-api</artifactId>
</dependency>

 

Add some dependencies to:

dspace-services/src/main/java/org/dspace/services/caching/CachingServiceImpl.java

import javax.servlet.ServletRequest;
import javax.servlet.http.HttpSession;

 

Navigate to dspace-api/src/main/java/org/dspace/app/launcher/ScriptLauncher.java, and click Run --> Edit Configurations...

 

And fill in the Configuration of:

Main class: org.dspace.app.launcher.ScriptLauncher

VM options: -Ddspace.dir=/dspace -Ddspace.configuration=/dspace/config/dspace.cfg -Dservice.manager.spring.configs=/dspace/config/spring/api/*.xml

(I was debugging the checksum checker, so I passed the args that would go to /dspace/bin/dspace )

Program arugments: checker

Working directory: /dpsace/config

Environment variables: dspace.dir=/dspace/

From then, you can click Run -> Debug "ScriptLauncher", or click the green bug button, and the debugger should start up.

 

Tips

If you leave the "run" dialog boxes open at the bottom, you have a quick way to re-run the build and deployment tasks. The maven build can be re-run by clicking the green icon that looks like ">>", and likewise for the ant + tomcat deployment, except you'll have to click "stop" first, and wait for tomcat to shut down.

If you see an error that indicates that the dspace.dir folder cannot be found in your Tomcat/bin folder, (such as java.io.FileNotFoundException: /opt/local/share/java/tomcat6/bin/dspace.dir/config/dspace.cfg (No such file or directory)) when you attempt to call the Tomcat runconfig, you can try adding a symlink in your Tomcat/bin folder, like so:

cd /opt/local/share/java/tomcat6/bin/
sudo ln -s /dspace/ '${dspace.dir}'

It's not pretty, but it'll get the job done.

Useful plugins

IDEA has loads of plugins available to install. A couple that may be useful are: