Page History

...

The Web UI-related files are located in a variety of directories in the DSpace source tree. Note that as of DSpace version 1.5, the deployment has changed. The build systems has moved to a maven-based system enabling the various projects (JSPUI, XMLUI, etc.) into separate projects. The system still uses the familar 'Ant' to deploy the webapps in later stages.

The Build Process

The DSpace Maven build process constructs a full DSpace installation template directory structure containing a series of web applications. The results are placed in [dspace-source]/dspace/target/dspace-[version]-build.dir/. The process works as follows:

• All the DSpace source code is compiled, and/or automatically downloaded from the Maven Central code/libraries repository.
• A full DSpace "installation template" folder is built in [dspace-source]/dspace/target/dspace-[version]-build.dir/
  • This DSpace "installation template" folder has a structure identical to the Installed Directory Layout

In order to then install & deploy DSpace from this "installation template" folder, you must run the following from [dspace-source]/dspace/

...

This is where you place customized versions of JSPs—see 6. JSPUI Configuration and Customization

...

]]></ac:plain-text-body></ac:structured-macro>

target/dspace-[version]-build.dir/ :

ant -D [dspace]/config/dspace.cfg update

Please see the Installation instructions for more details about the Installation process.

Servlets and JSPs (JSPUI Only)

The JSPUI Web UI is loosely based around the MVC (model, view, controller) model. The content management API corresponds to the model, the Java Servlets are the controllers, and the JSPs are the views. Interactions take the following basic form:

1. An HTTP request is received from a browser
2. The appropriate servlet is invoked, and processes the request by invoking the DSpace business logic layer public API
3. Depending on the outcome of the processing, the servlet invokes the appropriate JSP
4. The JSP is processed and sent to the browser
   The reasons for this approach

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="043edd88-2e5d-4f93-aa3b-b52960651422"><ac:plain-text-body><![CDATA[

...

[dspace-source]/dspace/modules/xmlui/src/main/webapp

...

This is where you place customizations for the Manakin interface—see 7. Manakin [XMLUI] Configuration and Customization

...

]]></ac:plain-text-body></ac:structured-macro>

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b2ab8bba-6f47-4c29-ac21-c310b26c22af"><ac:plain-text-body><![CDATA[

...

