The following explains how the application layer is built and used.

Web User Interface

The DSpace Web UI is the largest and most-used component in the application layer. Built on Java Servlet and JavaServer Page technology, it allows end-users to access DSpace over the Web via their Web browsers. As of Dspace 1.3.2 the UI meets both XHTML 1.0 standards and Web Accessibility Initiative (WAI) level-2 standard.

It also features an administration section, consisting of pages intended for use by central administrators. Presently, this part of the Web UI is not particularly sophisticated; users of the administration section need to know what they are doing! Selected parts of this may also be used by collection administrators.

Web UI Files

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.

Location

Description

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/webui

Web UI source files

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/filters

Servlet Filters (Servlet 2.3 spec)

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/jsptag

Custom JSP tag class files

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/servlet

Servlets for main Web UI (controllers)

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/servlet/admin

Servlets that comprise the administration part of the Web UI

[dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/webui/util/

Miscellaneous classes used by the servlets and filters

[dspace-source]/dspace-jspui

The JSP files

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

This is where you place customized versions of JSPs‚ see JSPUI Configuration and Customization

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

This is where you place customizations for the Manakin interface‚ see XMLUI Configuration and Customization

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

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

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

Custom DSpace JSP tag descriptor

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-installer/. The process works as follows:

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

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

Please see the Installing DSpace 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 DSpace servlets are subclasses of the DSpaceServlet class. The DSpaceServlet class handles some basic operations such as creating a DSpace Context object (opening a database connection etc.), authentication and error handling. Instead of overriding the doGet and doPost methods as one normally would for a servlet, DSpace servlets implement doDSGet or doDSPost which have an extra context parameter, and allow the servlet to throw various exceptions that can be handled in a standard way.

The DSpace servlet processes the contents of the HTTP request. This might involve retrieving the results of a search with a query term, accessing the current user's eperson record, or updating a submission in progress. According to the results of this processing, the servlet must decide which JSP should be displayed. The servlet then fills out the appropriate attributes in the HttpRequest object that represents the HTTP request being processed. This is done by invoking the setAttribute method of the javax.servlet.http.HttpServletRequest object that is passed into the servlet from Tomcat. The servlet then forwards control of the request to the appropriate JSP using the JSPManager.showJSP method.

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.

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.

[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.

Many JSPs containing forms will include hidden parameters that tell the servlets which form has been filled out. The submission UI servlet (SubmissionController is a prime example of a servlet that deals with the input from many different JSPs. The step and page hidden parameters (written out by the SubmissionController.getSubmissionParameters() method) are used to inform the servlet which page of which step has just been filled out (i.e. which page of the submission the user has just completed).

Below is a detailed, scary diagram depicting the flow of control during the whole process of processing and responding to an HTTP request. More information about the authentication mechanism is mostly described in the configuration section.

Flow of Control During HTTP Request Processing

Custom JSP Tags (JSPUI Only)

The DSpace JSPs all use some custom tags defined in /dspace/jsp/WEB-INF/dspace-tags.tld, and the corresponding Java classes reside in org.dspace.app.webui.jsptag. The tags are listed below. The dspace-tags.tld file contains detailed comments about how to use the tags, so that information is not repeated here.

Internationalization (JSPUI Only)

For information about XMLUI Internationalization please see: XMLUI Multilingual Support.

The Java Standard Tag Library v1.0 is used to specify messages in the JSPs like this:

OLD:

<H1>Search Results</H1>

NEW:

<H1><fmt:message key="jsp.search.results.title"/></H1>

This message can now be changed using the config/language-packs/Messages.properties file. (This must be done at build-time: Messages.properties is placed in the dspace.war Web application file.)

jsp.search.results.title = Search Results

Phrases may have parameters to be passed in, to make the job of translating easier, reduce the number of 'keys' and to allow translators to make the translated text flow more appropriately for the target language.

OLD:

<P>Results <%= r.getFirst() %> to <%= r.getLast() %> of <%=r.getTotal() %></P>

NEW:

<fmt:message key="jsp.search.results.text">
  <fmt:param><%= r.getFirst() %></fmt:param>
  <fmt:param><%= r.getLast() %></fmt:param>
  <fmt:param><%= r.getTotal() %></fmt:param>
</fmt:message>

(Note: JSTL 1.0 does not seem to allow JSP <%= %> expressions to be passed in as values of attribute in <fmt:param value=""/>)

The above would appear in the Messages_xx.properties file as:

jsp.search.results.text = Results {0}-{1} of {2} 

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

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

In the JSP using this key can be used in the way belov:

<fmt:message key="jsp.submit.show-uploaded-file.size-in-bytes">
  <fmt:param><fmt:formatNumber><%= bitstream.getSize()%></fmt:formatNumber></fmt:param>
</fmt:message>

(Note: JSTL offers a way to include numbers in the message keys as jsp.foo.key = {0,number} bytes. Setting the parameter as <fmt:param value="${variable}" /> workes when variable is a single variable name and doesn't work when trying to use a method's return value instead: bitstream.getSize(). Passing the number as string (or using the <%= %> expression) also does not work.)

Multiple Messages.properties can be created for different languages. See ResourceBundle.getBundle. e.g. you can add German and Canadian French translations:

Messages_de.properties
Messages_fr_CA.properties

The end user's browser settings determine which language is used. The English language file Messages.properties (or the default server locale) will be used as a default if there's no language bundle for the end user's preferred language. (Note that the English file is not called Messages_en.properties – this is so it is always available as a default, regardless of server configuration.)

The dspace:layout tag has been updated to allow dictionary keys to be passed in for the titles. It now has two new parameters: titlekey and parenttitlekey. So where before you'd do:

<dspace:layout title="Here"
               parentlink="/mydspace"
               parenttitle="My DSpace">

You now do:

<dspace:layout titlekey="jsp.page.title"
               parentlink="/mydspace"
               parenttitlekey="jsp.mydspace">

And so the layout tag itself gets the relevant stuff out of the dictionary. title and parenttitle still work as before for backwards compatibility, and the odd spot where that's preferable.

Message Key Convention

When translating further pages, please follow the convention for naming message keys to avoid clashes.

For text in JSPs use the complete path + filename of the JSP, then a one-word name for the message. e.g. for the title of jsp/mydspace/main.jsp use:

jsp.mydspace.main.title

Some common words (e.g. "Help") can be brought out into keys starting jsp. for ease of translation, e.g.:

jsp.admin = Administer

Other common words/phrases are brought out into 'general' parameters if they relate to a set (directory) of JSPs, e.g.

jsp.tools.general.delete = Delete

Phrases that relate strongly to a topic (eg. MyDSpace) but used in many JSPs outside the particular directory are more convenient to be cross-referenced. For example one could use the key below in jsp/submit/saved.jsp to provide a link back to the user's MyDSpace:

(Cross-referencing of keys in general is not a good idea as it may make maintenance more difficult. But in some cases it has more advantages as the meaning is obvious.)

jsp.mydspace.general.goto-mydspace = Go to My DSpace

For text in servlet code, in custom JSP tags or wherever applicable use the fully qualified classname + a one-word name for the message. e.g.

org.dspace.app.webui.jsptag.ItemListTag.title = Title

Which Languages are currently supported?

To view translations currently being developed, please refer to the i18n page of the DSpace Wiki.

HTML Content in Items

For the most part, the DSpace item display just gives a link that allows an end-user to download a bitstream. However, if a bundle has a primary bitstream whose format is of MIME type text/html, instead a link to the HTML servlet is given.

So if we had an HTML document like this:

contents.html
chapter1.html
chapter2.html
chapter3.html
figure1.gif
figure2.jpg
figure3.gif
figure4.jpg
figure5.gif
figure6.gif

The Bundle's primary bitstream field would point to the contents.html Bitstream, which we know is HTML (check the format MIME type) and so we know which to serve up first.

The HTML servlet employs a trick to serve up HTML documents without actually modifying the HTML or other files themselves. Say someone is looking at contents.html from the above example, the URL in their browser will look like this:

https://dspace.mit.edu/html/1721.1/12345/contents.html

If there's an image called figure1.gif in that HTML page, the browser will do HTTP GET on this URL:

https://dspace.mit.edu/html/1721.1/12345/figure1.gif

The HTML document servlet can work out which item the user is looking at, and then which Bitstream in it is called figure1.gif, and serve up that bitstream. Similar for following links to other HTML pages. Of course all the links and image references have to be relative and not absolute.

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 constraints. 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.

<IMG SRC="images/figure1.gif">

If the item has been uploaded via the Web submit UI, in the Bitstream table in the database we have the 'name' field, which will contain the filename with no path (figure1.gif). We can still work out what images/figure1.gif is by making the HTML document servlet strip any path that comes in from the URL, e.g.

https://dspace.mit.edu/html/1721.1/12345/images/figure1.gif
                                         ^^^^^^^
                                        Strip this

BUT all the filenames (regardless of directory names) must be unique. For example, this wouldn't work:

contents.html
chapter1.html
chapter2.html
chapter1_images/figure.gif
chapter2_images/figure.gif

since the HTML document servlet wouldn't know which bitstream to serve up for:

https://dspace.mit.edu/html/1721.1/12345/chapter1_images/figure.gif
https://dspace.mit.edu/html/1721.1/12345/chapter2_images/figure.gif

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

This information now has it's own subpage: OAI-PMH Data Provider 2.0 (Internals)

DSpace Command Launcher

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

Prior 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

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: