Versions Compared

Old Version 2

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Mark H. Wood

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

System Architecture: Application Layer

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

...

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="ac37583c-7b05-48dc-b306-400f14764d62"><ac:plain-text-body><!

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

Web UI source files

[dspace-source]]></ac:plain-text-body></ac:structured-macro><ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="bc01c3ad-fa75-4e66-9511-6cb433b896c6"><ac:plain-text-body><![CDATA[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/filters

Servlet Filters (Servlet 2.3 spec)

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

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) <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="6da2e410-11b3-4cd8-9c6c-7e3562f9b117"><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>

servlet/admin

Servlets that comprise the administration part of the Web UI <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="4783b8f7-eb6c-4415-b406-d45e4fe6c7b6"><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>

webui/util/

Miscellaneous classes used by the servlets and filters <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c18ccbdf-024e-4fe1-9fe9-cd727afdf109"><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="3d4a1300-fb13-4130-92a7-914e2fa1d950"><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="4f87c320-791c-4aed-a7a1-eec30b80223d"><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="1f61967c-6c78-4c3f-880f-d62f8b303f73"><ac:plain-text-body><![CDATA[

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

This is where you place customized versions of JSPs‚ see [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="9fc316df-528b-4b23-b72a-f5b54a3633dc"><ac:plain-text-body><![CDATA[

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

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

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

-jspui

The JSP files <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="44fabc99-ffc8-4a33-96fe-2de06cef9ab9"><ac:plain-text-body><![CDATA[

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

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

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

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. <ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="94ec423e-d3b5-4aa0-8fdf-6436a50ae358"><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

-INF/dspace-tags.tld

Custom DSpace JSP tag descriptor ]]></ac:plain-text-body></ac:structured-macro>

The Build Process

Wiki MarkupThe 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 MarkupA full DSpace "installation template" folder is built in {{\[dspace-source\]/dspace/target/dspace-\[version\]-build.dir/}}

Wiki MarkupIn 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/}} :

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

...

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.

...

  • 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 (JSPUI Only)
Anchor
internationalization
internationalization

Info
titleXMLUI Internationalization

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

...

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.unmigrated-wiki-markup

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:

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

...

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

Wiki MarkupIt 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).

...

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

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.

...

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

...

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 command
  • <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>
     .