[dspace-source/dspace/modules/jspui/src/main/resources

...

This is where you can place you customize version of the Messages.properties file.

...

]]></ac:plain-text-body></ac:structured-macro>

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="26a6992b-3886-4aa8-af12-d9998fad8fd0"><ac:plain-text-body><![CDATA[

...

[dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/WEB-INF/dspace-tags.tld

...

Custom DSpace JSP tag descriptor

...

]]></ac:plain-text-body></ac:structured-macro>

The Build Process

The DSpace Maven build process constructs a full DSpace installation template directory structure containing a series of web applications.  The results  are placed in _\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/_. The process works as follows:

• All the DSpace source code is compiled, and/or automatically downloaded from the Maven Central code/libraries repository.

• Wiki Markup
  A full DSpace "installation template" folder is built in {{\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/}}

  • This DSpace "installation template" folder has a structure identical to the Installed Directory Layout

In order to then install & deploy DSpace from this "installation template" folder, you must run the following from {{\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/}} :

ant -D [dspace]/config/dspace.cfg update

Please see the Installation instructions for more details about the Installation process.

Servlets and JSPs (JSPUI Only)

The JSPUI Web UI is loosely based around the MVC (model, view, controller) model. The content management API corresponds to the model, the Java Servlets are the controllers, and the JSPs are the views. Interactions take the following basic form:

1. An HTTP request is received from a browser
2. The appropriate servlet is invoked, and processes the request by invoking the DSpace business logic layer public API
3. Depending on the outcome of the processing, the servlet invokes the appropriate JSP
4. The JSP is processed and sent to the browser
   The reasons for this approach are:

• All of the processing is done before the JSP is invoked, so any error or problem that occurs does not occur halfway through HTML rendering
• The JSPs contain as little code as possible, so they can be customized without having to delve into Java code too much
  The org.dspace.app.webui.servlet.LoadDSpaceConfig servlet is always loaded first. This is a very simple servlet that checks the dspace-config context parameter from the DSpace deployment descriptor, and uses it to locate dspace.cfg. It also loads up the Log4j configuration. It's important that this servlet is loaded first, since if another servlet is loaded up, it will cause the system to try and load DSpace and Log4j configurations, neither of which would be found.

...

The JSPManager.showJSP method uses the standard Java servlet forwarding mechanism is then used to forward the HTTP request to the JSP. The JSP is processed by Tomcat and the results sent back to the user's browser.unmigrated-wiki-markup

There is an exception to this servlet/JSP style: _index.jsp_, the 'home page', receives the HTTP request directly from Tomcat without a servlet being invoked first. This is because in the servlet 2.3 specification, there is no way to map a servlet to handle only requests made to '_/_'; such a mapping results in every request being directed to that servlet. By default, Tomcat forwards requests to '_/_' to _index.jsp_. To try and make things as clean as possible, _index.jsp_ contains some simple code that would normally go in a servlet, and then forwards to _home.jsp_ using the _JSPManager.showJSP_ method. This means localized versions of the 'home page' can be created by placing a customized _home.jsp_ in _\[dspace-source\]/jsp/local_, in the same manner as other JSPs.

Wiki Markup_\[dspace-source\]/jsp/dspace-admin/index.jsp_, the administration UI index page, is invoked directly by Tomcat and not through a servlet for similar reasons.

At the top of each JSP file, right after the license and copyright header, is documented the appropriate attributes that a servlet must fill out prior to forwarding to that JSP. No validation is performed; if the servlet does not fill out the necessary attributes, it is likely that an internal server error will occur.

...

Introducing number parameters that should be formatted according to the locale used makes no difference in the message key compared to atring string parameters:

jsp.submit.show-uploaded-file.size-in-bytes = {0} bytes

...

HTML documents must be "self-contained", as explained here. Provided that full path information is known by DSpace, any depth or complexity of HTML document can be served subject to those contraintsconstraints. This is usually possible with some kind of batch import. If, however, the document has been uploaded one file at a time using the Web UI, the path information has been stripped. The system can cope with relative links that refer to a deeper path, e.g.

...

since it would just have figure.gif

To prevent "infinite URL spaces" appearing (e.g. if a file foo.html linked to bar/foo.html, which would link to bar/bar/foo.html...) this behavior can be configured by setting the configuration property webui.html.max-depth-guess.For example, if we receive a request for foo/bar/index.html, and we have a bitstream called just index.html, we will serve up that bitstream for the request if webui.html.max-depth-guess is 2 or greater. If webui.html.max-depth-guess is 1 or less, we would not serve that bitstream, as the depth of the file is greater. If prevent "infinite URL spaces" appearing (e.g. if a file foo.html linked to bar/foo.html, which would link to bar/bar/foo.html...) this behavior can be configured by setting the configuration property webui.html.max-depth-guess is zero, the request filename and path must always exactly match the bitstream name. The default value (if that property is not present in dspace.cfg) is 3.

Thesis Blocking

The submission UI has an optional feature that came about as a result of MIT Libraries policy. If the block.theses parameter in dspace.cfg is true, an extra checkbox is included in the first page of the submission UI. This asks the user if the submission is a thesis. If the user checks this box, the submission is halted (deleted) and an error message displayed, explaining that DSpace should not be used to submit theses. This feature can be turned off and on, and the message displayed (/dspace/jsp/submit/no-theses.jsp can be localized as necessary.

OAI-PMH Data Provider

The DSpace platform supports the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) version 2.0 as a data provider. This is accomplished using the OAICat framework from OCLC.

The DSpace build process builds a Web application archive, _\[dspace-source\]/build/oai.war_), in much the same way as the Web UI build process described above. The only differences are that the JSPs are not included, and _\[dspace-source\]/etc/oai-web.xml_ is used as the deployment descriptor. This 'webapp' is deployed to receive and respond to OAI-PMH requests via HTTP. Note that typically it should _not_ be deployed on SSL (_https:_ protocol). In a typical configuration, this is deployed at _oai_, for example:

http://dspace.myu.edu/oai/request?verb=Identify

The 'base URL' of this DSpace deployment would be:

http://dspace.myu.edu/oai/request

