This is a collection of bits and pieces we have painfully learned over the years regarding the setup of Tomcat proxied through Apache, enabling the reliable use of UTF-8 encoding in form submissions etc.
To make sure Tomcat starts with UTF-8 instead of the default, I put a script in [tomcat]/bin called utf8startup.sh:
#!/bin/bash ./startup.sh dFile.encoding="UTF-8"
If another script is starting Tomcat, that script must ensure that the process is launched with the dFile.encoding="UTF-8" flag on the command line.
Add the correct parameter (URIEncoding="UTF-8") in conf/server.xml:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" URIEncoding="UTF-8" />
If Tomcat is proxied through Apache using the AJP connector, Tomcat's conf/server.xml file may need to be tweaked to add a URIEncoding="UTF-8" parameter for that:
<!-- Define an AJP 1.3 Connector on port 8019 -->
<Connector port="8019" protocol="AJP/1.3" redirectPort="8081" />
changed to:
<!-- Define an AJP 1.3 Connector on port 8019 -->
<Connector port="8019" protocol="AJP/1.3" redirectPort="8081" URIEncoding="UTF-8" />
This needs to be added to the Apache configuration:
JkOptions +ForwardURICompatUnparsedThis does not relate specifically to UTF-8 encoding, but it's collected here for completeness:
Tomcat 7 handles default "welcome files" differently from 6. If you look in Tomcat's conf/web.xml, you'll see this:
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
<welcome-file>index.jsp</welcome-file>
</welcome-file-list>
Obviously, there's no handler for an empty directory root; Tomcat 7, when presented with a directory root, goes to this list to see what to pass to the webapp. Absent a matching item, Tomcat 6 would simply pass the directory root through to the webapp, but Tomcat 7 doesn't; it always chooses the first item and passes that through. If your application isn't expecting it, the result will be an error. Assuming your application (Cocoon or eXist) is set up to handle everything it might get, then the best option is to comment out all the <welcome-file> elements; if this is done, then Tomcat seems to hand off all processing to the webapp.
Incidentally, you have to restart Tomcat between changes to web.xml to cause them to have an effect (according to the web).
Other configuration changes may need to be made in eXist and/or Cocoon (if used), and these are detailed elsewhere on the blog. These changes relate specifically to Tomcat.