hazza/DSpace
1
0
Fork 0
mirror of https://github.com/DSpace/DSpace.git synced 2025-10-15 22:13:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

An initial conversion of the html documents to docbook, the script

Browse Source 
to do that conversion, and the resulting html and pdf documents.
All of the work is done in subdirectories.
This is for review, comment, and adjustment.  Still to be done:
- Integrate the docbook to html and pdf into the Maven build.
- Merge changes from the Foundation version of docs into HTML.
- Remove the legacy HTML source.
- Remove the generated html and pdf once the build does it.
- Various small formatting cleanups.


git-svn-id: http://scm.dspace.org/svn/repo/branches/dspace-1_5_x@3042 9c30dcfa-912a-0410-8fc2-9e0234be79fd
This commit is contained in:
Brad McLean
2008-08-12 12:39:05 +00:00
parent 4f2868a901
commit 2e853aee50
40 changed files with 22866 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
dspace/docs/convert2DB.sh Executable file
View File

@@ -0,0 +1,250 @@
#! /bin/bash
# August 2008, Bradley McLean. No rights reserved. Do what you will.
#
# Developed On Ubuntu Hardy Heron, you'll need at least:
# apt-get install herold docbook-utils docbook2x xsltproc docbook-xsl dbdoclet
DBxml="docbook"
HTMLfinal="html"
PDFfinal="pdf"
# The first part of this script is hypothetically to be used only once, to make
# the initial transformation from html docs to docbook source.
haveDB=`ls $DBxml | wc -w`
if [ $haveDB -lt 1 ]; then
if [ ! -d $DBxml ]; then
mkdir $DBxml
fi
cp *.html $DBxml
cd $DBxml
# A couple quick cleanups needed
sed -ie "762s/it>/i>/g" configure.html
sed -ie "2903,2905s/gt; . \&l/gt; ... \&l/" DRISchemaReference.html
# sed -ie "/<div class=\"element-type\">/,/<\/div>/d" DRISchemaReference.html
sed -ie "s/href=\"#type/name=\"#type/g" DRISchemaReference.html
sed -ie "s/href=\"#Meta/name=\"#Meta/g" DRISchemaReference.html
sed -ie "s/href=\"#newfilter/name=\"#newfilter/g" configure.html
sed -ie "s/href=\"#browse/name=\"#browse/g" configure.html
sed -ie "s/href=\"#element/name=\"#element/g" DRISchemaReference.html
sed -ie "s/href=\"#stepDefinitions/name=\"#stepDefinitions/g" submission.html
sed -ie "s/href=\"#authenticate/name=\"#authenticate/g" configure.html
sed -ie "s/300px/175px/g" configure.html
sed -ie "/Back to contents/d" *html
sed -ie "/\&copy/d" *html
sed -ie "s/\&nbsp;/ /g" *html
sed -ie "11,63d" configure.html
sed -ie "44,56d" DRISchemaReference.html
sed -ie "2,34d" DRISchemaReference.html
sed -ie "11,28d" install.html
sed -ie "20,28d" submission.html
filelist=`ls *html`
cd ..
title="DSpace 1.5.1 Manual"
# The initial raw conversion:
for file in $filelist; do
herold --no-prolog --destination-encoding=UTF-8 \
-t "$title" -i $DBxml/$file -o $DBxml/${file/.html/.xml}
done
rm $DBxml/*html $DBxml/*htmle
for file in `ls $DBxml`; do
# Move the fixed section types into generic hierachies, built into chapters, and loose the article wrappers to form subset files.
sed -i -e "s/sect1>/chapter>/" -e "s/<sect1 /<chapter /" $DBxml/$file
sed -i -e "2,4d" -e "s,</article>,," $DBxml/$file
sed -i -e "s/sect[2-9]>/section>/g" -e "s/<sect[2-9] /<section /" $DBxml/$file
# Tell the images to scale to fit
sed -ie "s/\<imagedata.*format=...../& width=\"6.5in\" scalefit=\"1\"/g" $DBxml/$file
sed -ie "s,docbook/image,image,g" $DBxml/$file
# Forcibly clean up any literal blocks (screen elements) that don't line wrap narrowly enough for a print formatted manual.
mv $DBxml/$file $DBxml/$file.prewrap
./wrapscreen.py $DBxml/$file.prewrap $DBxml/$file
rm $DBxml/$file.prewrap
done
# ln -s ../image $DBxml/image
# Generate the Book Wrapper
cat <<EOF >$DBxml/book.xml
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY art01 SYSTEM "index.xml">
<!ENTITY art02 SYSTEM "introduction.xml">
<!ENTITY art03 SYSTEM "install.xml">
<!ENTITY art04 SYSTEM "update.xml">
<!ENTITY art05 SYSTEM "configure.xml">
<!ENTITY art06 SYSTEM "storage.xml">
<!ENTITY art07 SYSTEM "directories.xml">
<!ENTITY art08 SYSTEM "architecture.xml">
<!ENTITY art09 SYSTEM "application.xml">
<!ENTITY art10 SYSTEM "business.xml">
<!ENTITY art11 SYSTEM "functional.xml">
<!ENTITY art12 SYSTEM "submission.xml">
<!ENTITY art13 SYSTEM "DRISchemaReference.xml">
<!ENTITY art14 SYSTEM "history.xml">
<!ENTITY art15 SYSTEM "appendix.xml">
]>
<book>
<bookinfo>
<title>DSpace 1.5.1 Manual</title>
<author>
<surname>The DSpace Foundation</surname>
<affiliation>
<address><email>webmaster@dspace.org</email></address>
</affiliation>
</author>
<copyright>
<year>2002-2008</year>
<holder>
<ulink url="http://www.dspace.org/">The DSpace Foundation</ulink>
</holder>
</copyright>
<legalnotice>
<para>
<ulink url="http://creativecommons.org/licenses/by/3.0/us/">
<inlinemediaobject>
<imageobject>
<imagedata fileref="http://i.creativecommons.org/l/by/3.0/us/88x31.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
Licensed under a Creative Commons Attribution 3.0 United States License
</ulink>
</para>
</legalnotice>
<abstract>
<para></para>
</abstract>
</bookinfo>
<preface>
<title>Preface</title>
<para></para>
</preface>
<toc/>
<!-- &art01; -->
&art02;
&art03;
&art04;
&art05;
&art06;
&art07;
&art08;
&art09;
&art10;
&art11;
&art12;
&art13;
&art14;
&art15;
<index/>
</book>
EOF
# Generate an XSL customization wrapper for print
cat <<EOF >$DBxml/print.xsl
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
<xsl:template match="lineannotation">
<fo:inline font-style="italic">
<xsl:call-template name="inline.charseq"/>
</fo:inline>
</xsl:template>
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="wrap-option">wrap</xsl:attribute>
<xsl:attribute name="hyphenation-character">\</xsl:attribute>
</xsl:attribute-set>
</xsl:stylesheet>
EOF
# Generate an XSL customization wrapper for HTML
cat <<EOF >$DBxml/html.xsl
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
<!-- <xsl:param name="html.stylesheet" select="'corpstyle.css'"/>
<xsl:param name="admon.graphics" select="1"/> -->
<!-- footer xsl stuff?
(could use user.footer.navigational too)
-->
<xsl:template name="user.footer.content">
<HR/>
<xsl:apply-templates select="//copyright[1]" mode="titlepage.mode"/>
<xsl:apply-templates select="//legalnotice[1]" mode="titlepage.mode"/>
</xsl:template>
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="wrap-option">wrap</xsl:attribute>
<xsl:attribute name="hyphenation-character">\</xsl:attribute>
</xsl:attribute-set>
</xsl:stylesheet>
EOF
fi
########################################################################
# The rest of this script contains processing to create two .pdfs using
# two different techniques, and regenerate HTML from the docbook.
# All of this should eventually get replaced with something that can be
# driven from our Maven builds, ideally in a pure java space to reduce
# the number of moving parts and dependencies.
#
# Part of this has already been done below; the DSSL stuff is no longer
# used, and all of the processing is done with Fop (and Xalan under the
# hood). The Maven linkage still needs to be done.
if [ ! -d $PDFfinal ]; then
mkdir $PDFfinal
fi
# PDF it using DSSL - this can probably never be java-itized, and should
# be considered a legacy technique. Hopefully nobody develops a preference
# for its appearance ;-)
# docbook2pdf $DBxml/book.xml
# mv book.pdf $PDFfinal/book-dssl.pdf
xslprint="$DBxml/print.xsl"
xslhtml="$DBxml/html.xsl"
# Some XSL appearance tweaks for our document.
XSLTP=" -param body.start.indent 0pt \
-param section.autolabel 1 \
-param section.autolabel.max.depth 2 \
-param section.label.includes.component.label 1 \
-param chunk.section.depth 0 \
-param variablelist.as.blocks 1"
# PDF it using XSL, note that fop is actually java hiding under a script
if [ "a$FOP_HOME" == "a" ]; then
FOP_HOME=/usr/local/share/fop-0.94
fi
java -Xmx128m -Dfop.home=$FOP_HOME -jar $FOP_HOME/build/fop.jar -xml $DBxml/book.xml -xsl $xslprint -pdf $PDFfinal/book-foppure.pdf $XSLTP
# HTML it using XSL
if [ ! -d $HTMLfinal ]; then
mkdir $HTMLfinal
fi
rm $HTMLfinal/*html
# Lie to Fop, and tell it we're generating an fo (which will be empty with these stylesheets).
# This saves figuring out a separate set of dependencies, classpath and command line for the underlying Xalan.
java -Xmx64m -Dfop.home=$FOP_HOME -jar /usr/local/share/fop-0.94/build/fop.jar -xml $DBxml/book.xml -xsl $xslhtml -foout fo.fo $XSLTP
rm fo.fo
mv $DBxml/*html $HTMLfinal

3322
dspace/docs/docbook/DRISchemaReference.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1686
dspace/docs/docbook/appendix.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1125
dspace/docs/docbook/application.xml Normal file
View File

File diff suppressed because it is too large Load Diff

209
dspace/docs/docbook/architecture.xml Normal file
View File

@@ -0,0 +1,209 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Architecture</title>
<section remap="h2">
<title><anchor id="docbook-architecture.html-overview" xreflabel="Overview"/>Overview</title>
<para>The DSpace system is organized into three layers, each of which consists of a number of components.</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image/architecture-600x450.gif" format="GIF" width="6.5in" scalefit="1"/>
</imageobject>
</inlinemediaobject>
</para>
<para>DSpace System Architecture</para>
<para>The storage layer is responsible for physical storage of metadata and content. The business logic layer deals with managing the content of the archive, users of the archive (e-people), authorization, and workflow. The application layer contains components that communicate with the world outside of the individual DSpace installation, for example the Web user interface and the <ulink url="http://www.openarchives.org/">Open Archives Initiative</ulink> protocol for metadata harvesting service.</para>
<para>Each layer only invokes the layer below it; the application layer may not used the storage layer directly, for example. Each component in the storage and business logic layers has a defined public API. The union of the APIs of those components are referred to as the Storage API (in the case of the storage layer) and the DSpace Public API (in the case of the business logic layer). These APIs are in-process Java classes, objects and methods.</para>
<para>It is important to note that each layer is <emphasis>trusted</emphasis>. Although the logic for <emphasis>authorising actions</emphasis> is in the business logic layer, the system relies on individual applications in the application layer to correctly and securely <emphasis>authenticate</emphasis> e-people. If a &apos;hostile&apos; or insecure application were allowed to invoke the Public API directly, it could very easily perform actions as any e-person in the system.</para>
<para>The reason for this design choice is that authentication methods will vary widely between different applications, so it makes sense to leave the logic and responsibility for that in these applications.</para>
<para>The source code is organized to cohere very strictly to this three-layer architecture. Also, only methods in a component&apos;s public API are given the <literal>public</literal> access level. This means that the Java compiler helps ensure that the source code conforms to the architecture.</para>
<table frame="none">
<title>Source Code Packages</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold">Packages within</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Correspond to components in</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>org.dspace.app</literal>
</para>
</entry>
<entry>
<para>Application layer</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>org.dspace</literal>
</para>
</entry>
<entry>
<para>Business logic layer (except <literal>storage</literal> and <literal>app</literal>)</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>org.dspace.storage</literal>
</para>
</entry>
<entry>
<para>Storage layer</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>The storage and business logic layer APIs are extensively documented with Javadoc-style comments. Generate the HTML version of these by entering the source directory and running:</para>
<screen>
ant public_api
</screen>
<para>The package-level documentation of each package usually contains an overview of the package and some example usage. This information is not repeated in this architecture document; this and the Javadoc APIs are intended to be used in parallel.</para>
<para>Each layer is described in a separate section:</para>
<itemizedlist>
<listitem>
<para>
<ulink url="storage.html">Storage Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="storage.html#rdbms">RDBMS</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="storage.html#bitstreams">Bitstream Store</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html">Business Logic Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="business.html#core">Core Classes</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#content">Content Management API</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#workflow">Workflow System</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#administer">Administration Toolkit</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#eperson">E-person/Group Manager</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#authorize">Authorisation</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#handle">Handle Manager/Handle Plugin</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#search">Search</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#browse">Browse API</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#history">History Recorder</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#checker">Checksum Checker</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html">Application Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="application.html#webui">Web User Interface</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#oai">OAI-PMH Data Provider</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#itemimporter">Item Importer and Exporter</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#transferitem">Transferring Items Between DSpace Instances</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#registration">Registration</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#mets">METS Tools</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#mediafilters">Media Filters</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#filiator">Sub-Community Management</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<para> 2002-2008 The DSpace Foundation </para>
</section>
</chapter>

79
dspace/docs/docbook/book.xml Normal file
View File

@@ -0,0 +1,79 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY art01 SYSTEM "index.xml">
<!ENTITY art02 SYSTEM "introduction.xml">
<!ENTITY art03 SYSTEM "install.xml">
<!ENTITY art04 SYSTEM "update.xml">
<!ENTITY art05 SYSTEM "configure.xml">
<!ENTITY art06 SYSTEM "storage.xml">
<!ENTITY art07 SYSTEM "directories.xml">
<!ENTITY art08 SYSTEM "architecture.xml">
<!ENTITY art09 SYSTEM "application.xml">
<!ENTITY art10 SYSTEM "business.xml">
<!ENTITY art11 SYSTEM "functional.xml">
<!ENTITY art12 SYSTEM "submission.xml">
<!ENTITY art13 SYSTEM "DRISchemaReference.xml">
<!ENTITY art14 SYSTEM "history.xml">
<!ENTITY art15 SYSTEM "appendix.xml">
]>
<book>
<bookinfo>
<title>DSpace 1.5.1 Manual</title>
<author>
<surname>The DSpace Foundation</surname>
<affiliation>
<address><email>webmaster@dspace.org</email></address>
</affiliation>
</author>
<copyright>
<year>2002-2008</year>
<holder>
<ulink url="http://www.dspace.org/">The DSpace Foundation</ulink>
</holder>
</copyright>
<legalnotice>
<para>
<ulink url="http://creativecommons.org/licenses/by/3.0/us/">
<inlinemediaobject>
<imageobject>
<imagedata fileref="http://i.creativecommons.org/l/by/3.0/us/88x31.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
Licensed under a Creative Commons Attribution 3.0 United States License
</ulink>
</para>
</legalnotice>
<abstract>
<para></para>
</abstract>
</bookinfo>
<preface>
<title>Preface</title>
<para></para>
</preface>
<toc/>
<!-- &art01; -->
&art02;
&art03;
&art04;
&art05;
&art06;
&art07;
&art08;
&art09;
&art10;
&art11;
&art12;
&art13;
&art14;
&art15;
<index/>
</book>

1461
dspace/docs/docbook/business.xml Normal file
View File

File diff suppressed because it is too large Load Diff

2497
dspace/docs/docbook/configure.xml Normal file
View File

File diff suppressed because it is too large Load Diff

430
dspace/docs/docbook/directories.xml Normal file
View File

@@ -0,0 +1,430 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Directories and Files</title>
<section remap="h2">
<title><anchor id="docbook-directories.html-overview" xreflabel="Overview"/>Overview</title>
<para>A complete DSpace installation consists of three separate directory trees:</para>
<variablelist>
<varlistentry>
<term>The source directory:</term>
<listitem>
<para> This is where (surprise!) the source code lives. Note that the config files here are used only during the initial install process. After the install, config files should be changed in the install directory. It is referred to in this document as <literal>[dspace-source]</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The install directory:</term>
<listitem>
<para> This directory is populated during the install process and also by DSpace as it runs. It contains config files, command-line tools (and the libraries necessary to run them), and usually--although not necessarily--the contents of the DSpace archive (depending on how DSpace is configured). After the initial build and install, changes to config files should be made in this directory. It is referred to in this document as <literal>[dspace]</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>The web deployment directory:</term>
<listitem>
<para> This directory is generated by the web server the first time it finds a dspace.war file in its webapps directory. It contains the unpacked contents of dspace.war, i.e. the JSPs and java classes and libraries necessary to run DSpace. Files in this directory should never be edited directly; if you wish to modify your DSpace installation, you should edit files in the source directory and then rebuild. The contents of this directory aren&apos;t listed here since its creation is completely automatic. It is usually referred to in this document as <literal>[tomcat]/webapps/dspace</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section remap="h2">
<title><anchor id="docbook-directories.html-sourcedir" xreflabel="Source Directory Layout"/>Source Directory Layout</title>
<itemizedlist>
<listitem>
<para>
<literal>[dspace-source]</literal>
<itemizedlist>
<listitem>
<para><literal>dspace/</literal> - Directory which contains all build and configuration information for DSpace </para>
<itemizedlist>
<listitem>
<para><literal>build.xml</literal> - The Build file for Ant -- used to preform a fresh_install, upgrade, or deploy new changes.</para>
</listitem>
<listitem>
<para><literal>CHANGES</literal> - Detailed list of code changes between versions.</para>
</listitem>
<listitem>
<para><literal>KNOWN_BUGS</literal> - Known bugs in the current version.</para>
</listitem>
<listitem>
<para><literal>LICENSE</literal> - DSpace source code license.</para>
</listitem>
<listitem>
<para><literal>README</literal> - Obligatory basic information file.</para>
</listitem>
<listitem>
<para><literal>bin/</literal> - Some shell and Perl scripts for running DSpace command-line tasks.</para>
</listitem>
<listitem>
<para><literal>config/</literal> - Configuration files: </para>
<itemizedlist>
<listitem>
<para><literal>controlled-vocabularies/</literal> - Fixed, limited vocabularies used in metadata entry</para>
</listitem>
<listitem>
<para><literal>crosswalks/</literal> - Metadata crosswalks - property files or XSL stylesheets</para>
</listitem>
<listitem>
<para><literal>dspace.cfg</literal> - The Main DSpace configuration file (You will need to edit this).</para>
</listitem>
<listitem>
<para><literal>dc2mods.cfg</literal> - Mappings from Dublin Core metadata to <ulink url="http://www.loc.gov/standards/mods/">MODS</ulink> for the METS export.</para>
</listitem>
<listitem>
<para><literal>default.license</literal> - The default license that users must grant when submitting items.</para>
</listitem>
<listitem>
<para><literal>dstat.cfg</literal> , <literal>dstat.map</literal> - Configuration for statistical reports.</para>
</listitem>
<listitem>
<para><literal>input-forms.xml</literal> - Submission UI metadata field configuration.</para>
</listitem>
<listitem>
<para><literal>news-side.html</literal> - Text of the front-page news in the sidebar, only used in JSPUI.</para>
</listitem>
<listitem>
<para><literal>news-top.html</literal> - Text of the front-page news in the top box, only used in teh JSPUI.</para>
</listitem>
<listitem>
<para><literal>emails/</literal> - Text and layout templates for emails sent out by the system.</para>
</listitem>
<listitem>
<para><literal>language-packs/</literal> - Contains &quot;dictionary files&quot; -- Java properties files that contain user interface text in different languages</para>
</listitem>
<listitem>
<para><literal>registries/</literal> - <emphasis role="bold">Initial</emphasis> contents of the bitstream format registry and Dublin Core element/qualifier registry. These are only used on initial system setup, after which they are maintained in the database.</para>
</listitem>
<listitem>
<para><literal>templates/</literal> - Configuration files for libraries and external applications (e.g. Apache, Tomcat) are kept and edited here. They can refer to properties in the main DSpace configuration - have a look at a couple. When they&apos;re updated, a command line tool fills out these files with appropriate values from dspace.cfg, and copies them to their appropriate location (hence &quot;templates&quot;.)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>docs/</literal> - DSpace system documentation. The technical documentation for functionality, installation, configuration, etc.</para>
</listitem>
<listitem>
<para><literal>etc/</literal> - Miscelleanous configuration need to install DSpace that isn&apos;t really to do with system configuration - e.g. the PostgreSQL database schema, and a couple of configuration files that are used during the build process but not by the live system. Also contains the deployment descriptors (<literal>web.xml</literal> files) for the Web UI and OAI-PMH support <literal>.war</literal> files. </para>
<itemizedlist>
<listitem>
<para><literal>oracle/</literal> - Versions of the database schema and updater SQL scripts for Oracle.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>modules/</literal> - The Web UI modules &quot;overlay&quot; directory. DSpace uses Maven to automatically look here for any customizations you wish to make to DSpace Web interfaces. </para>
<itemizedlist>
<listitem>
<para><literal>jspui</literal> - Contains all customizations for the JSP User Interface. </para>
<itemizedlist>
<listitem>
<para><literal>src/main/resources/</literal> - The overlay for JSPUI Resources. This is the location to place any custom Messages.properties files.</para>
</listitem>
<listitem>
<para><literal>src/main/webapp/</literal> - The overlay for JSPUI Web Application. This is the location to place any custom JSPs to be used by DSpace.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>lni</literal> - Contains all customizations for the Lightweight Network Interface.</para>
</listitem>
<listitem>
<para><literal>oai</literal> - Contains all customizations for the OAI-PMH Interface.</para>
</listitem>
<listitem>
<para><literal>sword</literal> - Contains all customizations for the SWORD (Simple Web-service Offering Repository Deposit) Interface.</para>
</listitem>
<listitem>
<para><literal>xmlui</literal> - Contains all customizations for the XML User Interface (aka Manakin). </para>
<itemizedlist>
<listitem>
<para><literal>src/main/webapp/</literal> - The overlay for XMLUI Web Application. This is the location to place custom Themes or Configurations. </para>
<itemizedlist>
<listitem>
<para><literal>i18n/</literal> - The location to place a custom version of the XMLUI&apos;s messages.xml</para>
</listitem>
<listitem>
<para><literal>themes/</literal> - The location to place custom Themes for the XMLUI</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>src/</literal> - Maven configurations for DSpace System. This directory contains the Maven and Ant build files for DSpace.</para>
</listitem>
<listitem>
<para><literal>target/</literal> - (Only exists after building DSpace) This is the location Maven uses to build your DSpace installation package. </para>
<itemizedlist>
<listitem>
<para><literal>dspace-[version].dir</literal> - The location of the DSpace Installation Package (which can then be installed by running <literal>ant update</literal>)</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-directories.html-installdir" xreflabel="Installed Directory Layout"/>Installed Directory Layout</title>
<para>Below is the basic layout of a DSpace installation using the default configuration. These paths can be configured if necessary.</para>
<itemizedlist>
<listitem>
<para>
<literal>[dspace]</literal>
<itemizedlist>
<listitem>
<para><literal>assetstore/</literal> - asset store files</para>
</listitem>
<listitem>
<para><literal>bin/</literal> - shell and Perl scripts</para>
</listitem>
<listitem>
<para><literal>config/</literal> - configuration, with sub-directories as above</para>
</listitem>
<listitem>
<para><literal>handle-server/</literal> - Handles server files</para>
</listitem>
<listitem>
<para><literal>history/</literal> - stored history files (generally RDF/XML)</para>
</listitem>
<listitem>
<para><literal>lib/</literal> - JARs, including dspace.jar, containing the DSpace classes</para>
</listitem>
<listitem>
<para><literal>log/</literal> - Log files</para>
</listitem>
<listitem>
<para><literal>reports/</literal> - Reports generated by statistical report generator</para>
</listitem>
<listitem>
<para><literal>search/</literal> - Lucene search index files</para>
</listitem>
<listitem>
<para><literal>upload/</literal> - temporary directory used during file uploads etc.</para>
</listitem>
<listitem>
<para><literal>webapps/</literal> - location where DSpace installs all Web Applications</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-directories.html-webapp" xreflabel="Contents of JSPUI Web Application"/>Contents of JSPUI Web Application</title>
<para>DSpace&apos;s Ant build file creates a <literal>dspace-jspui-webapp/</literal> directory with the following structure:</para>
<itemizedlist>
<listitem>
<para> (top level dir) </para>
<itemizedlist>
<listitem>
<para> The JSPs</para>
</listitem>
<listitem>
<para>
<literal>WEB-INF/</literal>
<itemizedlist>
<listitem>
<para><literal>web.xml</literal> - DSpace JSPUI Web Application configuration and Servlet mappings</para>
</listitem>
<listitem>
<para><literal>dspace-tags.tld</literal> - DSpace custom tag descriptor</para>
</listitem>
<listitem>
<para><literal>fmt.tld</literal> - JSTL message format tag descriptor, for internationalization</para>
</listitem>
<listitem>
<para><literal>lib/</literal> - All the third-party JARs and pre-compiled DSpace API JARs needed to run JSPUI</para>
</listitem>
<listitem>
<para><literal>classes/</literal> - Any additional necessary class files</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-directories.html-webapp.1" xreflabel="Contents of XMLUI Web Application (aka
Manakin)"/>Contents of XMLUI Web Application (aka Manakin)</title>
<para>DSpace&apos;s Ant build file creates a <literal>dspace-xmlui-webapp/</literal> directory with the following structure:</para>
<itemizedlist>
<listitem>
<para> (top level dir) </para>
<itemizedlist>
<listitem>
<para><literal>aspects/</literal> - Contains overarching Aspect Generator config and Prototype DRI (Digital Repository Interface) document for Manakin.</para>
</listitem>
<listitem>
<para><literal>i18n/</literal> - Internationalization / Multilingual support. Contains the <literal>messages.xml</literal> English language pack by default.</para>
</listitem>
<listitem>
<para><literal>themes/</literal> - Contains all out-of-the-box Manakin themes </para>
<itemizedlist>
<listitem>
<para><literal>Classic/</literal> - The classic theme, which makes the XMLUI look like classic DSpace</para>
</listitem>
<listitem>
<para><literal>dri2xhtml/</literal> - The base theme, which converts XMLUI DRI (Digital Repository Interface) format into XHTML for display</para>
</listitem>
<listitem>
<para><literal>Reference/</literal> - The default reference theme for XMLUI</para>
</listitem>
<listitem>
<para><literal>template/</literal> - A theme template...useful as a starting point for your own custom theme(s)</para>
</listitem>
<listitem>
<para><literal>dri2xhtml.xsl</literal> - The DRI-to-XHTML XSL Stylesheet. Uses the above &apos;dri2xhtml&apos; theme to generate XHTML</para>
</listitem>
<listitem>
<para><literal>themes.xmap</literal> - The Theme configuration file. It determines which theme(s) are used by XMLUI</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<literal>WEB-INF/</literal>
<itemizedlist>
<listitem>
<para><literal>lib/</literal> - All the third-party JARs and pre-compiled DSpace JARs needed to run XMLUI</para>
</listitem>
<listitem>
<para><literal>classes/</literal> - Any additional necessary class files</para>
</listitem>
<listitem>
<para><literal>cocoon.xconf</literal> - XMLUI&apos;s Apache Cocoon configuration</para>
</listitem>
<listitem>
<para><literal>logkit.xconf</literal> - XMLUI&apos;s Apache Cocoon Logging configuration</para>
</listitem>
<listitem>
<para><literal>web.xml</literal> - XMLUI Web Application configuration and Servlet mappings</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-directories.html-logfiles" xreflabel="Log Files"/>Log Files</title>
<para>The first source of potential confusion is the log files. Since DSpace uses a number of third-party tools, problems can occur in a variety of places. Below is a table listing the main log files used in a typical DSpace setup. The locations given are defaults, and might be different for your system depending on where you installed DSpace and the third-party tools. The ordering of the list is roughly the recommended order for searching them for the details about a particular problem or error.</para>
<table frame="none">
<title>DSpace Log File Locations</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold">Log File</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">What&apos;s In It</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[dspace]/log/dspace.log</literal>
</para>
</entry>
<entry>
<para>Main DSpace log file. This is where the DSpace code writes a simple log of events and errors that occur within the DSpace code. You can control the verbosity of this by editing the <literal>[dspace]/config/templates/log4j.properties</literal> file and then running <literal>[dspace]/bin/install-configs</literal>.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[tomcat]/logs/catalina.out</literal>
</para>
</entry>
<entry>
<para>This is where Tomcat&apos;s standard output is written. Many errors that occur within the Tomcat code are logged here. For example, if Tomcat can&apos;t find the DSpace code (<literal>dspace.jar</literal>), it would be logged in <literal>catalina.out</literal>.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[tomcat]/logs/hostname_log.yyyy-mm-dd.txt</literal>
</para>
</entry>
<entry>
<para>If you&apos;re running Tomcat stand-alone (without Apache), it logs some information and errors for specific Web applications to this log file. <literal>hostname</literal> will be your host name (e.g. <literal>dspace.myu.edu</literal>) and <literal>yyyy-mm-dd</literal> will be the date.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[tomcat]/logs/apache_log.yyyy-mm-dd.txt</literal>
</para>
</entry>
<entry>
<para>If you&apos;re using Apache, Tomcat logs information about Web applications running through Apache (<literal>mod_webapp</literal>) in this log file (<literal>yyyy-mm-dd</literal> being the date.)</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[apache]/error_log</literal>
</para>
</entry>
<entry>
<para>Apache logs to this file. If there is a problem with getting <literal>mod_webapp</literal> working, this is a good place to look for clues. Apache also writes to several other log files, though <literal>error_log</literal> tends to contain the most useful information for tracking down problems.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[dspace]/log/handle-plug.log</literal>
</para>
</entry>
<entry>
<para>The Handle server runs as a separate process from the DSpace Web UI (which runs under Tomcat&apos;s JVM). Due to a limitation of log4j&apos;s &apos;rolling file appenders&apos;, the DSpace code running in the Handle server&apos;s JVM must use a separate log file. The DSpace code that is run as part of a Handle resolution request writes log information to this file. You can control the verbosity of this by editing <literal>[dspace]/config/templates/log4j-handle-plugin.properties</literal>.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[dspace]/log/handle-server.log</literal>
</para>
</entry>
<entry>
<para>This is the log file for CNRI&apos;s Handle server code. If a problem occurs within the Handle server code, before DSpace&apos;s plug-in is invoked, this is where it may be logged.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>[dspace]/handle-server/error.log</literal>
</para>
</entry>
<entry>
<para>On the other hand, a problem with CNRI&apos;s Handle server code might be logged here.</para>
</entry>
</row>
<row>
<entry>
<para>PostgreSQL log</para>
</entry>
<entry>
<para>PostgreSQL also writes a log file. This one doesn&apos;t seem to have a default location, you probably had to specify it yourself at some point during installation. In general, this log file rarely contains pertinent information--PostgreSQL is pretty stable, you&apos;re more likely to encounter problems with connecting via JDBC, and these problems will be logged in <literal>dspace.log</literal>.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</chapter>

702
dspace/docs/docbook/functional.xml Normal file
View File

@@ -0,0 +1,702 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Functional Overview</title>
<para>The following sections describe the various functional aspects of the DSpace system.</para>
<section remap="h2">
<title><anchor id="docbook-functional.html-data_model" xreflabel="Data Model"/>Data Model</title>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image/data-model.gif" format="GIF" width="6.5in" scalefit="1"/>
</imageobject>
</inlinemediaobject>
</para>
<para>Data Model Diagram</para>
<para>The way data is organized in DSpace is intended to reflect the structure of the organization using the DSpace system. Each DSpace site is divided into <emphasis>communities</emphasis>, which can be further divided into <emphasis>sub-communities</emphasis> reflecting the typical university structure of college, departement, research center, or laboratory.</para>
<para>Communities contain <emphasis>collections</emphasis>, which are groupings of related content. A collection may appear in more than one community.</para>
<para>Each collection is composed of <emphasis>items</emphasis>, which are the basic archival elements of the archive. Each item is owned by one collection. Additionally, an item may appear in additional collections; however every item has one and only one owning collection.</para>
<para>Items are further subdivided into named <emphasis>bundles</emphasis> of <emphasis>bitstreams</emphasis>. Bitstreams are, as the name suggests, streams of bits, usually ordinary computer files. Bitstreams that are somehow closely related, for example HTML files and images that compose a single HTML document, are organised into bundles.</para>
<para>In practice, most items tend to have these named bundles:</para>
<itemizedlist>
<listitem>
<para><emphasis>ORIGINAL</emphasis> -- the bundle with the original, deposited bitstreams</para>
</listitem>
<listitem>
<para><emphasis>THUMBNAILS</emphasis> -- thumbnails of any image bitstreams</para>
</listitem>
<listitem>
<para><emphasis>TEXT</emphasis> -- extracted full-text from bitstreams in ORIGINAL, for indexing</para>
</listitem>
<listitem>
<para><emphasis>LICENSE</emphasis> -- contains the deposit license that the submitter granted the host organization; in other words, specifies the rights that the hosting organization have</para>
</listitem>
<listitem>
<para><emphasis>CC_LICENSE</emphasis> -- contains the distribution license, if any (a <ulink url="http://www.creativecommons.org">Creative Commons</ulink> license) associated with the item. This license specifies what end users downloading the content can do with the content</para>
</listitem>
</itemizedlist>
<para>Each bitstream is associated with one <emphasis>Bitstream Format</emphasis>. Because preservation services may be an important aspect of the DSpace service, it is important to capture the specific formats of files that users submit. In DSpace, a bitstream format is a unique and consistent way to refer to a particular file format. An integral part of a bitstream format is an either implicit or explicit notion of how material in that format can be interpreted. For example, the interpretation for bitstreams encoded in the JPEG standard for still image compression is defined explicitly in the Standard ISO/IEC 10918-1. The interpretation of bitstreams in Microsoft Word 2000 format is defined implicitly, through reference to the Microsoft Word 2000 application. Bitstream formats can be more specific than MIME types or file suffixes. For example, <literal>application/ms-word</literal> and <literal>.doc</literal> span multiple versions of the Microsoft Word application, each of which produces bitstreams with presumably different characteristics.</para>
<para>Each bitstream format additionally has a <emphasis>support level</emphasis>, indicating how well the hosting institution is likely to be able to preserve content in the format in the future. There are three possible support levels that bitstream formats may be assigned by the hosting institution. The host institution should determine the exact meaning of each support level, after careful consideration of costs and requirements. MIT Libraries&apos; interpretation is shown below:</para>
<table frame="none">
<title>MIT Libraries&apos; Definitions of Bitstream Format Support Levels</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold">Supported</emphasis>
</para>
</entry>
<entry>
<para>The format is recognized, and the hosting institution is confident it can make bitstreams of this format useable in the future, using whatever combination of techniques (such as migration, emulation, etc.) is appropriate given the context of need.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">Known</emphasis>
</para>
</entry>
<entry>
<para>The format is recognized, and the hosting institution will promise to preserve the bitstream as-is, and allow it to be retrieved. The hosting institution will attempt to obtain enough information to enable the format to be upgraded to the &apos;supported&apos; level.</para>
</entry>
</row>
<row>
<entry>
<para>
<emphasis role="bold">Unsupported</emphasis>
</para>
</entry>
<entry>
<para>The format is unrecognized, but the hosting institution will undertake to preserve the bitstream as-is and allow it to be retrieved.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Each item has one qualified Dublin Core metadata record. Other metadata might be stored in an item as a serialized bitstream, but we store Dublin Core for every item for interoperability and ease of discovery. The Dublin Core may be entered by end-users as they submit content, or it might be derived from other metadata as part of an ingest process.</para>
<para><anchor id="docbook-functional.html-deletions" xreflabel="Items can be removed from
DSpace in one of two ways:"/>Items can be removed from DSpace in one of two ways: They may be &apos;withdrawn&apos;, which means they remain in the archive but are completely hidden from view. In this case, if an end-user attempts to access the withdrawn item, they are presented with a &apos;tombstone,&apos; that indicates the item has been removed. For whatever reason, an item may also be &apos;expunged&apos; if necessary, in which case all traces of it are removed from the archive.</para>
<table frame="none">
<title>Objects in the DSpace Data Model</title>
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold">Object</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Example</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>Community</para>
</entry>
<entry>
<para>Laboratory of Computer Science; Oceanographic Research Center</para>
</entry>
</row>
<row>
<entry>
<para>Collection</para>
</entry>
<entry>
<para>LCS Technical Reports; ORC Statistical Data Sets</para>
</entry>
</row>
<row>
<entry>
<para>Item</para>
</entry>
<entry>
<para>A technical report; a data set with accompanying description; a video recording of a lecture</para>
</entry>
</row>
<row>
<entry>
<para>Bundle</para>
</entry>
<entry>
<para>A group of HTML and image bitstreams making up an HTML document</para>
</entry>
</row>
<row>
<entry>
<para>Bitstream</para>
</entry>
<entry>
<para>A single HTML file; a single image file; a source code file</para>
</entry>
</row>
<row>
<entry>
<para>Bitstream Format</para>
</entry>
<entry>
<para>Microsoft Word version 6.0; JPEG encoded image format</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-plugin" xreflabel="Plugin Manager"/>Plugin Manager</title>
<para>The PluginManager is a very simple component container. It creates and organizes components (plugins), and helps select a plugin in the cases where there are many possible choices. It also gives some limited control over the lifecycle of a plugin.</para>
<para>A plugin is defined by a Java interface. The consumer of a plugin asks for its plugin by interface. A Plugin is an instance of any class that implements the plugin interface. It is interchangeable with other implementations, so that any of them may be &quot;plugged in&quot;.</para>
<para>The mediafilter is a simple example of a plugin implementation. Refer to the <ulink url="business.html#plugin">Business Logic Layer</ulink> for more details on Plugins.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-metadata" xreflabel="Metadata"/>Metadata</title>
<para>Broadly speaking, DSpace holds three sorts of metadata about archived content:</para>
<variablelist>
<varlistentry>
<term>Descriptive Metadata</term>
<listitem>
<para> DSpace can support multiple flat metadata schemas for describing an item.</para>
<para>A qualified Dublin Core metadata schema loosely based on the <ulink url="http://www.dublincore.org/documents/library-application-profile/">Library Application Profile</ulink> set of elements and qualifiers is provided by default. The <ulink url="http://dspace.org/technology/metadata.html">set of elements and qualifiers used by MIT Libraries</ulink> comes pre-configured with the DSpace source code. However, you can configure multiple schemas and select metadata fields from a mix of configured schemas to describe your items.</para>
<para>Other descriptive metadata about items (e.g. metadata described in a hierarchical schema) may be held in serialized bitstreams. <emphasis>Communities</emphasis> and <emphasis>collections</emphasis> have some simple descriptive metadata (a name, and some descriptive prose), held in the DBMS.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Administrative Metadata</term>
<listitem>
<para> This includes preservation metadata, provenance and authorization policy data. Most of this is held within DSpace&apos;s relation DBMS schema. Provenance metadata (prose) is stored in Dublin Core records. Additionally, some other administrative metadata (for example, bitstream byte sizes and MIME types) is replicated in Dublin Core records so that it is easily accessible outside of DSpace.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Structural Metadata</term>
<listitem>
<para> This includes information about how to present an item, or bitstreams within an item, to an end-user, and the relationships between constituent parts of the item. As an example, consider a thesis consisting of a number of TIFF images, each depicting a single page of the thesis. Structural metadata would include the fact that each image is a single page, and the ordering of the TIFF images/pages. Structural metadata in DSpace is currently fairly basic; within an item, bitstreams can be arranged into separate bundles as <link linkend="docbook-functional.html-data_model">described above</link>. A bundle may also optionally have a <emphasis>primary bitstream</emphasis>. This is currently used by the <link linkend="docbook-functional.html-html">HTML support</link> to indicate which bitstream in the bundle is the first HTML file to send to a browser.</para>
<para>In addition to some basic technical metadata, bitstreams also have a &apos;sequence ID&apos; that uniquely identifies it within an item. This is used to produce a <link linkend="docbook-functional.html-bitstream_ids">&apos;persistent&apos; bitstream identifier</link> for each bitstream.</para>
<para>Additional structural metadata can be stored in serialized bitstreams, but DSpace does not currently understand this natively.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-packager" xreflabel="Packager Plugins"/>Packager Plugins</title>
<para><emphasis>Packagers</emphasis> are software modules that translate between DSpace Item objects and a self-contained external representation, or &quot;package&quot;. A <emphasis>Package Ingester</emphasis> interprets, or <emphasis>ingests</emphasis>, the package and creates an Item. A <emphasis>Package Disseminator</emphasis> writes out the contents of an Item in the package format.</para>
<para>A package is typically an archive file such as a Zip or &quot;tar&quot; file, including a <emphasis>manifest</emphasis> document which contains metadata and a description of the package contents. The <ulink url="http://www.imsglobal.org/content/packaging/">IMS Content Package</ulink> is a typical packaging standard. A package might also be a single document or media file that contains its own metadata, such as a PDF document with embedded descriptive metadata.</para>
<para>Package ingesters and package disseminators are each a type of named plugin (see <link linkend="docbook-functional.html-plugin">Plugin Manager</link>), so it is easy to add new packagers specific to the needs of your site. You do not have to supply both an ingester and disseminator for each format; it is perfectly acceptable to just implement one of them.</para>
<para>Most packager plugins call upon Crosswalk plugins to translate the metadata between DSpace&apos;s object model and the package format.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-crosswalk" xreflabel="Crosswalk Plugins"/>Crosswalk Plugins</title>
<para><emphasis>Crosswalks</emphasis> are software modules that translate between DSpace object metadata and a specific external representation. An <emphasis>Ingestion Crosswalk</emphasis> interprets the external format and crosswalks it to DSpace&apos;s internal data structure, while a <emphasis>Dissemination Crosswalk</emphasis> does the opposite.</para>
<para>For example, a MODS ingestion crosswalk translates descriptive metadata from the MODS format to the metadata fields on a DSpace Item. A MODS dissemination crosswalk generates a MODS document from the metadata on a DSpace Item.</para>
<para>Crosswalk plugins are named plugins see <link linkend="docbook-functional.html-plugin">Plugin Manager</link>), so it is easy to add new crosswalks. You do not have to supply both an ingester and disseminator for each format; it is perfectly acceptable to just implement one of them.</para>
<para>There is also a special pair of crosswalk plugins which use XSL stylesheets to translate the external metadata to or from an internal DSpace format. You can add and modify XSLT crosswalks simply by editing the DSpace configuration and the stylesheets, which are stored in files in the DSpace installation directory.</para>
<para>The <link linkend="docbook-functional.html-packager">Packager plugins</link> and <link linkend="docbook-functional.html-oai">OAH-PMH server</link> make use of crosswalk plugins.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-epeople" xreflabel="E-People and Groups"/>E-People and Groups</title>
<para>Although many of DSpace&apos;s functions such as document discovery and retrieval can be used anonymously, some features (and perhaps some documents) are only available to certain &quot;privileged&quot; users. E-People and Groups are the way DSpace identifies application users for the purpose of granting privileges. This identity is bound to a session of a DSpace application such as the Web UI or one of the command-line batch programs. Both E-People and Groups are granted privileges by the <link linkend="docbook-functional.html-auth">authorization</link> system described below.</para>
<section remap="h3">
<title>E-Person</title>
<para>DSpace hold the following information about each e-person:</para>
<itemizedlist>
<listitem>
<para> E-mail address</para>
</listitem>
<listitem>
<para> First and last names</para>
</listitem>
<listitem>
<para> Whether the user is able to log in to the system via the Web UI, and whether they must use an X509 certificate to do so;</para>
</listitem>
<listitem>
<para> A password (encrypted), if appropriate</para>
</listitem>
<listitem>
<para> A list of collections for which the e-person wishes to be notified of new items</para>
</listitem>
<listitem>
<para> Whether the e-person &apos;self-registered&apos; with the system; that is, whether the system created the e-person record automatically as a result of the end-user independently registering with the system, as opposed to the e-person record being generated from the institution&apos;s personnel database, for example.</para>
</listitem>
<listitem>
<para> The network ID for the corresponding LDAP record</para>
</listitem>
</itemizedlist>
</section>
<section remap="h3">
<title>Groups</title>
<para>Groups are another kind of entity that can be granted permissions in the <link linkend="docbook-functional.html-auth">authorization</link> system. A group is usually an explicit list of E-People; anyone identified as one of those E-People also gains the privileges granted to the group.</para>
<para>However, an application session can be assigned membership in a group <emphasis>without</emphasis> being identified as an E-Person. For example, some sites use this feature to identify users of a local network so they can read restricted materials not open to the whole world. Sessions originating from the local network are given membership in the &quot;LocalUsers&quot; group and gain the corresonding privileges.</para>
<para>Administrators can also use groups as &quot;roles&quot; to manage the granting of privileges more efficiently.</para>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-authentication" xreflabel="Authentication"/>Authentication</title>
<para><emphasis>Authentication</emphasis> is when an application session positively identifies itself as belonging to an E-Person and/or Group. In DSpace 1.4, it is implemented by a mechanism called <emphasis>Stackable Authentication</emphasis>: the DSpace configuration declares a &quot;stack&quot; of authentication methods. An application (like the Web UI) calls on the Authentication Manager, which tries each of these methods in turn to identify the E-Person to which the session belongs, as well as any extra Groups. The E-Person authentication methods are tried in turn until one succeeds. Every authenticator in the stack is given a chance to assign extra Groups. This mechanism offers the following advantages:</para>
<itemizedlist>
<listitem>
<para> Separates authentication from the Web user interface so the same authentication methods are used for other applications such as non-interactive Web Services</para>
</listitem>
<listitem>
<para> Improved modularity: The authentication methods are all independent of each other. Custom authentication methods can be &quot;stacked&quot; on top of the default DSpace username/password method.</para>
</listitem>
<listitem>
<para> Cleaner support for &quot;implicit&quot; authentication where username is found in the environment of a Web request, e.g. in an X.509 client certificate.</para>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-auth" xreflabel="Authorization"/>Authorization</title>
<para>DSpace&apos;s authorization system is based on associating actions with objects and the lists of EPeople who can perform them. The associations are called Resource Policies, and the lists of EPeople are called Groups. There are two special groups: &apos;administrators&apos;, who can do anything in a site, and &apos;anonymous&apos;, which is a list that contains all users. Assigning a policy for an action on an object to anonymous means giving everyone permission to do that action. (For example, most objects in DSpace sites have a policy of &apos;anonymous&apos; READ.) Permissions must be explicit - lack of an explicit permission results in the default policy of &apos;deny&apos;. Permissions also do not &apos;commute&apos;; for example, if an e-person has READ permission on an item, they might not necessarily have READ permission on the bundles and bitstreams in that item. Currently Collections, Communities and Items are discoverable in the browse and search systems regardless of READ authorization.</para>
<para>The following actions are possible:</para>
<para>
<emphasis role="bold">Community</emphasis>
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>ADD/REMOVE</para>
</entry>
<entry>
<para>add or remove collections or sub-communities</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<emphasis role="bold">Collection</emphasis>
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>ADD/REMOVE</para>
</entry>
<entry>
<para>add or remove items (ADD = permission to submit items)</para>
</entry>
</row>
<row>
<entry>
<para>DEFAULT_ITEM_READ</para>
</entry>
<entry>
<para>inherited as READ by all submitted items</para>
</entry>
</row>
<row>
<entry>
<para>DEFAULT_BITSTREAM_READ</para>
</entry>
<entry>
<para>inherited as READ by bitstreams of all submitted items</para>
</entry>
</row>
<row>
<entry>
<para>COLLECTION_ADMIN</para>
</entry>
<entry>
<para>collection admins can edit items in a collection, withdraw items, map other items into this collection.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<emphasis role="bold">Item</emphasis>
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>ADD/REMOVE</para>
</entry>
<entry>
<para>add or remove bundles</para>
</entry>
</row>
<row>
<entry>
<para>READ</para>
</entry>
<entry>
<para>can view item (item metadata is always viewable)</para>
</entry>
</row>
<row>
<entry>
<para>WRITE</para>
</entry>
<entry>
<para>can modify item</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<emphasis role="bold">Bundle</emphasis>
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>ADD/REMOVE</para>
</entry>
<entry>
<para>add or remove bitstreams to a bundle</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<emphasis role="bold">Bitstream</emphasis>
</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>READ</para>
</entry>
<entry>
<para>view bitstream</para>
</entry>
</row>
<row>
<entry>
<para>WRITE</para>
</entry>
<entry>
<para>modify bitstream</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Note that there is no &apos;DELETE&apos; action. In order to &apos;delete&apos; an object (e.g. an item) from the archive, one must have REMOVE permission on all objects (in this case, collection) that contain it. The &apos;orphaned&apos; item is automatically deleted.</para>
<para>Policies can apply to individual e-people or groups of e-people.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-ingest" xreflabel="Ingest Process and
Workflow"/>Ingest Process and Workflow</title>
<para>Rather than being a single subsystem, ingesting is a process that spans several. Below is a simple illustration of the current ingesting process in DSpace.</para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image/ingest.gif" format="GIF" width="6.5in" scalefit="1"/>
</imageobject>
</inlinemediaobject>
</para>
<para>DSpace Ingest Process</para>
<para>The batch item importer is an application, which turns an external SIP (an XML metadata document with some content files) into an &quot;in progress submission&quot; object. The Web submission UI is similarly used by an end-user to assemble an &quot;in progress submission&quot; object.</para>
<para>Depending on the policy of the collection to which the submission in targeted, a workflow process may be started. This typically allows one or more human reviewers or &apos;gatekeepers&apos; to check over the submission and ensure it is suitable for inclusion in the collection.</para>
<para>When the Batch Ingester or Web Submit UI completes the InProgressSubmission object, and invokes the next stage of ingest (be that workflow or item installation), a provenance message is added to the Dublin Core which includes the filenames and checksums of the content of the submission. Likewise, each time a workflow changes state (e.g. a reviewer accepts the submission), a similar provenance statement is added. This allows us to track how the item has changed since a user submitted it. (The <link linkend="docbook-functional.html-history">History system</link> is also invoked, but provenance is easier for us to access at the moment.)</para>
<para>Once any workflow process is successfully and positively completed, the InProgressSubmission object is consumed by an &quot;item installer&quot;, that converts the InProgressSubmission into a fully blown archived item in DSpace. The item installer:</para>
<itemizedlist>
<listitem>
<para> Assigns an accession date</para>
</listitem>
<listitem>
<para> Adds a &quot;date.available&quot; value to the Dublin Core metadata record of the item</para>
</listitem>
<listitem>
<para> Adds an issue date if none already present</para>
</listitem>
<listitem>
<para> Adds a provenance message (including bitstream checksums)</para>
</listitem>
<listitem>
<para> Assigns a <link linkend="docbook-functional.html-handles">Handle</link> persistent identifier</para>
</listitem>
<listitem>
<para> Adds the item to the target collection, and adds appropriate authorization policies</para>
</listitem>
<listitem>
<para> Adds the new item to the search and browse indices</para>
</listitem>
</itemizedlist>
<section remap="h3">
<title>Workflow Steps</title>
<para>A collection&apos;s workflow can have up to three steps. Each collection may have an associated e-person group for performing each step; if no group is associated with a certain step, that step is skipped. If a collection has no e-person groups associated with any step, submissions to that collection are installed straight into the main archive.</para>
<para>In other words, the sequence is this: The collection receives a submission. If the collection has a group assigned for workflow step 1, that step is invoked, and the group is notified. Otherwise, workflow step 1 is skipped. Likewise, workflow steps 2 and 3 are performed if and only if the collection has a group assigned to those steps.</para>
<para>When a step is invoked, the task of performing that workflow step put in the &apos;task pool&apos; of the associated group. One member of that group takes the task from the pool, and it is then removed from the task pool, to avoid the situation where several people in the group may be performing the same task without realizing it.</para>
<para>The member of the group who has taken the task from the pool may then perform one of three actions:</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<emphasis role="bold">Workflow Step</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Possible actions</emphasis>
</para>
</entry>
</row>
<row>
<entry>
<para>1</para>
</entry>
<entry>
<para>Can accept submission for inclusion, or reject submission.</para>
</entry>
</row>
<row>
<entry>
<para>2</para>
</entry>
<entry>
<para>Can edit metadata provided by the user with the submission, but cannot change the submitted files. Can accept submission for inclusion, or reject submission.</para>
</entry>
</row>
<row>
<entry>
<para>3</para>
</entry>
<entry>
<para>Can edit metadata provided by the user with the submission, but cannot change the submitted files. Must then commit to archive; may not reject submission.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="image/workflow.gif" format="GIF" width="6.5in" scalefit="1"/>
</imageobject>
</inlinemediaobject>
</para>
<para>Submission Workflow in DSpace</para>
<para>If a submission is rejected, the reason (entered by the workflow participant) is e-mailed to the submitter, and it is returned to the submitter&apos;s &apos;My DSpace&apos; page. The submitter can then make any necessary modifications and re-submit, whereupon the process starts again.</para>
<para>If a submission is &apos;accepted&apos;, it is passed to the next step in the workflow. If there are no more workflow steps with associated groups, the submission is installed in the main archive.</para>
<para>One last possibility is that a workflow can be &apos;aborted&apos; by a DSpace site administrator. This is accomplished using the administration UI.</para>
<para>The reason for this apparently arbitrary design is that is was the simplist case that covered the needs of the early adopter communities at MIT. The functionality of the workflow system will no doubt be extended in the future.</para>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-supervision" xreflabel="Supervision and
Collaboration"/>Supervision and Collaboration</title>
<para>In order to facilitate, as a primary objective, the opportunity for thesis authors to be supervised in the preparation of their e-thesis, a supervision order system exists to bind groups of other users (thesis supervisors) to an item in someone&apos;s pre-submission workspace. The bound group can have system policies associated with it that allow different levels of interaction with the student&apos;s item; a small set of default policy groups are provided:</para>
<itemizedlist>
<listitem>
<para> Full editorial control</para>
</listitem>
<listitem>
<para> View item contents</para>
</listitem>
<listitem>
<para> No policies</para>
</listitem>
</itemizedlist>
<para>Once the default set has been applied, a system administrator may modify them as they would any other policy set in DSpace</para>
<para>This functionality could also be used in situations where researchers wish to collaborate on a particular submission, although there is no particular collaborative workspace functionality.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-handles" xreflabel="Handles"/>Handles</title>
<para>Researchers require a stable point of reference for their works. The simple evolution from sharing of citations to emailing of URLs broke when Web users learned that sites can disappear or be reconfigured without notice, and that their bookmark files containing critical links to research results couldn&apos;t be trusted long term. To help solve this problem, a core DSpace feature is the creation of persistent identifier for every item, collection and community stored in DSpace. To persist identifier, DSpace requires a storage- and location- independent mechanism for creating and maintaining identifiers. DSpace uses the <ulink url="http://www.handle.net/">CNRI Handle System</ulink> for creating these identifiers. The rest of this section assumes a basic familiarity with the Handle system.</para>
<para>DSpace uses Handles primarily as a means of assigning globally unique identifiers to objects. Each site running DSpace needs to obtain a Handle &apos;prefix&apos; from CNRI, so we know that if we create identifiers with that prefix, they won&apos;t clash with identifiers created elsewhere.</para>
<para>Presently, Handles are assigned to communities, collections, and items. Bundles and bitstreams are not assigned Handles, since over time, the way in which an item is encoded as bits may change, in order to allow access with future technologies and devices. Older versions may be moved to off-line storage as a new standard becomes de facto. Since it&apos;s usually the <emphasis>item</emphasis> that is being preserved, rather than the particular bit encoding, it only makes sense to persistently identify and allow access to the item, and allow users to access the appropriate bit encoding from there.</para>
<para>Of course, it may be that a particular bit encoding of a file is explicitly being preserved; in this case, the bitstream could be the only one in the item, and the item&apos;s Handle would then essentially refer just to that bitstream. The same bitstream can also be included in other items, and thus would be citable as part of a greater item, or individually.</para>
<para>The Handle system also features a global resolution infrastructure; that is, an end-user can enter a Handle into any service (e.g. Web page) that can resolve Handles, and the end-user will be directed to the object (in the case of DSpace, community, collection or item) identified by that Handle. In order to take advantage of this feature of the Handle system, a DSpace site must also run a &apos;Handle server&apos; that can accept and resolve incoming resolution requests. All the code for this is included in the DSpace source code bundle.</para>
<para>Handles can be written in two forms:</para>
<screen>
hdl:1721.123/4567
http://hdl.handle.net/1721.123/4567
</screen>
<para>The above represent the same Handle. The first is possibly more convenient to use only as an identifier; however, by using the second form, any Web browser becomes capable of resolving Handles. An end-user need only access this form of the Handle as they would any other URL. It is possible to enable some browsers to resolve the first form of Handle as if they were standard URLs using <ulink url="http://www.handle.net/resolver/index.html">CNRI&apos;s Handle Resolver plug-in</ulink>, but since the first form can always be simply derived from the second, DSpace displays Handles in the second form, so that it is more useful for end-users.</para>
<para>It is important to note that DSpace uses the CNRI Handle infrastructure only at the &apos;site&apos; level. For example, in the above example, the DSpace site has been assigned the prefix &apos;1721.123&apos;. It is still the responsibility of the DSpace site to maintain the association between a full Handle (including the &apos;4567&apos; local part) and the community, collection or item in question.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-bitstream_ids" xreflabel="Bitstream
'Persistent' Identifiers"/>Bitstream &apos;Persistent&apos; Identifiers</title>
<para>Similar to handles for DSpace items, bitstreams also have &apos;Persistent&apos; identifiers. They are more volatile than Handles, since if the content is moved to a different server or organizaion, they will no longer work (hence the quotes around &apos;persistent&apos;). However, they are more easily persisted than the simple URLs based on database primary key previously used. This means that external systems can more reliably refer to specific bitstreams stored in a DSpace instance.</para>
<para>Each bitstream has a sequence ID, unique within an item. This sequence ID is used to create a persistent ID, of the form:</para>
<para>
<literal>dspace url/bitstream/handle/sequence ID/filename</literal>
</para>
<para>For example:</para>
<screen>
https://dspace.myu.edu/bitstream/123.456/789/24/foo.html
</screen>
<para>The above refers to the bitstream with sequence ID 24 in the item with the Handle <literal>hdl:123.456/789</literal>. The <literal>foo.html</literal> is really just there as a hint to browsers: Although DSpace will provide the appropriate MIME type, some browsers only function correctly if the file has an expected extension.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-srb" xreflabel="Storage Resource Broker (SRB)
Support"/>Storage Resource Broker (SRB) Support</title>
<para>DSpace offers two means for storing bitstreams. The first is in the file system on the server. The second is using <ulink url="http://www.sdsc.edu/srb">SRB (Storage Resource Broker)</ulink>. Both are achieved using a simple, lightweight API.</para>
<para>SRB is purely an option but may be used in lieu of the server&apos;s file system or in addition to the file system. Without going into a full description, SRB is a very robust, sophisticated storage manager that offers essentially unlimited storage and straightforward means to replicate (in simple terms, backup) the content on other local or remote storage resources.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-search_browse" xreflabel="Search and
Browse"/>Search and Browse</title>
<para>DSpace allows end-users to discover content in a number of ways, including:</para>
<itemizedlist>
<listitem>
<para> Via external reference, such as a Handle</para>
</listitem>
<listitem>
<para> Searching for one or more keywords in metadata or extracted full-text</para>
</listitem>
<listitem>
<para> Browsing though title, author, date or subject indices, with optional image thumbnails</para>
</listitem>
</itemizedlist>
<para>Search is an essential component of discovery in DSpace. Users&apos; expectations from a search engine are quite high, so a goal for DSpace is to supply as many search features as possible. DSpace&apos;s indexing and search module has a very simple API which allows for indexing new content, regenerating the index, and performing searches on the entire corpus, a community, or collection. Behind the API is the Java freeware search engine <ulink url="http://jakarta.apache.org/lucene/">Lucene</ulink>. Lucene gives us fielded searching, stop word removal, stemming, and the ability to incrementally add new indexed content without regenerating the entire index. The specific Lucene search indexes are configurable enabling institutions to customize which DSpace metadata fields are indexed.</para>
<para>Another important mechanism for discovery in DSpace is the browse. This is the process whereby the user views a particular index, such as the title index, and navigates around it in search of interesting items. The browse subsystem provides a simple API for achieving this by allowing a caller to specify an index, and a subsection of that index. The browse subsystem then discloses the portion of the index of interest. Indices that may be browsed are item title, item issue date, item author, and subject terms. Additionally, the browse can be limited to items within a particular collection or community.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-html" xreflabel="HTML Support"/>HTML Support</title>
<para>For the most part, at present DSpace simply supports uploading and downloading of bitstreams as-is. This is fine for the majority of commonly-used file formats -- for example PDFs, Microsoft Word documents, spreadsheets and so forth. HTML documents (Web sites and Web pages) are far more complicated, and this has important ramifications when it comes to digital preservation:</para>
<itemizedlist>
<listitem>
<para> Web pages tend to consist of several files -- one or more HTML files that contain references to each other, and stylesheets and image files that are referenced by the HTML files.</para>
</listitem>
<listitem>
<para> Web pages also link to or include content from other sites, often imperceptably to the end-user. Thus, in a few year&apos;s time, when someone views the preserved Web site, they will probably find that many links are now broken or refer to other sites than are now out of context.</para>
<para>In fact, it may be unclear to an end-user when they are viewing content stored in DSpace and when they are seeing content included from another site, or have navigated to a page that is not stored in DSpace. This problem can manifest when a submitter uploads some HTML content. For example, the HTML document may include an image from an external Web site, or even their local hard drive. When the submitter views the HTML in DSpace, their browser is able to use the reference in the HTML to retrieve the appropriate image, and so to the submitter, the whole HTML document appears to have been deposited correctly. However, later on, when another user tries to view that HTML, their browser might not be able to retrieve the included image since it may have been removed from the external server. Hence the HTML will seem broken.</para>
</listitem>
<listitem>
<para> Often Web pages are produced dynamically by software running on the Web server, and represent the state of a changing database underneath it.</para>
</listitem>
</itemizedlist>
<para>Dealing with these issues is the topic of much active research. Currently, DSpace bites off a small, tractable chunk of this problem. DSpace can store and provide on-line browsing capability for <emphasis>self-contained, non-dynamic</emphasis> HTML documents. In practical terms, this means:</para>
<itemizedlist>
<listitem>
<para> No dynamic content (CGI scripts and so forth)</para>
</listitem>
<listitem>
<para> All links to preserved content must be <emphasis>relative links</emphasis>, that do not refer to &apos;parents&apos; above the &apos;root&apos; of the HTML document/site: </para>
<itemizedlist>
<listitem>
<para><literal>diagram.gif</literal> is OK</para>
</listitem>
<listitem>
<para><literal>image/foo.gif</literal> is OK</para>
</listitem>
<listitem>
<para><literal>../index.html</literal> is only OK in a file that is at least a directory deep in the HTML document/site hierarchy</para>
</listitem>
<listitem>
<para><literal>/stylesheet.css</literal> is not OK (the link will break)</para>
</listitem>
<listitem>
<para><literal>http://somedomain.com/content.html</literal> is not OK (the link will continue to link to the external site which may change or disappear)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Any &apos;absolute links&apos; (e.g. <literal>http://somedomain.com/content.html</literal>) are stored &apos;as is&apos;, and will continue to link to the external content (as opposed to relative links, which will link to the copy of the content stored in DSpace.) Thus, over time, the content refered to by the absolute link may change or disappear.</para>
</listitem>
</itemizedlist>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-oai" xreflabel="OAI Support"/>OAI Support</title>
<para>The <ulink url="http://www.openarchives.org/">Open Archives Initiative</ulink> has developed a <ulink url="http://www.openarchives.org/OAI/openarchivesprotocol.html">protocol for metadata harvesting</ulink>. This allows sites to programmatically retrieve or &apos;harvest&apos; the metadata from several sources, and offer services using that metadata, such as indexing or linking services. Such a service could allow users to access information from a large number of sites from one place.</para>
<para>DSpace exposes the Dublin Core metadata for items that are publicly (anonymously) accessible. Additionally, the collection structure is also exposed via the OAI protocol&apos;s &apos;sets&apos; mechanism. OCLC&apos;s open source <ulink url="http://www.oclc.org/research/software/oai/cat.shtm">OAICat</ulink> framework is used to provide this functionality.</para>
<para>You can also configure the OAI service to make use of any <link linkend="docbook-functional.html-crosswalk">crosswalk plugin</link> to offer additional metadata formats, such as MODS.</para>
<para>DSpace&apos;s OAI service does support the exposing of deletion information for withdrawn items, but not for items that are &apos;expunged&apos; (<link linkend="docbook-functional.html-deletions">see above</link>). DSpace also supports OAI-PMH resumption tokens.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-openurl" xreflabel="OpenURL Support"/>OpenURL Support</title>
<para>DSpace supports the <ulink url="http://www.sfxit.com/OpenURL/">OpenURL protocol</ulink> from <ulink url="http://www.sfxit.com/">SFX</ulink>, in a rather simple fashion. If your institution has an SFX server, DSpace will display an OpenURL link on every item page, automatically using the Dublin Core metadata. Additionally, DSpace can respond to incoming OpenURLs. Presently it simply passes the information in the OpenURL to the search subsystem. A list of results is then displayed, which usually gives the relevant item (if it is in DSpace) at the top of the list.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-creativecommons" xreflabel="Creative Commons
Support"/>Creative Commons Support</title>
<para>Dspace provides support for Creative Commons licenses to be attached to items in the repository. They represent an alternative to traditional copyright. To learn more about Creative Commons, visit <ulink url="http://creativecommons.org">their website</ulink>. Support for the licenses is controlled by a site-wide configuration option, and since license selection involves redirection to the Creative Commons website, additional parameters may be configured to work with a proxy server. If the option is enabled, users may select a Creative Commons license during the submission process, or elect to skip Creative Commons licensing. If a selection is made a copy of the license text and RDF metadata is stored along with the item in the repository. There is also an indication - text and a Creative Commons icon - in the item display page of the web user interface when an item is licensed under Creative Commons.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-subscriptions" xreflabel="Subscriptions"/>Subscriptions</title>
<para>As <link linkend="docbook-functional.html-epeople">noted above</link>, end-users (e-people) may &apos;subscribe&apos; to collections in order to be alerted when new items appear in those collections. Each day, end-users who are subscribed to one or more collections will receive an e-mail giving brief details of all new items that appeared in any of those collections the previous day. If no new items appeared in any of the subscribed collections, no e-mail is sent. Users can unsubscribe themselves at any time. RSS feeds of new items are also available for collections and communities.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-history" xreflabel="History"/>History</title>
<para>While provenance information in the form of prose is very useful, it is not easily programmatically manipulated. The History system captures a time-based record of significant changes in DSpace, in a manner suitable for later &apos;refactoring&apos; or repurposing.</para>
<para>Currently, the History subsystem is explicitly invoked when significant events occur (e.g., DSpace accepts an item into the archive). The History subsystem then creates RDF data describing the current state of the object. The RDF data is modeled using <ulink url="http://www.metadata.net/harmony/">Harmony/ABC</ulink>, an ontology for describing temporal-based data, and stored in the file system. Some simple indices for unwinding the data are available.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-importexport" xreflabel="Import and
Export"/>Import and Export</title>
<para>DSpace also includes batch tools to import and export items in a simple directory structure, where the Dublin Core metadata is stored in an XML file. This may be used as the basis for moving content between DSpace and other systems.</para>
<para>There is also a METS-based export tool, which exports items as METS-based metadata with associated bitstreams referenced from the METS file.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-registration" xreflabel="Registration"/>Registration</title>
<para>Registration is an alternate means of incorporating items, their metadata, and their bitstreams into DSpace by taking advantage of the bitstreams already being in accessible computer storage. An example might be that there is a repository for existing digital assets. Rather than using the normal <link linkend="docbook-functional.html-ingest">interactive ingest process</link> or the <link linkend="docbook-functional.html-importexport">batch import</link> to furnish DSpace the metadata and to upload bitstreams, registration provides DSpace the metadata and the location of the bitstreams. DSpace uses a variation of the import tool to accomplish registration.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-statistics" xreflabel="Statistics"/>Statistics</title>
<para>Various statistical report about the contents and use of your system can be automatically generated by the system. These are generated by analysing DSpace&apos;s log files. Statistics can be broken down monthly.</para>
<para>The report includes data such as:</para>
<itemizedlist>
<listitem>
<para> A customisable general summary of activities in the archive, by default including: </para>
<itemizedlist>
<listitem>
<para> Number of item views</para>
</listitem>
<listitem>
<para> Number of collection visits</para>
</listitem>
<listitem>
<para> Number of community visits</para>
</listitem>
<listitem>
<para> Number of OAI Requests</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Customisable summary of archive contents</para>
</listitem>
<listitem>
<para> Broken-down list of item viewings</para>
</listitem>
<listitem>
<para> A full break-down of all system activity</para>
</listitem>
<listitem>
<para> User logins</para>
</listitem>
<listitem>
<para> Most popular searches</para>
</listitem>
</itemizedlist>
<para>The results of statistical analysis can be presented on a by-month and an in-total report, and are available via the user interface. The reports can also either be made public or restricted to administrator access only.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-functional.html-checker" xreflabel="Checksum Checker"/>Checksum Checker</title>
<para>The purpose of the checker is to verify that the content in a DSpace repository has not become corrupted or been tampered with. The functionality can be invoked on an ad-hoc basis from the command line, or configured via cron or similar. Options exist to support large repositories that cannot be entirely checked in one run of the tool. The tool is extensible to new reporting and checking priority approaches.</para>
</section>
</chapter>

1352
dspace/docs/docbook/history.xml Normal file
View File

File diff suppressed because it is too large Load Diff

25
dspace/docs/docbook/html.xsl Normal file
View File

@@ -0,0 +1,25 @@
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
<!-- <xsl:param name="html.stylesheet" select="'corpstyle.css'"/>
<xsl:param name="admon.graphics" select="1"/> -->
<!-- footer xsl stuff?
(could use user.footer.navigational too)
-->
<xsl:template name="user.footer.content">
<HR/>
<xsl:apply-templates select="//copyright[1]" mode="titlepage.mode"/>
<xsl:apply-templates select="//legalnotice[1]" mode="titlepage.mode"/>
</xsl:template>
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="wrap-option">wrap</xsl:attribute>
<xsl:attribute name="hyphenation-character">\</xsl:attribute>
</xsl:attribute-set>
</xsl:stylesheet>

741
dspace/docs/docbook/index.xml Normal file
View File

@@ -0,0 +1,741 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Contents</title>
<para>Authors: Robert Tansley, Mick Bass, Margret Branschofsky, Grace Carpenter, Greg McClellan, David Stuve, and others</para>
<para>For DSpace Version: <emphasis role="bold">1.5</emphasis> (January-2008)</para>
<para>Documentation for other versions of DSpace are included with the source code.</para>
<itemizedlist>
<listitem>
<para>
<ulink url="introduction.html">Introduction</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html">Functional Overview</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="functional.html#data_model">Data Model</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#plugin">Plugin Manager</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#metadata">Metadata</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#packager">Packager Plugins</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#crosswalk">Crosswalk Plugins</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#epeople">E-people and Groups</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#authentication">Authentication</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#auth">Authorization</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#ingest">Ingest Process and Workflow</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#supervision">Supervision and Collaboration</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#handles">Handles</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#bitstream_ids">Bitstream &apos;Persistent&apos; Identifiers</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#srb">Storage Resource Broker (SRB) Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#search_browse">Search and Browse</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#html">HTML Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#oai">OAI Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#openurl">OpenURL Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#creativecommons">Creative Commons Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#subscriptions">Subscriptions</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#history">History</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#history">Import and Export</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#registration">Registration</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#statistics">Statistical Reports</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="functional.html#checker">Checksum Checker</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html">Installation</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="install.html#prerequisite">Prerequisite Software</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html#installsteps">Quick Installation Steps</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html#advancedinstall">Advanced Installation</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html#windows">Windows Installation</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html#knownbugs">Known Bugs</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="install.html#problems">Common Problems</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html">Updating a DSpace Installation</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="update.html#142_15">Updating from 1.4.2 to 1.5</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#14_141">Updating From 1.4 to 1.4.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#132_14">Updating From 1.3.x to 1.4.x</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#131_132">Updating From 1.3.1 to 1.3.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#12_13">Updating From 1.2.x to 1.3.x</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#121_122">Updating From 1.2.1 to 1.2.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#12_121">Updating From 1.2 to 1.2.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#11_12">Updating From 1.1 (or 1.1.1) to 1.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#11_111">Updating From 1.1 to 1.1.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="update.html#101_11">Updating From 1.0.1 to 1.1</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html">Configuration and Customization</ulink>
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="configure.html#general">General Configuration</ulink>
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="configure.html#general-dspacecfg">dspace.cfg</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-search">Search Indexes</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-browse">Browse Configuration</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-mediafilter">Configuring Media Filters</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-email">Email Messages</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-registries">Metadata and Bitstream Format Registries</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#general-license">Default Submission License</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html">Submission Configuration</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="submission.html#configurationFile">Understanding the Submission Configuration File</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html#stepOrdering">Reordering/Removing Submission Steps</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html#collectionSubmission">Assigning a custom Submission Process to a Collection</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html#metadataEntry">Customizing the Metadata-entry pages</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html#uploadStep">Configuring the File Upload step</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="submission.html#createStep">Creating new Submission Steps</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#xmlui">XMLUI Interface Customizations (Manakin)</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="configure.html#xmlui-dspacecfg">dspace.cfg</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#xmlui-configure">Configuring Themes and Aspects</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#xmlui-multilingual">Multilingual Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#xmlui-newtheme">Creating a New Theme</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#jspui">JSPUI Interface Customizations</ulink>
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="configure.html#jspui-dspacecfg">dspace.cfg</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#jspui-controlledvocabulary">Configuring Controlled Vocabularies</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#jspui-multilingual">Configuring Multilingual Support</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#jspui-jsp">Customizing the JSP Pages</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#advanced">Advanced DSpace Customizations</ulink>
</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<ulink url="configure.html#checksum">Checksum Checker</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#authentication">Custom Authentication</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#statistics">Configuring Statistical Reports</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#oai">Activating Additional OAI-PMH Crosswalks</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#packager">Configuring Packager Plugins</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#crosswalk">Configuring Crosswalk Plugins</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#mediafilters">Creating new Media/Format Filters</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#templates">Configuration Files for Other Applications</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="configure.html#browse-index">Browse Index Creation</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="directories.html">Directories and Files</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="directories.html#sourcedir">Source Directory Layout</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="directories.html#installdir">Installed Directory Layout</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="directories.html#webapp">Contents of Web Application</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="directories.html#logfiles">Log Files</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="architecture.html">Architecture</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="architecture.html#overview">Overview</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="storage.html">Storage Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="storage.html#rdbms">RDBMS</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="storage.html#bitstreams">Bitstream Store</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html">Business Logic Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="business.html#core">Core Classes</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#content">Content Management API</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#plugin">Plugin Manager</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#workflow">Workflow System</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#administer">Administration Toolkit</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#eperson">E-person/Group Manager</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#authorize">Authorization</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#handle">Handle Manager/Handle Plugin</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#search">Search</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#browse">Browse API</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="business.html#history">History Recorder</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html">Application Layer</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="application.html#webui">Web User Interface</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#oai">OAI-PMH Data Provider</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#structbuilder">Community and Collection Structure Importer</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#packager">Package Importer and Exporter</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#itemimporter">Item Importer and Exporter</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#transferitem">Transferring Items Between DSpace Instances</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#registration">Registering (Not Importing) Bitstreams</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#mets">METS Tools</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#mediafilters">Media Filters</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="application.html#filiator">Sub-Community Management</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html">DRI Schema Reference</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Introduction">Introduction</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#DRI_in_Manakin">DRI in Manakin</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Common_Design_Patterns">Common Design Patterns</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Schema_Overview">Schema Overview</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Merging_of_DRI_Documents">Merging of DRI Documents</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Version_Changes">Version Changes</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="DRISchemaReference.html#Element_Reference">Element Reference</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html">Version History</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="history.html#version1_5">Changes in DSpace 1.5</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_4_1">Changes in DSpace 1.4.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_4">Changes in DSpace 1.4</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_3_2">Changes in DSpace 1.3.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_3_1">Changes in DSpace 1.3.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_3">Changes in DSpace 1.3</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_2_2">Changes in DSpace 1.2.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_2_1">Changes in DSpace 1.2.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_2">Changes in DSpace 1.2</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_1_1">Changes in DSpace 1.1.1</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="history.html#version1_1">Changes in DSpace 1.1</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<ulink url="appendix.html">Appendices</ulink>
<itemizedlist>
<listitem>
<para>
<ulink url="appendix.html#dublincoreregistry">Default Dublin Core Metadata Registry</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="appendix.html#bitstreamformatregistry">Default Bitstream Format Registry</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</chapter>

918
dspace/docs/docbook/install.xml Normal file
View File

@@ -0,0 +1,918 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Installation</title>
<section remap="h2">
<title><anchor id="docbook-install.html-prerequisite" xreflabel="Prerequisite Software"/>Prerequisite Software</title>
<para>The list below describes the third-party components and tools you&apos;ll need to run a DSpace server. These are just guidelines. Since DSpace is built on open source, standards-based tools, there are numerous other possibilities and setups.</para>
<para>Also, please note that the configuration and installation guidelines relating to a particular tool below are here for convenience. You should refer to the documentation for each individual component for complete and up-to-date details. Many of the tools are updated on a frequent basis, and the guidelines below may become out of date.</para>
<section remap="h3">
<title>UNIX-like OS or Microsoft Windows</title>
<itemizedlist>
<listitem>
<para> UNIX-like OS (Linux, HP/UX etc) : Many distributions of Linux/Unix come with some of the dependencies below pre installed or easily installed via updates, you should consult your particular distributions documentation to determine what is already available.</para>
</listitem>
<listitem>
<para> Microsoft Windows: (see full <link linkend="docbook-install.html-windows">Windows Instructions</link> for full set of prerequisites)</para>
</listitem>
</itemizedlist>
</section>
<section remap="h3">
<title>Java JDK 5 or later (standard SDK is fine, you don&apos;t need J2EE)</title>
<para>DSpace now required Java 5 or greater because of usage of new language capabilities introduced in 5 that make coding easier and cleaner.</para>
<para>Java 5 or later can be downloaded from the following location: <ulink url="http://java.sun.com/javase/downloads/index.jsp">http://java.sun.com/javase/downloads/index.jsp</ulink></para>
</section>
<section remap="h3">
<title>Apache Maven 2.0.8 or later (Java build tool)</title>
<para>Maven is necessary in the first stage of the build process to assemble the installation package for your DSpace instance. It gives you the flexibility to customize DSpace using the exisitng Maven projects found in the <literal>[dspace-source]/dspace/modules</literal> directory or by adding in your own Maven project to build the installation package for DSpace, and apply any custom interface &quot;overlay&quot; changes.</para>
<para>Maven can be downloaded from the the following location: <ulink url="http://maven.apache.org/download.html">http://maven.apache.org/download.html</ulink></para>
</section>
<section remap="h3">
<title>Apache Ant 1.6.2 or later (Java build tool)</title>
<para>Apache Ant is still required for the second stage of the build process. It is used once the installation package has been constructed in <literal>[dspace-source]/dspace/target/dspace-&lt;version&gt;-build.dir</literal> and still uses some of the familiar ant build targets found in the 1.4.x build process.</para>
<para>Ant can be downloaded from the following location: <ulink url="http://ant.apache.org/">http://ant.apache.org</ulink></para>
</section>
<section remap="h3">
<title>Relational Database: (PostgreSQL or Oracle).</title>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">PostgreSQL 7.3 or greater</emphasis>
</para>
<para>PostgreSQL can be downloaded from the following location: <ulink url="http://www.postgresql.org/">http://www.postgresql.org/ </ulink> Its highly recommended that you try to work with Postgres 8.x or greater, however, 7.3 or greater should still work. Unicode (specifically UTF-8) support must be enabled. This is enabled by default in 8.0+. For 7.<emphasis>x</emphasis>, be sure to compile with the following options to the &apos;<literal>configure</literal>&apos; script:</para>
</listitem>
<listitem>
<para><screen>
--enable-multibyte --enable-unicode --with-java
</screen> <anchor id="docbook-install.html-enabletcpip"/>Once installed, you need to enable TCP/IP connections (DSpace uses JDBC). For 7.<emphasis>x</emphasis>, edit <literal>postgresql.conf</literal> (usually in <literal>/usr/local/pgsql/data</literal> or <literal>/var/lib/pgsql/data</literal>), and add this line:</para>
<screen>
tcpip_socket = true
</screen>
<para>For 8.0+, in <literal>postgresql.conf</literal> uncomment the line starting:</para>
<screen>
listen_addresses = &apos;localhost&apos;
</screen>
<para>Then tighten up security a bit by editing <literal>pg_hba.conf</literal> and adding this line:</para>
<screen>
host dspace dspace 127.0.0.1 255.255.255.255 md5
</screen>
<para>Then restart PostgreSQL.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Oracle 9 or greater</emphasis>
</para>
<para>Details on aquiring Oracle can be downloaded from the following location: <ulink url="http://www.oracle.com/database/">http://www.oracle.com/database/</ulink></para>
<para> You will need to create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is suggested that the Oracle database use the same character set. You will also need to create a user account for DSpace (e.g. <literal>dspace</literal>,) and ensure that it has permissions to add and remove tables in the database. Refer to the Quick Installation for more details.</para>
<para><emphasis role="bold">NOTE:</emphasis> DSpace uses sequences to generate unique object IDs - beware Oracle sequences, which are said to lose their values when doing a database export/import, say restoring from a backup. Be sure to run the script <literal>etc/update-sequences.sql</literal>.</para>
<para><emphasis role="bold">ALSO NOTE:</emphasis> Everything is fully functional, although Oracle limits you to 4k of text in text fields such as item metadata or collection descriptions.</para>
<para>For people interested in switching from Postgres to Oracle, I know of no tools that would do this automatically. You will need to recreate the community, collection, and eperson structure in the Oracle system, and then use the item export and import tools to move your content over.</para>
</listitem>
</itemizedlist>
</section>
<section remap="h3">
<title>Servlet Engine: (Jakarta Tomcat 4.x, Jetty, Caucho Resin or equivalent).</title>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">Jakarta Tomcat 4.x or later.</emphasis>
</para>
<para> Tomcat can be dowloaded from the following location: <ulink url="http://tomcat.apache.org/whichversion.html">http://tomcat.apache.org</ulink></para>
<para> Note that DSpace will need to run as the same user as Tomcat, so you might want to install and run Tomcat as a user called &apos;<literal>dspace</literal>&apos;.</para>
<para> You need to ensure that Tomcat has a) enough memory to run DSpace and b) uses UTF-8 as its default file encoding for international character support. So ensure in your startup scripts (etc) that the following environment variable is set: </para>
<screen>
JAVA_OPTS=&quot;-Xmx512M -Xms64M -Dfile.encoding=UTF-8&quot;
</screen>
<para> You also need to alter Tomcat&apos;s default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the <literal>&lt;Connector&gt;</literal> element in <literal>[tomcat]/config/server.xml</literal>: </para>
<screen>
URIEncoding=&quot;UTF-8&quot;
</screen>
<para> e.g. if you&apos;re using the default Tomcat config, it should read: </para>
<screen>
&lt;!-- Define a non-SSL HTTP/1.1 Connector on port 8080 --&gt;
&lt;Connector port=&quot;8080&quot;
maxThreads=&quot;150&quot; minSpareThreads=&quot;25&quot;
maxSpareThreads=&quot;75&quot;
enableLookups=&quot;false&quot; redirectPort=&quot;8443&quot;
acceptCount=&quot;100&quot;
connectionTimeout=&quot;20000&quot;
disableUploadTimeout=&quot;true&quot;
<emphasis role="bold"> URIEncoding=&quot;UTF-8&quot;</emphasis>
/&gt;
</screen>
</listitem>
<listitem>
<para>
<emphasis role="bold">Jetty or Caucho Resin</emphasis>
</para>
<para> DSpace will also run on an equivalent servlet Engine, such as Jetty (<ulink url="http://www.mortbay.org/jetty/index.html">http://www.mortbay.org/jetty/index.html</ulink>) or Caucho Resin (<ulink url="http://www.caucho.com/">http://www.caucho.com/)</ulink>.</para>
<para> Jetty and Resin are configured for correct handling of UTF-8 by default.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-installoptions" xreflabel="Installation Options"/>Installation Options</title>
<section remap="h3">
<title><anchor id="docbook-install.html-options" xreflabel="Overview of Install Options"/>Overview of Install Options</title>
<para>With the advent of a new Apache <ulink url="http://maven.apache.org/">Maven 2</ulink> based build architecture in DSpace 1.5.x, you now have two options in how you may wish to install and manage your local installation of DSpace. If you&apos;ve used DSpace 1.4.x, please recognize that the initial build proceedure has changed to allow for more customization. You will find the later &apos;Ant based&apos; stages of the installation proceedure familiar. Maven is used to resolve the dependencies of DSpace online from the &apos;Maven Central Repository&apos; server.</para>
<para>Its important to note that the strategies are identical in terms of the list of proceedures required to complete the build process, the only difference being that the Source Release includes &quot;more modules&quot; that will be built given their presence in the distribution package.</para>
<itemizedlist>
<listitem>
<para><anchor id="docbook-install.html-defaultRelease" xreflabel="Default Release (
dspace-&lt;version&gt;-release.zip )"/>Default Release ( dspace-&lt;version&gt;-release.zip )<itemizedlist>
<listitem>
<para>
<emphasis role="bold">This distribution will be adequate for most cases of running a DSpace instance.</emphasis>
<emphasis role="bold">It is intended to be the quickest way to get DSpace installed and running while still allowing for customization of the themes and branding of your DSpace instance.</emphasis>
</para>
</listitem>
<listitem>
<para> This method allows you to customize DSpace configurations (in dspace.cfg) or user interfaces, using basic pre-built interface &quot;overlays&quot;.</para>
</listitem>
<listitem>
<para> It downloads &quot;precompiled&quot; libraries for the core dspace-api, supporting servlets, taglibraries, aspects and themes for the dspace-xmlui, dspace-xmlui and other webservice/applications.</para>
</listitem>
<listitem>
<para> This approach exposes the parts of the application that the DSpace commiters would prefer to see customized. All other modules are downloaded from the &apos;Maven Central Repository&apos;</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<blockquote>
<para> The directory structure for this release is the following:</para>
</blockquote>
<itemizedlist>
<listitem>
<para>
<literal>[dspace-source]</literal>
<itemizedlist>
<listitem>
<para><literal>dspace/</literal> - DSpace &apos;build&apos; and configuration module</para>
</listitem>
<listitem>
<para><literal>pom.xml</literal> - DSpace Parent Project definition</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><anchor id="docbook-install.html-sourceRelease" xreflabel="Source Release (
dspace-&lt;version&gt;-src-release.zip )"/>Source Release ( dspace-&lt;version&gt;-src-release.zip )<itemizedlist>
<listitem>
<para>
<emphasis role="bold">This method is recommended for those who wish to develop DSpace further or alter its underlying capabilities to a greater degree.</emphasis>
</para>
</listitem>
<listitem>
<para> It contains &quot;all&quot; dspace code for the core dspace-api, supporting servlets, taglibraries, aspects and themes for the dspace-xmlui, dspace-xmlui and other webservice/applications.</para>
</listitem>
<listitem>
<para> Provides all the same capabilities as the normal release.</para>
</listitem>
</itemizedlist>
</para>
<para> The directory structure for this release is more detailed:</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para>
<literal>[dspace-source]</literal>
<itemizedlist>
<listitem>
<para><literal>dspace/</literal> - DSpace &apos;build&apos; and configuration module</para>
</listitem>
<listitem>
<para><literal>dspace-api/</literal> - Java API source module</para>
</listitem>
<listitem>
<para><literal>dspace-jspui/</literal> - JSP-UI source module</para>
</listitem>
<listitem>
<para><literal>dspace-oai/</literal> - OAI-PMH source module</para>
</listitem>
<listitem>
<para><literal>dspace-xmlui/</literal> - XML-UI source module</para>
</listitem>
<listitem>
<para><literal>dspace-lni/</literal> - Lightweight Network Interface source module</para>
</listitem>
<listitem>
<para><literal>dspace-sword/</literal> - SWORD (Simple Web-service Offering Repository Deposit) deposit service source module</para>
</listitem>
<listitem>
<para><literal>pom.xml</literal> - DSpace Parent Project definition</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<para>Both approaches provide you with the same control over how DSpace builds itself (especially in terms of adding completely custom/3rd-party DSpace &quot;modules&quot; you wish to use). Both methods allow you the ability to create more complex user interface &quot;overlays&quot; in Maven. An interface &quot;overlay&quot; allows you to only manage your local custom code (in your local CVS or SVN), and automatically download the rest of the interface code from the maven central repository whenever you build DSpace. This reduces the amount of out-of-the-box DSpace interface code maintained in your local CVS/SVN.</para>
</section>
<section remap="h3">
<title><anchor id="docbook-install.html-directories" xreflabel="Overview of DSpace Directories"/>Overview of DSpace Directories</title>
<para>Before beginning an installation, it is important to get a general understanding of the DSpace directories and the names by which they are generally referred. (Please attempt to use these below directory names when asking for help on the DSpace Mailing Lists, as it will help everyone better understand what directory you may be referring to.)</para>
<para>DSpace uses three separate directory trees. Although you don&apos;t need to know all the details of them in order to install DSpace, you do need to know they exist and also know how they&apos;re referred to in this document:</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">the installation directory</emphasis> , referred to as <emphasis>
<literal>[dspace]</literal>
</emphasis>
. This is the location where DSpace is installed and running off of it is the location that gets defined in the dspace.cfg as &quot;dspace.dir&quot;. It is where all the DSpace configuration files, command line scripts, documentation and webapps will be installed to.</para>
</listitem>
<listitem>
<para><emphasis role="bold">the source directory</emphasis> , referred to as <emphasis>
<literal>[dspace-source]</literal>
</emphasis>
. This is the location where the DSpace release distribution has been unzipped into. It usually has the name of the archive that you expanded such as <emphasis>dspace-&lt;version&gt;-release</emphasis> or <emphasis>dspace-&lt;version&gt;-src-release</emphasis>. It is the directory where all of your &quot;build&quot; commands will be run.</para>
</listitem>
<listitem>
<para><emphasis role="bold">the web deployment directory</emphasis> . This is the directory that contains your DSpace web application(s). In DSpace 1.5.x and above, this corresponds to <emphasis>
<literal>[dspace]/webapps</literal>
</emphasis>
by default. However, if you are using Tomcat, you may decide to copy your DSpace web applications from <emphasis>
<literal>[dspace]/webapps/</literal>
</emphasis>
to <literal>[tomcat]/webapps/</literal> (with <literal>[tomcat]</literal> being wherever you installed Tomcat--also known as <literal>$CATALINA_HOME</literal>).</para>
</listitem>
</orderedlist>
<para>For details on the contents of these separate directory trees, refer to <ulink url="directories.html">directories.html</ulink>. <emphasis>Note that the <literal>[dspace-source]</literal> and <literal>[dspace]</literal> directories are always separate!</emphasis></para>
</section>
<section remap="h3">
<title><anchor id="docbook-install.html-installsteps" xreflabel="Installation"/>Installation</title>
<para> This method gets you up and running with DSpace quickly and easily. It is identical in both the <link linkend="docbook-install.html-defaultRelease">Default Release</link> and <link linkend="docbook-install.html-sourceRelease">Source Release</link> distributions. </para>
<orderedlist>
<listitem>
<para> Create the DSpace user. This needs to be the same user that Tomcat (or Jetty etc) will run as. e.g. as root run:</para>
<screen>
useradd -m dspace
</screen>
</listitem>
<listitem>
<para> Download the <ulink url="http://sourceforge.net/projects/dspace/">latest DSpace release</ulink> and unpack it. Although there are two available releases (<literal>dspace-1.x-release.zip</literal> and <literal>dspace-1.x-src-release.zip</literal>), you only need to choose one. If you want a copy of all underlying Java source code, you should download the <literal>dspace-1.x-src-release.zip</literal> release. </para>
<screen>
unzip dspace-1.x-release.zip
</screen>
<para>For ease of reference, we will refer to the location of this unzipped version of the DSpace release as <literal>[dspace-source] in the remainder of these instructions.</literal></para>
</listitem>
<listitem>
<para> Database Setup</para>
<para>
<emphasis role="bold">Postgres:</emphasis>
</para>
<orderedlist>
<listitem>
<para> <anchor id="docbook-install.html-pgdriver"/> A PostgreSQL 8.1-404 jdbc3 driver is configure as part of the default DSpace build. You no longer need to copy any postgres jars to get postgres installed.</para>
</listitem>
<listitem>
<para> Create a <literal>dspace</literal> database, owned by the <literal>dspace</literal> PostgreSQL user:</para>
<screen>
createuser -U postgres -d -A -P dspace
createdb -U dspace -E UNICODE dspace
</screen>
<para>Enter a password for the DSpace database. (This isn&apos;t the same as the <literal>dspace</literal> user&apos;s UNIX password.)</para>
</listitem>
</orderedlist>
<para>
<emphasis role="bold">Oracle:</emphasis>
</para>
<orderedlist>
<listitem>
<para> Setting up oracle is a bit different now. You will need still need to get a Copy of the oracle JDBC driver, but instead of copying it into a lib directory you will need to install it into your local Maven repository. You&apos;ll need to download it first from this location: <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc_10201.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/htdocs/jdbc_10201.html</ulink></para>
<para>
<literal>$ mvn install:install-file -Dfile=ojdbc14.jar -DgroupId=com.oracle \ -DartifactId=ojdbc14 -Dversion=10.2.0.2.0 -Dpackaging=jar -DgeneratePom=true</literal>
</para>
</listitem>
<listitem>
<para> Create a database for DSpace. Make sure that the character set is one of the Unicode character sets. DSpace uses UTF-8 natively, and it is suggested that the Oracle database use the same character set. Create a user account for DSpace (e.g. <literal>dspace</literal>,) and ensure that it has permissions to add and remove tables in the database.</para>
</listitem>
<listitem>
<para> Edit the <literal>[dspace-source]/dspace/config/dspace.cfg</literal> database settings:</para>
<screen>
db.name = oracle
db.url = jdbc.oracle.thin:@//host:port/dspace
db.driver = oracle.jdbc.OracleDriver
</screen>
</listitem>
<listitem>
<para> Go to <literal>[dspace-source]/dspace/etc/oracle</literal> and copy the contents to their parent directory, overwriting the versions in the parent:</para>
<screen>
cd [dspace-source]/dspace/etc/oracle
cp * ..
</screen>
<para>You now have Oracle-specific <literal>.sql</literal> files in your <literal>etc</literal> directory, and your dspace.cfg is modified to point to your Oracle database.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para> Edit <literal>[dspace-source]/dspace/config/dspace.cfg</literal>, in particular you&apos;ll need to set these properties:</para>
<para><literal>dspace.dir</literal> -- must be set to the <literal>[dspace]</literal> (installation) directory.</para>
<para><literal>dspace.url</literal> -- complete URL of this server&apos;s DSpace home page.</para>
<para><literal>dspace.hostname</literal> -- fully-qualified domain name of web server.</para>
<para><literal>dspace.name</literal> -- &quot;Proper&quot; name of your server, e.g. &quot;My Digital Library&quot;.</para>
<para><literal>db.password</literal> -- the database password you entered in the previous step.</para>
<para><literal>mail.server</literal> -- fully-qualified domain name of your outgoing mail server.</para>
<para><literal>mail.from.address</literal> -- the &quot;From:&quot; address to put on email sent by DSpace.</para>
<para><literal>feedback.recipient</literal> -- mailbox for feedback mail.</para>
<para><literal>mail.admin</literal> -- mailbox for DSpace site administrator.</para>
<para><literal>alert.recipient</literal> -- mailbox for server errors/alerts (not essential but very useful!)</para>
<para><literal>registration.notify</literal> -- mailbox for emails when new users register (optional) </para>
<para><emphasis role="bold">NOTE:</emphasis> You can interpolate the value of one configuration variable in the value of another one. For example, to set <literal>feedback.recipient</literal> to the same value as <literal>mail.admin</literal>, the line would look like:</para>
<screen>
feedback.recipient = ${mail.admin}
</screen>
<para> See the <literal>dspace.cfg</literal> file for examples.</para>
</listitem>
<listitem>
<para> Create the directory for the DSpace installation (i.e. <literal>[dspace]</literal>). As <emphasis>root</emphasis> (or a user with appropriate permissions), run: </para>
<screen>
mkdir <emphasis> [dspace]</emphasis>
chown dspace <emphasis> [dspace]</emphasis>
</screen>
<para>(Assuming the <literal>dspace</literal> UNIX username.)</para>
</listitem>
<listitem>
<para> As the <literal>dspace</literal> UNIX user, generate the DSpace installation package in the <literal>[dspace-source]/dspace/target/dspace-[version].dir/</literal> directory:</para>
<screen>
cd <emphasis> [dspace-source]</emphasis>/dspace/
mvn package
</screen>
<para>Note: without any extra arguments, the DSpace installation package is initialized for PostgreSQL.</para>
<para> If you want to use Oracle instead, you should build the DSpace installation package as follows:</para>
<screen>
mvn -Ddb.name=oracle package
</screen>
</listitem>
<listitem>
<para> As the <literal>dspace</literal> UNIX user, initialize the DSpace database and install DSpace to <literal>[dspace]</literal>:</para>
<screen>
cd <emphasis>
[dspace-source]</emphasis>/dspace/target/dspace-[version].dir/
ant fresh_install
</screen>
<para><emphasis role="bold">Note:</emphasis> to see a complete list of build targets, run</para>
<screen>
ant help
</screen>
<para>The most likely thing to go wrong here is the database connection. See the <link linkend="docbook-install.html-problems">common problems section</link>.</para>
</listitem>
<listitem>
<para> Tell your Tomcat/Jetty/Resin installation where to find your DSpace web application(s). As an example, in the <literal>&lt;Host&gt;</literal> section of your <literal>[tomcat]/conf/server.xml</literal> you could add lines similar to the following (but replace <literal>[dspace]</literal> with your installation location):</para>
<screen>
&lt;!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface --&gt;
&lt;Context path=&quot;/jspui&quot; docBase=&quot;[dspace]\webapps\jspui&quot; debug=&quot;0&quot;
reloadable=&quot;true&quot; cachingAllowed=&quot;false&quot;
allowLinking=&quot;true&quot;/&gt;
&lt;!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface --&gt;
&lt;Context path=&quot;/oai&quot; docBase=&quot;[dspace]\webapps\oai&quot; debug=&quot;0&quot;
reloadable=&quot;true&quot; cachingAllowed=&quot;false&quot;
allowLinking=&quot;true&quot;/&gt;
</screen>
<para>Alternatively, you could copy only the DSpace Web application(s) you wish to use from <literal>[dspace]/webapps</literal> to the appropriate directory in your Tomcat/Jetty/Resin installation. For example:</para>
<screen>
cp -r <emphasis> [dspace]</emphasis>/webapps/jspui <emphasis>
[tomcat]</emphasis>/webapps
cp -r <emphasis> [dspace]</emphasis>/webapps/oai <emphasis>
[tomcat]</emphasis>/webapps
</screen>
</listitem>
<listitem>
<para> Create an initial administrator account: </para>
<screen>
<emphasis> [dspace]</emphasis>/bin/create-administrator
</screen>
</listitem>
<listitem>
<para> Now the moment of truth! Start up (or restart) Tomcat/Jetty/Resin. Visit the base URL(s) of your server, depending on which DSpace web applications you want to use. You should see the DSpace home page. Congratulations! </para>
<para>Base URLs of DSpace Web Applications:</para>
<itemizedlist>
<listitem>
<para><emphasis>JSP User Interface</emphasis> - (e.g.) http://dspace.myu.edu:8080/jspui</para>
</listitem>
<listitem>
<para><emphasis>XML User Interface (aka. Manakin)</emphasis> - (e.g.) http://dspace.myu.edu:8080/xmlui</para>
</listitem>
<listitem>
<para><emphasis>OAI-PMH Interface</emphasis> - (e.g.) http://dspace.myu.edu:8080/oai/request?verb=identify (Should return an XML-based response)</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para>In order to set up some communities and collections, you&apos;ll need to login as your DSpace Administrator (which you created with <literal>create-administrator</literal> above) and access the administration UI in either the JSP or XML user interface.</para>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-advancedinstall" xreflabel="Advanced Installation"/>Advanced Installation</title>
<para>The above installation steps are sufficient to set up a test server to play around with, but there are a few other steps and options you should probably consider before deploying a DSpace production site.</para>
<section remap="h3">
<title>&apos;cron&apos; Jobs</title>
<para>A couple of DSpace features require that a script is run regularly -- the e-mail subscription feature that alerts users of new items being deposited, and the new &apos;media filter&apos; tool, that generates thumbnails of images and extracts the full-text of documents for indexing.</para>
<para>To set these up, you just need to run the following command as the <literal>dspace</literal> UNIX user:</para>
<screen>
crontab -e
</screen>
<para>Then add the following lines:</para>
<screen>
# Send out subscription e-mails at 01:00 every day
0 1 * * * <emphasis> [dspace]</emphasis>/bin/sub-daily
# Run the media filter at 02:00 every day
0 2 * * * <emphasis> [dspace]</emphasis>/bin/filter-media
# Run the checksum checker at 03:00
0 3 * * * <emphasis> [dspace]</emphasis>/bin/checker -lp
# Mail the results to the sysadmin at 04:00
0 4 * * * <emphasis> [dspace]</emphasis>/bin/dsrun org.dspace.checker.DailyReportEmailer
-c
</screen>
<para>Naturally you should change the frequencies to suit your environment.</para>
<para>PostgreSQL also benefits from regular &apos;vacuuming&apos;, which optimizes the indices and clears out any deleted data. Become the <literal>postgres</literal> UNIX user, run <literal>crontab -e</literal> and add (for example):</para>
<screen>
# Clean up the database nightly at 4.20am
20 4 * * * vacuumdb --analyze dspace &gt; /dev/null 2&gt;&amp;1
</screen>
<para>In order that statistical reports are generated regularly and thus kept up to date you should set up the following cron jobs:</para>
<screen>
# Run stat analyses
0 1 * * * [dspace]/bin/stat-general
0 1 * * * [dspace]/bin/stat-monthly
0 2 * * * [dspace]/bin/stat-report-general
0 2 * * * [dspace]/bin/stat-report-monthly
</screen>
<para>Obviously, you should choose execution times which are most useful to you, and you should ensure that the <literal>-report-</literal> scripts run a short while after the analysis scripts to give them time to complete (a run of around 8 months worth of logs can take around 25 seconds to complete); the resulting reports will let you know how long analysis took and you can adjust your cron times accordingly.</para>
<para>For information on customising the output of this see <ulink url="configure.html#statistics">configuring system statistical reports</ulink>.</para>
</section>
<section remap="h3">
<title>Multilingual Installation</title>
<para> In order to deploy a multilingual version of DSpace you have to configure two parameters in <literal>[dspace]/config/dspace.cfg:</literal></para>
<para><literal>default.locale</literal>, e. g. default.locale = en</para>
<para><literal>webui.supported locales</literal>, e. g. webui.supported.locales = en, de</para>
<para> The Locales might have the form country, country_language, country_language_variant.</para>
<para> Accoding to the languages you wish to support, you have to make sure, that all the i18n related files are available see the <ulink url="configure.html#multilingualui">Multilingual User Interface</ulink> section in the configuration documentation. </para>
</section>
<section remap="h3">
<title><anchor id="docbook-install.html-https" xreflabel="DSpace over HTTPS"/>DSpace over HTTPS</title>
<para>If your DSpace is configured to have users login with a username and password (as opposed to, say, client Web certificates), then you should consider using HTTPS. Whenever a user logs in with the Web form (e.g. <literal>dspace.myuni.edu/dspace/password-login</literal>) their DSpace password is exposed in plain text on the network. This is a very serious security risk since network traffic monitoring is very common, especially at universities. If the risk seems minor, then consider that your DSpace administrators also login this way and they have ultimate control over the archive.</para>
<para>The solution is to use <emphasis>HTTPS</emphasis> (HTTP over SSL, i.e. Secure Socket Layer, an encrypted transport), which protects your passwords against being captured. You can configure DSpace to require SSL on all &quot;authenticated&quot; transactions so it only accepts passwords on SSL connections.</para>
<para>The following sections show how to set up the most commonly-used Java Servlet containers to support HTTP over SSL.</para>
<section remap="h4">
<title>To enable the HTTPS support in Tomcat 5.0:</title>
<orderedlist>
<listitem>
<para><emphasis role="bold">For Production use:</emphasis> Follow this procedure to set up SSL on your server. Using a &quot;real&quot; server certificate ensures your users&apos; browsers will accept it without complaints. </para>
<para>In the examples below, <literal>$CATALINA_BASE</literal> is the directory under which your Tomcat is installed.</para>
<orderedlist>
<listitem>
<para> Create a Java keystore for your server with the password <literal>changeit</literal>, and install your server certificate under the alias <literal>&quot;tomcat&quot;</literal>. This assumes the certificate was put in the file <literal>server.pem</literal>:</para>
<screen>
$JAVA_HOME/bin/keytool -import -noprompt -v -storepass changeit
-keystore $CATALINA_BASE/conf/keystore -alias tomcat -file
myserver.pem
</screen>
</listitem>
<listitem>
<para> Install the CA (Certifying Authority) certificate for the CA that granted your server cert, if necessary. This assumes the server CA certificate is in <literal>ca.pem</literal>:</para>
<screen>
$JAVA_HOME/bin/keytool -import -noprompt -storepass changeit
-trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias ServerCA
-file ca.pem
</screen>
</listitem>
<listitem>
<para> Optional -- ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the <ulink url="configure.html#authenticate">configuration section</ulink> for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in <literal>client1.pem</literal>:</para>
<screen>
$JAVA_HOME/bin/keytool -import -noprompt -storepass changeit
-trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1
-file client1.pem
</screen>
</listitem>
<listitem>
<para> Now add another Connector tag to your <literal>server.xml</literal> Tomcat configuration file, like the example below. The parts affecting or specific to SSL are shown in bold. (You may wish to change some details such as the port, pathnames, and keystore password)</para>
<screen>
&lt;Connector port=&quot;8443&quot;
maxThreads=&quot;150&quot; minSpareThreads=&quot;25&quot;
maxSpareThreads=&quot;75&quot;
enableLookups=&quot;false&quot;
disableUploadTimeout=&quot;true&quot;
acceptCount=&quot;100&quot; debug=&quot;0&quot;
<emphasis role="bold"> scheme=&quot;https&quot; secure=&quot;true&quot; sslProtocol=&quot;TLS&quot;
keystoreFile=&quot;conf/keystore&quot; keystorePass=&quot;changeit&quot; clientAuth=&quot;true&quot;</emphasis>
<emphasis> - ONLY if using client X.509 certs for authentication!</emphasis> <emphasis role="bold">
truststoreFile=&quot;conf/keystore&quot; trustedstorePass=&quot;changeit&quot;</emphasis>
/&gt;
</screen>
<para> Also, check that the default Connector is set up to redirect &quot;secure&quot; requests to the same port as your SSL connector, e.g.: </para>
<screen>
&lt;Connector port=&quot;8080&quot;
maxThreads=&quot;150&quot; minSpareThreads=&quot;25&quot;
maxSpareThreads=&quot;75&quot;
enableLookups=&quot;false&quot; <emphasis role="bold">
redirectPort=&quot;8443&quot;</emphasis>
acceptCount=&quot;100&quot; debug=&quot;0&quot;
/&gt;
</screen>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">Quick-and-dirty Procedure for Testing:</emphasis>
</para>
<para> If you are just setting up a DSpace server for testing, or to experiment with HTTPS, then you don&apos;t need to get a real server certificate. You can create a &quot;self-signed&quot; certificate for testing; web browsers will issue warnings before accepting it but they will function exactly the same after that as with a &quot;real&quot; certificate. </para>
<para>In the examples below, <literal>$CATALINA_BASE</literal> is the directory under which your Tomcat is installed.</para>
<orderedlist>
<listitem>
<para> Optional -- ONLY if you don&apos;t already have a server certificate. Follow this sub-procedure to request a new, signed server certificate from your Certifying Authority (CA):</para>
<itemizedlist>
<listitem>
<para> Create a new key pair under the alias name <literal>&quot;tomcat&quot;</literal>. When generating your key, give the Distinguished Name fields the appropriate values for your server and institution. CN should be the fully-qualified domain name of your server host. Here is an example:</para>
<screen>
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keysize
1024 \
-keystore $CATALINA_BASE/conf/keystore -storepass changeit
-validity 365 \
-dname &apos;CN=dspace.myuni.edu, OU=MIT Libraries, O=Massachusetts
Institute of Technology, L=Cambridge, S=MA, C=US&apos;
</screen>
</listitem>
<listitem>
<para> Then, create a <emphasis>CSR</emphasis> (Certificate Signing Request) and send it to your Certifying Authority. They will send you back a signed Server Certificate. This example command creates a CSR in the file <literal>tomcat.csr</literal></para>
<screen>
$JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore
-storepass changeit \
-certreq -alias tomcat -v -file tomcat.csr
</screen>
</listitem>
<listitem>
<para> Before importing the signed certificate, you must have the CA&apos;s certificate in your keystore as a <emphasis>trusted certificate</emphasis>. Get their certificate, and import it with a command like this (for the example <literal>mitCA.pem</literal>):</para>
<screen>
$JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore
-storepass changeit \
-import -alias mitCA -trustcacerts -file mitCA.pem
</screen>
</listitem>
<listitem>
<para> Finally, when you get the signed certificate from your CA, import it into the keystore with a command like the following example: (cert is in the file <literal>signed-cert.pem</literal>)</para>
<screen>
$JAVA_HOME/bin/keytool -keystore $CATALINA_BASE/conf/keystore
-storepass changeit \
-import -alias tomcat -trustcacerts -file signed-cert.pem
</screen>
<para> Since you now have a signed server certificate in your keystore, you can, obviously, skip the next steps of installing a signed server certificate and the server CA&apos;s certificate.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Create a Java keystore for your server with the password <literal>changeit</literal>, and install your server certificate under the alias <literal>&quot;tomcat&quot;</literal>. This assumes the certificate was put in the file <literal>server.pem</literal>:</para>
<screen>
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore
$CATALINA_BASE/conf/keystore -storepass changeit
</screen>
<para>When answering the questions to identify the certificate, be sure to respond to &quot;First and last name&quot; with the fully-qualified domain name of your server (e.g. <literal>test-dspace.myuni.edu</literal>). The other questions are not important.</para>
</listitem>
<listitem>
<para> Optional -- ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the <ulink url="configure.html#authenticate">configuration section</ulink> for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in <literal>client1.pem</literal>:</para>
<screen>
$JAVA_HOME/bin/keytool -import -noprompt -storepass changeit
-trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1
-file client1.pem
</screen>
</listitem>
<listitem>
<para> Follow the procedure in the section above to add another Connector tag, for the HTTPS port, to your <literal>server.xml</literal> file.</para>
</listitem>
</orderedlist>
</listitem>
</orderedlist>
</section>
<section remap="h4">
<title>To use SSL on Apache HTTPD with mod_jk:</title>
<para> If you choose <ulink url="http://httpd.apache.org/">Apache HTTPD</ulink> as your primary HTTP server, you can have it forward requests to the <ulink url="http://tomcat.apache.org/">Tomcat servlet container</ulink> via <ulink url="http://tomcat.apache.org/connectors-doc/">Apache Jakarta Tomcat Connector</ulink>. This can be configured to work over SSL as well. First, you must configure Apache for SSL; for Apache 2.0 see <ulink url="http://httpd.apache.org/docs/2.0/ssl/">Apache SSL/TLS Encryption</ulink> for information about using <ulink url="http://httpd.apache.org/docs/2.0/mod/mod_ssl.html">mod_ssl</ulink>.</para>
<para><emphasis>
<emphasis role="bold">If you are using X.509 Client Certificates for authentication:</emphasis>
</emphasis>
add these configuration options to the appropriate <emphasis>httpd</emphasis> configuration file, e.g. <literal>ssl.conf</literal>, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace:</para>
<screen>
## SSLVerifyClient can be &quot;optional&quot; or
&quot;require&quot;
SSLVerifyClient optional
SSLVerifyDepth 10
SSLCACertificateFile <emphasis>
path-to-your-client-CA-certificate</emphasis>
SSLOptions StdEnvVars ExportCertData
</screen>
<para>Now consult the <ulink url="http://tomcat.apache.org/connectors-doc/">Apache Jakarta Tomcat Connector</ulink> documentation to configure the <literal>mod_jk</literal> (note: <emphasis role="bold">NOT</emphasis><literal>mod_jk2</literal>) module. Select the AJP 1.3 connector protocol. Also follow the instructions there to configure your Tomcat server to respond to AJP.</para>
<para><emphasis role="bold">To use SSL on Apache HTTPD with mod_webapp</emphasis> consult the DSpace 1.3.2 documentation. Apache have deprecated the <literal>mod_webapp</literal> connector and recommend using <literal>mod_jk</literal>.</para>
<para><emphasis role="bold">To use Jetty&apos;s HTTPS support</emphasis> consult the documentation for the relevant tool.</para>
</section>
</section>
<section remap="h3">
<title><anchor id="docbook-install.html-handles" xreflabel="The Handle Server"/>The Handle Server</title>
<para>First a few facts to clear up some common misconceptions:</para>
<itemizedlist>
<listitem>
<para> You don&apos;t <emphasis role="bold">have</emphasis> to use CNRI&apos;s Handle system. At the moment, you need to change the code a little to use something else (e.g PURLs) but that should change soon.</para>
</listitem>
<listitem>
<para> You&apos;ll notice that while you&apos;ve been playing around with a test server, DSpace has apparently been creating handles for you looking like <literal>hdl:123456789/24</literal> and so forth. These aren&apos;t really Handles, since the global Handle system doesn&apos;t actually know about them, and lots of other DSpace test installs will have created the same IDs.</para>
<para>They&apos;re only really Handles once you&apos;ve registered a prefix with CNRI (see below) and have correctly set up the Handle server included in the DSpace distribution. This Handle server communicates with the rest of the global Handle infrastructure so that anyone that understands Handles can find the Handles your DSpace has created.</para>
</listitem>
</itemizedlist>
<para>If you want to use the Handle system, you&apos;ll need to set up a Handle server. This is included with DSpace. Note that this is not required in order to evaluate DSpace; you only need one if you are running a production service. You&apos;ll need to obtain a Handle prefix from <ulink url="http://www.handle.net/">the central CNRI Handle site</ulink>.</para>
<para>A Handle server runs as a separate process that receives TCP requests from other Handle servers, and issues resolution requests to a global server or servers if a Handle entered locally does not correspond to some local content. The Handle protocol is based on TCP, so it will need to be installed on a server that can broadcast and receive TCP on port 2641.</para>
<para>The Handle server code is included with the DSpace code in <literal>[dspace]/lib/handle.jar</literal>. <emphasis role="bold">Note:</emphasis> The latest version of the <literal>handle.jar</literal> file is not included in the release due to licensing conditions changing between the provided version and later versions. It is recommended you read the <ulink url="http://www.handle.net/upgrade_6-2_DSpace.html">new license conditions</ulink> and decide whether you wish to update your installation&apos;s <literal>handle.jar</literal>. If you decide to update, you should replace the existing <literal>handle.jar</literal> in <emphasis>[dspace]</emphasis>/lib with the new version and rebuild your war files.</para>
<para>A script exists to create a simple Handle configuration - simply run <literal>[dspace]/bin/make-handle-config</literal> after you&apos;ve set the appropriate parameters in <literal>dspace.cfg</literal>. You can also create a Handle configuration directly by following the <ulink url="http://www.handle.net/hs_manual_18jan02/server_manual_2.html">installation instructions on handle.net</ulink>, but with these changes:</para>
<itemizedlist>
<listitem>
<para> Instead of running: </para>
<screen>
java -cp /hs/bin/handle.jar net.handle.server.SimpleSetup /hs/svr_1
</screen>
<para> as directed in the <ulink url="http://hdl.handle.net/4263537/4093">Handle Server Administration Guide</ulink>, you should run </para>
<screen>
<emphasis> [dspace]</emphasis>/bin/dsrun net.handle.server.SimpleSetup <emphasis>
[dspace]</emphasis>/handle-server
</screen>
<para> ensuring that <literal>[dspace]/handle-server</literal> matches whatever you have in <literal>dspace.cfg</literal> for the <literal>handle.dir</literal> property.</para>
</listitem>
<listitem>
<para> Edit the resulting <literal>[dspace]/handle-server/config.dct</literal> file to include the following lines in the <literal>&quot;server_config&quot;</literal> clause: </para>
<screen>
&quot;storage_type&quot; = &quot;CUSTOM&quot;
&quot;storage_class&quot; =
&quot;org.dspace.handle.HandlePlugin&quot;
</screen>
<para>This tells the Handle server to get information about individual Handles from the DSpace code.</para>
</listitem>
</itemizedlist>
<para>Whichever approach you take, start the Handle server with <literal>[dspace]/bin/start-handle-server</literal>, as the DSpace user. Once the configuration file has been generated, you will need to go to <ulink url="http://hdl.handle.net/4263537/5014">http://hdl.handle.net/4263537/5014</ulink> to upload the generated sitebndl.zip file. The upload page will ask you for your contact information. An administrator will then create the naming authority/prefix on the root service (known as the Global Handle Registry), and notify you when this has been completed. You will not be able to continue the handle server installation until you receive further information concerning your naming authority.</para>
<para>Note that since the DSpace code manages individual Handles, administrative operations such as Handle creation and modification aren&apos;t supported by DSpace&apos;s Handle server.</para>
<para>If you need to update the handle prefix on items created before the CNRI registration process you can run the <literal>[dspace]/bin/update-handle-prefix script</literal>. You may need to do this if you loaded items prior to CNRI registration (e.g. setting up a demonstration system prior to migrating it to production). The script takes the current and new prefix as parameters. For example:</para>
<para>
<literal>[dspace]/bin/update-handle-prefix 123456789 1303</literal>
</para>
<para>will change any handles currently assigned prefix 123456789 to prefix 1303, so for example handle 123456789/23 will be updated to 1303/23 in the database.</para>
</section>
<section remap="h3">
<title><anchor id="docbook-install.html-sitemaps" xreflabel="Google and HTML sitemaps"/>Google and HTML sitemaps</title>
<para>To aid web crawlers index the content within your repository, you can make use of sitemaps. There are currently two forms of sitemaps included in DSpace; Google sitemaps and HTML sitemaps.</para>
<para>Sitemaps allow DSpace to expose it&apos;s content without the crawlers having to index every page. HTML sitemaps provide a list of all items, collections and communities in HTML format, whilst Google sitemaps provide the same information in gzipped XML format.</para>
<para>To generate the sitemaps, you need to run <literal>[dspace]/bin/generate-sitemaps</literal> This creates the sitemaps in <literal>[dspace]/sitemaps/</literal></para>
<para>The sitemaps can be accessed from the following URLs:</para>
<itemizedlist>
<listitem>
<para> http://dspace.example.com/dspace/sitemap - Index sitemap</para>
</listitem>
<listitem>
<para> http://dspace.example.com/dspace/sitemap?map=0 - First list of items (up to 50,000)</para>
</listitem>
<listitem>
<para> http://dspace.example.com/dspace/sitemap?map=n - Subsequent lists of items (e.g. 50,0001 to 100,000) etc...</para>
</listitem>
</itemizedlist>
<para> HTML sitemaps follow the same procedure: <itemizedlist>
<listitem>
<para> http://dspace.example.com/dspace/htmlmap - Index sitemap</para>
</listitem>
<listitem>
<para> etc...</para>
</listitem>
</itemizedlist>
</para>
<para> When running <literal>[dspace]/bin/generate-sitemaps</literal> the script informs Google that the sitemaps have been updated. For this update to register correctly, you must first register your Google sitemap index page (<literal>/dspace/sitemap</literal>) with Google at <ulink url="http://www.google.com/webmasters/sitemaps/">http://www.google.com/webmasters/sitemaps/</ulink>. If your DSpace server requires the use of a HTTP proxy to connect to the Internet, ensure that you have set <literal>http.proxy.host</literal> and <literal>http.proxy.port</literal> in <literal>[dspace]/config/dspace.cfg</literal></para>
<para>The URL for pinging Google, and in future, other search engines, is configured in <literal>[dspace]/config/dspace.cfg</literal> using the <literal>sitemap.engineurls</literal> setting where you can provide a comma-separated list of URLs to &apos;ping&apos;.</para>
<para>You can generate the sitemaps automatically every day using an additional cron job:</para>
<screen>
# Generate sitemaps
0 6 * * * [dspace]/bin/generate-sitemaps
</screen>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-windows" xreflabel="Windows Installation"/>Windows Installation</title>
<section remap="h3">
<title>Pre-requisite Software</title>
<para>You&apos;ll need to install this pre-requisite software:</para>
<itemizedlist>
<listitem>
<para> <ulink url="http://java.sun.com/">Java SDK 1.5</ulink> or later (standard SDK is fine, you don&apos;t need J2EE)</para>
</listitem>
<listitem>
<para> <ulink url="http://www.postgresql.org/ftp/">PostgreSQL 8.x for Windows</ulink> OR <ulink url="http://www.oracle.com/database/">Oracle 9 or later</ulink>.</para>
<itemizedlist>
<listitem>
<para> If you install PostgreSQL, it&apos;s recommended to select to install the pgAdmin III tool</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> <ulink url="http://ant.apache.org/">Apache Ant 1.6.2 or later</ulink>. Unzip the package in <literal>C:\</literal> and add <literal>C:\apache-ant-1.6.2\bin</literal> to the <literal>PATH</literal> environment variable. For Ant to work properly, you should ensure that <literal>JAVA_HOME</literal> is set.</para>
</listitem>
<listitem>
<para>
<ulink url="http://tomcat.apache.org/">Jakarta Tomcat 5.x or later</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://maven.apache.org/">Apache Maven 2.0.8 or later</ulink>
</para>
</listitem>
</itemizedlist>
</section>
<section remap="h3">
<title>Installation Steps</title>
<orderedlist>
<listitem>
<para> Download the DSpace source from <ulink url="http://sourceforge.net/projects/dspace">SourceForge</ulink> and untar it (<ulink url="http://www.winzip.com/">WinZip</ulink> will do this)</para>
</listitem>
<listitem>
<para> Ensure the PostgreSQL service is running, and then run pgAdmin III (Start -&gt; PostgreSQL 8.0 -&gt; pgAdmin III). Connect to the local database as the postgres user and:</para>
<itemizedlist>
<listitem>
<para> Create a &apos;Login Role&apos; (user) called <literal>dspace</literal> with the password <literal>dspace</literal></para>
</listitem>
<listitem>
<para> Create a database called <literal>dspace</literal> owned by the user <literal>dspace</literal>, with UTF-8 encoding</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Update paths in <literal>[dspace-source]\dspace\config\dspace.cfg</literal>. <emphasis role="bold">Note:</emphasis> Use forward slashes / for path separators, though you can still use drive letters, e.g.:</para>
<para>
<literal>dspace.dir = C:/DSpace</literal>
</para>
<para>Make sure you change all of the parameters with file paths to suit, specifically:</para>
<screen>
dspace.dir
config.template.log4j.properties
config.template.log4j-handle-plugin.properties
config.template.oaicat.properties
assetstore.dir
log.dir
upload.temp.dir
report.dir
handle.dir
</screen>
</listitem>
<listitem>
<para> Create the directory for the DSpace installation (e.g. <literal>C:\DSpace</literal>)</para>
</listitem>
<listitem>
<para> Generate the DSpace installation package by running the following from commandline (cmd) from your <literal>[dspace-source]/dspace/</literal> directory: </para>
<screen>
mvn package
</screen>
<para>Note #1: This will generate the DSpace installation package in your <literal>[dspace-source]/dspace/target/dspace-[version]-build.dir/</literal> directory.</para>
<para>Note #2: Without any extra arguments, the DSpace installation package is initialized for PostgreSQL.</para>
<para> If you want to use Oracle instead, you should build the DSpace installation package as follows:</para>
<screen>
mvn -Ddb.name=oracle package
</screen>
</listitem>
<listitem>
<para> Initialize the DSpace database and install DSpace to <literal>[dspace]</literal> (e.g. <literal>C:\DSpace</literal>) by running the following from commandline from your <literal>[dspace-source]/dspace/target/dspace-[version]-build.dir/</literal> directory:</para>
<screen>
ant fresh_install
</screen>
<para><emphasis role="bold">Note:</emphasis> to see a complete list of build targets, run</para>
<screen>
ant help
</screen>
</listitem>
<listitem>
<para> Create an administrator account, by running the following from your <literal>[dspace]</literal> (e.g. <literal>C:\DSpace</literal>) directory</para>
<para>
<literal>[dspace]\bin\dsrun org.dspace.administer.CreateAdministrator</literal>
</para>
<para>and enter the required information</para>
</listitem>
<listitem>
<para> Copy the Web application directories from <literal>[dspace]\webapps\</literal> to Tomcat&apos;s webapps dir, which should be somewhere like <literal>C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps</literal></para>
<itemizedlist>
<listitem>
<para> Alternatively, Tell your Tomcat installation where to find your DSpace web application(s). As an example, in the <literal>&lt;Host&gt;</literal> section of your <literal>[tomcat]/conf/server.xml</literal> you could add lines similar to the following (but replace <literal>[dspace]</literal> with your installation location):</para>
<screen>
&lt;!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface --&gt;
&lt;Context path=&quot;/jspui&quot; docBase=&quot;[dspace]\webapps\jspui&quot; debug=&quot;0&quot;
reloadable=&quot;true&quot; cachingAllowed=&quot;false&quot;
allowLinking=&quot;true&quot;/&gt;
&lt;!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface --&gt;
&lt;Context path=&quot;/oai&quot; docBase=&quot;[dspace]\webapps\oai&quot; debug=&quot;0&quot;
reloadable=&quot;true&quot; cachingAllowed=&quot;false&quot;
allowLinking=&quot;true&quot;/&gt;
</screen>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Start the Tomcat service</para>
</listitem>
<listitem>
<para> Browse to either <literal>http://localhost:8080/jspui</literal> or <literal>http://localhost:8080/xmlui</literal>. You should see the DSpace home page for either the JSPUI or XMLUI, respectively.</para>
</listitem>
</orderedlist>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-checking" xreflabel="Checking Your Installation"/>Checking Your Installation</title>
<para>TODO</para>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-knownbugs" xreflabel="Known Bugs"/>Known Bugs</title>
<para>In any software project of the scale of DSpace, there will be bugs. Sometimes, a stable version of DSpace includes known bugs. We do not always wait until every known bug is fixed before a release. If the software is sufficiently stable and an improvement on the previous release, and the bugs are minor and have known workarounds, we release it to enable the community to take advantage of those improvements.</para>
<para>The known bugs in a release are documented in the <literal>KNOWN_BUGS</literal> file in the source package.</para>
<para>Please see the <ulink url="#">DSpace bug tracker</ulink> for further information on current bugs, and to find out if the bug has subsequently been fixed. This is also where you can report any further bugs you find.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-install.html-problems" xreflabel="Common Problems"/>Common Problems</title>
<para>In an ideal world everyone would follow the above steps and have a fully functioning DSpace. Of couse, in the real world it doesn&apos;t always seem to work out that way. This section lists common problems that people encounter when installing DSpace, and likely causes and fixes. This is likely to grow over time as we learn about users&apos; experiences.</para>
<variablelist>
<varlistentry>
<term>Database errors occur when you run <literal>ant fresh_install</literal></term>
<listitem>
<para> There are two common errors that occur. If your error looks like this--</para>
<screen>
[java] 2004-03-25 15:17:07,730 INFO
org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database
[java] 2004-03-25 15:17:08,816 FATAL
org.dspace.storage.rdbms.InitializeDatabase @ Caught exception:
[java] org.postgresql.util.PSQLException: Connection refused. Check
that the hostname and port are correct and that the postmaster is
accepting TCP/IP connections.
[java] at
org.postgresql.jdbc1.AbstractJdbc1Connection.openConnection(AbstractJd
bc1Connection.java:204)
[java] at org.postgresql.Driver.connect(Driver.java:139)
</screen>
<para>it usually means you haven&apos;t yet added the relevant configuration parameter to your PostgreSQL configuration <link linkend="docbook-install.html-enabletcpip">(see above)</link>, or perhaps you haven&apos;t restarted PostgreSQL after making the change. Also, make sure that the <literal>db.username</literal> and <literal>db.password</literal> properties are correctly set in <literal>[dspace-source]/config/dspace.cfg</literal>.</para>
<para>An easy way to check that your DB is working OK over TCP/IP is to try this on the command line:</para>
<screen>
psql -U dspace -W -h localhost
</screen>
<para>Enter the <literal>dspace</literal><emphasis>database</emphasis> password, and you should be dropped into the psql tool with a <literal>dspace=&gt;</literal> prompt.</para>
<para>Another common error looks like this:</para>
<screen>
[java] 2004-03-25 16:37:16,757 INFO
org.dspace.storage.rdbms.InitializeDatabase @ Initializing Database
[java] 2004-03-25 16:37:17,139 WARN
org.dspace.storage.rdbms.DatabaseManager @ Exception initializing DB
pool
[java] java.lang.ClassNotFoundException: org.postgresql.Driver
[java] at java.net.URLClassLoader$1.run(URLClassLoader.java:198)
[java] at java.security.AccessController.doPrivileged(Native
Method)
[java] at
java.net.URLClassLoader.findClass(URLClassLoader.java:186)
</screen>
<para>This means that the PostgreSQL JDBC driver is not present in <literal>[dspace-source]/lib</literal>. <link linkend="docbook-install.html-pgdriver">See above.</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Tomcat doesn&apos;t shut down</term>
<listitem>
<para> If you&apos;re trying to tweak Tomcat&apos;s configuration but nothing seems to make a difference to the error you&apos;re seeing, you might find that Tomcat hasn&apos;t been shutting down properly, perhaps because it&apos;s waiting for a stale connection to close gracefully which won&apos;t happen. To see if this is the case, try:</para>
<screen>
ps -ef | grep java
</screen>
<para>and look for Tomcat&apos;s Java processes. If they stay arround after running Tomcat&apos;s <literal>shutdown.sh</literal> script, trying <literal>kill</literal>ing them (with <literal>-9</literal> if necessary), then starting Tomcat again.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Database connections don&apos;t work, or accessing DSpace takes forever</term>
<listitem>
<para> If you find that when you try to access a DSpace Web page and your browser sits there connecting, or if the database connections fail, you might find that a &apos;zombie&apos; database connection is hanging around preventing normal operation. To see if this is the case, try:</para>
<screen>
ps -ef | grep postgres
</screen>
<para>You might see some processes like this</para>
<screen>
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace
127.0.0.1 idle in transaction
</screen>
<para>This is normal--DSpace maintains a &apos;pool&apos; of open database connections, which are re-used to avoid the overhead of constantly opening and closing connections. If they&apos;re &apos;idle&apos; it&apos;s OK; they&apos;re waiting to be used. However sometimes, if something went wrong, they might be stuck in the middle of a query, which seems to prevent other connections from operating, e.g.:</para>
<screen>
dspace 16325 1997 0 Feb 14 ? 0:00 postgres: dspace dspace
127.0.0.1 SELECT
</screen>
<para>This means the connection is in the middle of a <literal>SELECT</literal> operation, and if you&apos;re not using DSpace right that instant, it&apos;s probably a &apos;zombie&apos; connection. If this is the case, try <literal>kill</literal>ing the process, and stopping and restarting Tomcat.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</chapter>

59
dspace/docs/docbook/introduction.xml Normal file
View File

@@ -0,0 +1,59 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Introduction</title>
<para>DSpace is an open source software platform that enables organisations to:</para>
<itemizedlist>
<listitem>
<para> capture and describe digital material using a submission workflow module, or a variety of programmatic ingest options</para>
</listitem>
<listitem>
<para> distribute an organisation&apos;s digital assets over the web through a search and retrieval system</para>
</listitem>
<listitem>
<para> preserve digital assets over the long term</para>
</listitem>
</itemizedlist>
<para>This system documentation includes <ulink url="functional.html">a functional overview of the system</ulink>, which is a good introduction to the capabilities of the system, and should be readable by non-technical folk. Everyone should read this section first because it introduces some terminology used throughout the rest of the documentation.</para>
<para>For people actually running a DSpace service, there is <ulink url="install.html">an installation guide</ulink>, and sections on <ulink url="configure.html">configuration</ulink> and <ulink url="directories.html">the directory structure</ulink>. Note that as of DSpace 1.2, the administration user interface guide is now on-line help available from within the DSpace system.</para>
<para>Finally, for those interested in the details of how DSpace works, and those potentially interested in modifying the code for their own purposes, there is <ulink url="architecture.html">a detailed architecture and design section</ulink>.</para>
<para>Other good sources of information are:</para>
<itemizedlist>
<listitem>
<para> The DSpace Public API Javadocs. Build these with the command <literal>mvn javadoc:javadoc</literal>.</para>
</listitem>
<listitem>
<para> The <ulink url="http://wiki.dspace.org/">DSpace Wiki</ulink> contains stacks of useful information about the DSpace platform and the work people are doing with it. You are strongly encouraged to visit this site and add information about your own work. Useful Wiki areas are: </para>
<itemizedlist>
<listitem>
<para><ulink url="http://wiki.dspace.org/DspaceResources">A list of DSpace resources</ulink> (Web sites, mailing lists etc.)</para>
</listitem>
<listitem>
<para>
<ulink url="http://wiki.dspace.org/TechnicalFaq">Technical FAQ</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://wiki.dspace.org/DspaceProjects">A list of projects using DSpace</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://wiki.dspace.org/ContributionGuidelines">Guidelines for contributing back to DSpace</ulink>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><ulink url="http://www.dspace.org/">www.dspace.org</ulink> has announcements and contains useful information about bringing up an instance of DSpace at your organization.</para>
</listitem>
<listitem>
<para> The <ulink url="#">dspace-tech e-mail list on SourceForge</ulink> is the recommended place to ask questions, since a growing community of DSpace developers and users is on hand on that list to help with any questions you might have. The e-mail archive of that list is a useful resource.</para>
</listitem>
<listitem>
<para> The <ulink url="#">dspace-devel e-mail list</ulink>, for those developing with the DSpace with a view to contributing to the core DSpace code.</para>
</listitem>
</itemizedlist>
</chapter>

20
dspace/docs/docbook/print.xsl Normal file
View File

@@ -0,0 +1,20 @@
<?xml version='1.0'?>
<xsl:stylesheet
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
<xsl:template match="lineannotation">
<fo:inline font-style="italic">
<xsl:call-template name="inline.charseq"/>
</fo:inline>
</xsl:template>
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="wrap-option">wrap</xsl:attribute>
<xsl:attribute name="hyphenation-character">\</xsl:attribute>
</xsl:attribute-set>
</xsl:stylesheet>

255
dspace/docs/docbook/storage.xml Normal file
View File

@@ -0,0 +1,255 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>DSpace System Documentation: Storage Layer</title>
<para>
<ulink url="architecture.html">Back to architecture overview</ulink>
</para>
<section remap="h2">
<title><anchor id="docbook-storage.html-rdbms" xreflabel="RDBMS"/>RDBMS</title>
<para>DSpace uses a relational database to store all information about the organization of content, metadata about the content, information about e-people and authorization, and the state of currently-running workflows. The DSpace system also uses the relational database in order to maintain indices that users can browse.</para>
<para>
<ulink url="image/db-schema.gif">Graphical visualization of the relational database</ulink>
</para>
<para>Most of the functionality that DSpace uses can be offered by any standard SQL database that supports transactions. Presently, the browse indices use some features specific to <ulink url="http://www.postgresql.org/">PostgreSQL</ulink> and <ulink url="http://www.oracle.com/database/">Oracle</ulink>, so some modification to the code would be needed before DSpace would function fully with an alternative database back-end.</para>
<para>The <literal>org.dspace.storage.rdbms</literal> package provides access to an SQL database in a somewhat simpler form than using JDBC directly. The main class is <literal>DatabaseManager</literal>, which executes SQL queries and returns <literal>TableRow</literal> or <literal>TableRowIterator</literal> objects. The <literal>InitializeDatabase</literal> class is used to load SQL into the database via JDBC, for example to set up the schema.</para>
<para>All calls to the <literal>Database Manager</literal> require a <ulink url="business.html#core">DSpace <literal>Context</literal> object</ulink>. Example use of the database manager API is given in the <literal>org.dspace.storage.rdbms</literal> package Javadoc.</para>
<para>The database schema used by DSpace (for PostgreSQL) is stored in <literal>[dspace-source]/dspace/etc/database_schema.sql</literal> in the source distribution. It is stored in the form of SQL that can be fed straight into the DBMS to construct the database. The schema SQL file also directly creates two e-person groups in the database that are required for the system to function properly.</para>
<para>Also in <literal>[dspace-source]/dspace/etc</literal> are various SQL files called <literal>database_schema_1x_1y</literal>. These contain the necessary SQL commands to update a live DSpace database from version 1.<literal>x</literal> to 1.<literal>y</literal>. Note that this might not be the only part of an upgrade process: see <ulink url="update.html">Updating a DSpace Installation</ulink> for details.</para>
<para>The DSpace database code uses an SQL function <literal>getnextid</literal> to assign primary keys to newly created rows. This SQL function must be safe to use if several JVMs are accessing the database at once; for example, the Web UI might be creating new rows in the database at the same time as the batch item importer. The PostgreSQL-specific implementation of the method uses <literal>SEQUENCES</literal> for each table in order to create new IDs. If an alternative database backend were to be used, the implementation of <literal>getnextid</literal> could be updated to operate with that specific DBMS.</para>
<para>The <literal>etc</literal> directory in the source distribution contains two further SQL files. <literal>clean-database.sql</literal> contains the SQL necessary to completely clean out the database, so use with caution! The Ant target <literal>clean_database</literal> can be used to execute this. <literal>update-sequences.sql</literal> contains SQL to reset the primary key generation sequences to appropriate values. You&apos;d need to do this if, for example, you&apos;re restoring a backup database dump which creates rows with specific primary keys already defined. In such a case, the sequences would allocate primary keys that were already used.</para>
<para>Versions of the <literal>*.sql*</literal> files for Oracle are stored in <literal>[dspace-source]/dspace/etc/oracle</literal>. These need to be copied over their PostgreSQL counterparts in <literal>[dspace-source]/dspace/etc</literal> prior to installation.</para>
<section remap="h3">
<title>Maintenance and Backup</title>
<para>When using PostgreSQL, it&apos;s a good idea to perform regular &apos;vacuuming&apos; of the database to optimize performance. This is performed by the <literal>vacuumdb</literal> command which can be executed via a &apos;cron&apos; job, for example by putting this in the system <literal>crontab</literal>:</para>
<screen>
# clean up the database nightly
40 2 * * * /usr/local/pgsql/bin/vacuumdb --analyze dspace &gt; /dev/null
2&gt;&amp;1
</screen>
<para>The DSpace database can be backed up and restored using usual methods, for example with <literal>pg_dump</literal> and <literal>psql</literal>. However when restoring a database, you will need to perform these additional steps:</para>
<itemizedlist>
<listitem>
<para> The <literal>fresh_install</literal> target loads up the initial contents of the Dublin Core type and bitstream format registries, as well as two entries in the <literal>epersongroup</literal> table for the system anonymous and administrator groups. Before you restore a raw backup of your database you will need to remove these, since they will already exist in your backup, possibly having been modified. For example, use:</para>
<screen>
DELETE FROM dctyperegistry;
DELETE FROM bitstreamformatregistry;
DELETE FROM epersongroup;
</screen>
</listitem>
<listitem>
<para> After restoring a backup, you will need to reset the primary key generation sequences so that they do not produce already-used primary keys. Do this by executing the SQL in <literal>[dspace-source]/dspace/etc/update-sequences.sql</literal>, for example with:</para>
<screen>
psql -U dspace -f <emphasis>
[dspace-source]</emphasis>/dspace/etc/update-sequences.sql
</screen>
</listitem>
</itemizedlist>
<para>Future updates of DSpace may involve minor changes to the database schema. Specific instructions on how to update the schema whilst keeping live data will be included. The current schema also contains a few currently unused database columns, to be used for extra functionality in future releases. These unused columns have been added in advance to minimize the effort required to upgrade.</para>
</section>
<section remap="h3">
<title>Configuring the RDBMS Component</title>
<para>The database manager is configured with the following properties in <literal>dspace.cfg</literal>:</para>
<informaltable frame="none">
<tgroup cols="2">
<colspec colname="c1" colwidth="50*"/>
<colspec colname="c2" colwidth="50*"/>
<tbody>
<row>
<entry>
<para>
<literal>db.url</literal>
</para>
</entry>
<entry>
<para>The JDBC URL to use for accessing the database. This should not point to a connection pool, since DSpace already implements a connection pool.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>db.driver</literal>
</para>
</entry>
<entry>
<para>JDBC driver class name. Since presently, DSpace uses PostgreSQL-specific features, this should be <literal>org.postgresql.Driver</literal>.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>db.username</literal>
</para>
</entry>
<entry>
<para>Username to use when accessing the database.</para>
</entry>
</row>
<row>
<entry>
<para>
<literal>db.password</literal>
</para>
</entry>
<entry>
<para>Corresponding password ot use when accessing the database.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-storage.html-bitstreams" xreflabel="Bitstream Store"/>Bitstream Store</title>
<para>DSpace offers two means for storing content. The first is in the file system on the server. The second is using <ulink url="http://www.sdsc.edu/srb">SRB (Storage Resource Broker)</ulink>. Both are achieved using a simple, lightweight API.</para>
<para>SRB is purely an option but may be used in lieu of the server&apos;s file system or in addition to the file system. Without going into a full description, SRB is a very robust, sophisticated storage manager that offers essentially unlimited storage and straightforward means to replicate (in simple terms, backup) the content on other local or remote storage resources.</para>
<para>The terms &quot;store&quot;, &quot;retrieve&quot;, &quot;in the system&quot;, &quot;storage&quot;, and so forth, used below can refer to storage in the file system on the server (&quot;traditional&quot;) or in SRB.</para>
<para>The <literal>BitstreamStorageManager</literal> provides low-level access to bitstreams stored in the system. In general, it should not be used directly; instead, use the <literal>Bitstream</literal> object in the <ulink url="business.html#content">content management API</ulink> since that encapsulated authorization and other metadata to do with a bitstream that are not maintained by the <literal>BitstreamStorageManager</literal>.</para>
<para>The bitstream storage manager provides three methods that store, retrieve and delete bitstreams. Bitstreams are referred to by their &apos;ID&apos;; that is the primary key <literal>bitstream_id</literal> column of the corresponding row in the database.</para>
<para>As of DSpace version 1.1, there can be multiple bitstream stores. Each of these bitstream stores can be traditional storage or SRB storage. This means that the potential storage of a DSpace system is not bound by the maximum size of a single disk or file system and also that traditional and SRB storage can be combined in one DSpace installation. Both traditional and SRB storage are specified by <ulink url="configure.html">configuration parameters</ulink>. Also see Configuring the Bitstream Store below.</para>
<para>Stores are numbered, starting with zero, then counting upwards. Each bitstream entry in the database has a store number, used to retrieve the bitstream when required.</para>
<para>At the moment, the store in which new bitstreams are placed is decided using a configuration parameter, and there is no provision for moving bitstreams between stores. Administrative tools for manipulating bitstreams and stores will be provided in future releases. Right now you can move a whole store (e.g. you could move store number 1 from <literal>/localdisk/store</literal> to <literal>/fs/anotherdisk/store</literal> but it would still have to be store number 1 and have the exact same contents.</para>
<para>Bitstreams also have an 38-digit internal ID, different from the primary key ID of the bitstream table row. This is not visible or used outside of the bitstream storage manager. It is used to determine the exact location (relative to the relevant store directory) that the bitstream is stored in traditional or SRB storage. The first three pairs of digits are the directory path that the bitstream is stored under. The bitstream is stored in a file with the internal ID as the filename.</para>
<para>For example, a bitstream with the internal ID <literal>12345678901234567890123456789012345678</literal> is stored in the directory:</para>
<screen>
(assetstore dir)/12/34/56/12345678901234567890123456789012345678
</screen>
<para>The reasons for storing files this way are:</para>
<itemizedlist>
<listitem>
<para> Using a randomly-generated 38-digit number means that the &apos;number space&apos; is less cluttered than simply using the primary keys, which are allocated sequentially and are thus close together. This means that the bitstreams in the store are distributed around the directory structure, improving access efficiency.</para>
</listitem>
<listitem>
<para> The internal ID is used as the filename partly to avoid requiring an extra lookup of the filename of the bitstream, and partly because bitstreams may be received from a variety of operating systems. The original name of a bitstream may be an illegal UNIX filename.</para>
</listitem>
</itemizedlist>
<para>When storing a bitstream, the <literal>BitstreamStorageManager</literal> DOES set the following fields in the corresponding database table row:</para>
<itemizedlist>
<listitem>
<para>
<literal>bitstream_id</literal>
</para>
</listitem>
<listitem>
<para>
<literal>size</literal>
</para>
</listitem>
<listitem>
<para>
<literal>checksum</literal>
</para>
</listitem>
<listitem>
<para>
<literal>checksum_algorithm</literal>
</para>
</listitem>
<listitem>
<para>
<literal>internal_id</literal>
</para>
</listitem>
<listitem>
<para>
<literal>deleted</literal>
</para>
</listitem>
<listitem>
<para>
<literal>store_number</literal>
</para>
</listitem>
</itemizedlist>
<para>The remaining fields are the responsibility of the <literal>Bitstream</literal> content management API class.</para>
<para>The bitstream storage manager is fully transaction-safe. In order to implement transaction-safety, the following algorithm is used to store bitstreams:</para>
<orderedlist>
<listitem>
<para> A database connection is created, separately from the currently active connection in the <ulink url="business.html#core">current DSpace context</ulink>.</para>
</listitem>
<listitem>
<para> An unique internal identifier (separate from the database primary key) is generated.</para>
</listitem>
<listitem>
<para> The bitstream DB table row is created using this new connection, with the <literal>deleted</literal> column set to <literal>true</literal>.</para>
</listitem>
<listitem>
<para> The new connection is <literal>commit</literal>ted, so the &apos;deleted&apos; bitstream row is written to the database</para>
</listitem>
<listitem>
<para> The bitstream itself is stored in a file in the configured &apos;asset store directory&apos;, with a directory path and filename derived from the internal ID</para>
</listitem>
<listitem>
<para> The <literal>deleted</literal> flag in the bitstream row is set to <literal>false</literal>. This will occur (or not) as part of the current DSpace <literal>Context</literal>.</para>
</listitem>
</orderedlist>
<para>This means that should anything go wrong before, during or after the bitstream storage, only one of the following can be true:</para>
<itemizedlist>
<listitem>
<para> No bitstream table row was created, and no file was stored</para>
</listitem>
<listitem>
<para> A bitstream table row with <literal>deleted=true</literal> was created, no file was stored</para>
</listitem>
<listitem>
<para> A bitstream table row with <literal>deleted=true</literal> was created, and a file was stored</para>
</listitem>
</itemizedlist>
<para>None of these affect the integrity of the data in the database or bitstream store.</para>
<para>Similarly, when a bitstream is deleted for some reason, its <literal>deleted</literal> flag is set to true as part of the overall transaction, and the corresponding file in storage is <emphasis>not</emphasis> deleted.</para>
<para>The above techniques mean that the bitstream storage manager is transaction-safe. Over time, the bitstream database table and file store may contain a number of &apos;deleted&apos; bitstreams. The <literal>cleanup</literal> method of <literal>BitstreamStorageManager</literal> goes through these deleted rows, and actually deletes them along with any corresponding files left in the storage. It only removes &apos;deleted&apos; bitstreams that are more than one hour old, just in case cleanup is happening in the middle of a storage operation.</para>
<para>This cleanup can be invoked from the command line via the <literal>Cleanup</literal> class, which can in turn be easily executed from a shell on the server machine using <literal>/dspace/bin/cleanup</literal>. You might like to have this run regularly by <literal>cron</literal>, though since DSpace is read-lots, write-not-so-much it doesn&apos;t need to be run very often.</para>
<section remap="h3">
<title>Backup</title>
<para>The bitstreams (files) in traditional storage may be backed up very easily by simply &apos;tarring&apos; or &apos;zipping&apos; the <literal>assetstore</literal> directory (or whichever directory is configured in <literal>dspace.cfg</literal>). Restoring is as simple as extracting the backed-up compressed file in the appropriate location.</para>
<para>Similar means could be used for SRB, but SRB offers many more options for managing backup.</para>
<para>It is important to note that since the bitstream storage manager holds the bitstreams in storage, and information about them in the database, that a database backup and a backup of the files in the bitstream store must be made at the same time; the bitstream data in the database must correspond to the stored files.</para>
<para>Of course, it isn&apos;t really ideal to &apos;freeze&apos; the system while backing up to ensure that the database and files match up. Since DSpace uses the bitstream data in the database as the authoritative record, it&apos;s best to back up the database before the files. This is because it&apos;s better to have a bitstream in storage but not the database (effectively non-existent to DSpace) than a bitstream record in the database but not storage, since people would be able to find the bitstream but not actually get the contents.</para>
</section>
<section remap="h3">
<title>Configuring the Bitstream Store</title>
<para>Both traditional and SRB bitstream stores are configured in <literal>dspace.cfg</literal>.</para>
<section remap="h4">
<title>Configuring Traditonal Storage</title>
<para>Bitstream stores in the file system on the server are configured like this:</para>
<screen>
assetstore.dir = <emphasis> [dspace]</emphasis>/assetstore
</screen>
<para>(Remember that <emphasis>[dspace]</emphasis> is a placeholder for the actual name of your DSpace install directory).</para>
<para>The above example specifies a single asset store.</para>
<screen>
assetstore.dir = <emphasis> [dspace]</emphasis>/assetstore_0
assetstore.dir.1 = /mnt/other_filesystem/assetstore_1
</screen>
<para>The above example specifies two asset stores. assetstore.dir specifies the asset store number 0 (zero); after that use assetstore.dir.1, assetstore.dir.2 and so on. The particular asset store a bitstream is stored in is held in the database, so don&apos;t move bitstreams between asset stores, and don&apos;t renumber them.</para>
<para>By default, newly created bitstreams are put in asset store 0 (i.e. the one specified by the assetstore.dir property.) This allows backwards compatibility with pre-DSpace 1.1 configurations. To change this, for example when asset store 0 is getting full, add a line to <literal>dspace.cfg</literal> like:</para>
<screen>
assetstore.incoming = 1
</screen>
<para>Then restart DSpace (Tomcat). New bitstreams will be written to the asset store specified by <literal>assetstore.dir.1</literal>, which is <literal>/mnt/other_filesystem/assetstore_1</literal> in the above example.</para>
</section>
<section remap="h4">
<title>Configuring SRB Storage</title>
<para>The same framework is used to configure SRB storage. That is, the asset store number (0..n) can reference a file system directory as above or it can reference a set of SRB account parameters. But any particular asset store number can reference one or the other but not both. This way traditional and SRB storage can both be used but with different asset store numbers. The same cautions mentioned above apply to SRB asset stores as well: The particular asset store a bitstream is stored in is held in the database, so don&apos;t move bitstreams between asset stores, and don&apos;t renumber them.</para>
<para>For example, let&apos;s say asset store number 1 will refer to SRB. The there will be a set of SRB account parameters like this:</para>
<screen>
srb.host.1 = mysrbmcathost.myu.edu
srb.port.1 = 5544
srb.mcatzone.1 = mysrbzone
srb.mdasdomainname.1 = mysrbdomain
srb.defaultstorageresource.1 = mydefaultsrbresource
srb.username.1 = mysrbuser
srb.password.1 = mysrbpassword
srb.homedirectory.1 = /mysrbzone/home/mysrbuser.mysrbdomain
srb.parentdir.1 = mysrbdspaceassetstore
</screen>
<para>Several of the terms, such as <literal>mcatzone</literal>, have meaning only in the SRB context and will be familiar to SRB users. The last, <literal>srb.parentdir.n</literal>, can be used to used for addition (SRB) upper directory structure within an SRB account. This property value could be blank as well.</para>
<para>(If asset store 0 would refer to SRB it would be <literal>srb.host =</literal> ..., <literal>srb.port =</literal> ..., and so on (<literal>.0</literal> omitted) to be consistent with the traditional storage configuration above.)</para>
<para>The similar use of <literal>assetstore.incoming</literal> to reference asset store 0 (default) or 1..n (explicit property) means that new bitstreams will be written to traditional or SRB storage determined by whether a file system directory on the server is referenced or a set of SRB account parameters are referenced.</para>
<para>There are comments in dspace.cfg that further elaborate the configuration of traditional and SRB storage.</para>
</section>
</section>
</section>
</chapter>

716
dspace/docs/docbook/submission.xml Normal file
View File

@@ -0,0 +1,716 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title>Customizing and Configuring Submission User Interface</title>
<para>This page explains various customization and configuration options that are available within DSpace for the Item Submission user interface.</para>
<para>
<anchor id="docbook-submission.html-configurationFile"/>
</para>
<section remap="h2">
<title>Understanding the Submission Configuration File</title>
<para>The <literal>[dspace]/config/item-submission.xml</literal> contains the submission configurations for <emphasis>both</emphasis> the DSpace JSP user interface (JSPUI) or the DSpace XML user interface (XMLUI or Manakin). This configuration file contains detailed documentation within the file itself, which should help you better understand how to best utilize it.</para>
<section remap="h3">
<title>The Structure of <literal>item-submission.xml</literal></title>
<screen>
<literal> &lt;item-submission&gt; &lt;!-- Where submission processes are
mapped to specific Collections --&gt; &lt;submission-map&gt; &lt;name-map
collection-handle=&quot;default&quot; submission-name=&quot;traditional&quot; /&gt; ...
&lt;/submission-map&gt; &lt;!-- Where &quot;steps&quot; which are used across many
submission processes can be defined in a single place. They can then
be referred to by ID later. --&gt; &lt;step-definitions&gt; &lt;step
id=&quot;collection&quot;&gt;
&lt;processing-class&gt;org.dspace.submit.step.SelectCollectionStep&lt;/process
;/processing-class&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt; ... &lt;/step-definitions&gt; &lt;!-- Where actual submission
processes are defined and given names. Each &lt;submission-process&gt; has
many &lt;step&gt; nodes which are in the order that the steps should be
in.--&gt; &lt;submission-definitions&gt; &lt;submission-process name=&quot;traditional&quot;&gt;
... &lt;!-- Step definitions appear here! --&gt; &lt;/submission-process&gt; ...
&lt;/submission-definitions&gt; &lt;/item-submission&gt;</literal>
</screen>
<para> Because this file is in XML format, you should be familiar with XML before editing this file. By default, this file contains the &quot;traditional&quot; Item Submission Process for DSpace, which consists of the following Steps (in this order):</para>
<para>
<literal>Select Collection -&gt; Initial Questions -&gt; Describe -&gt; Upload -&gt; Verify -&gt; License -&gt; Complete</literal>
</para>
<para>If you would like to customize the steps used or the ordering of the steps, you can do so within the <literal>&lt;submission-definition&gt;</literal> section of the <literal>item-submission.xml</literal> .</para>
<para>In addition, you may also specify different Submission Processes for different DSpace Collections. This can be done in the <literal>&lt;submission-map&gt;</literal> section. The <literal>item-submission.xml</literal> file itself documents the syntax required to perform these configuration changes.</para>
<para>
<anchor id="docbook-submission.html--stepDefinitions"/>
</para>
</section>
<section remap="h3">
<title>Defining Steps (<literal>&lt;step&gt;</literal>) within the <literal>item-submission.xml</literal></title>
<para>This section describes how Steps of the Submission Process are defined within the <literal>item-submission.xml</literal>.</para>
<section remap="h4">
<title>Where to place your <literal>&lt;step&gt;</literal> definitions</title>
<para><literal>&lt;step&gt;</literal> definitions can appear in one of two places within the <literal>item-submission.xml</literal> configuration file.</para>
<orderedlist>
<listitem>
<para> Within the <literal>&lt;step-definitions&gt;</literal> section </para>
<itemizedlist>
<listitem>
<para> This is for globally defined <literal>&lt;step&gt;</literal> definitions (i.e. steps which are used in multiple <literal>&lt;submission-process&gt;</literal> definitions). Steps defined in this section <emphasis role="bold">must</emphasis> define a unique <literal>id</literal> which can be used to reference this step.</para>
</listitem>
<listitem>
<para> For example: </para>
<screen>
<literal> &lt;step-definitions&gt; &lt;step id=&quot;custom-step&quot;&gt; ...
&lt;/step&gt; ... &lt;/step-definitions&gt; </literal>
</screen>
</listitem>
<listitem>
<para> The above step definition could then be referenced from within a <literal>&lt;submission-process&gt;</literal> as simply <literal>&lt;step id=&quot;custom-step&quot;/&gt;</literal></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> Within a specific <literal>&lt;submission-process&gt;</literal> definition </para>
<itemizedlist>
<listitem>
<para> This is for steps which are specific to a single <literal>&lt;submission-process&gt;</literal> definition.</para>
</listitem>
<listitem>
<para> For example: </para>
<screen>
<literal> &lt;submission-process&gt; &lt;step&gt; ... &lt;/step&gt;
&lt;/submission-process&gt;</literal>
</screen>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
</section>
<section remap="h4">
<title>The ordering of <literal>&lt;step&gt;</literal> definitions <emphasis role="bold">matters</emphasis>!</title>
<para>The ordering of the <literal>&lt;step&gt;</literal> tags within a <literal>&lt;submission-process&gt;</literal> definition directly corresponds to the order in which those steps will appear!</para>
<para>For example, the following defines a Submission Process where the <emphasis>License</emphasis> step directly precedes the <emphasis>Initial Questions</emphasis> step (more information about the structure of the information under each &lt;step&gt; tag can be found in the section on <link linkend="docbook-submission.html-stepStructure">Structure of the &lt;step&gt; Definition</link> below):</para>
<screen>
<literal> &lt;submission-process&gt; &lt;!--Step 1 will be to Sign off on
the License--&gt; &lt;step&gt; &lt;heading&gt;submit.progressbar.license&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.LicenseStep&lt;/processing-class
ing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPLicenseStep&lt;/jspui-
t;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.LicenseSt
enseStep&lt;/xmlui-binding&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt; &lt;!--Step 2 will be to Ask Initial Questions--&gt; &lt;step&gt;
&lt;heading&gt;submit.progressbar.initial-questions&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.InitialQuestionsStep&lt;/process
;/processing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPInitialQuestionsSte
onsStep&lt;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.InitialQu
tialQuestionsStep&lt;/xmlui-binding&gt;
&lt;workflow-editable&gt;true&lt;/workflow-editable&gt; &lt;/step&gt; ...[other
steps]... &lt;/submission-process&gt; </literal>
</screen>
<para>
<anchor id="docbook-submission.html-stepStructure"/>
</para>
</section>
<section remap="h4">
<title>Structure of the &lt;step&gt; Definition</title>
<para>The same &lt;step&gt; definition is used by both the DSpace JSP user interface (JSPUI) an the DSpace XML user interface (XMLUI or Manakin). Therefore, you will notice each &lt;step&gt; definition contains information specific to each of these two interfaces.</para>
<para>The structure of the &lt;step&gt; Definition is as follows:</para>
<screen>
<literal> &lt;step&gt; &lt;heading&gt;submit.progressbar.describe&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.DescribeStep&lt;/processing-clas
sing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPDescribeStep&lt;/jspui
lt;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.DescribeS
cribeStep&lt;/xmlui-binding&gt; &lt;workflow-editable&gt;true&lt;/workflow-editable&gt;
&lt;/step&gt; </literal>
</screen>
<para>Each <literal>step</literal> contains the following elements. The required elements are so marked:</para>
<variablelist>
<varlistentry>
<term>
<emphasis role="bold">heading</emphasis>
</term>
<listitem>
<para>Partial I18N key (defined in <literal>Messages.properties</literal> for JSPUI or <literal>messages.xml</literal> for XMLUI) which corresponds to the text that should be displayed in the submission Progress Bar for this step. This partial I18N key is prefixed within either the Messages.properties or messages.xml file, depending on the interface you are using. Therefore, to find the actual key, you will need to search for the partial key with the following prefix: <itemizedlist>
<listitem>
<para> XMLUI: prefix is <literal>xmlui.Submission.</literal> (e.g. &quot;xmlui.Submission.submit.progressbar.describe&quot; for &apos;Describe&apos; step)</para>
</listitem>
<listitem>
<para> JSPUI: prefix is <literal>jsp.</literal> (e.g. &quot;jsp.submit.progressbar.describe&quot; for &apos;Describe&apos; step)</para>
</listitem>
</itemizedlist>
<emphasis>The &apos;heading&apos; need not be defined if the step should not appear in the progress bar (e.g. steps which perform automated processing, i.e. non-interactive, should not appear in the progress bar).</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">processing-class</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Full Java path to the Processing Class for this Step. This Processing Class <emphasis>must</emphasis> perform the primary processing of any information gathered in this step, <emphasis>for both the XMLUI and JSPUI</emphasis>. All valid step processing classes must extend the abstract `<literal>org.dspace.submit.AbstractProcessingStep</literal>` class (or alternatively, extend one of the pre-existing step processing classes in <literal>org.dspace.submit.step.*</literal>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">jspui-binding</emphasis>
</term>
<listitem>
<para>Full Java path of the JSPUI &quot;binding&quot; class for this Step. This &quot;binding&quot; class should initialize and call the appropriate JSPs to display the step&apos;s user interface. A valid JSPUI &quot;binding&quot; class <emphasis>must</emphasis> extend the abstract `<literal>org.dspace.app.webui.submit.JSPStep</literal>` class. <emphasis>This property need not be defined if you are using the XMLUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">xmlui-binding</emphasis>
</term>
<listitem>
<para>Full Java path of the XMLUI &quot;binding&quot; class for this Step. This &quot;binding&quot; class should generate the Manakin XML (DRI document) necessary to generate the step&apos;s user interface. A valid XMLUI &quot;binding&quot; class <emphasis>must</emphasis> extend the abstract `<literal>org.dspace.app.xmlui.submission.AbstractSubmissionStep</literal>` class. <emphasis>This property need not be defined if you are using the JSPUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">workflow-editable</emphasis>
</term>
<listitem>
<para>Defines whether or not this step can be edited during the <emphasis>Edit Metadata</emphasis> process with the DSpace approval/rejection workflow process. Possible values include <literal>true</literal> and <literal>false</literal>. If undefined, defaults to <literal>true</literal> (which means that workflow reviewers would be allowed to edit information gathered during that step).</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<anchor id="docbook-submission.html-stepOrdering"/>
</para>
</section>
</section>
</section>
<section remap="h2">
<title>Reordering/Removing Submission Steps</title>
<para>The removal of existing steps and reordering of existing steps is a relatively easy process!</para>
<para>
<emphasis role="bold">Reordering steps</emphasis>
</para>
<orderedlist>
<listitem>
<para> Locate the <literal>&lt;submission-process&gt;</literal> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it&apos;s likely the one with <literal>name=&quot;traditional&quot;</literal>, since this is the traditional DSpace submission process.</para>
</listitem>
<listitem>
<para> Reorder the <literal>&lt;step&gt;</literal> tags within that <literal>&lt;submission-process&gt;</literal> tag. Be sure to move the <emphasis>entire</emphasis><literal>&lt;step&gt;</literal> tag (i.e. everything between and including the opening <literal>&lt;step&gt;</literal> and closing <literal>&lt;/step&gt;</literal> tags). </para>
<itemizedlist>
<listitem>
<para><emphasis>Hint #1:</emphasis> The <literal>&lt;step&gt;</literal> defining the <emphasis>Review/Verify</emphasis> step only allows the user to review information from steps which appear <emphasis role="bold">before</emphasis> it. So, it&apos;s likely you&apos;d want this to appear as one of your last few steps</para>
</listitem>
<listitem>
<para><emphasis>Hint #2:</emphasis> If you are using it, the <literal>&lt;step&gt;</literal> defining the <emphasis>Initial Questions</emphasis> step should always appear <emphasis role="bold">before</emphasis> the <emphasis>Upload</emphasis> or <emphasis>Describe</emphasis> steps since it asks questions which help to set up those later steps.</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para>
<emphasis role="bold">Removing one or more steps</emphasis>
</para>
<orderedlist>
<listitem>
<para> Locate the <literal>&lt;submission-process&gt;</literal> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it&apos;s likely the one with <literal>name=&quot;traditional&quot;</literal>, since this is the traditional DSpace submission process.</para>
</listitem>
<listitem>
<para> Comment out (i.e. surround with &lt;!-- and --&gt;) the <literal>&lt;step&gt;</literal> tags which you want to remove from that <literal>&lt;submission-process&gt;</literal> tag. Be sure to comment out the <emphasis>entire</emphasis><literal>&lt;step&gt;</literal> tag (i.e. everything between and including the opening <literal>&lt;step&gt;</literal> and closing <literal>&lt;/step&gt;</literal> tags). </para>
<itemizedlist>
<listitem>
<para><emphasis>Hint #1:</emphasis> You cannot remove the <emphasis>Select a Collection</emphasis> step, as an DSpace Item cannot exist without belonging to a Collection.</para>
</listitem>
<listitem>
<para><emphasis>Hint #2:</emphasis> If you decide to remove the <literal>&lt;step&gt;</literal> defining the <emphasis>Initial Questions</emphasis> step, you should be aware that this may affect your <emphasis>Describe</emphasis> and <emphasis>Upload</emphasis> steps! The <emphasis>Initial Questions</emphasis> step asks questions which help to initialize these later steps. If you decide to remove the <emphasis>Initial Questions</emphasis> step you may wish to create a custom, automated step which will provide default answers for the questions asked!</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para>
<anchor id="docbook-submission.html-collectionSubmission"/>
</para>
</section>
<section remap="h2">
<title>Assigning a custom Submission Process to a Collection</title>
<para>Assigning a custom submission process to a Collection in DSpace involves working with the <literal>submission-map</literal> section of the <literal>item-submission.xml</literal>. For a review of the structure of the <literal>item-submission.xml</literal> see the section above on <link linkend="docbook-submission.html-configurationFile">Understanding the Submission Configuration File</link>.</para>
<para>Each <literal>name-map</literal> element within <literal>submission-map</literal> associates a collection with the name of a submission definition. Its <literal>collection-handle</literal> attribute is the Handle of the collection. Its <literal>submission-name</literal> attribute is the submission definition name, which must match the <literal>name</literal> attribute of a <literal>submission-process</literal> element (in the <literal>submission-definitions</literal> section of <literal>item-submission.xml</literal>.</para>
<para>For example, the following fragment shows how the collection with handle &quot;12345.6789/42&quot; is assigned the &quot;custom&quot; submission process:</para>
<screen>
&lt;submission-map&gt;
&lt;name-map collection-handle=&quot;<emphasis role="bold"> 12345.6789/42</emphasis>&quot; submission-name=&quot;<emphasis role="bold">
custom</emphasis>&quot; /&gt;
...
&lt;/submission-map&gt;
&lt;submission-definitions&gt;
&lt;submission-process name=&quot;<emphasis role="bold">
custom</emphasis>&quot;&gt;
...
&lt;/submission-definitions&gt;
</screen>
<para>It&apos;s a good idea to keep the definition of the <literal>default</literal> name-map from the example <literal>input-forms.xml</literal> so there is always a default for collections which do not have a custom form set.</para>
<section remap="h3">
<title>Getting A Collection&apos;s Handle</title>
<para>You will need the <emphasis>handle</emphasis> of a collection in order to assign it a custom form set. To discover the handle, go to the &quot;Communities &amp; Collections&quot; page under &quot;<emphasis role="bold">Browse</emphasis>&quot; in the left-hand menu on your DSpace home page. Then, find the link to your collection. It should look something like:</para>
<screen>
http://myhost.my.edu/dspace/handle/<emphasis role="underline">
12345.6789/42</emphasis>
</screen>
<para>The underlined part of the URL is the handle. It should look familiar to any DSpace administrator. That is what goes in the <literal>collection-handle</literal> attribute of your <literal>name-map</literal> element.</para>
<para>
<anchor id="docbook-submission.html-metadataEntry"/>
</para>
</section>
</section>
<section remap="h2">
<title>Custom Metadata-entry Pages for Submission</title>
<section remap="h3">
<title>Introduction</title>
<para>This section explains how to customize the Web forms used by submitters and editors to enter and modify the metadata for a new item. These metadata web forms are controlled by the <emphasis>Describe</emphasis> step within the Submission Process. However, they are also configurable via their own XML configuration file (<literal>input-forms.xml</literal>).</para>
<para>You can customize the &quot;default&quot; metadata forms used by all collections, and also create alternate sets of metadata forms and assign them to specific collections. In creating custom metadata forms, you can choose:</para>
<itemizedlist>
<listitem>
<para> The number of metadata-entry pages.</para>
</listitem>
<listitem>
<para> Which fields appear on each page, and their sequence.</para>
</listitem>
<listitem>
<para> Labels, prompts, and other text associated with each field.</para>
</listitem>
<listitem>
<para> List of available choices for each menu-driven field.</para>
</listitem>
</itemizedlist>
<para><emphasis role="bold">N.B.</emphasis>The cosmetic and ergonomic details of metadata entry fields remain the same as the fixed metadata pages in previous DSpace releases, and can only be altered by modifying the appropriate stylesheet and JSP pages.</para>
<para>All of the custom metadata-entry forms for a DSpace instance are controlled by a single XML file, <literal>input-forms.xml</literal>, in the <literal>config</literal> subdirectory under the DSpace home. DSpace comes with a sample configuration that implements the traditional metadata-entry forms, which also serves as a well-documented example. The rest of this section explains how to create your own sets of custom forms.</para>
</section>
<section remap="h3">
<title>Describing Custom Metadata Forms</title>
<para>The description of a set of pages through which submitters enter their metadata is called a <emphasis>form</emphasis> (although it is actually a set of forms, in the HTML sense of the term). A form is identified by a unique symbolic <emphasis>name</emphasis>. In the XML structure, the <emphasis>form</emphasis> is broken down into a series of <emphasis>pages</emphasis>: each of these represents a separate Web page for collecting metadata elements.</para>
<para>To set up one of your DSpace collections with customized submission forms, first you make an entry in the <emphasis>form-map</emphasis>. This is effectively a table that relates a collection to a form set, by connecting the collection&apos;s <emphasis>Handle</emphasis> to the form name. Collections are identified by handle because their names are mutable and not necessarily unique, while handles are unique and persistent.</para>
<para>A special map entry, for the collection handle &quot;default&quot;, defines the <emphasis>default</emphasis> form set. It applies to all collections which are not explicitly mentioned in the map. In the example XML this form set is named <literal>traditional</literal> (for the &quot;traditional&quot; DSpace user interface) but it could be named anything.</para>
</section>
<section remap="h3">
<title>The Structure of <literal>input-forms.xml</literal></title>
<para>The XML configuration file has a single top-level element, <literal>input-forms</literal>, which contains three elements in a specific order. The outline is as follows:</para>
<screen>
&lt;input-forms&gt;
&lt;-- <emphasis> Map of Collections to Form Sets</emphasis> --&gt;
&lt;form-map&gt;
&lt;name-map collection-handle=&quot;default&quot; form-name=&quot;traditional&quot;
/&gt;
...
&lt;/form-map&gt;
&lt;-- <emphasis> Form Set Definitions</emphasis> --&gt;
&lt;form-definitions&gt;
&lt;form name=&quot;traditional&quot;&gt;
...
&lt;/form-definitions&gt;
&lt;-- <emphasis> Name/Value Pairs used within Multiple Choice Widgets</emphasis>
--&gt;
&lt;form-value-pairs&gt;
&lt;value-pairs value-pairs-name=&quot;common_iso_languages&quot;
dc-term=&quot;language_iso&quot;&gt;
...
&lt;/form-value-pairs&gt;
&lt;/input-forms&gt;
</screen>
<section remap="h4">
<title>Adding a Collection Map</title>
<para>Each <literal>name-map</literal> element within <literal>form-map</literal> associates a collection with the name of a form set. Its <literal>collection-handle</literal> attribute is the Handle of the collection, and its <literal>form-name</literal> attribute is the form set name, which must match the <literal>name</literal> attribute of a <literal>form</literal> element.</para>
<para>For example, the following fragment shows how the collection with handle &quot;12345.6789/42&quot; is attached to the &quot;TechRpt&quot; form set:</para>
<screen>
&lt;form-map&gt;
&lt;name-map collection-handle=&quot;<emphasis role="bold"> 12345.6789/42</emphasis>&quot; form-name=&quot;<emphasis role="bold"> TechRpt</emphasis>&quot;
/&gt;
...
&lt;/form-map&gt;
&lt;form-definitions&gt;
&lt;form name=&quot;<emphasis role="bold">
TechRept</emphasis>&quot;&gt;
...
&lt;/form-definitions&gt;
</screen>
<para>It&apos;s a good idea to keep the definition of the <literal>default</literal> name-map from the example <literal>input-forms.xml</literal> so there is always a default for collections which do not have a custom form set.</para>
<section remap="h5">
<title>Getting A Collection&apos;s Handle</title>
<para>You will need the <emphasis>handle</emphasis> of a collection in order to assign it a custom form set. To discover the handle, go to the &quot;Communities &amp; Collections&quot; page under &quot;<emphasis role="bold">Browse</emphasis>&quot; in the left-hand menu on your DSpace home page. Then, find the link to your collection. It should look something like:</para>
<screen>
http://myhost.my.edu/dspace/handle/<emphasis role="underline">
12345.6789/42</emphasis>
</screen>
<para>The underlined part of the URL is the handle. It should look familiar to any DSpace administrator. That is what goes in the <literal>collection-handle</literal> attribute of your <literal>name-map</literal> element.</para>
</section>
</section>
<section remap="h4">
<title>Adding a Form Set</title>
<para>You can add a new form set by creating a new <literal>form</literal> element within the <literal>form-definitions</literal> element. It has one attribute, <literal>name</literal>, which as seen above must match the value of the <literal>name-map</literal> for the collections it is to be used for.</para>
<section remap="h5">
<title>Forms and Pages</title>
<para>The content of the <literal>form</literal> is a sequence of <literal>page</literal> elements. Each of these corresponds to a Web page of forms for entering metadata elements, presented in sequence between the initial &quot;Describe&quot; page and the final &quot;Verify&quot; page (which presents a summary of all the metadata collected).</para>
<para>A <literal>form</literal> must contain at least one and at most six pages. They are presented in the order they appear in the XML. Each <literal>page</literal> element must include a <literal>number</literal> attribute, that should be its sequence number, e.g.</para>
<screen>
&lt;page number=&quot;1&quot;&gt;
</screen>
<para>The <literal>page</literal> element, in turn, contains a sequence of <literal>field</literal> elements. Each field defines an interactive dialog where the submitter enters one of the Dublin Core metadata items.</para>
</section>
<section remap="h5">
<title>Composition of a Field</title>
<para>Each <literal>field</literal> contains the following elements, in the order indicated. The required sub-elements are so marked:</para>
<variablelist>
<varlistentry>
<term>
<emphasis role="bold">dc-schema</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Name of metadata schema employed, e.g. <literal>dc</literal> for Dublin Core. This value must match the value of the <literal>schema</literal> element defined in <literal>dublin-core-types.xml</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">dc-element</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Name of the Dublin Core element entered in this field, e.g. <literal>contributor</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">dc-qualifier</emphasis>
</term>
<listitem>
<para>Qualifier of the Dublin Core element entered in this field, e.g. when the field is <literal>contributor.advisor</literal> the value of this element would be <literal>advisor</literal>. Leaving this out means the input is for an unqualified DC element.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">repeatable</emphasis>
</term>
<listitem>
<para>Value is <literal>true</literal> when multiple values of this field are allowed, <literal>false</literal> otherwise. When you mark a field repeatable, the UI servlet will add a control to let the user ask for more fields to enter additional values. Intended to be used for arbitrarily-repeating fields such as subject keywords, when it is impossible to know in advance how many input boxes to provide.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">label</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Text to display as the label of this field, describing what to enter, e.g. &quot;<literal>Your Advisor&apos;s Name</literal>&quot;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">input-type</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Defines the kind of interactive widget to put in the form to collect the Dublin Core value. Content must be one of the following keywords: <itemizedlist>
<listitem>
<para><emphasis role="bold">onebox</emphasis> -- A single text-entry box.</para>
</listitem>
<listitem>
<para><emphasis role="bold">twobox</emphasis> -- A pair of simple text-entry boxes, used for <emphasis>repeatable</emphasis> values such as the DC <literal>subject</literal> item. <emphasis>Note:</emphasis> The &apos;twobox&apos; input type is rendered the same as a &apos;onebox&apos; in the XML-UI, but both allow for ease of adding multiple values.</para>
</listitem>
<listitem>
<para><emphasis role="bold">textarea</emphasis> -- Large block of text that can be entered on multiple lines, e.g. for an abstract.</para>
</listitem>
<listitem>
<para><emphasis role="bold">name</emphasis> -- Personal name, with separate fields for family name and first name. When saved they are appended in the format &apos;LastName, FirstName&apos;</para>
</listitem>
<listitem>
<para><emphasis role="bold">date</emphasis> -- Calendar date. When required, demands that at least the year be entered.</para>
</listitem>
<listitem>
<para><emphasis role="bold">series</emphasis> -- Series/Report name and number. Separate fields are provided for series name and series number, but they are appended (with a semicolon between) when saved.</para>
</listitem>
<listitem>
<para><emphasis role="bold">dropdown</emphasis> -- Choose value(s) from a &quot;drop-down&quot; menu list. <emphasis role="bold">Note:</emphasis> You must also include a value for the <literal>value-pairs-name</literal> attribute to specify a list of menu entries from which to choose. Use this to make a choice from a restricted set of options, such as for the <literal>language</literal> item.</para>
</listitem>
<listitem>
<para><emphasis role="bold">qualdrop_value</emphasis> -- Enter a &quot;qualified value&quot;, which includes <emphasis>both</emphasis> a qualifier from a drop-down menu and a free-text value. Used to enter items like alternate identifers and codes for a submitted item, e.g. the DC <literal>identifier</literal> field. <emphasis role="bold">Note:</emphasis> As for the <literal>dropdown</literal> type, you must include the <literal>value-pairs-name</literal> attribute to specify a menu choice list.</para>
</listitem>
<listitem>
<para><emphasis role="bold">list</emphasis> -- Choose value(s) from a checkbox or radio button list. If the <literal>repeatable</literal> attribute is set to <literal>true</literal>, a list of checkboxes is displayed. If the <literal>repeatable</literal> attribute is set to <literal>false</literal>, a list of radio buttons is displayed. <emphasis role="bold">Note:</emphasis> You must also include a value for the <literal>value-pairs-name</literal> attribute to specify a list of values from which to choose.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">hint</emphasis>
<emphasis>(Required)</emphasis>
</term>
<listitem>
<para>Content is the text that will appear as a &quot;hint&quot;, or instructions, next to the input fields. Can be left empty, but it must be present.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">required</emphasis>
</term>
<listitem>
<para>When this element is included with any content, it marks the field as a required input. If the user tries to leave the page without entering a value for this field, that text is displayed as a warning message. For example,</para>
<para><literal>&lt;required&gt;You must enter a title.&lt;/required&gt; Note that leaving the</literal> required element empty will <emphasis>not</emphasis> mark a field as required, e.g.:</para>
<para>
<literal>&lt;required&gt;&lt;/required&gt;</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">visibility</emphasis>
</term>
<listitem>
<para>When this optional element is included with a value, it restricts the visibility of the field to the scope defined by that value. If the element is missing or empty, the field is visible in all scopes. Currently supported scopes are: <itemizedlist>
<listitem>
<para><emphasis role="bold">workflow</emphasis> : the field will only be visible in the workflow stages of submission. This is good for hiding difficult fields for users, such as subject classifications, thereby easing the use of the submission system.</para>
</listitem>
<listitem>
<para><emphasis role="bold">submit</emphasis> : the field will only be visible in the initial submission, and not in the workflow stages.</para>
</listitem>
</itemizedlist>
For example:</para>
<para>
<literal>&lt;visibility&gt;workflow&lt;/visibility&gt;</literal>
</para>
<para> Note that it is considered a configuration error to limit a field&apos;s scope while also requiring it - an exception will be generated when this combination is detected.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Look at the example <literal>input-forms.xml</literal> and experiment with a a trial custom form to learn this specification language thoroughly. It is a very simple way to express the layout of data-entry forms, but the only way to learn all its subtleties is to use it.</para>
<para>For the use of controlled vocabularies see the <ulink url="configure.html#controlledvocabulary">Configuring Controlled Vocabularies</ulink> section.</para>
</section>
<section remap="h5">
<title>Automatically Elided Fields</title>
<para>You may notice that some fields are automatically skipped when a custom form page is displayed, depending on the kind of item being submitted. This is because the DSpace user-interface engine skips Dublin Core fields which are not needed, according to the initial description of the item. For example, if the user indicates there are no alternate titles on the first &quot;Describe&quot; page (the one with a few checkboxes), the input for the <literal>title.alternative</literal> DC element is automatically elided, <emphasis>even on custom submission pages.</emphasis></para>
<para> When a user initiates a submission, DSpace first displays what we&apos;ll call the &quot;initial-questions page&quot;. By default, it contains three questions with check-boxes: <orderedlist>
<listitem>
<para>
<emphasis role="bold">The item has more than one title, e.g. a translated title</emphasis>
</para>
<para> Controls <literal>title.alternative</literal> field.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">The item has been published or publicly distributed before</emphasis>
</para>
<para> Controls DC fields: </para>
<itemizedlist>
<listitem>
<para>
<literal>date.issued</literal>
</para>
</listitem>
<listitem>
<para>
<literal>publisher</literal>
</para>
</listitem>
<listitem>
<para>
<literal>identifier.citation</literal>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
<emphasis role="bold">The item consists of more than one file</emphasis>
</para>
<para>
<emphasis>Does not affect any metadata input fields.</emphasis>
</para>
</listitem>
</orderedlist>
The answers to the first two questions control whether inputs for certain of the DC metadata fields will displayed, even if they are defined as fields in a custom page. Conversely, if the metadata fields controlled by a checkbox are not mentioned in the custom form, the checkbox is elided from the initial page to avoid confusing or misleading the user.</para>
<para>The two relevant checkbox entries are &quot;The item has more than one title, e.g. a translated title&quot;, and &quot;The item has been published or publicly distributed before&quot;. The checkbox for multiple titles trigger the display of the field with dc-element equal to &apos;title&apos; and dc-qualifier equal to &apos;alternative&apos;. If the controlling collection&apos;s form set does not contain this field, then the multiple titles question will not appear on the initial questions page.</para>
</section>
</section>
<section remap="h4">
<title>Adding <literal>Value-Pairs</literal></title>
<para> Finally, your custom form description needs to define the &quot;value pairs&quot; for any fields with input types that refer to them. Do this by adding a <literal>value-pairs</literal> element to the contents of <literal>form-value-pairs</literal>. It has the following required attributes: <itemizedlist>
<listitem>
<para><emphasis role="bold">value-pairs-name</emphasis> -- Name by which an <literal>input-type</literal> refers to this list.</para>
</listitem>
<listitem>
<para><emphasis role="bold">dc-term</emphasis> -- Qualified Dublin Core field for which this choice list is selecting a value.</para>
</listitem>
</itemizedlist>
Each <literal>value-pairs</literal> element contains a sequence of <literal>pair</literal> sub-elements, each of which in turn contains two elements: <itemizedlist>
<listitem>
<para><emphasis role="bold">displayed-value</emphasis> -- Name shown (on the web page) for the menu entry.</para>
</listitem>
<listitem>
<para><emphasis role="bold">stored-value</emphasis> -- Value stored in the DC element when this entry is chosen.</para>
</listitem>
</itemizedlist>
Unlike the HTML <literal>select</literal> tag, there is no way to indicate one of the entries should be the default, so the first entry is always the default choice.</para>
<section remap="h5">
<title>Example</title>
<para>Here is a menu of types of common identifiers:</para>
<screen>
&lt;value-pairs value-pairs-name=&quot;common_identifiers&quot;
dc-term=&quot;identifier&quot;&gt;
&lt;pair&gt;
&lt;displayed-value&gt;Gov&apos;t Doc
#&lt;/displayed-value&gt;
&lt;stored-value&gt;govdoc&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;pair&gt;
&lt;displayed-value&gt;URI&lt;/displayed-value&gt;
&lt;stored-value&gt;uri&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;pair&gt;
&lt;displayed-value&gt;ISBN&lt;/displayed-value&gt;
&lt;stored-value&gt;isbn&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;/value-pairs&gt;
</screen>
<para> It generates the following HTML, which results in the
menu widget below. (Note that there is no way to indicate a default
choice in the custom input XML, so it cannot generate the HTML
<literal>SELECTED</literal> attribute to mark one of the options as a pre-selected
default.) <screen>
&lt;select name=&quot;identifier_qualifier_0&quot;&gt;
&lt;option VALUE=&quot;govdoc&quot;&gt;Gov&apos;t Doc
#&lt;/option&gt;
&lt;option VALUE=&quot;uri&quot;&gt;URI&lt;/option&gt;
&lt;option VALUE=&quot;isbn&quot;&gt;ISBN&lt;/option&gt;
&lt;/select&gt;
</screen><emphasis role="bold">Identifiers:</emphasis>Gov&apos;t Doc #URIISBN</para>
</section>
</section>
</section>
<section remap="h3">
<title>Deploying Your Custom Forms</title>
<para> The DSpace web application only reads your custom form definitions when it starts up, so it is important to remember: <blockquote>
<para>
<emphasis><emphasis role="bold">You must always restart Tomcat</emphasis> (or whatever servlet container you are using) for changes made to the <literal>input-forms.xml</literal> file take effect.</emphasis>
</para>
</blockquote>
Any mistake in the syntax or semantics of the form definitions, such as poorly formed XML or a reference to a nonexistent field name, will cause a fatal error in the DSpace UI. The exception message (at the top of the stack trace in the <literal>dspace.log</literal> file) usually has a concise and helpful explanation of what went wrong. Don&apos;t forget to stop and restart the servlet container before testing your fix to a bug.</para>
<para>
<anchor id="docbook-submission.html-uploadStep"/>
</para>
</section>
</section>
<section remap="h2">
<title>Configuring the File Upload step</title>
<para>The <emphasis>Upload</emphasis> step in the DSpace submission process has two configuration options which can be set with your <literal>[dspace]/config/dspace.cfg</literal> configuration file. They are as follows:</para>
<itemizedlist>
<listitem>
<para><literal>upload.max</literal> - The maximum size of a file (in bytes) that can be uploaded from the JSPUI (not applicable for the XMLUI). It defaults to 536870912 bytes (512MB). You may set this to -1 to disable any file size limitation. </para>
<itemizedlist>
<listitem>
<para><emphasis>Note:</emphasis> Increasing this value or setting to -1 does <emphasis role="bold">not</emphasis> guarantee that DSpace will be able to successfully upload larger files via the web, as large uploads depend on many other factors including bandwidth, web server settings, internet connection speed, etc.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><literal>webui.submit.upload.required</literal> - Whether or not all users are <emphasis>required</emphasis> to upload a file when they submit an item to DSpace. It defaults to &apos;true&apos;. When set to &apos;false&apos; users will see an option to skip the upload step when they submit a new item.</para>
</listitem>
</itemizedlist>
<para>
<anchor id="docbook-submission.html-createStep"/>
</para>
</section>
<section remap="h2">
<title>Creating new Submission Steps</title>
<para>First, a brief warning: <emphasis>Creating a new Submission Step requires some Java knowledge, and is therefore recommended to be undertaken by a Java programmer whenever possible</emphasis></para>
<para>That being said, at a higher level, creating a new Submission Step requires the following (in this relative order):</para>
<orderedlist>
<listitem>
<para> (<emphasis role="bold">Required</emphasis>) Create a new Step Processing class </para>
<itemizedlist>
<listitem>
<para> This class <emphasis role="bold">must</emphasis> extend the abstract <literal>org.dspace.submit.AbstractProcessingStep</literal> class and implement all methods defined by that abstract class.</para>
</listitem>
<listitem>
<para> This class should be built in such a way that it can process the input gathered from <emphasis>either</emphasis> the XMLUI or JSPUI interface.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> (<emphasis>For steps using JSPUI</emphasis>) Create the JSPs to display the user interface. Create a new JSPUI &quot;binding&quot; class to initialize and call these JSPs.</para>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<para> Your JSPUI &quot;binding&quot; class must extend the abstract class <literal>org.dspace.app.webui.submit.JSPStep</literal> and implement all methods defined there. It&apos;s recommended to use one of the classes in <literal>org.dspace.app.webui.submit.step.*</literal> as a reference.</para>
</listitem>
<listitem>
<para> Any JSPs created should be loaded by calling the showJSP() method of the <literal>org.dspace.app.webui.submit.JSPStepManager</literal> class</para>
</listitem>
<listitem>
<para> If this step gathers information to be reviewed, you must also create a Review JSP which will display a read-only view of all data gathered during this step. The path to this JSP must be returned by your getReviewJSP() method. You will find examples of Review JSPs (named similar to <literal>review-[step].jsp</literal>) in the JSP <literal>submit/</literal> directory.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para> (<emphasis>For steps using XMLUI</emphasis>) Create an XMLUI &quot;binding&quot; Step Transformer which will generate the DRI XML which Manakin requires. </para>
<itemizedlist>
<listitem>
<para> The Step Transformer must extend and implement all necessary methods within the abstract class <literal>org.dspace.app.xmlui.submission.AbstractSubmissionStep</literal></para>
</listitem>
<listitem>
<para> It is useful to use the existing classes in <literal>org.dspace.app.xmlui.submission.submit.*</literal> as references</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> (<emphasis role="bold">Required</emphasis>) Add a valid Step Definition to the <literal>item-submission.xml</literal> configuration file. </para>
<itemizedlist>
<listitem>
<para> This may also require that you add an I18N (Internationalization) key for this step&apos;s <literal>heading</literal>. See the sections on <ulink url="configure.html#jspui-multilingual">Configuring Multilingual Support for JSPUI</ulink> or <ulink url="configure.html#xmlui-multilingual">Configuring Multilingual Support for XMLUI</ulink> for more details.</para>
</listitem>
<listitem>
<para> For more information on <literal>&lt;step&gt;</literal> definitions within the <literal>item-submission.xml</literal>, see the section above on <anchor id="docbook-submission.html--stepDefinitions.1" xreflabel="Defining Steps
(&lt;step&gt;) within the item-submission.xml"/>Defining Steps (<literal>&lt;step&gt;</literal>) within the <literal>item-submission.xml</literal>.</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para>
<anchor id="docbook-submission.html-createStep.1"/>
</para>
<section remap="h3">
<title>Creating a Non-Interactive Step</title>
<para>Non-interactive steps are ones that have no user interface and only perform backend processing. You may find a need to create non-interactive steps which perform further processing of previously entered information.</para>
<para>To create a non-interactive step, do the following:</para>
<orderedlist>
<listitem>
<para> Create the required Step Processing class, which extends the abstract <literal>org.dspace.submit.AbstractProcessingStep</literal> class. In this class add any processing which this step will perform.</para>
</listitem>
<listitem>
<para> Add your non-interactive step to your <literal>item-submission.xml</literal> at the place where you wish this step to be called during the submission process. For example, if you want it to be called <emphasis>immediately after</emphasis> the existing &apos;Upload File&apos; step, then place its configuration immediately after the configuration for that &apos;Upload File&apos; step. The configuration should look similar to the following: </para>
<screen>
<literal> &lt;step&gt;
&lt;processing-class&gt;org.dspace.submit.step.MyNonInteractveStep&lt;/processi
/processing-class&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt;</literal>
</screen>
</listitem>
</orderedlist>
<para>Note: Non-interactive steps will not appear in the Progress Bar! Therefore, your submitters will not even know they are there. However, because they are not visible to your users, you should make sure that your non-interactive step does not take a large amount of time to finish its processing and return control to the next step (otherwise there will be a visible time delay in the user interface).</para>
</section>
</section>
</chapter>

1097
dspace/docs/docbook/update.xml Normal file
View File

File diff suppressed because it is too large Load Diff

14
dspace/docs/html/ch01.html Normal file
View File

@@ -0,0 +1,14 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter&nbsp;1.&nbsp;DSpace System Documentation: Introduction</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="pr01.html" title="Preface"><link rel="next" href="ch02.html" title="Chapter&nbsp;2.&nbsp;DSpace System Documentation: Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&nbsp;1.&nbsp;DSpace System Documentation: Introduction</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="pr01.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ch02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N1002C"></a>Chapter&nbsp;1.&nbsp;DSpace System Documentation: Introduction</h2></div></div></div><p>DSpace is an open source software platform that enables organisations to:</p><div class="itemizedlist"><ul type="disc"><li><p> capture and describe digital material using a submission workflow module, or a variety of programmatic ingest options</p></li><li><p> distribute an organisation's digital assets over the web through a search and retrieval system</p></li><li><p> preserve digital assets over the long term</p></li></ul></div><p>This system documentation includes <a class="ulink" href="functional.html" target="_top">a functional overview of the system</a>, which is a good introduction to the capabilities of the system, and should be readable by non-technical folk. Everyone should read this section first because it introduces some terminology used throughout the rest of the documentation.</p><p>For people actually running a DSpace service, there is <a class="ulink" href="install.html" target="_top">an installation guide</a>, and sections on <a class="ulink" href="configure.html" target="_top">configuration</a> and <a class="ulink" href="directories.html" target="_top">the directory structure</a>. Note that as of DSpace 1.2, the administration user interface guide is now on-line help available from within the DSpace system.</p><p>Finally, for those interested in the details of how DSpace works, and those potentially interested in modifying the code for their own purposes, there is <a class="ulink" href="architecture.html" target="_top">a detailed architecture and design section</a>.</p><p>Other good sources of information are:</p><div class="itemizedlist"><ul type="disc"><li><p> The DSpace Public API Javadocs. Build these with the command <code class="literal">mvn javadoc:javadoc</code>.</p></li><li><p> The <a class="ulink" href="http://wiki.dspace.org/" target="_top">DSpace Wiki</a> contains stacks of useful information about the DSpace platform and the work people are doing with it. You are strongly encouraged to visit this site and add information about your own work. Useful Wiki areas are: </p><div class="itemizedlist"><ul type="circle"><li><p><a class="ulink" href="http://wiki.dspace.org/DspaceResources" target="_top">A list of DSpace resources</a> (Web sites, mailing lists etc.)</p></li><li><p>
<a class="ulink" href="http://wiki.dspace.org/TechnicalFaq" target="_top">Technical FAQ</a>
</p></li><li><p>
<a class="ulink" href="http://wiki.dspace.org/DspaceProjects" target="_top">A list of projects using DSpace</a>
</p></li><li><p>
<a class="ulink" href="http://wiki.dspace.org/ContributionGuidelines" target="_top">Guidelines for contributing back to DSpace</a>
</p></li></ul></div></li><li><p><a class="ulink" href="http://www.dspace.org/" target="_top">www.dspace.org</a> has announcements and contains useful information about bringing up an instance of DSpace at your organization.</p></li><li><p> The <a class="ulink" href="#" target="_top">dspace-tech e-mail list on SourceForge</a> is the recommended place to ask questions, since a growing community of DSpace developers and users is on hand on that list to help with any questions you might have. The e-mail archive of that list is a useful resource.</p></li><li><p> The <a class="ulink" href="#" target="_top">dspace-devel e-mail list</a>, for those developing with the DSpace with a view to contributing to the core DSpace code.</p></li></ul></div></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="pr01.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ch02.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Preface&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;2.&nbsp;DSpace System Documentation: Installation</td></tr></table></div></body></html>

304
dspace/docs/html/ch02.html Normal file
View File

File diff suppressed because one or more lines are too long

482
dspace/docs/html/ch03.html Normal file
View File

File diff suppressed because one or more lines are too long

1065
dspace/docs/html/ch04.html Normal file
View File

File diff suppressed because one or more lines are too long

80
dspace/docs/html/ch05.html Normal file
View File

File diff suppressed because one or more lines are too long

80
dspace/docs/html/ch06.html Normal file
View File

File diff suppressed because one or more lines are too long

89
dspace/docs/html/ch07.html Normal file
View File

@@ -0,0 +1,89 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter&nbsp;7.&nbsp;DSpace System Documentation: Architecture</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="ch06.html" title="Chapter&nbsp;6.&nbsp;DSpace System Documentation: Directories and Files"><link rel="next" href="ch08.html" title="Chapter&nbsp;8.&nbsp;DSpace System Documentation: Application Layer"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&nbsp;7.&nbsp;DSpace System Documentation: Architecture</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch06.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ch08.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N128F7"></a>Chapter&nbsp;7.&nbsp;DSpace System Documentation: Architecture</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch07.html#N128FB">7.1. Overview</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N128FB"></a>7.1.&nbsp;<a name="docbook-architecture.html-overview"></a>Overview</h2></div></div></div><p>The DSpace system is organized into three layers, each of which consists of a number of components.</p><p>
<span class="inlinemediaobject"><img src="image/architecture-600x450.gif" width="585"></span>
</p><p>DSpace System Architecture</p><p>The storage layer is responsible for physical storage of metadata and content. The business logic layer deals with managing the content of the archive, users of the archive (e-people), authorization, and workflow. The application layer contains components that communicate with the world outside of the individual DSpace installation, for example the Web user interface and the <a class="ulink" href="http://www.openarchives.org/" target="_top">Open Archives Initiative</a> protocol for metadata harvesting service.</p><p>Each layer only invokes the layer below it; the application layer may not used the storage layer directly, for example. Each component in the storage and business logic layers has a defined public API. The union of the APIs of those components are referred to as the Storage API (in the case of the storage layer) and the DSpace Public API (in the case of the business logic layer). These APIs are in-process Java classes, objects and methods.</p><p>It is important to note that each layer is <span class="emphasis"><em>trusted</em></span>. Although the logic for <span class="emphasis"><em>authorising actions</em></span> is in the business logic layer, the system relies on individual applications in the application layer to correctly and securely <span class="emphasis"><em>authenticate</em></span> e-people. If a 'hostile' or insecure application were allowed to invoke the Public API directly, it could very easily perform actions as any e-person in the system.</p><p>The reason for this design choice is that authentication methods will vary widely between different applications, so it makes sense to leave the logic and responsibility for that in these applications.</p><p>The source code is organized to cohere very strictly to this three-layer architecture. Also, only methods in a component's public API are given the <code class="literal">public</code> access level. This means that the Java compiler helps ensure that the source code conforms to the architecture.</p><div class="table"><a name="N1292B"></a><p class="title"><b>Table&nbsp;7.1.&nbsp;Source Code Packages</b></p><div class="table-contents"><table summary="Source Code Packages" border="0"><colgroup><col><col></colgroup><tbody><tr><td>
<p>
<span class="bold"><strong>Packages within</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Correspond to components in</strong></span>
</p>
</td></tr><tr><td>
<p>
<code class="literal">org.dspace.app</code>
</p>
</td><td>
<p>Application layer</p>
</td></tr><tr><td>
<p>
<code class="literal">org.dspace</code>
</p>
</td><td>
<p>Business logic layer (except <code class="literal">storage</code> and <code class="literal">app</code>)</p>
</td></tr><tr><td>
<p>
<code class="literal">org.dspace.storage</code>
</p>
</td><td>
<p>Storage layer</p>
</td></tr></tbody></table></div></div><br class="table-break"><p>The storage and business logic layer APIs are extensively documented with Javadoc-style comments. Generate the HTML version of these by entering the source directory and running:</p><pre class="screen">
ant public_api
</pre><p>The package-level documentation of each package usually contains an overview of the package and some example usage. This information is not repeated in this architecture document; this and the Javadoc APIs are intended to be used in parallel.</p><p>Each layer is described in a separate section:</p><div class="itemizedlist"><ul type="disc"><li><p>
<a class="ulink" href="storage.html" target="_top">Storage Layer</a>
<div class="itemizedlist"><ul type="circle"><li><p>
<a class="ulink" href="storage.html#rdbms" target="_top">RDBMS</a>
</p></li><li><p>
<a class="ulink" href="storage.html#bitstreams" target="_top">Bitstream Store</a>
</p></li></ul></div>
</p></li><li><p>
<a class="ulink" href="business.html" target="_top">Business Logic Layer</a>
<div class="itemizedlist"><ul type="circle"><li><p>
<a class="ulink" href="business.html#core" target="_top">Core Classes</a>
</p></li><li><p>
<a class="ulink" href="business.html#content" target="_top">Content Management API</a>
</p></li><li><p>
<a class="ulink" href="business.html#workflow" target="_top">Workflow System</a>
</p></li><li><p>
<a class="ulink" href="business.html#administer" target="_top">Administration Toolkit</a>
</p></li><li><p>
<a class="ulink" href="business.html#eperson" target="_top">E-person/Group Manager</a>
</p></li><li><p>
<a class="ulink" href="business.html#authorize" target="_top">Authorisation</a>
</p></li><li><p>
<a class="ulink" href="business.html#handle" target="_top">Handle Manager/Handle Plugin</a>
</p></li><li><p>
<a class="ulink" href="business.html#search" target="_top">Search</a>
</p></li><li><p>
<a class="ulink" href="business.html#browse" target="_top">Browse API</a>
</p></li><li><p>
<a class="ulink" href="business.html#history" target="_top">History Recorder</a>
</p></li><li><p>
<a class="ulink" href="business.html#checker" target="_top">Checksum Checker</a>
</p></li></ul></div>
</p></li><li><p>
<a class="ulink" href="application.html" target="_top">Application Layer</a>
<div class="itemizedlist"><ul type="circle"><li><p>
<a class="ulink" href="application.html#webui" target="_top">Web User Interface</a>
</p></li><li><p>
<a class="ulink" href="application.html#oai" target="_top">OAI-PMH Data Provider</a>
</p></li><li><p>
<a class="ulink" href="application.html#itemimporter" target="_top">Item Importer and Exporter</a>
</p></li><li><p>
<a class="ulink" href="application.html#transferitem" target="_top">Transferring Items Between DSpace Instances</a>
</p></li><li><p>
<a class="ulink" href="application.html#registration" target="_top">Registration</a>
</p></li><li><p>
<a class="ulink" href="application.html#mets" target="_top">METS Tools</a>
</p></li><li><p>
<a class="ulink" href="application.html#mediafilters" target="_top">Media Filters</a>
</p></li><li><p>
<a class="ulink" href="application.html#filiator" target="_top">Sub-Community Management</a>
</p></li></ul></div>
</p></li></ul></div><p> 2002-2008 The DSpace Foundation </p></div></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch06.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ch08.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter&nbsp;6.&nbsp;DSpace System Documentation: Directories and Files&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;8.&nbsp;DSpace System Documentation: Application Layer</td></tr></table></div></body></html>

382
dspace/docs/html/ch08.html Normal file
View File

File diff suppressed because one or more lines are too long

517
dspace/docs/html/ch09.html Normal file
View File

File diff suppressed because one or more lines are too long

145
dspace/docs/html/ch10.html Normal file
View File

File diff suppressed because one or more lines are too long

246
dspace/docs/html/ch11.html Normal file
View File

@@ -0,0 +1,246 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter&nbsp;11.&nbsp;Customizing and Configuring Submission User Interface</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="ch10.html" title="Chapter&nbsp;10.&nbsp;DSpace System Documentation: Functional Overview"><link rel="next" href="ch12.html" title="Chapter&nbsp;12.&nbsp;docbook/DRISchemaReference.html"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&nbsp;11.&nbsp;Customizing and Configuring Submission User Interface</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch10.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ch12.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N145E9"></a>Chapter&nbsp;11.&nbsp;Customizing and Configuring Submission User Interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch11.html#N145F4">11.1. Understanding the Submission Configuration File</a></span></dt><dd><dl><dt><span class="section"><a href="ch11.html#N14601">11.1.1. The Structure of item-submission.xml</a></span></dt><dt><span class="section"><a href="ch11.html#N14630">11.1.2. Defining Steps (&lt;step&gt;) within the item-submission.xml</a></span></dt></dl></dd><dt><span class="section"><a href="ch11.html#N14764">11.2. Reordering/Removing Submission Steps</a></span></dt><dt><span class="section"><a href="ch11.html#N14811">11.3. Assigning a custom Submission Process to a Collection</a></span></dt><dd><dl><dt><span class="section"><a href="ch11.html#N14864">11.3.1. Getting A Collection's Handle</a></span></dt></dl></dd><dt><span class="section"><a href="ch11.html#N14887">11.4. Custom Metadata-entry Pages for Submission</a></span></dt><dd><dl><dt><span class="section"><a href="ch11.html#N1488B">11.4.1. Introduction</a></span></dt><dt><span class="section"><a href="ch11.html#N148B6">11.4.2. Describing Custom Metadata Forms</a></span></dt><dt><span class="section"><a href="ch11.html#N148D9">11.4.3. The Structure of input-forms.xml</a></span></dt><dt><span class="section"><a href="ch11.html#N14B67">11.4.4. Deploying Your Custom Forms</a></span></dt></dl></dd><dt><span class="section"><a href="ch11.html#N14B84">11.5. Configuring the File Upload step</a></span></dt><dt><span class="section"><a href="ch11.html#N14BB0">11.6. Creating new Submission Steps</a></span></dt><dd><dl><dt><span class="section"><a href="ch11.html#N14C49">11.6.1. Creating a Non-Interactive Step</a></span></dt></dl></dd></dl></div><p>This page explains various customization and configuration options that are available within DSpace for the Item Submission user interface.</p><p>
<a name="docbook-submission.html-configurationFile"></a>
</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N145F4"></a>11.1.&nbsp;Understanding the Submission Configuration File</h2></div></div></div><p>The <code class="literal">[dspace]/config/item-submission.xml</code> contains the submission configurations for <span class="emphasis"><em>both</em></span> the DSpace JSP user interface (JSPUI) or the DSpace XML user interface (XMLUI or Manakin). This configuration file contains detailed documentation within the file itself, which should help you better understand how to best utilize it.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N14601"></a>11.1.1.&nbsp;The Structure of <code class="literal">item-submission.xml</code></h3></div></div></div><pre class="screen">
<code class="literal"> &lt;item-submission&gt; &lt;!-- Where submission processes are
mapped to specific Collections --&gt; &lt;submission-map&gt; &lt;name-map
collection-handle="default" submission-name="traditional" /&gt; ...
&lt;/submission-map&gt; &lt;!-- Where "steps" which are used across many
submission processes can be defined in a single place. They can then
be referred to by ID later. --&gt; &lt;step-definitions&gt; &lt;step
id="collection"&gt;
&lt;processing-class&gt;org.dspace.submit.step.SelectCollectionStep&lt;/process
;/processing-class&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt; ... &lt;/step-definitions&gt; &lt;!-- Where actual submission
processes are defined and given names. Each &lt;submission-process&gt; has
many &lt;step&gt; nodes which are in the order that the steps should be
in.--&gt; &lt;submission-definitions&gt; &lt;submission-process name="traditional"&gt;
... &lt;!-- Step definitions appear here! --&gt; &lt;/submission-process&gt; ...
&lt;/submission-definitions&gt; &lt;/item-submission&gt;</code>
</pre><p> Because this file is in XML format, you should be familiar with XML before editing this file. By default, this file contains the "traditional" Item Submission Process for DSpace, which consists of the following Steps (in this order):</p><p>
<code class="literal">Select Collection -&gt; Initial Questions -&gt; Describe -&gt; Upload -&gt; Verify -&gt; License -&gt; Complete</code>
</p><p>If you would like to customize the steps used or the ordering of the steps, you can do so within the <code class="literal">&lt;submission-definition&gt;</code> section of the <code class="literal">item-submission.xml</code> .</p><p>In addition, you may also specify different Submission Processes for different DSpace Collections. This can be done in the <code class="literal">&lt;submission-map&gt;</code> section. The <code class="literal">item-submission.xml</code> file itself documents the syntax required to perform these configuration changes.</p><p>
<a name="docbook-submission.html--stepDefinitions"></a>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N14630"></a>11.1.2.&nbsp;Defining Steps (<code class="literal">&lt;step&gt;</code>) within the <code class="literal">item-submission.xml</code></h3></div></div></div><p>This section describes how Steps of the Submission Process are defined within the <code class="literal">item-submission.xml</code>.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N14641"></a>Where to place your <code class="literal">&lt;step&gt;</code> definitions</h4></div></div></div><p><code class="literal">&lt;step&gt;</code> definitions can appear in one of two places within the <code class="literal">item-submission.xml</code> configuration file.</p><div class="orderedlist"><ol type="1"><li><p> Within the <code class="literal">&lt;step-definitions&gt;</code> section </p><div class="itemizedlist"><ul type="disc"><li><p> This is for globally defined <code class="literal">&lt;step&gt;</code> definitions (i.e. steps which are used in multiple <code class="literal">&lt;submission-process&gt;</code> definitions). Steps defined in this section <span class="bold"><strong>must</strong></span> define a unique <code class="literal">id</code> which can be used to reference this step.</p></li><li><p> For example: </p><pre class="screen">
<code class="literal"> &lt;step-definitions&gt; &lt;step id="custom-step"&gt; ...
&lt;/step&gt; ... &lt;/step-definitions&gt; </code>
</pre></li><li><p> The above step definition could then be referenced from within a <code class="literal">&lt;submission-process&gt;</code> as simply <code class="literal">&lt;step id="custom-step"/&gt;</code></p></li></ul></div></li><li><p> Within a specific <code class="literal">&lt;submission-process&gt;</code> definition </p><div class="itemizedlist"><ul type="disc"><li><p> This is for steps which are specific to a single <code class="literal">&lt;submission-process&gt;</code> definition.</p></li><li><p> For example: </p><pre class="screen">
<code class="literal"> &lt;submission-process&gt; &lt;step&gt; ... &lt;/step&gt;
&lt;/submission-process&gt;</code>
</pre></li></ul></div></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N1469D"></a>The ordering of <code class="literal">&lt;step&gt;</code> definitions <span class="bold"><strong>matters</strong></span>!</h4></div></div></div><p>The ordering of the <code class="literal">&lt;step&gt;</code> tags within a <code class="literal">&lt;submission-process&gt;</code> definition directly corresponds to the order in which those steps will appear!</p><p>For example, the following defines a Submission Process where the <span class="emphasis"><em>License</em></span> step directly precedes the <span class="emphasis"><em>Initial Questions</em></span> step (more information about the structure of the information under each &lt;step&gt; tag can be found in the section on <a class="link" href="ch11.html#docbook-submission.html-stepStructure">Structure of the &lt;step&gt; Definition</a> below):</p><pre class="screen">
<code class="literal"> &lt;submission-process&gt; &lt;!--Step 1 will be to Sign off on
the License--&gt; &lt;step&gt; &lt;heading&gt;submit.progressbar.license&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.LicenseStep&lt;/processing-class
ing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPLicenseStep&lt;/jspui-
t;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.LicenseSt
enseStep&lt;/xmlui-binding&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt; &lt;!--Step 2 will be to Ask Initial Questions--&gt; &lt;step&gt;
&lt;heading&gt;submit.progressbar.initial-questions&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.InitialQuestionsStep&lt;/process
;/processing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPInitialQuestionsSte
onsStep&lt;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.InitialQu
tialQuestionsStep&lt;/xmlui-binding&gt;
&lt;workflow-editable&gt;true&lt;/workflow-editable&gt; &lt;/step&gt; ...[other
steps]... &lt;/submission-process&gt; </code>
</pre><p>
<a name="docbook-submission.html-stepStructure"></a>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N146CB"></a>Structure of the &lt;step&gt; Definition</h4></div></div></div><p>The same &lt;step&gt; definition is used by both the DSpace JSP user interface (JSPUI) an the DSpace XML user interface (XMLUI or Manakin). Therefore, you will notice each &lt;step&gt; definition contains information specific to each of these two interfaces.</p><p>The structure of the &lt;step&gt; Definition is as follows:</p><pre class="screen">
<code class="literal"> &lt;step&gt; &lt;heading&gt;submit.progressbar.describe&lt;/heading&gt;
&lt;processing-class&gt;org.dspace.submit.step.DescribeStep&lt;/processing-clas
sing-class&gt;
&lt;jspui-binding&gt;org.dspace.app.webui.submit.step.JSPDescribeStep&lt;/jspui
lt;/jspui-binding&gt;
&lt;xmlui-binding&gt;org.dspace.app.xmlui.aspect.submission.submit.DescribeS
cribeStep&lt;/xmlui-binding&gt; &lt;workflow-editable&gt;true&lt;/workflow-editable&gt;
&lt;/step&gt; </code>
</pre><p>Each <code class="literal">step</code> contains the following elements. The required elements are so marked:</p><div class="variablelist"><dl><dt><span class="term">
<span class="bold"><strong>heading</strong></span>
</span></dt><dd><p>Partial I18N key (defined in <code class="literal">Messages.properties</code> for JSPUI or <code class="literal">messages.xml</code> for XMLUI) which corresponds to the text that should be displayed in the submission Progress Bar for this step. This partial I18N key is prefixed within either the Messages.properties or messages.xml file, depending on the interface you are using. Therefore, to find the actual key, you will need to search for the partial key with the following prefix: <div class="itemizedlist"><ul type="disc"><li><p> XMLUI: prefix is <code class="literal">xmlui.Submission.</code> (e.g. "xmlui.Submission.submit.progressbar.describe" for 'Describe' step)</p></li><li><p> JSPUI: prefix is <code class="literal">jsp.</code> (e.g. "jsp.submit.progressbar.describe" for 'Describe' step)</p></li></ul></div>
<span class="emphasis"><em>The 'heading' need not be defined if the step should not appear in the progress bar (e.g. steps which perform automated processing, i.e. non-interactive, should not appear in the progress bar).</em></span></p></dd><dt><span class="term">
<span class="bold"><strong>processing-class</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Full Java path to the Processing Class for this Step. This Processing Class <span class="emphasis"><em>must</em></span> perform the primary processing of any information gathered in this step, <span class="emphasis"><em>for both the XMLUI and JSPUI</em></span>. All valid step processing classes must extend the abstract `<code class="literal">org.dspace.submit.AbstractProcessingStep</code>` class (or alternatively, extend one of the pre-existing step processing classes in <code class="literal">org.dspace.submit.step.*</code>)</p></dd><dt><span class="term">
<span class="bold"><strong>jspui-binding</strong></span>
</span></dt><dd><p>Full Java path of the JSPUI "binding" class for this Step. This "binding" class should initialize and call the appropriate JSPs to display the step's user interface. A valid JSPUI "binding" class <span class="emphasis"><em>must</em></span> extend the abstract `<code class="literal">org.dspace.app.webui.submit.JSPStep</code>` class. <span class="emphasis"><em>This property need not be defined if you are using the XMLUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.</em></span></p></dd><dt><span class="term">
<span class="bold"><strong>xmlui-binding</strong></span>
</span></dt><dd><p>Full Java path of the XMLUI "binding" class for this Step. This "binding" class should generate the Manakin XML (DRI document) necessary to generate the step's user interface. A valid XMLUI "binding" class <span class="emphasis"><em>must</em></span> extend the abstract `<code class="literal">org.dspace.app.xmlui.submission.AbstractSubmissionStep</code>` class. <span class="emphasis"><em>This property need not be defined if you are using the JSPUI interface, or for steps which only perform automated processing, i.e. non-interactive steps.</em></span></p></dd><dt><span class="term">
<span class="bold"><strong>workflow-editable</strong></span>
</span></dt><dd><p>Defines whether or not this step can be edited during the <span class="emphasis"><em>Edit Metadata</em></span> process with the DSpace approval/rejection workflow process. Possible values include <code class="literal">true</code> and <code class="literal">false</code>. If undefined, defaults to <code class="literal">true</code> (which means that workflow reviewers would be allowed to edit information gathered during that step).</p></dd></dl></div><p>
<a name="docbook-submission.html-stepOrdering"></a>
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N14764"></a>11.2.&nbsp;Reordering/Removing Submission Steps</h2></div></div></div><p>The removal of existing steps and reordering of existing steps is a relatively easy process!</p><p>
<span class="bold"><strong>Reordering steps</strong></span>
</p><div class="orderedlist"><ol type="1"><li><p> Locate the <code class="literal">&lt;submission-process&gt;</code> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it's likely the one with <code class="literal">name="traditional"</code>, since this is the traditional DSpace submission process.</p></li><li><p> Reorder the <code class="literal">&lt;step&gt;</code> tags within that <code class="literal">&lt;submission-process&gt;</code> tag. Be sure to move the <span class="emphasis"><em>entire</em></span><code class="literal">&lt;step&gt;</code> tag (i.e. everything between and including the opening <code class="literal">&lt;step&gt;</code> and closing <code class="literal">&lt;/step&gt;</code> tags). </p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>Hint #1:</em></span> The <code class="literal">&lt;step&gt;</code> defining the <span class="emphasis"><em>Review/Verify</em></span> step only allows the user to review information from steps which appear <span class="bold"><strong>before</strong></span> it. So, it's likely you'd want this to appear as one of your last few steps</p></li><li><p><span class="emphasis"><em>Hint #2:</em></span> If you are using it, the <code class="literal">&lt;step&gt;</code> defining the <span class="emphasis"><em>Initial Questions</em></span> step should always appear <span class="bold"><strong>before</strong></span> the <span class="emphasis"><em>Upload</em></span> or <span class="emphasis"><em>Describe</em></span> steps since it asks questions which help to set up those later steps.</p></li></ul></div></li></ol></div><p>
<span class="bold"><strong>Removing one or more steps</strong></span>
</p><div class="orderedlist"><ol type="1"><li><p> Locate the <code class="literal">&lt;submission-process&gt;</code> tag which defines the Submission Process that you are using. If you are unsure which Submission Process you are using, it's likely the one with <code class="literal">name="traditional"</code>, since this is the traditional DSpace submission process.</p></li><li><p> Comment out (i.e. surround with &lt;!-- and --&gt;) the <code class="literal">&lt;step&gt;</code> tags which you want to remove from that <code class="literal">&lt;submission-process&gt;</code> tag. Be sure to comment out the <span class="emphasis"><em>entire</em></span><code class="literal">&lt;step&gt;</code> tag (i.e. everything between and including the opening <code class="literal">&lt;step&gt;</code> and closing <code class="literal">&lt;/step&gt;</code> tags). </p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>Hint #1:</em></span> You cannot remove the <span class="emphasis"><em>Select a Collection</em></span> step, as an DSpace Item cannot exist without belonging to a Collection.</p></li><li><p><span class="emphasis"><em>Hint #2:</em></span> If you decide to remove the <code class="literal">&lt;step&gt;</code> defining the <span class="emphasis"><em>Initial Questions</em></span> step, you should be aware that this may affect your <span class="emphasis"><em>Describe</em></span> and <span class="emphasis"><em>Upload</em></span> steps! The <span class="emphasis"><em>Initial Questions</em></span> step asks questions which help to initialize these later steps. If you decide to remove the <span class="emphasis"><em>Initial Questions</em></span> step you may wish to create a custom, automated step which will provide default answers for the questions asked!</p></li></ul></div></li></ol></div><p>
<a name="docbook-submission.html-collectionSubmission"></a>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N14811"></a>11.3.&nbsp;Assigning a custom Submission Process to a Collection</h2></div></div></div><p>Assigning a custom submission process to a Collection in DSpace involves working with the <code class="literal">submission-map</code> section of the <code class="literal">item-submission.xml</code>. For a review of the structure of the <code class="literal">item-submission.xml</code> see the section above on <a class="link" href="ch11.html#docbook-submission.html-configurationFile">Understanding the Submission Configuration File</a>.</p><p>Each <code class="literal">name-map</code> element within <code class="literal">submission-map</code> associates a collection with the name of a submission definition. Its <code class="literal">collection-handle</code> attribute is the Handle of the collection. Its <code class="literal">submission-name</code> attribute is the submission definition name, which must match the <code class="literal">name</code> attribute of a <code class="literal">submission-process</code> element (in the <code class="literal">submission-definitions</code> section of <code class="literal">item-submission.xml</code>.</p><p>For example, the following fragment shows how the collection with handle "12345.6789/42" is assigned the "custom" submission process:</p><pre class="screen">
&lt;submission-map&gt;
&lt;name-map collection-handle="<span class="bold"><strong> 12345.6789/42</strong></span>" submission-name="<span class="bold"><strong>
custom</strong></span>" /&gt;
...
&lt;/submission-map&gt;
&lt;submission-definitions&gt;
&lt;submission-process name="<span class="bold"><strong>
custom</strong></span>"&gt;
...
&lt;/submission-definitions&gt;
</pre><p>It's a good idea to keep the definition of the <code class="literal">default</code> name-map from the example <code class="literal">input-forms.xml</code> so there is always a default for collections which do not have a custom form set.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N14864"></a>11.3.1.&nbsp;Getting A Collection's Handle</h3></div></div></div><p>You will need the <span class="emphasis"><em>handle</em></span> of a collection in order to assign it a custom form set. To discover the handle, go to the "Communities &amp; Collections" page under "<span class="bold"><strong>Browse</strong></span>" in the left-hand menu on your DSpace home page. Then, find the link to your collection. It should look something like:</p><pre class="screen">
http://myhost.my.edu/dspace/handle/<span class="underline">
12345.6789/42</span>
</pre><p>The underlined part of the URL is the handle. It should look familiar to any DSpace administrator. That is what goes in the <code class="literal">collection-handle</code> attribute of your <code class="literal">name-map</code> element.</p><p>
<a name="docbook-submission.html-metadataEntry"></a>
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N14887"></a>11.4.&nbsp;Custom Metadata-entry Pages for Submission</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1488B"></a>11.4.1.&nbsp;Introduction</h3></div></div></div><p>This section explains how to customize the Web forms used by submitters and editors to enter and modify the metadata for a new item. These metadata web forms are controlled by the <span class="emphasis"><em>Describe</em></span> step within the Submission Process. However, they are also configurable via their own XML configuration file (<code class="literal">input-forms.xml</code>).</p><p>You can customize the "default" metadata forms used by all collections, and also create alternate sets of metadata forms and assign them to specific collections. In creating custom metadata forms, you can choose:</p><div class="itemizedlist"><ul type="disc"><li><p> The number of metadata-entry pages.</p></li><li><p> Which fields appear on each page, and their sequence.</p></li><li><p> Labels, prompts, and other text associated with each field.</p></li><li><p> List of available choices for each menu-driven field.</p></li></ul></div><p><span class="bold"><strong>N.B.</strong></span>The cosmetic and ergonomic details of metadata entry fields remain the same as the fixed metadata pages in previous DSpace releases, and can only be altered by modifying the appropriate stylesheet and JSP pages.</p><p>All of the custom metadata-entry forms for a DSpace instance are controlled by a single XML file, <code class="literal">input-forms.xml</code>, in the <code class="literal">config</code> subdirectory under the DSpace home. DSpace comes with a sample configuration that implements the traditional metadata-entry forms, which also serves as a well-documented example. The rest of this section explains how to create your own sets of custom forms.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N148B6"></a>11.4.2.&nbsp;Describing Custom Metadata Forms</h3></div></div></div><p>The description of a set of pages through which submitters enter their metadata is called a <span class="emphasis"><em>form</em></span> (although it is actually a set of forms, in the HTML sense of the term). A form is identified by a unique symbolic <span class="emphasis"><em>name</em></span>. In the XML structure, the <span class="emphasis"><em>form</em></span> is broken down into a series of <span class="emphasis"><em>pages</em></span>: each of these represents a separate Web page for collecting metadata elements.</p><p>To set up one of your DSpace collections with customized submission forms, first you make an entry in the <span class="emphasis"><em>form-map</em></span>. This is effectively a table that relates a collection to a form set, by connecting the collection's <span class="emphasis"><em>Handle</em></span> to the form name. Collections are identified by handle because their names are mutable and not necessarily unique, while handles are unique and persistent.</p><p>A special map entry, for the collection handle "default", defines the <span class="emphasis"><em>default</em></span> form set. It applies to all collections which are not explicitly mentioned in the map. In the example XML this form set is named <code class="literal">traditional</code> (for the "traditional" DSpace user interface) but it could be named anything.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N148D9"></a>11.4.3.&nbsp;The Structure of <code class="literal">input-forms.xml</code></h3></div></div></div><p>The XML configuration file has a single top-level element, <code class="literal">input-forms</code>, which contains three elements in a specific order. The outline is as follows:</p><pre class="screen">
&lt;input-forms&gt;
&lt;-- <span class="emphasis"><em> Map of Collections to Form Sets</em></span> --&gt;
&lt;form-map&gt;
&lt;name-map collection-handle="default" form-name="traditional"
/&gt;
...
&lt;/form-map&gt;
&lt;-- <span class="emphasis"><em> Form Set Definitions</em></span> --&gt;
&lt;form-definitions&gt;
&lt;form name="traditional"&gt;
...
&lt;/form-definitions&gt;
&lt;-- <span class="emphasis"><em> Name/Value Pairs used within Multiple Choice Widgets</em></span>
--&gt;
&lt;form-value-pairs&gt;
&lt;value-pairs value-pairs-name="common_iso_languages"
dc-term="language_iso"&gt;
...
&lt;/form-value-pairs&gt;
&lt;/input-forms&gt;
</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N148F2"></a>Adding a Collection Map</h4></div></div></div><p>Each <code class="literal">name-map</code> element within <code class="literal">form-map</code> associates a collection with the name of a form set. Its <code class="literal">collection-handle</code> attribute is the Handle of the collection, and its <code class="literal">form-name</code> attribute is the form set name, which must match the <code class="literal">name</code> attribute of a <code class="literal">form</code> element.</p><p>For example, the following fragment shows how the collection with handle "12345.6789/42" is attached to the "TechRpt" form set:</p><pre class="screen">
&lt;form-map&gt;
&lt;name-map collection-handle="<span class="bold"><strong> 12345.6789/42</strong></span>" form-name="<span class="bold"><strong> TechRpt</strong></span>"
/&gt;
...
&lt;/form-map&gt;
&lt;form-definitions&gt;
&lt;form name="<span class="bold"><strong>
TechRept</strong></span>"&gt;
...
&lt;/form-definitions&gt;
</pre><p>It's a good idea to keep the definition of the <code class="literal">default</code> name-map from the example <code class="literal">input-forms.xml</code> so there is always a default for collections which do not have a custom form set.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N1492B"></a>Getting A Collection's Handle</h5></div></div></div><p>You will need the <span class="emphasis"><em>handle</em></span> of a collection in order to assign it a custom form set. To discover the handle, go to the "Communities &amp; Collections" page under "<span class="bold"><strong>Browse</strong></span>" in the left-hand menu on your DSpace home page. Then, find the link to your collection. It should look something like:</p><pre class="screen">
http://myhost.my.edu/dspace/handle/<span class="underline">
12345.6789/42</span>
</pre><p>The underlined part of the URL is the handle. It should look familiar to any DSpace administrator. That is what goes in the <code class="literal">collection-handle</code> attribute of your <code class="literal">name-map</code> element.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N14949"></a>Adding a Form Set</h4></div></div></div><p>You can add a new form set by creating a new <code class="literal">form</code> element within the <code class="literal">form-definitions</code> element. It has one attribute, <code class="literal">name</code>, which as seen above must match the value of the <code class="literal">name-map</code> for the collections it is to be used for.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N1495F"></a>Forms and Pages</h5></div></div></div><p>The content of the <code class="literal">form</code> is a sequence of <code class="literal">page</code> elements. Each of these corresponds to a Web page of forms for entering metadata elements, presented in sequence between the initial "Describe" page and the final "Verify" page (which presents a summary of all the metadata collected).</p><p>A <code class="literal">form</code> must contain at least one and at most six pages. They are presented in the order they appear in the XML. Each <code class="literal">page</code> element must include a <code class="literal">number</code> attribute, that should be its sequence number, e.g.</p><pre class="screen">
&lt;page number="1"&gt;
</pre><p>The <code class="literal">page</code> element, in turn, contains a sequence of <code class="literal">field</code> elements. Each field defines an interactive dialog where the submitter enters one of the Dublin Core metadata items.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N14988"></a>Composition of a Field</h5></div></div></div><p>Each <code class="literal">field</code> contains the following elements, in the order indicated. The required sub-elements are so marked:</p><div class="variablelist"><dl><dt><span class="term">
<span class="bold"><strong>dc-schema</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Name of metadata schema employed, e.g. <code class="literal">dc</code> for Dublin Core. This value must match the value of the <code class="literal">schema</code> element defined in <code class="literal">dublin-core-types.xml</code></p></dd><dt><span class="term">
<span class="bold"><strong>dc-element</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Name of the Dublin Core element entered in this field, e.g. <code class="literal">contributor</code>.</p></dd><dt><span class="term">
<span class="bold"><strong>dc-qualifier</strong></span>
</span></dt><dd><p>Qualifier of the Dublin Core element entered in this field, e.g. when the field is <code class="literal">contributor.advisor</code> the value of this element would be <code class="literal">advisor</code>. Leaving this out means the input is for an unqualified DC element.</p></dd><dt><span class="term">
<span class="bold"><strong>repeatable</strong></span>
</span></dt><dd><p>Value is <code class="literal">true</code> when multiple values of this field are allowed, <code class="literal">false</code> otherwise. When you mark a field repeatable, the UI servlet will add a control to let the user ask for more fields to enter additional values. Intended to be used for arbitrarily-repeating fields such as subject keywords, when it is impossible to know in advance how many input boxes to provide.</p></dd><dt><span class="term">
<span class="bold"><strong>label</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Text to display as the label of this field, describing what to enter, e.g. "<code class="literal">Your Advisor's Name</code>".</p></dd><dt><span class="term">
<span class="bold"><strong>input-type</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Defines the kind of interactive widget to put in the form to collect the Dublin Core value. Content must be one of the following keywords: <div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>onebox</strong></span> -- A single text-entry box.</p></li><li><p><span class="bold"><strong>twobox</strong></span> -- A pair of simple text-entry boxes, used for <span class="emphasis"><em>repeatable</em></span> values such as the DC <code class="literal">subject</code> item. <span class="emphasis"><em>Note:</em></span> The 'twobox' input type is rendered the same as a 'onebox' in the XML-UI, but both allow for ease of adding multiple values.</p></li><li><p><span class="bold"><strong>textarea</strong></span> -- Large block of text that can be entered on multiple lines, e.g. for an abstract.</p></li><li><p><span class="bold"><strong>name</strong></span> -- Personal name, with separate fields for family name and first name. When saved they are appended in the format 'LastName, FirstName'</p></li><li><p><span class="bold"><strong>date</strong></span> -- Calendar date. When required, demands that at least the year be entered.</p></li><li><p><span class="bold"><strong>series</strong></span> -- Series/Report name and number. Separate fields are provided for series name and series number, but they are appended (with a semicolon between) when saved.</p></li><li><p><span class="bold"><strong>dropdown</strong></span> -- Choose value(s) from a "drop-down" menu list. <span class="bold"><strong>Note:</strong></span> You must also include a value for the <code class="literal">value-pairs-name</code> attribute to specify a list of menu entries from which to choose. Use this to make a choice from a restricted set of options, such as for the <code class="literal">language</code> item.</p></li><li><p><span class="bold"><strong>qualdrop_value</strong></span> -- Enter a "qualified value", which includes <span class="emphasis"><em>both</em></span> a qualifier from a drop-down menu and a free-text value. Used to enter items like alternate identifers and codes for a submitted item, e.g. the DC <code class="literal">identifier</code> field. <span class="bold"><strong>Note:</strong></span> As for the <code class="literal">dropdown</code> type, you must include the <code class="literal">value-pairs-name</code> attribute to specify a menu choice list.</p></li><li><p><span class="bold"><strong>list</strong></span> -- Choose value(s) from a checkbox or radio button list. If the <code class="literal">repeatable</code> attribute is set to <code class="literal">true</code>, a list of checkboxes is displayed. If the <code class="literal">repeatable</code> attribute is set to <code class="literal">false</code>, a list of radio buttons is displayed. <span class="bold"><strong>Note:</strong></span> You must also include a value for the <code class="literal">value-pairs-name</code> attribute to specify a list of values from which to choose.</p></li></ul></div>
</p></dd><dt><span class="term">
<span class="bold"><strong>hint</strong></span>
<span class="emphasis"><em>(Required)</em></span>
</span></dt><dd><p>Content is the text that will appear as a "hint", or instructions, next to the input fields. Can be left empty, but it must be present.</p></dd><dt><span class="term">
<span class="bold"><strong>required</strong></span>
</span></dt><dd><p>When this element is included with any content, it marks the field as a required input. If the user tries to leave the page without entering a value for this field, that text is displayed as a warning message. For example,</p><p><code class="literal">&lt;required&gt;You must enter a title.&lt;/required&gt; Note that leaving the</code> required element empty will <span class="emphasis"><em>not</em></span> mark a field as required, e.g.:</p><p>
<code class="literal">&lt;required&gt;&lt;/required&gt;</code>
</p></dd><dt><span class="term">
<span class="bold"><strong>visibility</strong></span>
</span></dt><dd><p>When this optional element is included with a value, it restricts the visibility of the field to the scope defined by that value. If the element is missing or empty, the field is visible in all scopes. Currently supported scopes are: <div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>workflow</strong></span> : the field will only be visible in the workflow stages of submission. This is good for hiding difficult fields for users, such as subject classifications, thereby easing the use of the submission system.</p></li><li><p><span class="bold"><strong>submit</strong></span> : the field will only be visible in the initial submission, and not in the workflow stages.</p></li></ul></div>
For example:</p><p>
<code class="literal">&lt;visibility&gt;workflow&lt;/visibility&gt;</code>
</p><p> Note that it is considered a configuration error to limit a field's scope while also requiring it - an exception will be generated when this combination is detected.</p></dd></dl></div><p>Look at the example <code class="literal">input-forms.xml</code> and experiment with a a trial custom form to learn this specification language thoroughly. It is a very simple way to express the layout of data-entry forms, but the only way to learn all its subtleties is to use it.</p><p>For the use of controlled vocabularies see the <a class="ulink" href="configure.html#controlledvocabulary" target="_top">Configuring Controlled Vocabularies</a> section.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N14AC8"></a>Automatically Elided Fields</h5></div></div></div><p>You may notice that some fields are automatically skipped when a custom form page is displayed, depending on the kind of item being submitted. This is because the DSpace user-interface engine skips Dublin Core fields which are not needed, according to the initial description of the item. For example, if the user indicates there are no alternate titles on the first "Describe" page (the one with a few checkboxes), the input for the <code class="literal">title.alternative</code> DC element is automatically elided, <span class="emphasis"><em>even on custom submission pages.</em></span></p><p> When a user initiates a submission, DSpace first displays what we'll call the "initial-questions page". By default, it contains three questions with check-boxes: <div class="orderedlist"><ol type="1"><li><p>
<span class="bold"><strong>The item has more than one title, e.g. a translated title</strong></span>
</p><p> Controls <code class="literal">title.alternative</code> field.</p></li><li><p>
<span class="bold"><strong>The item has been published or publicly distributed before</strong></span>
</p><p> Controls DC fields: </p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">date.issued</code>
</p></li><li><p>
<code class="literal">publisher</code>
</p></li><li><p>
<code class="literal">identifier.citation</code>
</p></li></ul></div></li><li><p>
<span class="bold"><strong>The item consists of more than one file</strong></span>
</p><p>
<span class="emphasis"><em>Does not affect any metadata input fields.</em></span>
</p></li></ol></div>
The answers to the first two questions control whether inputs for certain of the DC metadata fields will displayed, even if they are defined as fields in a custom page. Conversely, if the metadata fields controlled by a checkbox are not mentioned in the custom form, the checkbox is elided from the initial page to avoid confusing or misleading the user.</p><p>The two relevant checkbox entries are "The item has more than one title, e.g. a translated title", and "The item has been published or publicly distributed before". The checkbox for multiple titles trigger the display of the field with dc-element equal to 'title' and dc-qualifier equal to 'alternative'. If the controlling collection's form set does not contain this field, then the multiple titles question will not appear on the initial questions page.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N14B14"></a>Adding <code class="literal">Value-Pairs</code></h4></div></div></div><p> Finally, your custom form description needs to define the "value pairs" for any fields with input types that refer to them. Do this by adding a <code class="literal">value-pairs</code> element to the contents of <code class="literal">form-value-pairs</code>. It has the following required attributes: <div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>value-pairs-name</strong></span> -- Name by which an <code class="literal">input-type</code> refers to this list.</p></li><li><p><span class="bold"><strong>dc-term</strong></span> -- Qualified Dublin Core field for which this choice list is selecting a value.</p></li></ul></div>
Each <code class="literal">value-pairs</code> element contains a sequence of <code class="literal">pair</code> sub-elements, each of which in turn contains two elements: <div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>displayed-value</strong></span> -- Name shown (on the web page) for the menu entry.</p></li><li><p><span class="bold"><strong>stored-value</strong></span> -- Value stored in the DC element when this entry is chosen.</p></li></ul></div>
Unlike the HTML <code class="literal">select</code> tag, there is no way to indicate one of the entries should be the default, so the first entry is always the default choice.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N14B51"></a>Example</h5></div></div></div><p>Here is a menu of types of common identifiers:</p><pre class="screen">
&lt;value-pairs value-pairs-name="common_identifiers"
dc-term="identifier"&gt;
&lt;pair&gt;
&lt;displayed-value&gt;Gov't Doc
#&lt;/displayed-value&gt;
&lt;stored-value&gt;govdoc&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;pair&gt;
&lt;displayed-value&gt;URI&lt;/displayed-value&gt;
&lt;stored-value&gt;uri&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;pair&gt;
&lt;displayed-value&gt;ISBN&lt;/displayed-value&gt;
&lt;stored-value&gt;isbn&lt;/stored-value&gt;
&lt;/pair&gt;
&lt;/value-pairs&gt;
</pre><p> It generates the following HTML, which results in the
menu widget below. (Note that there is no way to indicate a default
choice in the custom input XML, so it cannot generate the HTML
<code class="literal">SELECTED</code> attribute to mark one of the options as a pre-selected
default.) <pre class="screen">
&lt;select name="identifier_qualifier_0"&gt;
&lt;option VALUE="govdoc"&gt;Gov't Doc
#&lt;/option&gt;
&lt;option VALUE="uri"&gt;URI&lt;/option&gt;
&lt;option VALUE="isbn"&gt;ISBN&lt;/option&gt;
&lt;/select&gt;
</pre><span class="bold"><strong>Identifiers:</strong></span>Gov't Doc #URIISBN</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N14B67"></a>11.4.4.&nbsp;Deploying Your Custom Forms</h3></div></div></div><p> The DSpace web application only reads your custom form definitions when it starts up, so it is important to remember: <div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em><span class="bold"><strong>You must always restart Tomcat</strong></span> (or whatever servlet container you are using) for changes made to the <code class="literal">input-forms.xml</code> file take effect.</em></span>
</p></blockquote></div>
Any mistake in the syntax or semantics of the form definitions, such as poorly formed XML or a reference to a nonexistent field name, will cause a fatal error in the DSpace UI. The exception message (at the top of the stack trace in the <code class="literal">dspace.log</code> file) usually has a concise and helpful explanation of what went wrong. Don't forget to stop and restart the servlet container before testing your fix to a bug.</p><p>
<a name="docbook-submission.html-uploadStep"></a>
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N14B84"></a>11.5.&nbsp;Configuring the File Upload step</h2></div></div></div><p>The <span class="emphasis"><em>Upload</em></span> step in the DSpace submission process has two configuration options which can be set with your <code class="literal">[dspace]/config/dspace.cfg</code> configuration file. They are as follows:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">upload.max</code> - The maximum size of a file (in bytes) that can be uploaded from the JSPUI (not applicable for the XMLUI). It defaults to 536870912 bytes (512MB). You may set this to -1 to disable any file size limitation. </p><div class="itemizedlist"><ul type="circle"><li><p><span class="emphasis"><em>Note:</em></span> Increasing this value or setting to -1 does <span class="bold"><strong>not</strong></span> guarantee that DSpace will be able to successfully upload larger files via the web, as large uploads depend on many other factors including bandwidth, web server settings, internet connection speed, etc.</p></li></ul></div></li><li><p><code class="literal">webui.submit.upload.required</code> - Whether or not all users are <span class="emphasis"><em>required</em></span> to upload a file when they submit an item to DSpace. It defaults to 'true'. When set to 'false' users will see an option to skip the upload step when they submit a new item.</p></li></ul></div><p>
<a name="docbook-submission.html-createStep"></a>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N14BB0"></a>11.6.&nbsp;Creating new Submission Steps</h2></div></div></div><p>First, a brief warning: <span class="emphasis"><em>Creating a new Submission Step requires some Java knowledge, and is therefore recommended to be undertaken by a Java programmer whenever possible</em></span></p><p>That being said, at a higher level, creating a new Submission Step requires the following (in this relative order):</p><div class="orderedlist"><ol type="1"><li><p> (<span class="bold"><strong>Required</strong></span>) Create a new Step Processing class </p><div class="itemizedlist"><ul type="disc"><li><p> This class <span class="bold"><strong>must</strong></span> extend the abstract <code class="literal">org.dspace.submit.AbstractProcessingStep</code> class and implement all methods defined by that abstract class.</p></li><li><p> This class should be built in such a way that it can process the input gathered from <span class="emphasis"><em>either</em></span> the XMLUI or JSPUI interface.</p></li></ul></div></li><li><p> (<span class="emphasis"><em>For steps using JSPUI</em></span>) Create the JSPs to display the user interface. Create a new JSPUI "binding" class to initialize and call these JSPs.</p></li><li><p>
<div class="itemizedlist"><ul type="disc"><li><p> Your JSPUI "binding" class must extend the abstract class <code class="literal">org.dspace.app.webui.submit.JSPStep</code> and implement all methods defined there. It's recommended to use one of the classes in <code class="literal">org.dspace.app.webui.submit.step.*</code> as a reference.</p></li><li><p> Any JSPs created should be loaded by calling the showJSP() method of the <code class="literal">org.dspace.app.webui.submit.JSPStepManager</code> class</p></li><li><p> If this step gathers information to be reviewed, you must also create a Review JSP which will display a read-only view of all data gathered during this step. The path to this JSP must be returned by your getReviewJSP() method. You will find examples of Review JSPs (named similar to <code class="literal">review-[step].jsp</code>) in the JSP <code class="literal">submit/</code> directory.</p></li></ul></div>
</p></li><li><p> (<span class="emphasis"><em>For steps using XMLUI</em></span>) Create an XMLUI "binding" Step Transformer which will generate the DRI XML which Manakin requires. </p><div class="itemizedlist"><ul type="disc"><li><p> The Step Transformer must extend and implement all necessary methods within the abstract class <code class="literal">org.dspace.app.xmlui.submission.AbstractSubmissionStep</code></p></li><li><p> It is useful to use the existing classes in <code class="literal">org.dspace.app.xmlui.submission.submit.*</code> as references</p></li></ul></div></li><li><p> (<span class="bold"><strong>Required</strong></span>) Add a valid Step Definition to the <code class="literal">item-submission.xml</code> configuration file. </p><div class="itemizedlist"><ul type="disc"><li><p> This may also require that you add an I18N (Internationalization) key for this step's <code class="literal">heading</code>. See the sections on <a class="ulink" href="configure.html#jspui-multilingual" target="_top">Configuring Multilingual Support for JSPUI</a> or <a class="ulink" href="configure.html#xmlui-multilingual" target="_top">Configuring Multilingual Support for XMLUI</a> for more details.</p></li><li><p> For more information on <code class="literal">&lt;step&gt;</code> definitions within the <code class="literal">item-submission.xml</code>, see the section above on <a name="docbook-submission.html--stepDefinitions.1"></a>Defining Steps (<code class="literal">&lt;step&gt;</code>) within the <code class="literal">item-submission.xml</code>.</p></li></ul></div></li></ol></div><p>
<a name="docbook-submission.html-createStep.1"></a>
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N14C49"></a>11.6.1.&nbsp;Creating a Non-Interactive Step</h3></div></div></div><p>Non-interactive steps are ones that have no user interface and only perform backend processing. You may find a need to create non-interactive steps which perform further processing of previously entered information.</p><p>To create a non-interactive step, do the following:</p><div class="orderedlist"><ol type="1"><li><p> Create the required Step Processing class, which extends the abstract <code class="literal">org.dspace.submit.AbstractProcessingStep</code> class. In this class add any processing which this step will perform.</p></li><li><p> Add your non-interactive step to your <code class="literal">item-submission.xml</code> at the place where you wish this step to be called during the submission process. For example, if you want it to be called <span class="emphasis"><em>immediately after</em></span> the existing 'Upload File' step, then place its configuration immediately after the configuration for that 'Upload File' step. The configuration should look similar to the following: </p><pre class="screen">
<code class="literal"> &lt;step&gt;
&lt;processing-class&gt;org.dspace.submit.step.MyNonInteractveStep&lt;/processi
/processing-class&gt; &lt;workflow-editable&gt;false&lt;/workflow-editable&gt;
&lt;/step&gt;</code>
</pre></li></ol></div><p>Note: Non-interactive steps will not appear in the Progress Bar! Therefore, your submitters will not even know they are there. However, because they are not visible to your users, you should make sure that your non-interactive step does not take a large amount of time to finish its processing and return control to the next step (otherwise there will be a visible time delay in the user interface).</p></div></div></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch10.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ch12.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter&nbsp;10.&nbsp;DSpace System Documentation: Functional Overview&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;12.&nbsp;docbook/DRISchemaReference.html</td></tr></table></div></body></html>

8
dspace/docs/html/ch12.html Normal file
View File

@@ -0,0 +1,8 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter&nbsp;12.&nbsp;docbook/DRISchemaReference.html</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="ch11.html" title="Chapter&nbsp;11.&nbsp;Customizing and Configuring Submission User Interface"><link rel="next" href="ch13.html" title="Chapter&nbsp;13.&nbsp;DRI Schema Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&nbsp;12.&nbsp;docbook/DRISchemaReference.html</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch11.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ch13.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N14C6E"></a>Chapter&nbsp;12.&nbsp;docbook/DRISchemaReference.html</h2></div></div></div><p> /* Code style */ div.element-example pre { border: 1px dashed black; overflow-x: hidden; background: rgb(240,240,240); margin: 0px; padding: 10px;} </p></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch11.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ch13.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter&nbsp;11.&nbsp;Customizing and Configuring Submission User Interface&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;13.&nbsp;DRI Schema Reference</td></tr></table></div></body></html>