It is this URL that should be registered with [www.openarchives.org|http://www.openarchives.org/|www.openarchives.org]. Note that you can easily change the '_request_' portion of the URL by editing _\[dspace-source\]/etc/oai-web.xml_ and rebuilding and deploying _oai.war_.

DSpace provides implementations of the OAICat interfaces AbstractCatalog, RecordFactory and Crosswalk that interface with the DSpace content management API and harvesting API (in the search subsystem).

Only the basic oai_dc unqualified Dublin Core metadata set export is enabled by default; this is particularly easy since all items have qualified Dublin Core metadata. When this metadata is harvested, the qualifiers are simply stripped; for example, description.abstract is exposed as unqualified description. The description.provenance field is hidden, as this contains private information about the submitter and workflow reviewers of the item, including their e-mail addresses. Additionally, to keep in line with OAI community practices, values of contributor.author are exposed as creator values.

Other metadata formats are supported as well, using other Crosswalk implementations; consult the oaicat.properties file described below. To enable a format, simply uncomment the lines beginning with Crosswalks.*. Multiple formats are allowed, and the current list includes, in addition to unqualified DC: MPEG DIDL, METS, MODS. There is also an incomplete, experimental qualified DC.

Note that the current simple DC implementation (org.dspace.app.oai.OAIDCCrosswalk) does not currently strip out any invalid XML characters that may be lying around in the data. If your database contains a DC value with, for example, some ASCII control codes (form feed etc.) this may cause OAI harvesters problems. This should rarely occur, however. XML entities (such as >) are encoded (e.g. to >)

In addition to the implementations of the OAICat interfaces, there are two configuration files relevant to OAI support:

.

For example, if we receive a request for foo/bar/index.html, and we have a bitstream called just index.html, we will serve up that bitstream for the request if webui.html.max-depth-guess is 2 or greater. If webui.html.max-depth-guess is 1 or less, we would not serve that bitstream, as the depth of the file is greater. If webui.html.max-depth-guess is zero, the request filename and path must always exactly match the bitstream name. The default value (if that property is not present in dspace.cfg) is 3.

Thesis Blocking

The submission UI has an optional feature that came about as a result of MIT Libraries policy. If the block.theses parameter in dspace.cfg is true, an extra checkbox is included in the first page of the submission UI. This asks the user if the submission is a thesis. If the user checks this box, the submission is halted (deleted) and an error message displayed, explaining that DSpace should not be used to submit theses. This feature can be turned off and on, and the message displayed (/dspace/jsp/submit/no-theses.jsp can be localized as necessary.

OAI-PMH Data Provider

The DSpace platform supports the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) version 2.0 as a data provider. This is accomplished using the OAICat framework from OCLC.

The DSpace build process builds a Web application archive, [dspace-source]/build/oai.war), in much the same way as the Web UI build process described above. The only differences are that the JSPs are not included, and [dspace-source]/etc/oai-web.xml is used as the deployment descriptor. This 'webapp' is deployed to receive and respond to OAI-PMH requests via HTTP. Note that typically it should not be deployed on SSL (https: protocol). In a typical configuration, this is deployed at oai, for example:

http://dspace.myu.edu/oai/request?verb=Identify

The 'base URL' of this DSpace deployment would be:

http://dspace.myu.edu/oai/request

It is this URL that should be registered with www.openarchives.org. Note that you can easily change the 'request' portion of the URL by editing [dspace-source]/etc/oai-web.xml and rebuilding and deploying oai.war.

DSpace provides implementations of the OAICat interfaces AbstractCatalog, RecordFactory and Crosswalk that interface with the DSpace content management API and harvesting API (in the search subsystem).

Only the basic oai_dc unqualified Dublin Core metadata set export is enabled by default; this is particularly easy since all items have qualified Dublin Core metadata. When this metadata is harvested, the qualifiers are simply stripped; for example, description.abstract is exposed as unqualified description. The description.provenance field is hidden, as this contains private information about the submitter and workflow reviewers of the item, including their e-mail addresses. Additionally, to keep in line with OAI community practices, values of contributor.author are exposed as creator values.

