Maintenance

Greg and I have now deployed Cocoon servlets on Tomcat a number of times, and we've come up with some detailed documentation. This is the state of the art as of today, based on our experience deploying the Cocoon containing the teiJournal application for the IALLT Journal on Tomcat 6.0.14 running on Lettuce.

• First, check your Tomcat setting to make sure it's been modified to handle character encodings in documents and URIs as UTF-8. There are two aspects to this:
  1. The process must be launched with the dFile.encoding="UTF-8" flag on the command line.
  2. Check that you set the URIEncoding parameter of the <Connector> tag in the [tomcat]/conf/server.xml file, like this:

     <Connector port="8081" protocol="HTTP/1.1" 
                    URIEncoding="UTF-8"
                    connectionTimeout="20000" 
                    redirectPort="8444" />
     

• Change web.xml to rename the application from "Cocoon" to "teiJournal". We don't actually know what this DOES, but we think it's probably the right thing to do, and it will prevent there being multiple applications running under the same Tomcat with the same servlet name.
• Also change web.xml to set all encodings to UTF-8 (some are still 8859-1 in the default setup). This assumes that the Tomcat process is itself being launched with a UTF-8 flag in the VM, as part of the Java launch command. Finally, you may want to change the log-level parameter from WARN to DEBUG, to get better debug messages from your application.
• Rename the WAR file to something that works for you. In these instructions, we'll assume you renamed it to ialltjournal.war, which will result in an application that deploys in a directory called ialltjournal.
• Deploy the application itself by putting the WAR file in the webapps directory of Tomcat. Restart Tomcat, and check that the application has deployed OK by going into the Tomcat manager application to see it, and also going to :[port#]/ialltjournal/.
• Delete the WAR file from the server, so that it is not deployed again.
• Stop ialltjournal from within the Tomcat manager so you can add some custom Java libraries.
• For teiJournal, add the following libraries to ialltjournal/WEB-INF/lib:
  • TitleSortComparator.jar (sorts titles ignoring leading articles, etc.)
  • xqSearchUtils.jar (contains the search-string parsing functionality used for teiJournal's search).
  TitleSortComparator was written with Eclipse, and will be found in your Eclipse workspace folder; xqSearchUtils was written with NetBeans, and will be found in your NetBeans project folder.
• For support of XSLT 2.0, you need to add and configure the Saxon 9 libraries. Get the Saxon-B download from here. Then extract all the .jar libraries into cocoon/WEB-INF/lib.
• Now we need to configure Cocoon so that Saxon can be called. First, open cocoon/WEB-INF/cocoon.xconf, and find the bit that refers to Saxon XSLT, which is commented out by default. Uncomment the code and change it according to the instructions in the file, so that it enables Saxon 9:

        	<component logger="core.xslt"
                     role="org.apache.excalibur.xml.xslt.XSLTProcessor/saxon"
                     class="org.apache.cocoon.components.xslt.TraxProcessor">
              <parameter name="use-store" value="true"/>
              <parameter name="transformer-factory" value="net.sf.saxon.TransformerFactoryImpl"/>
            </component>

• Now we need to edit cocoon/sitemap.xmap to enable the Saxon transformer. In the <map:transformers> section, add this below the other XSLT transformers:

        <map:transformer name="saxon" pool-grow="2" pool-max="32" pool-min="8"
        		     src="org.apache.cocoon.transformation.TraxTransformer">
        	    <use-request-parameters>false</use-request-parameters>
        	    <use-browser-capabilities-db>false</use-browser-capabilities-db>
        	    <xslt-processor-role>saxon</xslt-processor-role>
            </map:transformer>

• Add the following in the <map:serializers> section, to enable a couple more useful output formats:

        	<!-- Customization: compatibility setting for IE6 -->
            <map:serializer logger="sitemap.serializer.xhtml" mime-type="text/html" name="xhtml11_compat" pool-grow="2" pool-max="64" pool-min="2" src="org.apache.cocoon.serialization.XMLSerializer">
              <doctype-public>-//W3C//DTD XHTML 1.1//EN</doctype-public>
              <doctype-system>http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd</doctype-system>
              <encoding>UTF-8</encoding>
            </map:serializer>    
            <!-- Customization: set text output to UTF-8 -->
            <map:serializer logger="sitemap.serializer.text" mime-type="text/plain" name="text" src="org.apache.cocoon.serialization.TextSerializer">
              <encoding>UTF-8</encoding>
            </map:serializer>

• Now we need to edit eXist's conf.xml file (in ialltjournal/WEB-INF) to handle whitespace in mixed content. This part of conf.xml needs to be changed, from:

  <indexer caseSensitive="yes" index-depth="5" preserve-whitespace-mixed-content="no" stemming="no" suppress-whitespace="both" tokenizer="org.exist.storage.analysis.SimpleTokenizer" track-term-freq="yes" validation="none">

  to:

  <indexer caseSensitive="no" index-depth="8" preserve-whitespace-mixed-content="yes" stemming="no" suppress-whitespace="none" tokenizer="org.exist.storage.analysis.SimpleTokenizer" track-term-freq="yes" validation="none">

  In other words, four changes to attribute values. Then you have to re-upload all the documents in the the db, if there are any still in there.
• Restart Tomcat (restarting just Cocoon doesn't seem to be enough).
• Go to the Tomcat manager and check that the application is running; if it's not, then start it.
• Check that the application is running successfully (:[port#]/ialltjournal/).
• Check that eXist is running (:[port#]/ialltjournal/samples/blocks/exist/).
• Start the eXist client for the first time (using the Webstart Client Launch link on the menu of the page above).
• There will be no admin password at first; just log in as admin with no password, then change the admin password. You'll immediately get an error; don't worry, just close the client down and restart it, then log in with the new password.
• Now you can add data and a project folder as necessary, and test the results.