1303
dspace/docs/html/ch13.html Normal file
View File

File diff suppressed because one or more lines are too long

125
dspace/docs/html/ch14.html Normal file
View File

File diff suppressed because one or more lines are too long

974
dspace/docs/html/ch15.html Normal file
View File

@@ -0,0 +1,974 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter&nbsp;15.&nbsp;DSpace System Documentation: Appendices</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="ch14.html" title="Chapter&nbsp;14.&nbsp;DSpace System Documentation: Version History"><link rel="next" href="ix01.html" title="Index"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&nbsp;15.&nbsp;DSpace System Documentation: Appendices</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch14.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ix01.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N1679D"></a>Chapter&nbsp;15.&nbsp;DSpace System Documentation: Appendices</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch15.html#N167A1">15.1. Default Dublin Core Metadata Registry</a></span></dt><dt><span class="section"><a href="ch15.html#N16CFA">15.2. Default Bitstream Format Registry</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N167A1"></a>15.1.&nbsp;<a name="docbook-appendix.html-dublincoreregistry"></a>Default Dublin Core Metadata Registry</h2></div></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td>
<p>
<span class="bold"><strong>Element</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Qualifier</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Scope Note</strong></span>
</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>contributor</p>
</td><td>
<p></p>
</td><td>
<p>A person, organization, or service responsible for the content of the resource. Catch-all for unspecified contributors.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>contributor</p>
</td><td>
<p>advisor</p>
</td><td>
<p>Use primarily for thesis advisor.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>contributor<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>author</p>
</td><td>
<p></p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>contributor</p>
</td><td>
<p>editor</p>
</td><td>
<p></p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>contributor</p>
</td><td>
<p>illustrator</p>
</td><td>
<p></p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>contributor</p>
</td><td>
<p>other</p>
</td><td>
<p></p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>coverage</p>
</td><td>
<p>spatial</p>
</td><td>
<p>Spatial characteristics of content.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>coverage</p>
</td><td>
<p>temporal</p>
</td><td>
<p>Temporal characteristics of content.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>creator</p>
</td><td>
<p></p>
</td><td>
<p>Do not use; only for harvested metadata.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date</p>
</td><td>
<p></p>
</td><td>
<p>Use qualified form if possible.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>accessioned</p>
</td><td>
<p>Date DSpace takes possession of item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>available</p>
</td><td>
<p>Date or date range item became available to the public.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date</p>
</td><td>
<p>copyright</p>
</td><td>
<p>Date of copyright.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date</p>
</td><td>
<p>created</p>
</td><td>
<p>Date of creation or manufacture of intellectual content if different from date.issued.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>issued</p>
</td><td>
<p>Date of publication or distribution.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>date</p>
</td><td>
<p>submitted</p>
</td><td>
<p>Recommend for theses/dissertations.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>identifier</p>
</td><td>
<p></p>
</td><td>
<p>Catch-all for unambiguous identifiers not defined by qualified form; use identifier.other for a known identifier common to a local collection instead of unqualified form.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>citation</p>
</td><td>
<p>Human-readable, standard bibliographic citation of non-DSpace format of this item</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>govdoc</p>
</td><td>
<p>A government document number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>isbn</p>
</td><td>
<p>International Standard Book Number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>issn</p>
</td><td>
<p>International Standard Serial Number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier</p>
</td><td>
<p>sici</p>
</td><td>
<p>Serial Item and Contribution Identifier</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>ismn</p>
</td><td>
<p>International Standard Music Number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>other</p>
</td><td>
<p>A known identifier type common to a local collection.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>identifier<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>uri</p>
</td><td>
<p>Uniform Resource Identifier</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>description<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Catch-all for any description not defined by qualifiers.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>abstract</p>
</td><td>
<p>Abstract or summary.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>provenance</p>
</td><td>
<p>The history of custody of the item since its creation, including any changes successive custodians made to it.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>sponsorship</p>
</td><td>
<p>Information about sponsoring agencies, individuals, or contractual arrangements for the item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description</p>
</td><td>
<p>statementofresponsibility</p>
</td><td>
<p>To preserve statement of responsibility from MARC records.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description</p>
</td><td>
<p>tableofcontents</p>
</td><td>
<p>A table of contents for a given item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>description</p>
</td><td>
<p>uri</p>
</td><td>
<p>Uniform Resource Identifier pointing to description of this item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>format<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Catch-all for any format information not defined by qualifiers.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>format<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>extent</p>
</td><td>
<p>Size or duration.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>format</p>
</td><td>
<p>medium</p>
</td><td>
<p>Physical medium.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>format<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>mimetype</p>
</td><td>
<p>Registered MIME type identifiers.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>language</p>
</td><td>
<p></p>
</td><td>
<p>Catch-all for non-ISO forms of the language of the item, accommodating harvested values.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>language<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>iso</p>
</td><td>
<p>Current ISO standard for language of intellectual content, including country codes (e.g. "en_US").</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>publisher<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Entity responsible for publication, distribution, or imprint.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p></p>
</td><td>
<p>Catch-all for references to other related items.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>isformatof</p>
</td><td>
<p>References additional physical form.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>ispartof</p>
</td><td>
<p>References physically or logically containing item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>ispartofseries</p>
</td><td>
<p>Series name and number within that series, if available.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>haspart</p>
</td><td>
<p>References physically or logically contained item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>isversionof</p>
</td><td>
<p>References earlier version.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>hasversion</p>
</td><td>
<p>References later version.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>isbasedon</p>
</td><td>
<p>References source.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>isreferencedby</p>
</td><td>
<p>Pointed to by referenced resource.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>requires</p>
</td><td>
<p>Referenced resource is required to support function, delivery, or coherence of item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>replaces</p>
</td><td>
<p>References preceeding item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>isreplacedby</p>
</td><td>
<p>References succeeding item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>relation</p>
</td><td>
<p>uri</p>
</td><td>
<p>References Uniform Resource Identifier for related item.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>rights</p>
</td><td>
<p></p>
</td><td>
<p>Terms governing use and reproduction.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>rights</p>
</td><td>
<p>uri</p>
</td><td>
<p>References terms governing use and reproduction.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>source</p>
</td><td>
<p></p>
</td><td>
<p>Do not use; only for harvested metadata.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>source</p>
</td><td>
<p>uri</p>
</td><td>
<p>Do not use; only for harvested metadata.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>subject<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Uncontrolled index term.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>classification</p>
</td><td>
<p>Catch-all for value from local classification system. Global classification systems will receive specific qualifier</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>ddc</p>
</td><td>
<p>Dewey Decimal Classification Number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>lcc</p>
</td><td>
<p>Library of Congress Classification Number</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>lcsh</p>
</td><td>
<p>Library of Congress Subject Headings</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>mesh</p>
</td><td>
<p>MEdical Subject Headings</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>subject</p>
</td><td>
<p>other</p>
</td><td>
<p>Local controlled vocabulary; global vocabularies will receive specific qualifier.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>title<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Title statement/title proper.</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>title<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p>alternative</p>
</td><td>
<p>Varying (or substitute) form of title proper appearing in item, e.g. abbreviation or translation</p>
</td><td class="auto-generated">&nbsp;</td></tr><tr><td>
<p>type<a class="link" href="ch15.html#docbook-appendix.html-note1">&sup1;</a></p>
</td><td>
<p></p>
</td><td>
<p>Nature or genre of content.</p>
</td><td>
<p></p>
</td></tr></tbody></table></div><p>
<a name="docbook-appendix.html-note1"></a>
</p><p>&sup1;Used by system: do not remove</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N16CFA"></a>15.2.&nbsp;<a name="docbook-appendix.html-bitstreamformatregistry"></a>Default Bitstream Format Registry</h2></div></div></div><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col><col></colgroup><tbody><tr><td>
<p>
<span class="bold"><strong>Mimetype</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Short Description</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Description</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Support Level</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Internal</strong></span>
</p>
</td><td>
<p>
<span class="bold"><strong>Extensions</strong></span>
</p>
</td></tr><tr><td>
<p>application/octet-stream<a class="link" href="ch15.html#docbook-appendix.html-note2">&sup1;</a></p>
</td><td>
<p>Unknown</p>
</td><td>
<p>Unknown data format</p>
</td><td>
<p>Unknown</p>
</td><td>
<p>false</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>text/plain<a class="link" href="ch15.html#docbook-appendix.html-note2">&sup1;</a></p>
</td><td>
<p>License</p>
</td><td>
<p>Item-specific license agreed upon to submission</p>
</td><td>
<p>Known</p>
</td><td>
<p>true</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>application/marc</p>
</td><td>
<p>MARC</p>
</td><td>
<p>Machine-Readable Cataloging records</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p></p>
</td></tr><tr><td>
<p>application/mathematica</p>
</td><td>
<p>Mathematica</p>
</td><td>
<p>Mathematica Notebook</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>ma</p>
</td></tr><tr><td>
<p>application/msword</p>
</td><td>
<p>Microsoft Word</p>
</td><td>
<p>Microsoft Word</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>doc</p>
</td></tr><tr><td>
<p>application/pdf</p>
</td><td>
<p>Adobe PDF</p>
</td><td>
<p>Adobe Portable Document Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>pdf</p>
</td></tr><tr><td>
<p>application/postscript</p>
</td><td>
<p>Postscript</p>
</td><td>
<p>Postscript Files</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>ai, eps, ps</p>
</td></tr><tr><td>
<p>application/sgml</p>
</td><td>
<p>SGML</p>
</td><td>
<p>SGML application (RFC 1874)</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>sgm, sgml</p>
</td></tr><tr><td>
<p>application/vnd.ms-excel</p>
</td><td>
<p>Microsoft Excel</p>
</td><td>
<p>Microsoft Excel</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>xls</p>
</td></tr><tr><td>
<p>application/vnd.ms-powerpoint</p>
</td><td>
<p>Microsoft Powerpoint</p>
</td><td>
<p>Microsoft Powerpoint</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>ppt</p>
</td></tr><tr><td>
<p>application/vnd.ms-project</p>
</td><td>
<p>Microsoft Project</p>
</td><td>
<p>Microsoft Project</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>mpd, mpp, mpx</p>
</td></tr><tr><td>
<p>application/vnd.visio</p>
</td><td>
<p>Microsoft Visio</p>
</td><td>
<p>Microsoft Visio</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>vsd</p>
</td></tr><tr><td>
<p>application/wordperfect5.1</p>
</td><td>
<p>WordPerfect</p>
</td><td>
<p>WordPerfect 5.1 document</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>wpd</p>
</td></tr><tr><td>
<p>application/x-dvi</p>
</td><td>
<p>TeX dvi</p>
</td><td>
<p>TeX dvi format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>dvi</p>
</td></tr><tr><td>
<p>application/x-filemaker</p>
</td><td>
<p>FMP3</p>
</td><td>
<p>Filemaker Pro</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>fm</p>
</td></tr><tr><td>
<p>application/x-latex</p>
</td><td>
<p>LateX</p>
</td><td>
<p>LaTeX document</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>latex</p>
</td></tr><tr><td>
<p>application/x-photoshop</p>
</td><td>
<p>Photoshop</p>
</td><td>
<p>Photoshop</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>pdd, psd</p>
</td></tr><tr><td>
<p>application/x-tex</p>
</td><td>
<p>TeX</p>
</td><td>
<p>Tex/LateX document</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>tex</p>
</td></tr><tr><td>
<p>audio/basic</p>
</td><td>
<p>audio/basic</p>
</td><td>
<p>Basic Audio</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>au, snd</p>
</td></tr><tr><td>
<p>audio/x-aiff</p>
</td><td>
<p>AIFF</p>
</td><td>
<p>Audio Interchange File Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>aif, aifc, aiff</p>
</td></tr><tr><td>
<p>audio/x-mpeg</p>
</td><td>
<p>MPEG Audio</p>
</td><td>
<p>MPEG Audio</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>abs, mpa, mpega</p>
</td></tr><tr><td>
<p>audio/x-pn-realaudio</p>
</td><td>
<p>RealAudio</p>
</td><td>
<p>RealAudio file</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>ra, ram</p>
</td></tr><tr><td>
<p>audio/x-wav</p>
</td><td>
<p>WAV</p>
</td><td>
<p>Broadcase Wave Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>wav</p>
</td></tr><tr><td>
<p>image/gif</p>
</td><td>
<p>GIF</p>
</td><td>
<p>Graphics Interchange Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>gif</p>
</td></tr><tr><td>
<p>image/jpeg</p>
</td><td>
<p>JPEG</p>
</td><td>
<p>Joint Photographic Experts Group/JPEG File Interchange Format (JFIF)</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>jpeg, jpg</p>
</td></tr><tr><td>
<p>image/png</p>
</td><td>
<p>image/png</p>
</td><td>
<p>Portable Network Graphics</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>png</p>
</td></tr><tr><td>
<p>image/tiff</p>
</td><td>
<p>TIFF</p>
</td><td>
<p>Tag Image File Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>tif, tiff</p>
</td></tr><tr><td>
<p>image/x-ms-bmp</p>
</td><td>
<p>BMP</p>
</td><td>
<p>Microsoft Windows bitmap</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>bmp</p>
</td></tr><tr><td>
<p>image/x-photo-cd</p>
</td><td>
<p>Photo CD</p>
</td><td>
<p>Kodak Photo CD image</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>pcd</p>
</td></tr><tr><td>
<p>text/css</p>
</td><td>
<p>CSS</p>
</td><td>
<p>Cascading Style Sheets</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>css</p>
</td></tr><tr><td>
<p>text/html</p>
</td><td>
<p>HTML</p>
</td><td>
<p>Hypertext Markup Language</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>htm, html</p>
</td></tr><tr><td>
<p>text/plain</p>
</td><td>
<p>Text</p>
</td><td>
<p>Plain Text</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>asc, txt</p>
</td></tr><tr><td>
<p>text/richtext</p>
</td><td>
<p>RTF</p>
</td><td>
<p>Rich Text Format</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>rtf</p>
</td></tr><tr><td>
<p>text/xml</p>
</td><td>
<p>XML</p>
</td><td>
<p>Extensible Markup Language</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>xml</p>
</td></tr><tr><td>
<p>video/mpeg</p>
</td><td>
<p>MPEG</p>
</td><td>
<p>Moving Picture Experts Group</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>mpe, mpeg, mpg</p>
</td></tr><tr><td>
<p>video/quicktime</p>
</td><td>
<p>Video Quicktime</p>
</td><td>
<p>Video Quicktime</p>
</td><td>
<p>Known</p>
</td><td>
<p>false</p>
</td><td>
<p>mov, qt</p>
</td></tr></tbody></table></div><p>
<a name="docbook-appendix.html-note2"></a>
</p><p>&sup1; Used by system: do not remove</p></div></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch14.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ix01.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Chapter&nbsp;14.&nbsp;DSpace System Documentation: Version History&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Index</td></tr></table></div></body></html>

