Setting Up Mdc

Dependencies

Apache Jakarta Tomcat

You require a servlet container such as tomcat or an application server supporting servlet api 2.3 (2.2 should work as well, but we may use features from 2.3 in future).

We have used tomcat version 5.5.7 for development and testing, although earlier versions should work as well. Note that if you use tomcat version 5.5.x, and you have java jre/sdk 1.4.x then you must also install the compatibility pack for tomcat. See the jakarta.apache.org for details on tomcat version 5.5.x.

Exist DB

Mdc uses Exist-db for caching query results and also for storing user created resource lists in a repository. The Mdc configuration (mdc-config.xml in WEB-INF/classes) allows you to specify the location of the Exist-db server for both cache and repository. The distribution comes bundled with the Exist-db jars, so you can run the cache in the same web context as Mdc. The default configuration and the install ant build, are set up to have the cache in the Mdc web context, but the repository in a separate Exist context. The reason for this, is so that you have all the other Exist facilities available to examine or work with the repository. Also Mdc makes use of transformations which are done by Cocoon installed with the standard Exist-db installation.

The advantage of running Exist in the same context as the application is db related activity is most efficient as xml-rpc calls are handled internally and not passed through a "transport" mechanism such as http. The disadvantage is that you cannot administer the db using standard Exist tools as you could when Exist is installed in its own web context.

So, for the standard installation you need to install Exist-db in its own web context and Mdc in its own context, but Mdc will use a local Exist db for caching. See the installation notes below.

Jafer

Mdc uses Jafer for its Z39.50 and other searches. Jafer comes as a zip file with the distribution rather than as a jar along with the other jars. The reason for this is that Jafer has a number of config files which may need to be changed as part of the federated search configuration, so Jafer files actually get installed to WEB-INF/classes in order to facilitate this process. Also note that some of the older tomcat versions had problems loading resource files from jars.

Cocoon

When a resource list is formatted or exported, this is done using XSLT transforms. Presently these transforms are done through Cocoon - in fact, the Cocoon that is bundled with Exist. The mdc-config file contains the base url to be used for invoking stylesheet transforms.

Note that one of the transforms generates a PDF resource list. This requires that Apache FOP is installed in Cocoon (see the installation notes below).

Citeproc

We have also integrated Citeproc with Mdc which allows resource lists to be formatted by the facilities provided by citeproc.

Other Jars

There are other dependencies but these are all provided as jars in WEB-INF/lib.

Installation

Obtain Mdc Distribution

Obtain the Mdc distribution from SourceForge and unpack it to a local directory.

Obtain and Install Exist DB

  1. Get snapshot-2005-06-20 of Exist and install it to a local directory. You can do this by downloading the snapshot jar file from www.exist-db.org. This jar is actually an installer and when you run it it will prompt you for a directory into which to install Exist. To run the installer use "java -jar eXist-snapshot-20050314.jar"
  2. Now you need to build the exist war file. You must have ant (version 1.6.2 or later). Change to the exist install (home) directory and issue "ant dist-war". This will compile exist and generate the exist.war file in directory dist off the exist home directory
  3. Copy the exist.war file to your tomcat webapps directory. Make a new "exist" directory off the webapps directory. Change (cd) to the exist directory. Unpack the exist.jar file with "jar -xvf ../exist.war".
  4. Restart tomcat.
  5. You should now be able to browse the Exist main page (http://localhost:8080/exist/). You can optionally setup the Exist samples by selecting "Admin" from the Exist home page and then logging in as "admin" with no password. Choose the "Examples Setup" option. If all of that works ok, you now have the vanilla Exist web application correctly set up.
  6. Next you need to copy some additional Mdc specific files to Exist. These are in the exist-extra directory of the Mdc distribution. There's a target "exist-extra" in the Mdc build that copies the appropriate files to your local Exist installation. If you will run Exist on a remote machine, you will need to copy these files yourself.

Install Citeproc

Read the readme.txt file in the citeproc directory of the Mdc distribution. This involves running an Ant task in the citeproc directory to copy the appropriate files to your Exist installation.

Build Mdc

  1. Update the build.properties file and change the properties to reflect your local environment.
  2. Edit mdc-config.xml in the webapps/WEB-INF/classes directory and change configuration parameters as required. Note that it is in this file that you specify the jafer targets to be searched by Mdc.
  3. From the Mdc directory, run the ant all target. This will build Mdc into the directory webdist.
  4. Run the to-tomcat target. This will copy the webdist directory to your local tomcat installation.
  5. Restart/reload tomcat.
  6. From your browser, go to the search.jsp url, e.g. http://localhost/mdc/search.jsp. You should now be able to perform a jafer search against the targets you configured, and to build a resource list and to save it to the repository. Try and Create a document from your resource list to ensure the Cocoon and Citeproc installtions are correct.