1. Introduction

Depuis la version 5.5 de JCMS, toutes les ressources et flux sortant/entrant de JCMS sont encodés en UTF-8 qui est un format de codage de caractères Unicode (UCS).

Ceci concerne les ressources suivantes :

2. Migration d'une ancienne webapp

2.1 Configuration du serveur d'applications

2.1.1 Tomcat 5

Ajoutez URIEncoding='UTF-8' dans le connector Coyote (conf/server.xml).
Cette modification est incompatible avec les anciennes versions de JCMS. Si d'autre webapps JCMS 5.0 ou 4 fonctionnent avec ce connecteur, déclarer un nouveau connecteur pour la migration.

2.1.2 Resin 2

Ajoutez <character-encoding>UTF-8</character-encoding> dans la section <host>.
Cette modification est incompatible avec les anciennes versions de JCMS. Si d'autre webapps JCMS 5.0 ou 4 fonctionnent avec sur cet hôte, déclarer un nouvel hôte pour la migration.

Modifiez l'attribut compiler-args de la balise <java> pour y ajouter les options de compilations des classes en UTF-8:
<java compiler="internal" compiler-args="-encoding UTF-8"/>

2.1.3 Resin 3

Ajoutez l'attribut encoding de la balise <javac> avec la valeur UTF-8:
<javac compiler="internal" args="" encoding="UTF-8"/>

2.1.4 Weblogic 8.1 et WebSphere 6

Aucune modification n'est nécessaire pour ces serveurs d'applications.

2.1.5 Autres serveurs d'applications

Consultez la documentation de votre serveur d'application.

2.2 Conversion des fichiers

Après avoir récupéré un delta de votre webapp via le Gestionnaire des changements, utilisez l'utilitaire UTF8Converter pour convertir automatiquement l'ensemble des fichiers qui ne sont pas déjà en UTF-8 :

• Dans JCMS 5.5, aller sur admin/classpath.jsp et suivre les instructions. Garder la fenêtre de commande ouverte, vous en aurez besoins à l'étape 3 pour la conversion UTF-8.
• Dans la fenêtre de commande, déplacez vous dans le répertoire parent du répertoire delta.
• Lancer le UTF8Converter sur le répertoire delta :
  • java com.jalios.jcms.tools.UTF8Converter delta

Outre la conversion UTF-8, le convertisseur fournit dans JCMS 5.5 se charge de modifier les entêtes des fichiers XML et d'ajouter la directive contentType pour les JSP (uniquement à partir de JCMS 5.6).

3. Recommandations de développement

3.1 Sources Java

3.1.1 Servlet et ServletFilter

Dans les Servlets précisez request.setCharacterEncoding("UTF-8") avant tout appel à request.getParameter(String) pour assurer le bon décodage des paramêtres par le serveur d'applications. Pour les ServletFilter, ca n'est pas nécessaire si elles se situent après la InitFilter de JCMS 5.5 qui s'en charge. Dans le cas contraire, il faut faire la même déclaration pour les Servlets.

3.1.2 String.getBytes()

Utilisez systématiquement la méthode String.getBytes(String) ou l'on précise l'encodage :

String.getBytes() ==> String.getBytes("UTF-8")

3.1.3 RandomAccessFile.write...

N'utilisez pas RandomAccessFile.writeUTF() qui ajoute un BOM (Byte Order Mark), ni tout autre méthode "write" de la classe RandomAccessFile à l'exception de RandomAccessFile.write(byte), en ayant au préalable converti votre String en bytes UTF-8.

raf.write(strToWrite.getBytes("UTF-8"))

3.1.4 ByteArrayOutputStream

Pensez à correctement convertir les ByteArrayOutputStream en UTF-8, par exemple:

ByteArrayOutputStream baos = new ByteArrayOutputStream();
...
String str = baos.toString("UTF-8");

3.1.5 FileReader et FileWriter

N'utilisez plus FileReader(String|File) et FileWriter(String|File), qui utilise l'encodage par défaut de la plate-forme, mais à la place :

// FileWriter
Writer w = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(file), "UTF-8"));
// FileReader
Reader r = new BufferedReader(new InputStreamReader(new FileInputStream(file), "UTF-8"));

Cependant, pensez à bien conserver le paramètre append dans FileInputStream le cas échéant.

3.1.6 PrintStream

Utilisez pas le constructeur PrintStream(...) en précisant l'encodage :

new PrintStream(fos, false, "UTF-8");

3.2 Sources JSP

3.2.1 Encodage des JSP

Ajoutez systématiquement la directive contentType au début des JSP qui contiennent des caractères non ASCII:

<%@ page contentType="text/plain; charset=UTF-8"%>

Cet ajout est automatiquement réalisé par l'utilitaire de conversion UTF8Converter à partir de JCMS 5.6.

3.2.2 Content-Type des JSP

Lorsque vous avez besoin de modifier le content-type de sortie d'un JSP (pour faire du XML ou du CSV par exemple), précisez l'attribut de requête ContentType avant l'inclusion de doInitPage.jsp (attribut spécifique à JCMS).

<%
  // inform doInitPage to set the proper content type
  request.setAttribute("ContentType", "text/xml; charset=UTF-8"); 
%><?xml version="1.0" encoding="UTF-8"?>
<%@ include file="/jcore/doInitPage.jsp" %>

3.3 Fichiers statiques

3.3.1 HTML

Précisez l'entête suivante le plus tôt possible dans la balise head :

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

3.3.2 XML

Ajoutez l'entête XML UTF-8 en tout début de fichier :

<?xml version="1.0" encoding="UTF-8"?>