001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018
019 package filters;
020
021
022 import java.io.IOException;
023 import javax.servlet.Filter;
024 import javax.servlet.FilterChain;
025 import javax.servlet.FilterConfig;
026 import javax.servlet.ServletException;
027 import javax.servlet.ServletRequest;
028 import javax.servlet.ServletResponse;
029
030
031 /**
032 * <p>Example filter that sets the character encoding to be used in parsing the
033 * incoming request, either unconditionally or only if the client did not
034 * specify a character encoding. Configuration of this filter is based on
035 * the following initialization parameters:</p>
036 * <ul>
037 * <li><strong>encoding</strong> - The character encoding to be configured
038 * for this request, either conditionally or unconditionally based on
039 * the <code>ignore</code> initialization parameter. This parameter
040 * is required, so there is no default.</li>
041 * <li><strong>ignore</strong> - If set to "true", any character encoding
042 * specified by the client is ignored, and the value returned by the
043 * <code>selectEncoding()</code> method is set. If set to "false,
044 * <code>selectEncoding()</code> is called <strong>only</strong> if the
045 * client has not already specified an encoding. By default, this
046 * parameter is set to "true".</li>
047 * </ul>
048 *
049 * <p>Although this filter can be used unchanged, it is also easy to
050 * subclass it and make the <code>selectEncoding()</code> method more
051 * intelligent about what encoding to choose, based on characteristics of
052 * the incoming request (such as the values of the <code>Accept-Language</code>
053 * and <code>User-Agent</code> headers, or a value stashed in the current
054 * user's session.</p>
055 *
056 * @author Craig McClanahan
057 * @version $Revision: 514091 $ $Date: 2007-03-03 01:26:39 -0500 (Sat, 03 Mar 2007) $
058 */
059
060 public class SetCharacterEncodingFilter implements Filter {
061
062
063 // ----------------------------------------------------- Instance Variables
064
065
066 /**
067 * The default character encoding to set for requests that pass through
068 * this filter.
069 */
070 protected String encoding = null;
071
072
073 /**
074 * The filter configuration object we are associated with. If this value
075 * is null, this filter instance is not currently configured.
076 */
077 protected FilterConfig filterConfig = null;
078
079
080 /**
081 * Should a character encoding specified by the client be ignored?
082 */
083 protected boolean ignore = true;
084
085
086 // --------------------------------------------------------- Public Methods
087
088
089 /**
090 * Take this filter out of service.
091 */
092 public void destroy() {
093
094 this.encoding = null;
095 this.filterConfig = null;
096
097 }
098
099
100 /**
101 * Select and set (if specified) the character encoding to be used to
102 * interpret request parameters for this request.
103 *
104 * @param request The servlet request we are processing
105 * @param result The servlet response we are creating
106 * @param chain The filter chain we are processing
107 *
108 * @exception IOException if an input/output error occurs
109 * @exception ServletException if a servlet error occurs
110 */
111 public void doFilter(ServletRequest request, ServletResponse response,
112 FilterChain chain)
113 throws IOException, ServletException {
114
115 // Conditionally select and set the character encoding to be used
116 if (ignore || (request.getCharacterEncoding() == null)) {
117 String encoding = selectEncoding(request);
118 if (encoding != null)
119 request.setCharacterEncoding(encoding);
120 }
121
122 // Pass control on to the next filter
123 chain.doFilter(request, response);
124
125 }
126
127
128 /**
129 * Place this filter into service.
130 *
131 * @param filterConfig The filter configuration object
132 */
133 public void init(FilterConfig filterConfig) throws ServletException {
134
135 this.filterConfig = filterConfig;
136 this.encoding = filterConfig.getInitParameter("encoding");
137 String value = filterConfig.getInitParameter("ignore");
138 if (value == null)
139 this.ignore = true;
140 else if (value.equalsIgnoreCase("true"))
141 this.ignore = true;
142 else if (value.equalsIgnoreCase("yes"))
143 this.ignore = true;
144 else
145 this.ignore = false;
146
147 }
148
149
150 // ------------------------------------------------------ Protected Methods
151
152
153 /**
154 * Select an appropriate character encoding to be used, based on the
155 * characteristics of the current request and/or filter initialization
156 * parameters. If no character encoding should be set, return
157 * <code>null</code>.
158 * <p>
159 * The default implementation unconditionally returns the value configured
160 * by the <strong>encoding</strong> initialization parameter for this
161 * filter.
162 *
163 * @param request The servlet request we are processing
164 */
165 protected String selectEncoding(ServletRequest request) {
166
167 return (this.encoding);
168
169 }
170
171
172 }