Installing the EUL Add-On (v0.2)

The following instructions will guide you through the installation of the various parts of the EUL-DSpace Add-On, depending on which parts you wish to use. The process is relatively simple, although at some points it is necessary to modify DSpace files in order to make the system work.

In order to make a clear distinction between your DSpace install and our Add-On source code, we will use the notation:

[eul] - The directory in which you have the unpacked EUL Add-On code.

[dspace] - Your target DSpace installation to add our code to.

This software has been tested for full compatibility with v1.1.1 of DSpace, and should also work with earlier versions.


1. Compulsory Installation Steps

This section explains how to install the parts of the system that are required before any of the subsequent facilities can be made to work. It does not matter if you are upgrading from v0.1a or installing from scratch for this section.

1.1.
Download and unpack the .tar.gz (available here) to the directory to which we will refer as [eul] from now on.

1.2.
Ensuring that ant is in the environment path, go to the [eul]/java directory and use the following command:

ant -Ddslib=[dspace]/lib

This will produce 1 warning regarding a deprecated method, which you should not worry about.

Next use the command:

ant -Ddslib=[dspace]/lib install

This will create an eul-dspace.jar file in the [dspace]/lib directory.

You now have all the compiled java installed that is required to run any of the following facilities.


2. Supervised WorkSpace

This section explains how to install the supervised workspace (see the Documentation for more information). If you are upgrading from v0.1a you can go directly to section 3.

2.1.
Ensuring that you are logged in as the dspace user, open a console to your dspace database with a command like:

psql dspace


2.2.
Once connected use the following SQL to create the database tables needed for this facility: 

CREATE SEQUENCE eulepersongroup2workspaceitem_seq;

CREATE TABLE EULepersongroup2workspaceitem (
	id integer DEFAULT nextval('EULepersongroup2workspaceitem_seq'),
	eperson_group_id integer,
	workspace_item_id integer,
	CONSTRAINT EULepersongroup2item_pkey PRIMARY KEY (id)
);

CREATE SEQUENCE eulworkspaceitemnotes_seq;

CREATE TABLE eulworkspaceitemnotes (
	note_id integer DEFAULT nextval('eulworkspaceitemnotes_seq'),
	item_id integer,
	note text,
	submitter_id integer,
	date_submitted timestamp without time zone,
	CONSTRAINT eulworkspaceitemnotes_pkey PRIMARY KEY (note_id)
);


2.3.
Disconnect from the database terminal using \q

2.4.
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code: 

<!-- Servlets -->

<servlet>
    <servlet-name>notes</servlet-name>
    <servlet-class>ac.ed.dspace.NotesServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>supervise</servlet-name>
    <servlet-class>ac.ed.dspace.SuperviseServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>view-workspaceitem</servlet-name>
    <servlet-class>ac.ed.dspace.ViewWorkspaceItemServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>notes</servlet-name>
    <url-pattern>/notes</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>supervise</servlet-name>
    <url-pattern>/admin/supervise</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>view-workspaceitem</servlet-name>
    <url-pattern>/view-workspaceitem</url-pattern>
</servlet-mapping>


2.5.
Go into [eul]/jsp/new/workspace/ and copy all the JSPs here into the [dspace]/jsp/ directory. Note that the new files are directory structured in the same way as the corresponding JSPs in DSpace (so you may use a command like: cp -r * [dspace]/jsp). Note also that we do not use the [dspace]/jsp/local directory if possible since there are some bugs in the core code which can cause files here not to be picked up.

2.6.
Go into [eul]/jsp/update/workspace/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (2.5). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** WORKSPACE ***************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP. If additional instructions are required, they will be detailed in the file itself. Note that the updated files are directory structured in the same way as the corresponding JSPs in DSpace. Note also that some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

2.6.
If you are only installing this module go directly to section 5, otherwise go on to section 3.

3. Submission Interfaces