1
dspace/docs/html/image Symbolic link
View File

@@ -0,0 +1 @@
../image

15
dspace/docs/html/index.html Normal file
View File

File diff suppressed because one or more lines are too long

8
dspace/docs/html/ix01.html Normal file
View File

@@ -0,0 +1,8 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Index</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="ch15.html" title="Chapter&nbsp;15.&nbsp;DSpace System Documentation: Appendices"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Index</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch15.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;</td></tr></table><hr></div><div class="index"><div class="titlepage"><div><div><h2 class="title"><a name="N171B6"></a>Index</h2></div></div></div><div class="index"></div></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch15.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;</td></tr><tr><td valign="top" align="left" width="40%">Chapter&nbsp;15.&nbsp;DSpace System Documentation: Appendices&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;</td></tr></table></div></body></html>

8
dspace/docs/html/pr01.html Normal file
View File

@@ -0,0 +1,8 @@
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Preface</title><meta content="DocBook XSL Stylesheets V1.74.0" name="generator"><link rel="home" href="index.html" title="DSpace 1.5.1 Manual"><link rel="up" href="index.html" title="DSpace 1.5.1 Manual"><link rel="prev" href="index.html" title="DSpace 1.5.1 Manual"><link rel="next" href="ch01.html" title="Chapter&nbsp;1.&nbsp;DSpace System Documentation: Introduction"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Preface</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ch01.html">Next</a></td></tr></table><hr></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10026"></a>Preface</h2></div></div></div><p></p></div><HR><p class="copyright">Copyright &copy; 2002-2008
<a class="ulink" href="http://www.dspace.org/" target="_top">The DSpace Foundation</a>
</p><div class="legalnotice"><a name="N10017"></a><p>
<a class="ulink" href="http://creativecommons.org/licenses/by/3.0/us/" target="_top">
<span class="inlinemediaobject"><img src="http://i.creativecommons.org/l/by/3.0/us/88x31.png"></span>
Licensed under a Creative Commons Attribution 3.0 United States License
</a>
</p></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ch01.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">DSpace 1.5.1 Manual&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Chapter&nbsp;1.&nbsp;DSpace System Documentation: Introduction</td></tr></table></div></body></html>

