Latest revision as of 23:51, 19 November 2015

By default some servers use the ISO-8859-1 encoding for request parameters and request body. What is more, changing the encoding for request body on such servers has no influence on the encoding of the request parameters. This may cause problems if you want to use international file names with CKFinder which expects request body and parameters to be encoded in UTF-8. To overcome this issue you can either set UTF-8 URI encoding on the server or if you do not have enough privileges to do that, you can adjust CKFinder to use same URI encoding as your server.
You will find more detailed instructions below.

GlassFish 3.0

According to Glassfish 3.0 documentation default parameter encoding for requests is ISO-8859-1. To change this encoding to UTF-8 you have to use the sun-web.xml file with xml parameter-encoding element. This file has to be placed in the WEB-INF folder of your web application.
CKFinder sample web application comes with such a file. If you are using Glassfish 3.0, want to use UTF-8, and to integrate CKFinder in to your application then apart from files mentioned in the Integration section, copy sun-web.xml as well.
Below is the code for the sun-web.xml file:

<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD GlassFish Application Server 3.0 Servlet 3.0//EN"
 "http://www.sun.com/software/appserver/dtds/sun-web-app_3_0-0.dtd">
<sun-web-app>
	<parameter-encoding default-charset="UTF-8" />
</sun-web-app>

GlassFish 3.1+

By default this server uses ISO-8859-1 for parameter encoding. In order to change this to UTF-8, you have to use the glassfish-web.xml file with xml parameter-encoding element. This file has to be placed in the WEB-INF folder of the web application.
CKFinder sample web application comes with such a file. If you are using Glassfish 3.1 or above, want to use UTF-8, and to integrate CKFinder in to your application then apart from files mentioned in the Integration section, copy glassfish-web.xml as well.
Below is the code for the glassfish-web.xml file:

<!DOCTYPE glassfish-web-app PUBLIC "-//GlassFish.org//DTD GlassFish Application Server 3.1 Servlet 3.0//EN" 
"http://glassfish.org/dtds/glassfish-web-app_3_0-1.dtd">
<glassfish-web-app>
    <parameter-encoding default-charset="UTF-8" />
</glassfish-web-app>

Tomcat

According to Tomcat FAQ, Tomcat 5-7 by default use the ISO-8859-1 encoding for handling HTTP request parameters.

Starting with version 5 for all GET requests, when the encoding type used is different from the default one, the query parameters are not encoded in the same way as the request body. To be more specific, if you want to use the encoding other than the default ISO-8859-1 (like UTF-8, for example), the HttpServletRequest.setCharacterEncoding("UTF-8") method will only be applied to the request body, and not the URI.

In order to encode the query parameters just like the requests, you should use the URIEncoding="UTF-8" attribute in the Connector element of the Server.xml file:

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

In Tomcat 8 the default value of URIEncoding attribute depends on org.apache.catalina.STRICT_SERVLET_COMPLIANCE system property. When "strict servlet compliance" is off (default value), URIEncoding is now UTF-8. If "strict servlet compliance" is enabled, the URIEncoding is ISO-8859-1.
In other words, the URIEncoding in Tomcat 8+ is now optional but if you are getting encoding problems (e.g. because org.apache.catalina.STRICT_SERVLET_COMPLIANCE was enabled) you can set this attribute explicitly to UTF-8 in the Connector element.

JBOSS EAP 6

By default this server uses ISO-8859-1 for parameter encoding. To change this to UTF-8, you have to modify the configuration file appropriate for the mode and configuration used.
As you probably know, JBOSS EAP can run in two modes ("domain" and "standalone") and can use various configurations. To simplify the example let us assume that the server uses the standalone mode and default configuration. In order to set UTF-8 for URI encoding you have to edit the JBOSS_HOME/standalone/configuration/standalone.xml file and add a system property named org.apache.catalina.connector.URI_ENCODING,(with value set to UTF-8) to the system-properties element.
Below is the code that needs to be added to the configuration file you use:

<system-properties>
    <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/>
</system-properties>

Please note that the system-properties node has to be placed directly under the extensions node, in standalone.xml file, or you will get parse errors.

WildFly

The WildFly belongs to the group of servers which use UTF-8 encoding for handling request parameters. Configuration setting responsible for the encoding is url-charset. In order to use international file names in CKFinder, one must leave url-charset setting with its default value and use setCharacterEncoding("UTF-8"); for requests and setCharacterEncoding("UTF-8"); or setContentType("UTF-8"); for responses in the application. CKFinder is using the mentioned methods however since request parameters sent in the request body (occurs with an HTTP POST request) are parsed only once, it is very important that proper encoding is set as early as possible (best in a filter), before any reading of the parameters is performed.

Weblogic

This server follows J2EE specification when it comes to encoding. This means that if no encoding is specified then default ISO-8859-1 is set for everything (Servlets, JSP, Tag Files) except for XML format files.
Weblogic documentation provides a couple of ways for setting the encoding you want (UTF-8 in this case). There are server typical methods as well as general Servlet API methods. It seems the best way to set encoding in the WLS server is using setCharacterEncoding("UTF-8"); for requests and setCharacterEncoding("UTF-8"); or setContentType("UTF-8"); for responses.

Please see this link (Web Components section) for more details on setting appropriate encoding on the server-side.

Jetty

The Jetty server uses UTF-8 by default. Jetty documentation states if no overriding character encoding is set on a request, Jetty uses UTF-8 encoding.

Alternative Solution (CKFinder Adjustment)

By default, CKFinder uses the UTF-8 encoding, so you should stick to the guidelines presented above in order to make it work properly.

If you cannot or do not want to set this parameter in the server configuration file, CKFinder will try to address this problem for you. This is why the uriEncoding configuration element was created in the config.xml<code> file. This parameter accepts the encoding of your query parameters.
For example, for Tomcat, JBoss, Glassfish, and Weblogic with their default configuration set (which is ISO-8859-1) you should set uriEncoding to ISO-8859-1 and CKFinder will convert the query parameters for you.

<uriEncoding>ISO-8859-1</uriEncoding>