mirror of
https://github.com/DSpace/DSpace.git
synced 2025-10-07 01:54:22 +00:00
1959ee1b5a
git-svn-id: http://scm.dspace.org/svn/repo/trunk@1560 9c30dcfa-912a-0410-8fc2-9e0234be79fd
955 lines
66 KiB
HTML
955 lines
66 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>DSpace System Documentation: Application Layer</title>
|
|
<link rel="StyleSheet" href="style.css" type="text/css">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>DSpace System Documentation: Application Layer</h1>
|
|
|
|
<p><a href="index.html">Back to contents</a></P>
|
|
<P><a href="architecture.html">Back to architecture overview</a></p>
|
|
|
|
<h2><a name="webui" id="webui">Web User Interface</a></h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 [FIXME: administrators or editors?]</p>
|
|
|
|
<h3>Web UI Files</h3>
|
|
|
|
<p>The Web UI-related files are located in a variety of directories in the DSpace source tree. Note that as of DSpace version 1.2, the deployment mechanism has changed; the build process creates easy-to-deploy Web application archives (<code>.war</code> files).</p>
|
|
|
|
<table>
|
|
<caption>
|
|
Locations of Web UI Source Files
|
|
</caption>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<th>Location</th>
|
|
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui</code></td>
|
|
|
|
<td>Web UI source files</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui.filter</code></td>
|
|
|
|
<td>Servlet Filters (Servlet 2.3 spec)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui.jsptag</code></td>
|
|
|
|
<td>Custom JSP tag class files</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui.servlet</code></td>
|
|
|
|
<td>Servlets for main Web UI (controllers)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui.servlet.admin</code></td>
|
|
|
|
<td>Servlets that comprise the administration part of the Web UI</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>org.dspace.app.webui.util</code></td>
|
|
|
|
<td>Miscellaneous classes used by the servlets and filters</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><em>[dspace-source]</em>/jsp</code></td>
|
|
|
|
<td>The JSP files</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><em>[dspace-source]</em>/jsp/local</code></td>
|
|
|
|
<td>This is where you can place customized versions of JSPs -- see <a href="configure.html#customui">the configuration section</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><em>[dspace-source]</em>/jsp/WEB-INF/dspace-tags.tld</code></td>
|
|
|
|
<td>Custom DSpace JSP tag descriptor</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><em>[dspace-source]</em>/etc/dspace-web.xml</code></td>
|
|
|
|
<td>The Web application deployment descriptor. Before including in the <code>.war</code> file, the text <code>@@dspace.dir@@</code> will be replaced with the DSpace installation directory (referred to as <em>[dspace]</em> elsewhere in this system documentation). This allows the Web application to pick up the DSpace configuration and environment.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3><a name="webui_build" id="webui_build">The Build Process</a></h3>
|
|
|
|
<p>The DSpace build process constructs a Web application archive, which is placed in <code><em>[dspace-source]</em>/build/dspace.war</code>. The <code>build_wars</code> Ant target does the work. The process works as follows:</p>
|
|
|
|
<ul>
|
|
<li>All the DSpace source code is compiled.</li>
|
|
|
|
<li><code><em>[dspace-source]</em>/etc/dspace-web.xml</code> is copied to <code><em>[dspace-source]</em>/build</code> and the <code>@@dspace.dir@@</code> token inside it replaced with the DSpace installation directory (<code>dspace.dir</code> property from <code>dspace.cfg</code></li>
|
|
|
|
<li>The JSPs are all copied to <code><em>[dspace-source]</em>/build/jsp</code></li>
|
|
|
|
<li>Customized JSPs from <code><em>[dspace-source]</em>/jsp/local</code> are copied on top of these, thus 'overriding' the default versions</li>
|
|
|
|
<li><code><em>[dspace-source]</em>/build/dspace.war</code> is built</li>
|
|
</ul>
|
|
|
|
<p>The contents of <code>dspace.war</code> are:</p>
|
|
|
|
<ul>
|
|
<li>(Top level) -- the JSPs (customized versions from <code><em>[dspace-source]</em>/jsp/local</code> will have overwritten the defaults from the DSpace source distribution)</li>
|
|
|
|
<li><code>WEB-INF/classes</code> -- the compiled DSpace classes</li>
|
|
|
|
<li><code>WEB-INF/lib</code> -- the third party library JAR files from <code><em>[dspace-source]</em>/lib</code>, minus <code>servlet.jar</code> which will be available as part of Tomcat (or other servlet engine)</li>
|
|
|
|
<li><code>WEB-INF/web.xml</code> -- web deployment descriptor, copied from <code><em>[dspace-source]</em>/build/dspace-web.xml</code></li>
|
|
|
|
<li><code>WEB-INF/dspace-tags.tld</code> -- tag descriptor</li>
|
|
</ul>
|
|
|
|
<p>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 (<code><em>[dspace]</em></code>), and to rebuild and redeploy the Web UI and OAI <code>.war</code> files, by running this in <code><em>[dspace-source]</em></code>:</p>
|
|
<pre>
|
|
ant -D<em>[dspace]</em>/config/dspace.cfg update
|
|
</pre>
|
|
|
|
<p>and then following the instructions that command writes to the console.</p>
|
|
|
|
<h3>Servlets and JSPs</h3>
|
|
|
|
<p>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:</p>
|
|
|
|
<ol>
|
|
<li>An HTTP request is received from a browser</li>
|
|
|
|
<li>The appropriate servlet is invoked, and processes the request by invoking the DSpace business logic layer public API</li>
|
|
|
|
<li>Depending on the outcome of the processing, the servlet invokes the appropriate JSP</li>
|
|
|
|
<li>The JSP is processed and sent to the browser</li>
|
|
</ol>
|
|
|
|
<p>The reasons for this approach are:</p>
|
|
|
|
<ul>
|
|
<li>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</li>
|
|
|
|
<li>The JSPs contain as little code as possible, so they can be customized without having to delve into Java code too much</li>
|
|
</ul>
|
|
|
|
<p>The <code>org.dspace.app.webui.servlet.LoadDSpaceConfig</code> servlet is always loaded first. This is a very simple servlet that checks the <code>dspace-config</code> context parameter from the DSpace deployment descriptor, and uses it to locate <code>dspace.cfg</code>. 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.</p>
|
|
|
|
<p>All DSpace servlets are subclasses of the <code>DSpaceServlet</code> class. The <code>DSpaceServlet</code> class handles some basic operations such as creating a DSpace <code>Context</code> object (opening a database connection etc.), authentication and error handling. Instead of overriding the <code>doGet</code> and <code>doPost</code> methods as one normally would for a servlet, DSpace servlets implement <code>doDSGet</code> or <code>doDSPost</code> which have an extra context parameter, and allow the servlet to throw various exceptions that can be handled in a standard way.</p>
|
|
|
|
<p>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 <code>HttpRequest</code> object that represents the HTTP request being processed. This is done by invoking the <code>setAttribute</code> method of the <code>javax.servlet.http.HttpServletRequest</code> object that is passed into the servlet from Tomcat. The servlet then forwards control of the request to the appropriate JSP using the <code>JSPManager.showJSP</code> method.</p>
|
|
|
|
<p>The <code>JSPManager.showJSP</code> 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.</p>
|
|
|
|
<p>There is an exception to this servlet/JSP style: <code>index.jsp</code>, 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 '<code>/</code>'; such a mapping results in every request being directed to that servlet. By default, Tomcat forwards requests to '<code>/</code>' to <code>index.jsp</code>. To try and make things as clean as possible, <code>index.jsp</code> contains some simple code that would normally go in a servlet, and then forwards to <code>home.jsp</code> using the <code>JSPManager.showJSP</code> method. This means localized versions of the 'home page' can be created by placing a customized <code>home.jsp</code> in <code><em>[dspace-source]</em>/jsp/local</code>, in the same manner as other JSPs.</p>
|
|
|
|
<p><code><em>[dspace-source]</em>/jsp/dspace-admin/index.jsp</code>, the administration UI index page, is invoked directly by Tomcat and not through a servlet for similar reasons.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Many JSPs containing forms will include hidden parameters that tell the servlets which form has been filled out. The submission UI servlet (<code>SubmitServlet</code> is a prime example of a servlet that deals with the input from many different JSPs. The <code>step</code> hidden parameter is used to inform the servlet which form has been filled out (which step of submission the user has just completed.)</p>
|
|
|
|
<p>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 <a href="configure.html#authenticate">described in the configuration section</a>.</p>
|
|
|
|
<p class="figure"><img src="image/web-ui-flow.gif" alt="Web UI Control Flow"></p>
|
|
|
|
<p class="caption">Flow of Control During HTTP Request Processing</p>
|
|
|
|
<h3>Custom JSP Tags</h3>
|
|
|
|
<p>The DSpace JSPs all use some custom tags defined in <code>/dspace/jsp/WEB-INF/dspace-tags.tld</code>, and the corresponding Java classes reside in <code>org.dspace.app.webui.jsptag</code>. The tags are listed below. The <code>dspace-tags.tld</code> file contains detailed comments about how to use the tags, so that information is not repeated here.</p>
|
|
|
|
<dl>
|
|
<dt><code>layout</code></dt>
|
|
|
|
<dd>
|
|
<p>Just about every JSP uses this tag. It produces the standard HTML header and <code><BODY></code>tag. Thus the content of each JSP is nested inside a <code><dspace:layout></code> tag. The (XML-style)attributes of this tag are slightly complicated--see <code>dspace-tags.tld</code>. The JSPs in the source code bundle also provide plenty of examples.</p>
|
|
</dd>
|
|
|
|
<dt><code>sidebar</code></dt>
|
|
|
|
<dd>
|
|
<p>Can only be used inside a <code>layout</code> tag, and can only be used once per JSP. The content between the start and end <code>sidebar</code> 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'.</p>
|
|
</dd>
|
|
|
|
<dt><code>date</code></dt>
|
|
|
|
<dd>
|
|
<p>Displays the date represented by an <code>org.dspace.content.DCDate</code> 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.</p>
|
|
</dd>
|
|
|
|
<dt><code>include</code></dt>
|
|
|
|
<dd>
|
|
<p>Obsolete, simple tag, similar to <code>jsp:include</code>. 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.</p>
|
|
</dd>
|
|
|
|
<dt><code>item</code></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
|
|
<p>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 (<code>org.dspace.app.webui.jsptag.ItemTag</code>). Hopefully a better solution can be found in the future.</p>
|
|
</dd>
|
|
|
|
<dt><code>itemlist</code>, <code>collectionlist</code>, <code>communitylist</code></dt>
|
|
|
|
<dd>
|
|
<p>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.</p>
|
|
</dd>
|
|
|
|
<dt><code>popup</code></dt>
|
|
|
|
<dd>
|
|
<p>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 '<code>dspace.popup</code>'. 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.</p>
|
|
</dd>
|
|
|
|
<dt><code>selecteperson</code></dt>
|
|
|
|
<dd>
|
|
<p>A tag which produces a widget analogous to HTML <code><SELECT></code>, that allows a user to select one or multiple e-people from a pop-up list.</p>
|
|
</dd>
|
|
|
|
<dt><code>sfxlink</code></dt>
|
|
|
|
<dd>
|
|
<p>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 <code>sfx.server.url</code> property is defined in <code>dspace.cfg</code>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a name="i18n" id="i18n">Internationalisation</a></h3>
|
|
|
|
<p>The <a class="external" href="http://jakarta.apache.org/taglibs/doc/standard-1.0-doc/intro.html">Java Standard Tag Library v1.0</a> is used to specify messages in the JSPs like this:</p>
|
|
|
|
<p>OLD:</p>
|
|
<pre>
|
|
<H1>Search Results</H1>
|
|
</pre>
|
|
|
|
<p>NEW:</p>
|
|
<pre>
|
|
<H1><fmt:message key="jsp.search.results.title" /></H1>
|
|
</pre>
|
|
|
|
<p>This message can now be changed using the <tt>config/language-packs/Messages.properties</tt> file. (This must be done at build-time: <tt>Messages.properties</tt> is placed in the <tt>dspace.war</tt> Web application file.)</p>
|
|
<pre>
|
|
jsp.search.results.title = Search Results
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>OLD:</p>
|
|
<pre>
|
|
<P>Results <%= r.getFirst() %> to <%= r.getLast() %> of <%= r.getTotal() %></P>
|
|
</pre>
|
|
|
|
<p>NEW:</p>
|
|
<pre>
|
|
<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>
|
|
</pre>
|
|
|
|
<p>(Note: JSTL 1.0 does not seem to allow JSP <%= %> expressions to be passed in as values of attribute in <fmt:param value=""/>)</p>
|
|
|
|
<p>The above would appear in the <tt>Messages_xx.properties</tt> file as:</p>
|
|
<pre>
|
|
jsp.search.results.text = Results {0}-{1} of {2}
|
|
</pre>
|
|
|
|
<p>Introducing number parameters that should be formatted according to the locale used makes no difference in the message key compared to atring parameters:</p>
|
|
<pre>
|
|
jsp.submit.show-uploaded-file.size-in-bytes = {0} bytes
|
|
</pre>
|
|
|
|
<p>In the JSP using this key can be used in the way belov:</p>
|
|
<pre>
|
|
<fmt:message key="jsp.submit.show-uploaded-file.size-in-bytes">
|
|
<fmt:param><fmt:formatNumber><%= bitstream.getSize() %></fmt:formatNumber></fmt:param>
|
|
</fmt:message>
|
|
</pre>
|
|
|
|
<p>(Note: JSTL offers a way to include numbers in the message keys as <tt>jsp.foo.key = {0,number} bytes</tt>. Setting the parameter as <tt><fmt:param value="${variable}" /></tt> workes when <tt>variable</tt> is a single variable name and doesn't work when trying to use a method's return value instead: <tt>bitstream.getSize()</tt>. Passing the number as string (or using the <%= %> expression) also does not work.)</p>
|
|
|
|
<p>Multiple <tt>Messages.properties</tt> can be created for different languages. See <a class="external" href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/ResourceBundle.html#getBundle(java.lang.String,%20java.util.Locale,%20java.lang.ClassLoader)">ResourceBundle.getBundle</a>. e.g. you can add German and Canadian French translations:</p>
|
|
<pre>
|
|
Messages_de.properties
|
|
Messages_fr_CA.properties
|
|
</pre>
|
|
|
|
<p>The end user's browser settings determine which language is used. The English language file <tt>Messages.properties</tt> (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 <code>Messages_en.properties</code> -- this is so it is always available as a default, regardless of server configuration.)</p>
|
|
|
|
<p>The <tt>dspace:layout</tt> tag has been updated to allow dictionary keys to be passed in for the titles. It now has two new parameters: <tt>titlekey</tt> and <tt>parenttitlekey</tt>. So where before you'd do:</p>
|
|
<pre>
|
|
<dspace:layout title="Here"
|
|
parentlink="/mydspace"
|
|
parenttitle="My DSpace">
|
|
</pre>
|
|
|
|
<p>You now do:</p>
|
|
<pre>
|
|
<dspace:layout titlekey="jsp.page.title"
|
|
parentlink="/mydspace"
|
|
parenttitlekey="jsp.mydspace">
|
|
|
|
</pre>
|
|
|
|
<p>And so the layout tag itself gets the relevant stuff out of the dictionary. <tt>title</tt> and <tt>parenttitle</tt> still work as before for backwards compatibility, and the odd spot where that's preferable.</p>
|
|
|
|
<h4>Message Key Convention</h4>
|
|
|
|
<p>When translating further pages, please follow the convention for naming message keys to avoid clashes.</p>
|
|
|
|
<p><strong>For text in JSPs</strong> use the complete path + filename of the JSP, then a one-word name for the message. e.g. for the title of <tt>jsp/mydspace/main.jsp</tt> use:</p>
|
|
<pre>
|
|
jsp.mydspace.main.title
|
|
</pre>
|
|
|
|
<p>Some common words (e.g. "Help") can be brought out into keys starting <tt>jsp.</tt> for ease of translation, e.g.:</p>
|
|
<pre>
|
|
jsp.admin = Administer
|
|
</pre>
|
|
|
|
<p>Other common words/phrases are brought out into 'general' parameters if they relate to a set (directory) of JSPs, e.g.</p>
|
|
<pre>
|
|
jsp.tools.general.delete = Delete
|
|
</pre>
|
|
|
|
<p>Phrases that relate <strong>strongly</strong> 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 <tt>jsp/submit/saved.jsp</tt> to provide a link back to the user's <em>MyDSpace</em>:</p>
|
|
|
|
<p><em>(Cross-referencing of keys <strong>in general</strong> 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.)</em></p>
|
|
<pre>
|
|
jsp.mydspace.general.goto-mydspace = Go to My DSpace
|
|
</pre>
|
|
|
|
<p><strong>For text in servlet code</strong>, in custom JSP tags or wherever applicable use the fully qualified classname + a one-word name for the message. e.g.</p>
|
|
<pre>
|
|
org.dspace.app.webui.jsptag.ItemListTag.title = Title
|
|
</pre>
|
|
|
|
<h4>Which Languages are currently supported?</h4>
|
|
|
|
<p>To view translations currently being developed, please refer to the <a href="http://wiki.dspace.org/I18nSupport">i18n page</a> of the DSpace Wiki.</p>
|
|
|
|
<h3>HTML Content in Items</h3>
|
|
|
|
<p>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 <code>text/html</code>, instead a link to the HTML servlet is given.</p>
|
|
|
|
<p>So if we had an HTML document like this:</p>
|
|
<pre>
|
|
contents.html
|
|
chapter1.html
|
|
chapter2.html
|
|
chapter3.html
|
|
figure1.gif
|
|
figure2.jpg
|
|
figure3.gif
|
|
figure4.jpg
|
|
figure5.gif
|
|
figure6.gif
|
|
</pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <code>contents.html</code> from the above example, the URL in their browser will look like this:</p>
|
|
<pre>
|
|
https://dspace.mit.edu/html/1721.1/12345/contents.html
|
|
</pre>
|
|
|
|
<p>If there's an image called <code>figure1.gif</code> in that HTML page, the browser will do HTTP GET on this URL:</p>
|
|
<pre>
|
|
https://dspace.mit.edu/html/1721.1/12345/figure1.gif
|
|
</pre>
|
|
|
|
<p>The HTML document servlet can work out which item the user is looking at, and then which Bitstream in it is called <code>figure1.gif</code>, 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.</p>
|
|
|
|
<p>This can cope with relative links that refer to a deeper path, e.g.</p>
|
|
<pre>
|
|
<IMG SRC="images/figure1.gif">
|
|
</pre>
|
|
|
|
<p>Remember that in the Bitstream table in the database we have the 'name' field, which always contains the filename with no path (<code>figure1.gif</code>). We also have the <code>source</code> field, which <em>may</em> contain the full pathname of the file as it appeared on the submitter's hard drive, but this is browser- and OS-dependent, so we can't rely on it. All we can rely on is the filename.</p>
|
|
|
|
<p>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.</p>
|
|
<pre>
|
|
https://dspace.mit.edu/html/1721.1/12345/images/figure1.gif
|
|
^^^^^^^
|
|
Strip this
|
|
</pre>
|
|
|
|
<p>BUT all the filenames (regardless of directory names) must be unique. For example, this wouldn't work:</p>
|
|
<pre>
|
|
contents.html
|
|
chapter1.html
|
|
chapter2.html
|
|
chapter1_images/figure.gif
|
|
chapter2_images/figure.gif
|
|
</pre>
|
|
|
|
<p>since the HTML document servlet wouldn't know which bitstream to serve up for:</p>
|
|
<pre>
|
|
https://dspace.mit.edu/html/1721.1/12345/chapter1_images/figure.gif
|
|
https://dspace.mit.edu/html/1721.1/12345/chapter2_images/figure.gif
|
|
</pre>
|
|
|
|
<p>since it would just have <code>figure.gif</code> in the Bitstream table. Thus, the limitations are:</p>
|
|
|
|
<ul>
|
|
<li>All links must be relative and not refer to parents (e.g. <code>../images/foo.gif</code> or <code>/images/foo.gif</code>)</li>
|
|
|
|
<li>If links refer to deeper directory levels, all the filenames must be different (as explained above)</li>
|
|
</ul>
|
|
|
|
<h3>Thesis Blocking</h3>
|
|
|
|
<p>The submission UI has an optional feature that came about as a result of MIT Libraries policy. If the <code>block.theses</code> parameter in <code>dspace.cfg</code> is <code>true</code>, 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 (<code>/dspace/jsp/submit/no-theses.jsp</code> can be localized as necessary.</p>
|
|
|
|
<h2><a name="oai" id="oai">OAI-PMH Data Provider</a></h2>
|
|
|
|
<p>The DSpace platform supports the <a href="http://www.openarchives.org/">Open Archives Initiative Protocol for Metadata Harvesting</a> (OAI-PMH) version 2.0 as a data provider. This is accomplished using the <a href="http://www.oclc.org/research/software/oai/cat.shtm">OAICat framework from OCLC</a>.</p>
|
|
|
|
<p>The DSpace build process builds a Web application archive, <code><em>[dspace-source]</em>/build/dspace-oai.war</code>), in much the same way as <a href="#webui_build">the Web UI build process</a> described above. The only differences are that the JSPs are not included, and <code><em>[dspace-source]</em>/etc/oai-web.xml</code> 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 <em>not</em> be deployed on SSL (<code>https:</code> protocol). In a typical configuration, this is deployed at <code>dspace-oai</code>, for example:</p>
|
|
<pre>
|
|
http://dspace.myu.edu/dspace-oai/request?verb=Identify
|
|
</pre>
|
|
|
|
<p>The 'base URL' of this DSpace deployment would be:</p>
|
|
<pre>
|
|
http://dspace.myu.edu/dspace-oai/request
|
|
</pre>
|
|
|
|
<p>It is this URL that should be registered with <a href="http://www.openarchives.org/">www.openarchives.org</a>. Note that you can easily change the '<code>request</code>' portion of the URL by editing <code><em>[dspace-source]</em>/etc/oai-web.xml</code> and rebuilding and deploying <code>dspace-oai.war</code>.</p>
|
|
|
|
<p>DSpace provides implementations of the OAICat interfaces <code>AbstractCatalog</code>, <code>RecordFactory</code> and <code>Crosswalk</code> that interface with the DSpace content management API and harvesting API (in the search subsystem).</p>
|
|
|
|
<p>Only the basic <code>oai_dc</code> 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, <code>description.abstract</code> is exposed as unqualified <code>description</code>. The <code>description.provenance</code> 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 <code>contributor.author</code> are exposed as <code>creator</code> values.</p>
|
|
|
|
<p>Other metadata formats are supported as well, using other <code>Crosswalk</code> implementations; consult the <code>oaicat.properties</code> file described below. To enable a format, simply uncomment the lines beginning with <code>Crosswalks.*</code>. 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.</p>
|
|
|
|
<p>Note that the current simple DC implementation (<code>org.dspace.app.oai.OAIDCCrosswalk</code>) 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 <code>></code>) are encoded (e.g. to <code>&gt;</code>)</p>
|
|
|
|
<p>In addition to the implementations of the OAICat interfaces, there are two configuration files relevant to OAI support:</p>
|
|
|
|
<dl>
|
|
<dt><code>oaicat.properties</code></dt>
|
|
|
|
<dd>
|
|
<p>This resides as a template in <code><em>[dspace]</em>/config/templates</code>, and the live version is written to <code><em>[dspace]</em>/config</code>. You probably won't need to edit this; the <code>install-configs</code> script fills out the relevant deployment-specific parameters. You might want to change the <code>earliestDatestamp</code> field to accurately reflect the oldest datestamp in the system. (Note that this is the value of the <code>last_modified</code> column in the <code>Item</code> database table.)</p>
|
|
</dd>
|
|
|
|
<dt><code>oai-web.xml</code></dt>
|
|
|
|
<dd>
|
|
<p>This standard Java Servlet 'deployment descriptor' is stored in the source as <code><em>[dspace-source]</em>/etc/oai-web.xml</code>, and is written to <code>/dspace/oai/WEB-INF/web.xml</code>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3>Sets</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>DSpace exposes collections as sets. The organization of communities is likely to change over time, and is therefore a less stable basis for selective harvesting.</p>
|
|
|
|
<p>Each collection has a corresponding OAI set, discoverable by harvesters via the ListSets verb. The setSpec is the Handle of the collection, with the ':' and '/' converted to underscores so that the Handle is a legal setSpec, for example:</p>
|
|
<pre>
|
|
hdl_1721.1_1234
|
|
</pre>
|
|
|
|
<p>Naturally enough, the collection name is also the name of the corresponding set.</p>
|
|
|
|
<h3>Unique Identifier</h3>
|
|
|
|
<p>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 <em>metadata record</em> associated with the <em>resource</em>. The <em>resource</em> is the DSpace item, whose <em>resource identifier</em> 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.</p>
|
|
|
|
<p>The OAI identifiers that DSpace uses are of the form:</p>
|
|
|
|
<p><code>oai:<em>host name</em>:<em>handle</em></code></p>
|
|
|
|
<p>For example:</p>
|
|
|
|
<p><code>oai:dspace.myu.edu:123456789/345</code></p>
|
|
|
|
<p>If you wish to use a different scheme, this can easily be changed by editing the value of <code>OAI_ID_PREFIX</code> at the top of the <code>org.dspace.app.oai.DSpaceOAICatalog</code> 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.)</p>
|
|
|
|
<h3>Access control</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>A question is, "is all metadata public?" Presently the answer to this is yes; all metadata is exposed via OAI-PMH, even if the item has restricted access policies. The reasoning behind this is that people who do actually have permission to read a restricted item should still be able to use OAI-based services to discover the content.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3>Modification Date (OAI Date Stamp)</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3>'About' Information</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3>Deletions</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Once an item has been withdrawn, OAI-PMH harvests of the date range in which the withdrawal occurred will find the 'deleted' record header. Harvests of a date range prior to the withdrawal will <em>not</em> find the record, despite the fact that the record did exist at that time.</p>
|
|
|
|
<p>As an example of this, consider an item that was created on 2002-05-02 and withdrawn on 2002-10-06. A request to harvest the month 2002-10 will yield the 'record deleted' header. However, a harvest of the month 2002-05 will not yield the original record.</p>
|
|
|
|
<p>Note that presently, the deletion of 'expunged' items is not exposed through OAI.</p>
|
|
|
|
<h3>Flow Control (Resumption Tokens)</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>DSpace supports resumption tokens for 'ListRecords' OAI-PMH requests. ListIdentifiers and ListSets requests do not produce a particularly high load on the system, so resumption tokens are not used for those requests.</p>
|
|
|
|
<p>Each OAI-PMH ListRecords request will return at most 100 records. This limit is set at the top of <code>org.dspace.app.oai.DSpaceOAICatalog.java</code> (<code>MAX_RECORDS</code>). A potential issue here is that if a harvest yields an exact multiple of <code>MAX_RECORDS</code>, the last operation will result in a harvest with no records in it. It is unclear from the OAI-PMH specification if this is acceptable.</p>
|
|
|
|
<p>When a resumption token is issued, the optional <code>completeListSize</code> and <code>cursor</code> attributes are not included. OAICat sets the <code>expirationDate</code> of the resumption token to one hour after it was issued, though in fact since DSpace resumption tokens contain all the information required to continue a request they do not actually expire.</p>
|
|
|
|
<p>Resumption tokens contain all the state information required to continue a request. The format is:</p>
|
|
<pre>
|
|
from/until/setSpec/offset
|
|
</pre>
|
|
|
|
<p><code>from</code> and <code>until</code> are the ISO 8601 dates passed in as part of the original request, and <code>setSpec</code> is also taken from the original request. <code>offset</code> is the number of records that have already been sent to the harvester. For example:</p>
|
|
<pre>
|
|
2003-01-01//hdl_1721_1_1234/300
|
|
</pre>
|
|
|
|
<p>This means the harvest is 'from' <code>2003-01-01</code>, 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.)</p>
|
|
|
|
<h2><a name="packager" id="packager">Package Importer and Exporter</a></h2>
|
|
|
|
<p>This command-line tool gives you access to the Packager plugins. It can <em>ingest</em> a package to create a new DSpace Item, or <em>disseminate</em> an Item as a package.</p>
|
|
|
|
<p>To see all the options, invoke it as: <pre><em>[dspace]</em>/bin/dsrun org.dspace.app.packager.Packager --help</pre> This mode also displays a list of the names of package ingesters and disseminators that are available.</p>
|
|
|
|
<h3>Ingesting</h3>
|
|
|
|
<p>To ingest a package from a file, give the command: <pre><em>[dspace]</em>/bin/dsrun org.dspace.app.packager.Packager -e <em>user</em> -c <em>handle</em> -t <em>packager</em> <em>path</em></pre>
|
|
Where <em>user</em> is the e-mail address of the E-Person under whose authority this runs; <em>handle</em> is the Handle of the collection into which the Item is added, <em>packager</em> is the plugin name of the
|
|
package ingester to use, and <em>path</em> is the path to the file to ingest (or <code>"-"</code> to read from the standard input).</p>
|
|
|
|
<p>Here is an example that loads a PDF file with internal metadata as a package:
|
|
<pre>/dspace/bin/dsrun org.dspace.app.packager.Packager -e florey@mit.edu -c 1721.2/13 -t pdf thesis.pdf</pre>
|
|
</p>
|
|
|
|
<p>This example takes the result of retrieving a URL and ingests it:
|
|
<pre>wget -O - http://alum.mit.edu/jarandom/my-thesis.pdf | \
|
|
/dspace/bin/dsrun org.dspace.app.packager.Packager -e florey@mit.edu -c 1721.2/13 -t pdf -</pre></p>
|
|
|
|
<h3>Disseminating</h3>
|
|
|
|
<p>To disseminate an Item as a package, give the command:
|
|
<pre><em>[dspace]</em>/bin/dsrun org.dspace.app.packager.Packager -e <em>user</em> -d -i <em>handle</em> -t <em>packager</em> <em>path</em></pre> Where <em>user</em> is the e-mail address of the E-Person under whose
|
|
authority this runs; <em>handle</em> is the Handle of the Item to disseminate;
|
|
<em>packager</em> is the plugin name of the package disseminator to use; and <em>path</em> is the path to the file to
|
|
create (or <code>"-"</code> to write to the standard output).
|
|
|
|
This example writes an Item out as a METS package in the file "454.zip":
|
|
<pre>/dspace/bin/dsrun org.dspace.app.packager.Packager -e florey@mit.edu -d -i 1721.2/454 -t METS 454.zip</pre></p>
|
|
|
|
<h3>METS packages</h3>
|
|
|
|
<p>DSpace 1.4 includes a package disseminator and matching ingester for the DSpace METS SIP (Submission Information Package) format. They were created to help end users prepare sets of digital resources and metadata for submission
|
|
to the archive using well-defined standards such as
|
|
<a href="http://www.loc.gov/standards/mets/">METS</a>,
|
|
<a href="http://www.loc.gov/standards/mods/">MODS</a>,
|
|
<a href="http://www.loc.gov/standards/premis/">and PREMIS</a>.
|
|
The plugin name is <code>METS</code> by default, and it uses MODS for descriptive metadata.</p>
|
|
|
|
<p>The DSpace METS SIP profile is available at:
|
|
<a href="http://www.dspace.org/standards/METS/SIP/profilev1p0/metsipv1p0.pdf">
|
|
<code>http://www.dspace.org/standards/METS/SIP/profilev1p0/metsipv1p0.pdf</code></a>.</p>
|
|
|
|
<h2><a name="itemimporter" id="itemimporter">Item Importer and Exporter</a></h2>
|
|
|
|
<p>DSpace has a set of command line tools for importing and exporting items in batches, using the DSpace simple archive format. The tools are not terribly robust, but are useful and are easily modified. They also give a good demonstration of how to implement your own item importer if desired.</p>
|
|
|
|
<h3>Warning: templates may be applied</h3>
|
|
|
|
<p>Due to a bug as of 1.2 beta 2, if you have an Item template in your Collection, then those default values may be added to Items that you import. Be sure to remove the template if this is unwanted behavior.</p>
|
|
|
|
<h3>DSpace simple archive format</h3>
|
|
|
|
<p>The basic concept behind the DSpace's simple archive format is to create an archive, which is directory full of items, with a subdirectory per item. Each item directory contains a file for the item's descriptive metadata, and the files that make up the item.</p>
|
|
<pre>
|
|
archive_directory/
|
|
item_000/
|
|
dublin_core.xml -- qualified Dublin Core metadata
|
|
contents -- text file containing one line per filename
|
|
file_1.doc -- files to be added as bitstreams to the item
|
|
file_2.pdf
|
|
item_001/
|
|
dublin_core.xml
|
|
contents
|
|
file_1.png
|
|
...
|
|
</pre>
|
|
|
|
<p>The <code>dublin_core.xml</code> file has the following format, where each Dublin Core element has it's own entry within a <code><dcvalue></code> tagset. There are currently three tag elements available in the <code><dcvalue></code> tagset:</p>
|
|
|
|
<ul>
|
|
<li><code><element></code> - the Dublin Core element</li>
|
|
|
|
<li><code><qualifier></code> - the element's qualifier</li>
|
|
|
|
<li><code><language></code> - (optional)ISO language code for element</li>
|
|
</ul>
|
|
<pre>
|
|
<dublin_core>
|
|
<dcvalue element="title" qualifier="none">A Tale of Two Cities</dcvalue>
|
|
<dcvalue element="date" qualifier="issued">1990</dcvalue></dublin_core>
|
|
<dcvalue element="title" qualifier="alternate" language="fr" ">J'aime les Printemps</dcvalue>
|
|
</dublin_core>
|
|
|
|
</pre>
|
|
|
|
<p>(Note the optional language tag which notifies the system that the optional title is in French.)</p>
|
|
|
|
<p>The <code>contents</code> file simply enumerates, one file per line, the bitstream file names. The bitstream name may optionally be followed by the sequence:<br><br> <code>\tbundle:bundlename</code><br><br> where '\t' is the tab character and 'bundlename' is replaced by the name of the bundle to which the bitstream should be added. If no bundle is specified, the bitstream will be added to the 'ORIGINAL' bundle.<p>
|
|
|
|
<h3><a name="importingitems" id="importingitems">Importing Items</a></h3>
|
|
|
|
<p><strong>Note:</strong> Before running the item importer over items previously exported from a DSpace instance, please first refer to <a href="application.html#transferitem">Transferring Items Between DSpace Instances</a>.</p>
|
|
|
|
<p>The item importer is in <code>org.dspace.app.itemimport.ItemImport</code>, and is run with the <code>dsrun</code> utility in the <code>dspace/bin</code> directory. Running it with -h gets the current command-line arguments. Another very important flag is the --test flag, which you can use with any command to simulate all of the actions it will perform without actually making any changes to your DSpace instance - very useful for validating your item directories before doing an import. In the importer's arguments you can use either the user's database ID or email address and the eperson ID, and the collection's database ID or handle as arguments. Currently with the importer you can add, remove, and replace items in a collection. If you specify more than one collection argument then the items will be imported to multiple collections, and the first collection specified becomes the "owning" collection. If there is an error and the import is aborted, there is a --resume flag that you can try to resume the import where you left off after you fix the error.</p>
|
|
|
|
<p>To add items to a collection with an EPerson as the submitter, type:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport --add --eperson=joe@user.com --collection=collectionID --source=items_dir --mapfile=mapfile
|
|
</pre>
|
|
|
|
<p>(or by using the short form)</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport -a -e joe@user.com -c collectionID -s items_dir -m mapfile
|
|
</pre>
|
|
|
|
<p>which would then cycle through the archive directory's items, import them, and then generate a map file which stores the mapping of item directories to item handles. Save this map file! Using the map file you can then 'unimport' with the command:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport --delete --mapfile=mapfile
|
|
</pre>
|
|
|
|
<p>The imported items listed in the map file would then be deleted. If you wish to replace previously imported items, you can give the command:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport --replace --eperson=joe@user.com --collection=collectID --source=items_dir --mapfile=mapfile
|
|
</pre>
|
|
|
|
<p>Replacing items uses the map file to replace the old items and still retain their handles.</p>
|
|
|
|
<p>The importer usually bypasses any workflow assigned to a collection, but adding the --workflow option will route the imported items through the workflow system.</p>
|
|
|
|
<p>The importer also has a --test flag that will simulate the entire import process without actually doing the import. This is extremely useful for verifying your import files before doing the import step.</p>
|
|
|
|
<h3><a name="exportingitems" id="exportingitems"></a>Exporting Items</h3>
|
|
|
|
<p>The item exporter can export a single item or a collection of items, and creates a DSpace simple archive for each item to be exported. To export a collection's items you type:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemexport.ItemExport --type=COLLECTION --id=collID --dest=dest_dir --number=seq_num
|
|
</pre>
|
|
|
|
<p>The keyword <code>COLLECTION</code> means that you intend to export an entire collection. The ID can either be the database ID or the handle. The exporter will begin numbering the simple archives with the sequence number that you supply. To export a single item use the keyword <code>ITEM</code> and give the item ID as an argument:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemexport.ItemExport --type=ITEM --id=itemID --dest=dest_dir --number=seq_num
|
|
</pre>
|
|
|
|
<p>Each exported item will have an additional file in its directory, named 'handle'. This will contain the handle that was assigned to the item, and this file will be read by the importer so that items exported and then imported to another machine will retain the item's original handle.</p>
|
|
|
|
<h2><a name="transferitem" id="transferitem">Transferring Items Between DSpace Instances</a></h2>
|
|
|
|
<p>Where items are to be moved between DSpace instances (for example from a test DSpace into a production DSpace) the item exporter and item importer can be used in conjunction with a script to assist in this process.</p>
|
|
|
|
<p>After running the item exporter each <code>dublin_core.xml</code> file will contain metadata that was automatically added by DSpace. These fields are as follows:</p>
|
|
|
|
<ul>
|
|
<li>date.accessioned</li>
|
|
|
|
<li>date.available</li>
|
|
|
|
<li>date.issued</li>
|
|
|
|
<li>description.provenance</li>
|
|
|
|
<li>format.extent</li>
|
|
|
|
<li>format.mimetype</li>
|
|
|
|
<li>identifier.uri</li>
|
|
</ul>
|
|
|
|
<p>In order to avoid duplication of this metadata, run</p>
|
|
|
|
<p><code>dspace_migrate <exported item directory></code></p>
|
|
|
|
<p>prior to running the item importer. This will remove the above metadata items, except for date.issued - if the item has been published or publicly distributed before and identifier.uri - if it is not the handle, from the <code>dublin_core.xml</code> file and remove all <code>handle</code> files. It will then be safe to run the item exporter. Use</p>
|
|
|
|
<p><code>dspace_migrate --help</code></p>
|
|
|
|
<p>for instructions on use of the script.</p>
|
|
|
|
<h2><a name="registration" id="registration">Registering (Not Importing) Bitstreams</a></h2>
|
|
|
|
<p>Registration is an alternate means of incorporating items, their metadata, and their bitstreams into DSpace by taking advantage of the bitstreams already being in storage accessible to DSpace. An example might be that there is a repository for existing digital assets. Rather than using the normal <a href="functional.html#ingest">interactive ingest process</a> or the <a href="functional.html#importexport">batch import</a> to furnish DSpace the metadata and to upload bitstreams, registration provides DSpace the metadata and the <span style="font-style: italic;">location</span> of the bitstreams. DSpace uses a variation of the import tool to accomplish registration.</p>
|
|
|
|
<h3>Accessible Storage</h3>
|
|
|
|
<p>To register an item its bitstreams must reside on storage accessible to DSpace and therefore referenced by an <span style="font-style: italic;">asset store number</span> in <code>dspace.cfg</code>. The configuration file <code>dspace.cfg</code> establishes one or more asset stores through the use of an integer asset store number. This number relates to a directory in the DSpace host's file system or a set of SRB account parameters. This asset store number is described in <a href="configure.html#dspacecfg">The <code>dspace.cfg</code> Configuration Properties File</a> section and in the <code>dspace.cfg</code> file itself. The asset store number(s) used for registered items should generally not be the value of the <code>assetstore.incoming</code> property since it is unlikely that that you will want to mix the bitstreams of normally ingested and imported items and registered items.</p>
|
|
|
|
<h3>Registering Items Using the Item Importer</h3>
|
|
|
|
<p>DSpace uses the same import tool that is used for batch import except that several variations are employed to support registration. The discussion that follows assumes familiarity with the import tool.</p>
|
|
|
|
<p>The archive format for registration does not include the actual content files (bitstreams) being registered. The format is however a directory full of items to be registered, with a subdirectory per item. Each item directory contains a file for the item's descriptive metadata (<code>dublin_core.xml</code>) and a file listing the item's content files (<code>contents</code>), but not the actual content files themselves.</p>
|
|
|
|
<p>The <code>dublin_core.xml</code> file for item registration is exactly the same as for regular item import.</p>
|
|
|
|
<p>The <code>contents</code> file, like that for regular item import, lists the item's content files, one content file per line, but each line has the one of the following formats:</p>
|
|
<pre>
|
|
-r -s n -f filepath
|
|
-r -s n -f filepath\tbundle:bundlename
|
|
</pre>
|
|
|
|
<P>where</P>
|
|
|
|
<UL>
|
|
<LI><code>-r</code> indicates this is a file to be registered</LI>
|
|
<LI><code>-s n</code> indicates the asset store number (<code>n</code>)</li>
|
|
<li><code>-f filepath</code> indicates the path and name of the content file to be registered (filepath)</li>
|
|
<li><code>\t</code> is a tab character</li>
|
|
<li><code>bundle:bundlename</code> is an optional bundle name</li>
|
|
</ul>
|
|
|
|
<p>The bundle, that is everything after the filepath, is optional and is normally not used.</p>
|
|
|
|
<p>The command line for registration is just like the one for regular import:</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport --add --eperson=joe@user.com --collection=collectionID --source=items_dir --mapfile=mapfile
|
|
</pre>
|
|
|
|
<p>(or by using the short form)</p>
|
|
<pre>
|
|
dsrun org.dspace.app.itemimport.ItemImport -a -e joe@user.com -c collectionID -s items_dir -m mapfile
|
|
</pre>
|
|
|
|
<p>The <code>--workflow</code> and <code>--test</code> flags will function as described in <a href="application.html#importingitems">Importing Items</a>.</p>
|
|
|
|
<p>The <code>--delete</code> flag will function as described in <a href="application.html#importingitems">Importing Items</a> but the registered content files will not be removed from storage. See <a href="#deletingregistereditems">Deleting Registered Items</a>.</p>
|
|
|
|
<p>The <code>--replace</code> flag will function as described in <a href="application.html#importingitems">Importing Items</a> but care should be taken to consider different cases and implications. With old items and new items being registered or ingested normally, there are four combinations or cases to consider. Foremost, an old registered item deleted from DSpace using <code>--replace</code> will not be removed from the storage. See <a href="application.html#deletingregistereditems">Deleting Registered Items</a>. where is resides. A new item added to DSpace using <code>--replace</code> will be ingested normally or will be registered depending on whether or not it is marked in the <code>contents</code> files with the -r.</p>
|
|
|
|
<h3>Internal Identification and Retrieval of Registered Items</h3>
|
|
|
|
<p>Once an item has been registered, superficially it is indistinguishable from items ingested interactively or by batch import. But internally there are some differences:</p>
|
|
|
|
<p>First, the randomly generated internal ID is not used because DSpace does not control the file path and name of the bitstream. Instead, the file path and name are that specified in the <code>contents</code> file.</p>
|
|
|
|
<p>Second, the <code>store_number</code> column of the bitstream database row contains the asset store number specified in the <code>contents</code> file.</p>
|
|
|
|
<p>Third, the <code>internal_id</code> column of the bitstream database row contains a leading flag (<code>-R</code>) followed by the registered file path and name. For example, <code>-Rfilepath</code> where <code>filepath</code> is the file path and name relative to the asset store corresponding to the asset store number. The asset store could be traditional storage in the DSpace server's file system or an SRB account.</p>
|
|
|
|
<p>Fourth, an MD5 checksum is calculated by reading the registered file if it is in local storage. If the registerd file is in remote storage (say, SRB) a checksup is calulated on just the file name! This is an efficiency choice since registering a large number of large files that are in SRB would consume substantial network resources and time. A future option could be to have an SRB proxy process calculate MD5s and store them in SRB's metadata catalog (MCAT) for rapid retrieval. SRB offers such an option but it's not yet in production release.</p>
|
|
|
|
<p>Registered items and their bitstreams can be retrieved transparently just like normally ingested items.</p>
|
|
|
|
<h3>Exporting Registered Items</h3>
|
|
|
|
<p>Registered items may be exported as described in <a href="#exportingitems">Exporting Items</a>. If so, the export directory will contain actual copies of the files being exported but the lines in the contents file will flag the files as registered. This means that if DSpace items are "round tripped" (see Transferring Items Between DSpace Instances) using the exporter and importer, the registered files in the export directory will again registered in DSpace instead of being uploaded and ingested normally.</p>
|
|
|
|
<h3>METS Export of Registered Items</h3>
|
|
|
|
<p>The <a href="#mets">METS Export Tool</a> can also be used but note the cautions described in that section and note that MD5 values for items in remote storage are actually MD5 values on just the file name.</p>
|
|
|
|
<h3><a name="deletingregistereditems" id="deletingregistereditems"></a>Deleting Registered Items</h3>
|
|
|
|
<p>If a registered item is deleted from DSpace, either interactively or by using the <code>--delete</code> or <code>--replace</code> flags described in <a href="application.html#importingitems">Importing Items</a>, the item will disappear from DSpace but it's registered content files will remain in place just as they were prior to registration. Bitstreams not registered but added by DSpace as part of registration, such as <code>license.txt</code> files, will be deleted.</p>
|
|
|
|
<h2><a name="mets" id="mets">METS Tools</a></h2>
|
|
|
|
<p>The experimental (incomplete) METS export tool writes DSpace items to a filesystem with the metadata held in a more standard format based on METS.</p>
|
|
|
|
<h3>The Export Tool</h3>
|
|
|
|
<p>The METS export tool is invoked via the command line like this:</p>
|
|
<pre>
|
|
<em>[dspace]</em>/bin/dsrun org.dspace.app.mets.METSExport --help
|
|
</pre>
|
|
|
|
<p>The tool can export an individual item, the items within a given collection, or everything in the DSpace instance. To export an individual item, use:</p>
|
|
<pre>
|
|
<em>[dspace]</em>/bin/dsrun org.dspace.app.mets.METSExport --item <em>[handle]</em>
|
|
</pre>
|
|
|
|
<p>To export the items in collection <code>hdl:123.456/789</code>, use:</p>
|
|
<pre>
|
|
<em>[dspace]</em>/bin/dsrun org.dspace.app.mets.METSExport --collection hdl:123.456/789
|
|
</pre>
|
|
|
|
<p>To export all the items DSpace, use:</p>
|
|
<pre>
|
|
<em>[dspace]</em>/bin/dsrun org.dspace.app.mets.METSExport --all
|
|
</pre>
|
|
|
|
<p>With any of the above forms, you can specify the base directory into which the items will be exported, using <code>--destination <em>[directory]</em></code>. If this parameter is omitted, the current directory is used.</p>
|
|
|
|
<h3>The AIP Format</h3>
|
|
|
|
<p>Each exported item is written to a separate directory, created under the base directory specified in the command-line arguments, or in the current directory if <code>--destination</code> is omitted. The name of each directory is the Handle, URL-encoded so that the directory name is 'legal'.</p>
|
|
|
|
<p>Within each item directory is a <code>mets.xml</code> file which contains the METS-encoded metadata for the item. Bitstreams in the item are also stored in the directory. Their filenames are their MD5 checksums, firstly for easy integrity checking, and also to avoid any problems with 'special characters' in the filenames that were legal on the original filing system they came from but are illegal in the server filing system. The <code>mets.xml</code> file includes XLink pointers to these bitstream files.</p>
|
|
|
|
<p>An example AIP might look like this:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<code>hdl%3A123456789%2F8/</code>
|
|
|
|
<ul>
|
|
<li><code>mets.xml</code> -- METS metadata</li>
|
|
|
|
<li><code>184BE84F293342</code> -- bitstream</li>
|
|
|
|
<li><code>3F9AD0389CB821</code></li>
|
|
|
|
<li><code>135FB82113C32D</code></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The contents of the METS in the <code>mets.xml</code> file are as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>A <code>dmdSec</code> (descriptive metadata section) containing the item's metadata in <a href="http://www.loc.gov/standards/mods/">Metadata Object Description Schema (MODS)</a> XML. The Dublin Core descriptive metadata is mapped to MODS since there is no official qualified Dublin Core XML schema in existence as of yet, and the Library Application Profile of DC that DSpace uses includes some qualifiers that are not part of the <a href="http://dublincore.org/documents/dcmi-terms/">DCMI Metadata Terms</a>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>An <code>amdSec</code> (administrative metadata section), which contains the a rights metadata element, which in turn contains the base64-encoded deposit license (the license the submitter granted as part of the submission process).</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A <code>fileSec</code> containing a list of the bitstreams in the item. Each bundle constitutes a <code>fileGrp</code>. Each bitstream is represented by a <code>file</code> element, which contains an <code>FLocat</code> element with a simple XLink to the bitstream in the same directory as the <code>mets.xml</code> file. The <code>file</code> attributes consist of most of the basic technical metadata for the bitstream. Additionally, for those bitstreams that are thumbnails or text extracted from another bitstream in the item, those 'derived' bitstreams have the same <code>GROUPID</code> as the bitstream they were derived from, in order that clients understand that there is a relationship.</p>
|
|
|
|
<p>The <code>OWNERID</code> of each <code>file</code> is the <a href="functional.html#bitstream_ids">'persistent' bitstream identifier</a> assigned by the DSpace instance. The <code>ID</code> and <code>GROUPID</code> attributes consist of the item's Handle, together with the bitstream's sequence ID, which underscores used in place of dots and slashes. For example, a bitstream with sequence ID 24, in the item <code>hdl:123.456/789</code> will have the <code>ID</code> <code>123_456_789_24</code>. This is because <code>ID</code> and <code>GROUPID</code> attributes must be of type <code>xsd:id</code>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Limitations</h3>
|
|
|
|
<ul>
|
|
<li>No corresponding import tool yet</li>
|
|
|
|
<li>No <code>structmap</code> section</li>
|
|
|
|
<li>Some technical metadata not written, e.g. the primary bitstream in a bundle, original filenames or descriptions.</li>
|
|
|
|
<li>Only the MIME type is stored, not the (finer grained) bitstream format.</li>
|
|
|
|
<li>Dublin Core to MODS mapping is very simple, probably needs verification</li>
|
|
</ul>
|
|
|
|
<h2><a name="mediafilters" id="mediafilters">MediaFilters: Transforming DSpace Content</a></h2>
|
|
|
|
<p>DSpace can apply filters to content/bitstreams, creating new content. Filters are included that extract text for <strong>full-text searching</strong>, and create <strong>thumbnails</strong> for items that contain images. The media filters are controlled by the <code>MediaFilterManager</code> which traverses the asset store, invoking the <code>MediaFilter</code> subclasses on bitstreams. The MediaFilter plugin config item <code>plugin.named.org.dspace.app.mediafilter.MediaFilter</code> in <code>dspace.cfg</code> contains a list of bitstream format types and the filters that operate on bitstreams of that type. The media filter system is intended to be run from the command line (or regularly as a cron task):</p>
|
|
<pre>
|
|
dspace/bin/filter-media
|
|
</pre>
|
|
|
|
<p>Traverse the asset store, applying media filters to bitstreams, skipping bitstreams that have already been filtered.</p>
|
|
<pre>
|
|
dspace/bin/filter-media -f
|
|
</pre>
|
|
|
|
<p>Apply filters to ALL bitstreams, even if they've already been filtered.</p>
|
|
<pre>
|
|
dspace/bin/filter-media -v
|
|
</pre>
|
|
|
|
<p>Verbose mode - print all extracted text and other filter details to STDOUT.</p>
|
|
<pre>
|
|
dspace/bin/filter-media -n
|
|
</pre>
|
|
|
|
<p>Suppress index creation - by default, a new search index is created for full-text searching. This option suppresses index creation if you intend to run <code>index-all</code> elsewhere.</p>
|
|
|
|
<pre>
|
|
dspace/bin/filter-media -i 123456789/2
|
|
</pre>
|
|
|
|
<p>Restrict processing to the community, collection, or item named by the identifier - by default, all bitstreams of all items in the repository are processed. The identifier must be a handle, not a DB key. This option may be combined with any other option.</p>
|
|
|
|
<pre>
|
|
dspace/bin/filter-media -m 1000
|
|
</pre>
|
|
|
|
<p>Suspend operation after the specified maximum number of items have been processed - by default, no limit exists. This option may be combined with any other option.</p>
|
|
|
|
<p>Adding your own filters is done by creating a sub-class of the <code>MediaFilter</code> class. See the comments in the source file MediaFilter.java for more information. In theory filters could be implemented in any language (C, Perl, etc.) They only need to be invoked by the Java code in the <code>MediaFilter</code> class that you create.</p>
|
|
|
|
<h2><a name="filiator" id="filiator">Sub-Community Management</a></h2>
|
|
|
|
<p>DSpace provides an administrative tool - 'CommunityFiliator' - for managing community sub-structure. Normally this structure seldom changes, but prior to the 1.2 release sub-communities were not supported, so this tool could be used to place existing pre-1.2 communities into a hierarchy. It has two operations, either establishing a community to sub-community relationship, or dis-establishing an existing relationship.</p>
|
|
|
|
<p>The familiar parent/child metaphor can be used to explain how it works. Every community in DSpace can be either a 'parent' community - meaning it has at least one sub-community, or a 'child' community - meaning it is a sub-community of another community, or both or neither. In these terms, an 'orphan' is a community that lacks a parent (although it can be a parent); 'orphans' are referred to as 'top-level' communities in the DSpace user-interface, since there is no parent community 'above' them. The first operation - establishing a parent/child relationship - can take place between any community and an orphan. The second operation - removing a parent/child relationship - will make the child an orphan.</p>
|
|
|
|
<p>Using the dsrun utility in the dspace/bin directory, the establish operation looks like this:</p>
|
|
<pre>
|
|
dsrun org.dspace.administer.CommunityFiliator --set --parent=parentID --child=childID
|
|
</pre>
|
|
|
|
<p>(or using the short form)</p>
|
|
<pre>
|
|
dsrun org.dspace.administer.CommunityFiliator -s -p parentID -c childID
|
|
</pre>
|
|
|
|
<p>where '-s' or '--set' means establish a relationship whereby the community identified by the '-p' parameter becomes the parent of the community identified by the '-c' parameter. Both the 'parentID' and 'childID' values may be handles or database IDs.</p>
|
|
|
|
<p>The reverse operation looks like this:</p>
|
|
<pre>
|
|
dsrun org.dspace.administer.CommunityFiliator --remove --parent=parentID --child=childID
|
|
</pre>
|
|
|
|
<p>(or using the short form)</p>
|
|
<pre>
|
|
dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c childID
|
|
</pre>
|
|
|
|
<p>where '-r' or '--remove' means dis-establish the current relationship in which the community identified by 'parentID' is the parent of the community identified by 'childID'. The outcome will be that the 'childID' community will become an orphan, i.e. a top-level community.</p>
|
|
|
|
<p>If the required constraints of operation are violated, an error message will appear explaining the problem, and no change will be made. An example in a removal operation, where the stated child community does not have the stated parent community as its parent: "Error, child community not a child of parent community".</p>
|
|
|
|
<p>It is possible to effect arbitrary changes to the community hierarchy by chaining the basic operations together. For example, to move a child community from one parent to another, simply perform a 'remove' from its current parent (which will leave it an orphan), followed by a 'set' to its new parent.</p>
|
|
|
|
<p>It is important to understand that when any operation is performed, all the sub-structure of the child community follows it. Thus, if a child has itself children (sub-communities), or collections, they will all move with it to its new 'location' in the community tree.</p>
|
|
<hr>
|
|
|
|
<address>
|
|
Copyright © 2002-2005 MIT and Hewlett Packard
|
|
</address>
|
|
</body>
|
|
</html>
|