This module supports both the submission interface for a DSpace installation at a SHERPA (http://www.sherpa.ac.uk/) site and also the v1.0 of the submission interface for a UK recommended metadata set for E-theses. There is some pre- requisite installation and then there are 2 options for the install: both submission interfaces, with the option to choose between them based on submission type (3.6) or a single E-theses submission interface (3.5). If you are upgrading from v0.1a you need to follow this section in the same way as if you were installing from scratch.

3.1.
Ensuring that you are logged in as the dspace user, open a console to your dspace database with a command like:

psql dspace


3.2.
Once connected use the following SQL to create the database tables needed for this facility: 

CREATE SEQUENCE eulitem2submitengine_seq;

CREATE TABLE eulitem2submitengine (
	id integer DEFAULT nextval('eulitem2submitengine_seq'),
	item_id integer,
	submit_engine integer,
	CONSTRAINT eulitem2submitengine_pkey PRIMARY KEY (id)
);


3.3.
Disconnect from the database terminal using \q

3.4.
To ensure that both submission interfaces are supported by DSpace go to the Dublin Core Registry page in the admin area of your DSpace site and ensure that you have registered at least the following elements and qualifiers: 

contributor.advisor
contributor.author
contributor.editor
coverage.spatial
date.issued
description.abstract
description.sponsorship
format.extent
format.mimetype
identifier.citation
identifier.govdoc
identifier.isbn
identifier.ismn
identifier.issn
identifier.uri
identifier
language.iso
publisher
relation.ispartof
relation.ispartofseries
relation.requires
subject.ddc
subject.lcc
subject.lcsh
subject.mesh
subject.other
subject.udc
title.alternative
title
type


3.5.
Installing Only the E-theses submission system:-

If you wish only to provide an E-theses submission interface use the following instructions, otherwise move on to section 3.6. It is also recommended that if using the E-theses submission sytem that you install the custom tags in section 4.

3.5.1.
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code (Note that we are updating an already existing servlet 'submit' as well as adding a new one): 

<!-- Servlets -->

<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>ac.ed.dspace.GhostSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>theses-submit</servlet-name>
    <servlet-class>ac.ed.dspace.ThesesSubmitServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>theses-submit</servlet-name>
    <url-pattern>/theses-submit</url-pattern>
</servlet-mapping>

Note: To remove the submission interfaces and return to default simply update the submit servlet record in web.xml with: 


<servlet>
		<servlet-name>submit</servlet-name>
    <servlet-class>org.dspace.app.webui.servlet.SubmitServlet</servlet-class>
</servlet>


3.5.2.
Go into [eul]/jsp/new/submission/ and copy the directory /theses-submit into the [dspace]/jsp/ directory.

3.5.3.
Go into [eul]/jsp/update/submission/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (3.5.2). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** SUBMISSION **************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP. If additional instructions are required, they will be detailed in the file itself. Note that the updated files are directory structured in the same way as the corresponding JSPs in DSpace. Note also that some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

3.5.4.
It is recommended that you install the custom tags in section 4. Otherwise go straight to section 5.
3.6.
Installing both submission systems :-

This section will explain how to install both submission systems and the facility to choose between them depending on submission type.

3.6.1
Go to [dspace]/jsp/WEB-INF/ and open up the file web.xml for editing. Under the relevant sections, enter the following code (Note that we are updating an already existing servlet 'submit' as well as adding a new one): 

<!-- Servlets -->

<servlet>
    <servlet-name>sherpa-submit</servlet-name>
    <servlet-class>ac.ed.dspace.SherpaSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>ac.ed.dspace.SelectSubmitServlet</servlet-class>
</servlet>

<servlet>
    <servlet-name>theses-submit</servlet-name>
    <servlet-class>ac.ed.dspace.ThesesSubmitServlet</servlet-class>
</servlet>


<!-- Servlet Mappings -->

<servlet-mapping>
    <servlet-name>sherpa-submit</servlet-name>
    <url-pattern>/sherpa-submit</url-pattern>
</servlet-mapping>

<servlet-mapping>
    <servlet-name>theses-submit</servlet-name>
    <url-pattern>/theses-submit</url-pattern>
</servlet-mapping>

Note: To remove the submission interfaces and return to default simply update the submit servlet record in web.xml with: 


<servlet>
    <servlet-name>submit</servlet-name>
    <servlet-class>org.dspace.app.webui.servlet.SubmitServlet</servlet-class>
</servlet>


3.6.2.
Go into [eul]/jsp/new/submission/ and copy all the JSPs here into the [dspace]/jsp/ directory. Note that the new files are directory structured in the same way as the corresponding JSPs in DSpace.

3.6.3.
Go into [eul]/jsp/update/submission/. If you still have the default installation of dspace, you may copy the JSPs here into [dspace]/jsp/ as per step (3.6.2). If not, you will need to open the JSPs in this directory and move the code delimited by:

******* Start EUL Code Inclusion ********
*************** SUBMISSION **************

and

******* End EUL Code Inclusion ********

into the corresponding DSpace JSP. If additional instructions are required, they will be detailed in the file itself. Note that the updated files are directory structured in the same way as the corresponding JSPs in DSpace. Note also that some of the files may contain code for other facilities - these code snippents will be treated in exactly the same way when the facility is installed.

3.5.4.
It is recommended that you install the custom tags in section 4. Otherwise go straight to section 5.

4. Installing the Custom Tags

The custom tags imporve the interface slightly for searching and browsing and also allow for the increased quantity of metadata being collected by the module installed in section 3 when viewing the item record. If you have not installed the submission module in section 3 then the custom tags are not so important, although you may still find them useful. If you are upgrading from v0.1a you need to follow this section in the same way as if you were installing from scratch.

4.1.
Go to [dspace]/jsp/WEB-INF/ and open the file dspace-tags.tld for editing. Update the following tags with the new <tagclass> as shown below: 

<tag>
    <name>item</name>
    <tagclass>ac.ed.dspace.ItemTag</tagclass>
    ...
</tag>

<tag>
    <name>itemlist</name>
    <tagclass>ac.ed.dspace.ItemListTag</tagclass>
    ...
</tag>


4.2.
Go to section 5.

5. Finalising the Installation

5.1.
Restart Apache and Tomcat. The installed modules should now work. See the Documentation for more information. It may be necessary to remove Tomcat's cached files, located in work/ in the Tomcat directory, to force the system to refresh.


Creating the JavaDocs

To create the Public API documentation for the EUL code, in the [eul] directory execute the following command:

ant public_api

This will build a directory: [eul]/public-api/ containing the documentation.