BIN
dspace/docs/pdf/book-foppure.pdf Normal file
View File

Binary file not shown.

76
dspace/docs/wrapscreen.py Executable file
View File

@@ -0,0 +1,76 @@
#! /usr/bin/env python
""" Utility program to try to gently line wrap preformatted text inside an XML tag
"""
import sys, string
import codecs
def wrapElementLines(wrap=72,src=sys.stdin, dst=sys.stdout, srcenc='iso8859', dstenc='utf-8', elem='screen'):
# Tell python how to encode the output (generally utf-8)
(e,d,sr,sw) = codecs.lookup(dstenc)
out = sw(dst)
# Tell python how to interpret the input (generally iso8859)
(e,d,sr,sw) = codecs.lookup(srcenc)
inp = sr(src)
inElem = False
openElem = "<"+elem+">"
closeElem = "</"+elem+">"
for line in inp:
try:
index = line.index(openElem)
inElem = True
except:
pass
if inElem:
try:
line.index(closeElem)
inElem = False
except:
while len(line) > wrap:
lim = indexlimit(line,wrap)
try:
space = line[0:lim].rindex(' ')
out.write(line[0:space]+"\n\t") # " \\\n\t"
line = line[space+1:]
except:
out.write(line[0:lim]+"\n") # "\\\n"
line = line[wrap:]
out.write(line)
def indexlimit(string,limit=72):
tag=False
ent=False
ptr=0
cnt=0
for ch in string:
ptr = ptr + 1
if ch == '<' and not tag:
tag=True
elif ch == '>' and tag:
tag=False
elif ch == '&' and not ent:
ent=True
elif ch == ';' and ent:
cnt = cnt + 1
ent=False
elif not (tag or ent):
cnt = cnt + 1
if cnt >= limit:
return ptr
return ptr
src = sys.stdin
dst = sys.stdout
if len(sys.argv) > 1:
src = open(sys.argv[1])
if len(sys.argv) > 2:
dst = open(sys.argv[2],"w")
wrapElementLines(src=src,dst=dst,wrap=70,srcenc="utf-8")