...

You must be familiar with installing and configuring DSpace 1.5. It may help to review Building DSpace From Source.

...

The trick is to manage dependencies correctly. Your local project will depend explicitly on the

...

dspace-api

...

project so it can import DSpace API interfaces and classes. Thus, the

...

dspace-api

...

project cannot depend on it. You have to add a dependency on your local project to every POM that generates an executable build product (i.e. the webapps, and the command-line apps). Those projects also depend on

...

dspace-api

...

so the API classes will be available.

...

Here is a live example of how the DSpace 1.5.2 POMs were modified to add a local package named *

...

dash-api

...

*. This project contains several plugin implementations, and it has its own dependencies on some other projects which support that code. All of the classes in

...

dash-api

...

are in packages under the

...

edu.harvard...

...

hierarchy, so they do not conflict with DSpace.

...

Add the following sections to the POM of the

...

dspace

...

project. This ensures the code gets built, and that it will be available to DSpace command-line utilities.

...

The excellent presentation
Customizing DSpace 1.5 with Basic Overlays
from Open Repositories O8, by
Tim Donohue and
Graham Triggs shows how to manage your local UI customizations and keep your added code well-segregated from the DSpace codebase so upgrades are simplified.
It also provides an overview of the build process and how maven
overlays work.

Recipe 3: (Deprecated) Old Quick-and-Dirty Method of Adding Plugins

...

With the overlay mechanism,
it is easy to add a Crosswalk
or PackagerPlugins plugin to one of the webapps. This technique
does not let you add code to the libraries accessed by the
command-line utilities, such as dspace/bin/packager (more
about that later).

The following notes assume a binary installation of DSpace 1.5.0,
under the directories: *

• [source] is the "source" directory where builds are done.

...

• [dspace] is the target runtime directory, e.g. /dspace

Procedure to Add a Plugin

...

Add the necessary Java source files to the overlay directory for each
module that you want to have access to the plugin. This is
[source]/dspace/modules/{MODULE}/src/main/java
for additional Java sources.

...

For this example, I'll show an ingestion/dissemination crosswalk Plugin, and a
package ingester Plugin that are both implemented in the following class
files:

  edu/mit/libraries/facade/PIMConstants.java

  edu/mit/libraries/facade/PIMCrosswalk.java

  edu/mit/libraries/facade/PIMMETSIngester.java

For the example, assume these files reside under a development
directory, {development}.
To add these classes to the LNI module, we install the sources under
[source]/dspace/modules/lni/src/main/java with the following
commands:

 mkdir -p [source]/dspace/modules/lni/src/main/java/edu/mit/libraries/facade

 cp {development}/edu/mit/libraries/facade/*.java [source]/dspace/modules/lni/src/main/java/edu/mit/libraries/facade

Step 2: Update DSpace Configuration

If you maintain the DSpace configuration file in your source directory
and use the build tools to copy it into the runtime hierarchy, then
update the source copy of dspace.cfg now. (In my development
environment, I just edit the runtime copy in
[dspace]/config/dspace.cfg.)

Add entries for the crosswalks, e.g. like the bold line here
(other entries elided for clarity):

 # Crosswalk Plugins:

 plugin.named.org.dspace.content.crosswalk.IngestionCrosswalk =

 \
   edu.mit.libraries.facade.PIMCrosswalk =

 PIM \
   org.dspace.content.crosswalk.PREMISCrosswalk = PREMIS \

 ...

Step 3: Modify the POM to Add Dependencies

If your code has any new external dependencies (i.e. it needs modules
not already required by DSpace) then you need to add those to the
POM for the overlay module. In this example, we add the bold dependency lines to the
LNI module's POM at [source]/dspace/modules/lni/pom.xml

  
 <project>
   

...

   <dependencies>
     ...
     <dependency>
       <groupId>org.openrdf</groupId>
       <artifactId>sesame</artifactId>
       <version>2.1</version>
     </dependency>
   </dependencies>
 </project>

NOTE: Of course, this requires that all the libraries your code depends on
are available to Maven. If not, you'll have to add them to the local
Maven repository or convince someone to put them into a networked maven
repository. This example creates an entry in the local repository:

 mvn install:install-file

  \
   -Dfile=/opt/sesame/lib/openrdf-sesame-2.1-onejar.jar \

   -DgroupId=org.openrdf

                                \
   -DartifactId=sesame

                                  \
   -Dversion=2.1

                                        \
   -Dpackaging=jar                                      \
   -DgeneratePom=true

Step 4: Build with Maven and Deploy

First, build the sources:

  cd [source]/dspace

  mvn package

Assuming that succeeds, run Ant to install the build products.
NOTE: This does NOT install the configuration files, because I don't work that way; perhaps someone who does could add an alternate command here?

  { shut down servlet container such as Tomcat }

  cd [source]/dspace/target/dspace-1.5.0-build.dir

  ant update

  { start up servlet container such as Tomcat }

Your DSpace instance should now be running with the new plugins in the
LNI application.

Adding The Same Plugins to Other Applications

The procedure to add these same plugins to another DSpace application,
for example the OAI-PMH server ("oai"), is identical.

If you are adding
the plugins to both lni and oai, you may
wish to symbolically link the Java sources to one master copy someplace
else, so that any changes will take effect in both applications.

In the case of OAI-PMH, you'll also need to modify the
oaicat.properties configuration file to add the appropriate
plugins to OAICAT.

Recipe 4: (Deprecated) Use Overlays to Segregate Local Modifications

You can also use the overlay mechanism to implement a local change or bug-fix
to the DSpace codebase. The process is exactly the same as for
adding plugin implementations, only you add the appropriate DSpace
class files to the source directory instead. These will take precedence
over the distributed code in the classloader.

Again, add the sources under
[source]/dspace/modules/{MODULE}/src/main/java ,
only under the org/dspace/... hierarchy.

For example, to fix a bug in the org.dspace.app.oai.DSpaceOAICatalog
class, you add that file in Step 1 instead of your own source:

 mkdir -p [source]/dspace/modules/oai/src/main/java/org/dspace/app/oai

 cp {development}/org/dspace/app/oai/DSpaceOAICatalog.java [source]/dspace/modules/oai/src/main/java/org/dspace/app/oai

The procedure thereafter is exactly the same as the last recipe (deprecated) for adding plugin
implementations.

Recipe 5: (Deprecated) Old, Poor way of Adding Plugins to Command-Line Applications

The build system does not appear to have any way to accomplish this
with a binary DSpace installation.
(Please correct this if I'm wrong.)

As a kludgy workaround, I've simply added a JAR file manually to the
"lib" directory used by all command-line apps.

Using my crosswalk and packager example above, the command to add my
code to the runtime directory is:

 cd [source]/dspace

 jar cvf [dspace]/lib/pim.jar \

    -C target/dspace-1.5.0-build.dir/webapps/oai/WEB-INF/classes/ edu

Note that the JAR output file pim.jar
is simply what I chose to call it, use any unique name.
The classes are all in packages under edu.mit so the
jar command picks up everything under edu in the overlay module's
class directory.

Of course you also have to manually copy in whatever other
libraries your code depends on, e.g.

  cp /opt/sesame/lib/*.jar [dspace]/lib

Note that the build installation ("ant update") process wipes the
runtime "lib" directory clean each time, so you'll have to
repeat these commands after every new update.