Other metadata formats are supported as well, using other Crosswalk implementations; consult the oaicat.properties file described below. To enable a format, simply uncomment the lines beginning with Crosswalks.*. Multiple formats are allowed, and the current list includes, in addition to unqualified DC: MPEG DIDL, METS, MODS. There is also an incomplete, experimental qualified DC.

Note that the current simple DC implementation (org.dspace.app.oai.OAIDCCrosswalk) does not currently strip out any invalid XML characters that may be lying around in the data. If your database contains a DC value with, for example, some ASCII control codes (form feed etc.) this may cause OAI harvesters problems. This should rarely occur, however. XML entities (such as >) are encoded (e.g. to >)

In addition to the implementations of the OAICat interfaces, there is one main configuration file relevant to OAI-PMH support:

• oaicat.properties: This file resides in [dspace]/config. You probably won't need to edit this, as it is pre-configured to meet most needs. You might want to change the Identify.earliestDatestamp field to more accurately reflect the oldest datestamp in your local DSpace system. (Note that this is the value of the last_modified column in the Item database table.)

• Wiki Markup

  *{_}oaicat.properties{_}*: This resides as a template in _\[dspace\]/config/templates_, and the live version is written to _\[dspace\]/config_. You probably won't need to edit this; the _install-configs_ script fills out the relevant deployment-specific parameters. You might want to change the _earliestDatestamp_ field to accurately reflect the oldest datestamp in the system. (Note that this is the value of the _last_modified_ column in the _Item_ database table.)

• Wiki Markup*{_}oai-web.xml{_}*: This standard Java Servlet 'deployment descriptor' is stored in the source as _\[dspace-source\]/etc/oai-web.xml_, and is written to _/dspace/oai/WEB-INF/web.xml_.

Sets

OAI-PMH allows repositories to expose an hierarchy of sets in which records may be placed. A record can be in zero or more sets.

...

The OAI identifiers that DSpace uses are of the form:

oai:host name:handle

For example:

oai:dspace.myu.edu:123456789/345

If you wish to use a different scheme, this can easily be changed by editing the value of OAI_ID_PREFIX at the top of the org.dspace.app.oai.DSpaceOAICatalog class. (You do not need to change the code if the above scheme works for you; the code picks up the host name and Handles automatically from the DSpace configuration.)

...

Introduced in Release 1.6, the DSpace Command Launcher brings together the various command and scripts into a standard-practice for running CLI runtime programs.

Older Versions

Wiki MarkupPrior to Release 1.6, there were various scripts written that masked a more manual approach to running CLI programs. The user had to issue _\[dspace\]/bin/dsrun_ and then java class that ran that program. With release 1.5, scripts were written to mask the _\[dspace\]/bin/dsrun_ command. We have left the java class in the System Administration section since it does have value for debugging purposes and for those who wish to learn about DSpace
programming or wish to customize the code at any time.

Command Launcher Structure

...

Launcher Structure

There are two components to the command launcher: the dspace script and the launcher.xml. The DSpace command calls a java class which in turn refers to _launcher.xml_ that is stored in the _\[dspace\]/config_ directory

launcher.xml is made of several components:

• <command> begins the stanza for a comandcommand
• <name>_name of command_</name> the name of the command that you would use.
• <description>_the description of the command_</description>
• <step> </step> User arguments are parsed and tested.
• <class>_<the java class that is being used to run the CLI program>_</class>
  Prior to release 1.5 if one wanted to regenerate the browse index, one would have to issue the following commands manually: unmigrated-wiki-markup

  Code Block
  [dspace]/bin/dsrun org.dspace.browse.IndexBrowse -f -r [dspace]/bin/dsrun org.dspace.browse.ItemCounter [dspace]/bin/dsrun org.dspace.search.DSIndexer

  In release 1.5 a script was written and in release 1.6 the command _\[dspace\]/bin/dspace index-init_ replaces the script. The stanza from _launcher.xml_ show us how one can build more commands if needed:

  Code Block
  <command> <name>index-update</name> <description>Update the search and browse indexes</description> <step passuserargs="false"> <class>org.dspace.browse.IndexBrowse</class> <argument>-i</argument> </step> <step passuserargs="false"> <class>org.dspace.browse.ItemCounter</class> </step> <step passuserargs="false"> <class>org.dspace.search.DSIndexer</class> </step> </command>

  .