1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19 package filters;
20
21
22 import java.io.IOException;
23
24 import javax.servlet.Filter;
25 import javax.servlet.FilterChain;
26 import javax.servlet.FilterConfig;
27 import javax.servlet.ServletException;
28 import javax.servlet.ServletRequest;
29 import javax.servlet.ServletResponse;
30
31
32 /**
33 * <p>Example filter that sets the character encoding to be used in parsing the
34 * incoming request, either unconditionally or only if the client did not
35 * specify a character encoding. Configuration of this filter is based on
36 * the following initialization parameters:</p>
37 * <ul>
38 * <li><strong>encoding</strong> - The character encoding to be configured
39 * for this request, either conditionally or unconditionally based on
40 * the <code>ignore</code> initialization parameter. This parameter
41 * is required, so there is no default.</li>
42 * <li><strong>ignore</strong> - If set to "true", any character encoding
43 * specified by the client is ignored, and the value returned by the
44 * <code>selectEncoding()</code> method is set. If set to "false,
45 * <code>selectEncoding()</code> is called <strong>only</strong> if the
46 * client has not already specified an encoding. By default, this
47 * parameter is set to "true".</li>
48 * </ul>
49 * <p/>
50 * <p>Although this filter can be used unchanged, it is also easy to
51 * subclass it and make the <code>selectEncoding()</code> method more
52 * intelligent about what encoding to choose, based on characteristics of
53 * the incoming request (such as the values of the <code>Accept-Language</code>
54 * and <code>User-Agent</code> headers, or a value stashed in the current
55 * user's session.</p>
56 *
57 * @author Craig McClanahan
58 * @version $Revision: 664175 $ $Date: 2008-06-06 18:43:44 -0400 (Fri, 06 Jun 2008) $
59 */
60
61 public class SetCharacterEncodingFilter implements Filter {
62
63 // ----------------------------------------------------- Instance Variables
64
65
66 /**
67 * The default character encoding to set for requests that pass through
68 * this filter.
69 */
70 protected String encoding = null;
71
72
73 /**
74 * The filter configuration object we are associated with. If this value
75 * is null, this filter instance is not currently configured.
76 */
77 protected FilterConfig filterConfig = null;
78
79
80 /**
81 * Should a character encoding specified by the client be ignored?
82 */
83 protected boolean ignore = true;
84
85 // --------------------------------------------------------- Public Methods
86
87
88 /**
89 * Take this filter out of service.
90 */
91 public void destroy() {
92
93 this.encoding = null;
94 this.filterConfig = null;
95
96 }
97
98
99 /**
100 * Select and set (if specified) the character encoding to be used to
101 * interpret request parameters for this request.
102 *
103 * @param request The servlet request we are processing
104 * @param result The servlet response we are creating
105 * @param chain The filter chain we are processing
106 * @throws IOException if an input/output error occurs
107 * @throws ServletException if a servlet error occurs
108 */
109 public void doFilter(ServletRequest request, ServletResponse response,
110 FilterChain chain)
111 throws IOException, ServletException {
112
113 // Conditionally select and set the character encoding to be used
114 if (ignore || (request.getCharacterEncoding() == null)) {
115 String encoding = selectEncoding(request);
116 if (encoding != null)
117 request.setCharacterEncoding(encoding);
118 }
119
120 // Pass control on to the next filter
121 chain.doFilter(request, response);
122
123 }
124
125
126 /**
127 * Place this filter into service.
128 *
129 * @param filterConfig The filter configuration object
130 */
131 public void init(FilterConfig filterConfig) throws ServletException {
132
133 this.filterConfig = filterConfig;
134 this.encoding = filterConfig.getInitParameter("encoding");
135 String value = filterConfig.getInitParameter("ignore");
136 if (value == null)
137 this.ignore = true;
138 else if (value.equalsIgnoreCase("true"))
139 this.ignore = true;
140 else if (value.equalsIgnoreCase("yes"))
141 this.ignore = true;
142 else
143 this.ignore = false;
144
145 }
146
147 // ------------------------------------------------------ Protected Methods
148
149
150 /**
151 * Select an appropriate character encoding to be used, based on the
152 * characteristics of the current request and/or filter initialization
153 * parameters. If no character encoding should be set, return
154 * <code>null</code>.
155 * <p/>
156 * The default implementation unconditionally returns the value configured
157 * by the <strong>encoding</strong> initialization parameter for this
158 * filter.
159 *
160 * @param request The servlet request we are processing
161 */
162 protected String selectEncoding(ServletRequest request) {
163
164 return (this.encoding);
165
166 }
167
168
169 }