Page History
DSpace System Documentation: Application Layer
The following explains how the application layer is built and used.
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
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 | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="d9d7c42dbf25f2ae-1c77c5e6-44054a47-bc2fa10b-8044c33508feceb2047168b9"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/webui | Web UI source files | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0ed23086d5569b4b-e70ada03-471e44fa-89929ab9-1f1b9819601d2d3cc0757c67"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/filters | Servlet Filters (Servlet 2.3 spec) | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="fe6da9dcca0ee3ea-0efea3f5-4ec5417b-8aa7b143-eb83f31658f08a7743044c7c"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/jsptag | Custom JSP tag class files | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="bcc20f12d22f596a-508c178b-4f9a41b2-9b73862f-240e62a41f16dbb06ee7b8bb"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/servlet | Servlets for main Web UI (controllers) | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="e5bf932cc6c0984b-891d8c77-4e164211-b6169bd8-2895c35e6506e6a4f3abb4b4"><ac:plain-text-body><![CDATA[ | [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 | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f5eda60b557aa74d-7a1ba39d-4ed4406e-abd394dd-24fce061872c93aa624abd34"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui/dspace-jspui-api/src/main/java/org/dspace/app/webui/util/ | Miscellaneous classes used by the servlets and filters | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="26f347924f5b8095-a621bd92-41ae481b-a48f9987-52ace422ccfcca0ea1f1e4c9"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace-jspui | The JSP files | ]]></ac:plain-text-body></ac:structured-macro> |
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="16526bfa424a136c-69be09d4-490748fe-9f569b89-2810a72d2ad438ee374bf1c8"><ac:plain-text-body><![CDATA[ | [dspace-source]/dspace/modules/jspui/src/main/webapp | This is where you place customized versions of JSPs—see 6. JSPUI 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="226a28eb3b04ddaf-ead49664-4b8f4a12-9c4f99c6-02230cc5840d6dd31bb988e2"><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="46e96f8a11fad67c-a099387d-43b5406b-9c29b93e-140defacd583ddc0f761a44c"><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="0d27098741f7b369-aa08c63f-49b94efd-9219a02b-ff148d4f45d840d147cabf3e"><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
| Wiki Markup |
|---|
The DSpace build process constructs a Web application archive, which is placed in _\[dspace-source\]/build/dspace.war_. The _build_wars_ Ant target does the work. The process works as follows: |
...
Wiki Markup (Top level) -- the JSPs (customized versions from _\[dspace-source\]/jsp/local_ will have overwritten the defaults from the DSpace source distribution)
- WEB-INF/classes – the compiled DSpace classes
Wiki Markup _WEB-INF/lib_ -- the third party library JAR files from _\[dspace-source\]/lib_, minus _servlet.jar_ which will be available as part of Tomcat (or other servlet engine)
Wiki Markup _WEB-INF/web.xml_ -- web deployment descriptor, copied from _\[dspace-source\]/build/dspace-web.xml_
Wiki Markup _WEB-INF/dspace-tags.tld_ -- tag descriptor Note that this does mean there are multiple copies of the compiled DSpace code and third-party libraries in the system, so care must be taken to ensure that they are all in sync. (The storage overhead is a few megabytes, totally insignificant these days.) In general, when you change any DSpace code or JSP, it's best to do a complete update of both the installation (_\[dspace\]_), and to rebuild and redeploy the Web UI and OAI _.war_ files, by running this in _\[dspace-source\]_:
and then following the instructions that command writes to the console.Code Block ant -D [dspace]/config/dspace.cfg update
Servlets and JSPs
The 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:
...
Flow of Control During HTTP Request Processing
Custom JSP Tags
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.
- layout: Just about every JSP uses this tag. It produces the standard HTML header and <BODY>_tag. Thus the content of each JSP is nested inside a _<dspace:layout> tag. The (XML-style)attributes of this tag are slightly complicated--see dspace-tags.tld. The JSPs in the source code bundle also provide plenty of examples.
- sidebar: Can only be used inside a layout tag, and can only be used once per JSP. The content between the start and end sidebar tags is rendered in a column on the right-hand side of the HTML page. The contents can contain further JSP tags and Java 'scriptlets'.
- date: Displays the date represented by an org.dspace.content.DCDate object. Just the one representation of date is rendered currently, but this could use the user's browser preferences to display a localized date in the future.
- include: Obsolete, simple tag, similar to jsp:include. In versions prior to DSpace 1.2, this tag would use the locally modified version of a JSP if one was installed in jsp/local. As of 1.2, the build process now performs this function, however this tag is left in for backwards compatibility.
- item: Displays an item record, including Dublin Core metadata and links to the bitstreams within it. Note that the displaying of the bitstream links is simplistic, and does not take into account any of the bundling structure. This is because DSpace does not have a fully-fledged dissemination architectural piece yet.Displaying an item record is done by a tag rather than a JSP for two reasons: Firstly, it happens in several places (when verifying an item record during submission or workflow review, as well as during standard item accesses), and secondly, displaying the item turns out to be mostly code-work rather than HTML anyway. Of course, the disadvantage of doing it this way is that it is slightly harder to customize exactly what is displayed from an item record; it is necessary to edit the tag code (org.dspace.app.webui.jsptag.ItemTag). Hopefully a better solution can be found in the future.
- itemlist, collectionlist, communitylist: These tags display ordered sequences of items, collections and communities, showing minimal information but including a link to the page containing full details. These need to be used in HTML tables.
- popup: This tag is used to render a link to a pop-up page (typically a help page.) If Javascript is available, the link will either open or pop to the front any existing DSpace pop-up window. If Javascript is not available, a standard HTML link is displayed that renders the link destination in a window named 'dspace.popup'. In graphical browsers, this usually opens a new window or re-uses an existing window of that name, but if a window is re-used it is not 'raised' which might confuse the user. In text browsers, following this link will simply replace the current page with the destination of the link. This obviously means that Javascript offers the best functionality, but other browsers are still supported.
- selecteperson: A tag which produces a widget analogous to HTML <SELECT>, that allows a user to select one or multiple e-people from a pop-up list.
- sfxlink: Using an item's Dublin Core metadata DSpace can display an SFX link, if an SFX server is available. This tag does so for a particular item if the sfx.server.url property is defined in dspace.cfg.
Internationalization
The Java Standard Tag Library v1.0 is used to specify messages in the JSPs like this:
...
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.
...
| Code Block |
|---|
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.
...
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.
...
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.
...
Naturally enough, the collection name is also the name of the corresponding set.
Unique Identifier
Every item in OAI-PMH data repository must have an unique identifier, which must conform to the URI syntax. As of DSpace 1.2, Handles are not used; this is because in OAI-PMH, the OAI identifier identifies the metadata record associated with the resource. The resource is the DSpace item, whose resource identifier is the Handle. In practical terms, using the Handle for the OAI identifier may cause problems in the future if DSpace instances share items with the same Handles; the OAI metadata record identifiers should be different as the different DSpace instances would need to be harvested separately and may have different metadata for the item.
...
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.)
Access control
OAI provides no authentication/authorisation details, although these could be implemented using standard HTTP methods. It is assumed that all access will be anonymous for the time being.
...
If in the future, this 'expose all metadata' approach proves unsatisfactory for any reason, it should be possible to expose only publicly readable metadata. The authorisation system has separate permissions for READing and item and READing the content (bitstreams) within it. This means the system can differentiate between an item with public metadata and hidden content, and an item with hidden metadata as well as hidden content. In this case the OAI data repository should only expose items those with anonymous READ access, so it can hide the existence of records to the outside world completely. In this scenario, one should be wary of protected items that are made public after a time. When this happens, the items are "new" from the OAI-PMH perspective.
Modification Date (OAI Date Stamp)
OAI-PMH harvesters need to know when a record has been created, changed or deleted. DSpace keeps track of a 'last modified' date for each item in the system, and this date is used for the OAI-PMH date stamp. This means that any changes to the metadata (e.g. admins correcting a field, or a withdrawal) will be exposed to harvesters.
'About' Information
As part of each record given out to a harvester, there is an optional, repeatable "about" section which can be filled out in any (XML-schema conformant) way. Common uses are for provenance and rights information, and there are schemas in use by OAI communities for this. Presently DSpace does not provide any of this information.
Deletions
DSpace keeps track of deletions (withdrawals). These are exposed via OAI, which has a specific mechansim for dealing with this. Since DSpace keeps a permanent record of withdrawn items, in the OAI-PMH sense DSpace supports deletions 'persistently'. This is as opposed to 'transient' deletion support, which would mean that deleted records are forgotten after a time.
...
Note that presently, the deletion of 'expunged' items is not exposed through OAI.
Flow Control (Resumption Tokens)
An OAI data provider can prevent any performance impact caused by harvesting by forcing a harvester to receive data in time-separated chunks. If the data provider receives a request for a lot of data, it can send part of the data with a resumption token. The harvester can then return later with the resumption token and continue.
...
This means the harvest is 'from'
2003-01-01, has no 'until' date, is for collection hdl:1721.1/1234, and 300 records have already been sent to the harvester. (Actually, if the original OAI-PMH request doesn't specify a 'from' or 'until, OAICat fills them out automatically to '0000-00-00T00:00:00Z' and '9999-12-31T23:59:59Z' respectively. This means DSpace resumption tokens will always have from and until dates in them.)
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
| Wiki Markup |
|---|
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
| Wiki Markup |
|---|
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 |
...
Overview
Content Tools