Module org.omnifaces

Package org.omnifaces.filter

Class CharacterEncodingFilter

java.lang.Object

org.omnifaces.filter.HttpFilter

org.omnifaces.filter.CharacterEncodingFilter

All Implemented Interfaces:

Filter

public class CharacterEncodingFilter
extends HttpFilter

This filter will set the request body character encoding when not already set by the client. Even though Faces/Facelets uses by default UTF-8 everywhere, which is the best charset choice these days, Faces/Facelets might fail to set it to UTF-8 when something else has set it to a different value before Faces/Facelets gets the chance to set it during the restore view phase. PrimeFaces 3.x for example is known to do that. During ajax requests, it will call ExternalContext.getRequestParameterMap() inside PartialViewContext.isAjaxRequest() right before building/restoring the view, which will implicitly set the request body character encoding to the server-default value, which is not UTF-8 per se.

Installation

To get this filter to run, map it as follows in web.xml:

 <filter>
     <filter-name>characterEncodingFilter</filter-name>
     <filter-class>org.omnifaces.filter.CharacterEncodingFilter</filter-class>
 </filter>
 <filter-mapping>
     <filter-name>characterEncodingFilter</filter-name>
     <url-pattern>/*</url-pattern>
 </filter-mapping>
 

Configuration (optional)

As Faces/Facelets uses by default UTF-8 everywhere, the default charset is also set to UTF-8. When really necessary for some reason, then it can be overridden by specifying the encoding initialization parameter in the <filter> element as follows:

 <init-param>
     <description>The character encoding which is to be used to parse the HTTP request body. Defaults to UTF-8.</description>
     <param-name>encoding</param-name>
     <param-value>ISO-8859-1</param-value>
 </init-param>
 

Please note that this only affects HTTP POST requests, not HTTP GET requests. For HTTP GET requests, you should be specifying the charset at servletcontainer level (e.g. <Context URIEncoding="UTF-8"> in Tomcat, or <parameter-encoding default-charset="UTF-8"> in Glassfish, or <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true" /> in JBoss in combination with this filter). Also note that this doesn't affect HTTP responses in any way. For HTTP responses, you should be specifying the charset in <f:view encoding>, which also already defaults to UTF-8 by the way.

See also:
Unicode input retrieved via PrimeFaces input components become corrupted

Since:

1.2

Author:

Bauke Scholtz

See Also:

• HttpFilter

Constructor Summary

Constructors

Constructor	Description
CharacterEncodingFilter()

Method Summary

Modifier and Type	Method	Description
void	doFilter(HttpServletRequest request, HttpServletResponse response, HttpSession session, FilterChain chain)	Perform the filtering job.
void	init()	Initializes the filter parameters.

Methods inherited from class org.omnifaces.filter.HttpFilter

destroy, doFilter, getFilterConfig, getInitParameter, getServletContext, init

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CharacterEncodingFilter

public CharacterEncodingFilter()

Method Details

init

public void init()
          throws ServletException

Initializes the filter parameters.

Overrides:

init in class HttpFilter

Throws:

ServletException - When filter's initialization failed.

doFilter

public void doFilter(HttpServletRequest request,
 HttpServletResponse response,
 HttpSession session,
 FilterChain chain)
              throws ServletException,
IOException

Perform the filtering job. Only if the request character encoding has not been set yet, then set it.

Specified by:

doFilter in class HttpFilter

Parameters:

request - The HTTP request.

response - The HTTP response.

session - The HTTP session, if any, else null.

chain - The filter chain to continue.

Throws:

ServletException - As wrapper exception when something fails in the request processing.

IOException - Whenever something fails at I/O level.

See Also:

• Filter.doFilter(ServletRequest, ServletResponse, FilterChain)