source: trunk/doc/configure_unicode_support.txt @ 3675

How to configure MySQL and Tomcat to support unicode
====================================================

The BASE core and web client supports unicode, but to take
advantage of that the database and the servlet container must
also be correctly configured. This document describes how to configure
MySQL and Tomcat to fully support unicode using the UTF-8 character
encoding. The configuration should be done BEFORE installing and
building the database.


MySQL
-----
There are two steps that must be done BEFORE the BASE
server is installed:

1. Make sure the database tables can handle UTF-8 data.
   This easiest done when you create the database by adding 
   a default character encoding to the CREATE DATABASE statment,
   for example:

   CREATE DATABASE base2 DEFAULT CHARACTER SET utf8;

2. Make sure the JDBC connection uses UTF-8 as the character set 
   to communicate with the database. This is done by specifying it
   in the db.url property in the base.config file:
   
   db.url = jdbc:mysql://127.0.0.1/base2?characterEncoding=UTF-8

Note that in the SQL statement you should use 'utf8' but in the
connection string you should use 'UTF-8'. If 'UTF-8' doesn't work
in the connection string you may try using 'utf8' there as well.
In our original test only 'utf8' worked but we have got reports
stating that now only 'UTF-8' works. If you are using another 
database than MySQL you have to look in the documentation for that 
database how to enable unicode support.

Tomcat
------
Again, there are two steps that must be done:

1. Change the character encoding parameter in the web.xml file.
   The web.xml file is located in the BASE_HOME/www/WEB-INF
   directory. In the bottom of that file you will find a <filter>
   tag with the name "characterEncoding". Change the value
   of the <param-value> tag to UTF-8:

   <filter>
      <filter-name>characterEncoding</filter-name>
      <filter-class>
         net.sf.basedb.clients.web.servlet.CharacterEncodingFilter
      </filter-class>
      <init-param>
         <param-name>characterEncoding</param-name>
         <param-value>UTF-8</param-value>
      </init-param>
   </filter>

2. You must also edit the server.xml found in Tomcats configuration
   directory, TOMCAT_HOME/conf. In this file you must add the 
   useBodyEncodingForURI="true" attribute to the <Connector> tag:

   <Connector port="8080" 
      ...lots of other attributes...
      useBodyEncodingForURI="true"
   />

If you are using another servlet container than Tomcat you should
look in the documentation for that container how to make the configuration
in step 2. 


Other character encodings
-------------------------
Of course, you are not limited to the UTF-8 character encoding. You can specify 
any encoding you want as long as the encoding is supported by both the database 
and the servlet container. If you want to change the encoding after the database
has been created and populated with data you must somehow tell the database engine
to convert the existing data to the new encoding. For instructions how to do that
(it might be impossible) look in the documentation for your database.