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 018package org.apache.commons.codec.net; 019 020import java.io.ByteArrayOutputStream; 021import java.io.UnsupportedEncodingException; 022import java.util.BitSet; 023 024import org.apache.commons.codec.BinaryDecoder; 025import org.apache.commons.codec.BinaryEncoder; 026import org.apache.commons.codec.CharEncoding; 027import org.apache.commons.codec.DecoderException; 028import org.apache.commons.codec.EncoderException; 029import org.apache.commons.codec.StringDecoder; 030import org.apache.commons.codec.StringEncoder; 031import org.apache.commons.codec.binary.StringUtils; 032 033/** 034 * Implements the 'www-form-urlencoded' encoding scheme, also misleadingly known as URL encoding. 035 * <p> 036 * This codec is meant to be a replacement for standard Java classes {@link java.net.URLEncoder} and 037 * {@link java.net.URLDecoder} on older Java platforms, as these classes in Java versions below 038 * 1.4 rely on the platform's default charset encoding. 039 * </p> 040 * <p> 041 * This class is thread-safe as of 1.11 042 * </p> 043 * 044 * @see <a href="http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1">Chapter 17.13.4 Form content types</a> 045 * of the <a href="http://www.w3.org/TR/html4/">HTML 4.01 Specification</a> 046 * 047 * @since 1.2 048 */ 049public class URLCodec implements BinaryEncoder, BinaryDecoder, StringEncoder, StringDecoder { 050 051 /** 052 * The default charset used for string decoding and encoding. 053 * 054 * @deprecated TODO: This field will be changed to a private final Charset in 2.0. (CODEC-126) 055 */ 056 @Deprecated 057 protected volatile String charset; // added volatile: see CODEC-232 058 059 /** 060 * Release 1.5 made this field final. 061 */ 062 protected static final byte ESCAPE_CHAR = '%'; 063 064 /** 065 * BitSet of www-form-url safe characters. 066 * This is a copy of the internal BitSet which is now used for the conversion. 067 * Changes to this field are ignored. 068 * @deprecated 1.11 Will be removed in 2.0 (CODEC-230) 069 */ 070 @Deprecated 071 protected static final BitSet WWW_FORM_URL; 072 073 private static final BitSet WWW_FORM_URL_SAFE = new BitSet(256); 074 075 // Static initializer for www_form_url 076 static { 077 // alpha characters 078 for (int i = 'a'; i <= 'z'; i++) { 079 WWW_FORM_URL_SAFE.set(i); 080 } 081 for (int i = 'A'; i <= 'Z'; i++) { 082 WWW_FORM_URL_SAFE.set(i); 083 } 084 // numeric characters 085 for (int i = '0'; i <= '9'; i++) { 086 WWW_FORM_URL_SAFE.set(i); 087 } 088 // special chars 089 WWW_FORM_URL_SAFE.set('-'); 090 WWW_FORM_URL_SAFE.set('_'); 091 WWW_FORM_URL_SAFE.set('.'); 092 WWW_FORM_URL_SAFE.set('*'); 093 // blank to be replaced with + 094 WWW_FORM_URL_SAFE.set(' '); 095 096 // Create a copy in case anyone (ab)uses it 097 WWW_FORM_URL = (BitSet) WWW_FORM_URL_SAFE.clone(); 098 } 099 100 101 /** 102 * Default constructor. 103 */ 104 public URLCodec() { 105 this(CharEncoding.UTF_8); 106 } 107 108 /** 109 * Constructor which allows for the selection of a default charset. 110 * 111 * @param charset the default string charset to use. 112 */ 113 public URLCodec(final String charset) { 114 this.charset = charset; 115 } 116 117 /** 118 * Encodes an array of bytes into an array of URL safe 7-bit characters. Unsafe characters are escaped. 119 * 120 * @param urlsafe 121 * bitset of characters deemed URL safe 122 * @param bytes 123 * array of bytes to convert to URL safe characters 124 * @return array of bytes containing URL safe characters 125 */ 126 public static final byte[] encodeUrl(BitSet urlsafe, final byte[] bytes) { 127 if (bytes == null) { 128 return null; 129 } 130 if (urlsafe == null) { 131 urlsafe = WWW_FORM_URL_SAFE; 132 } 133 134 final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); 135 for (final byte c : bytes) { 136 int b = c; 137 if (b < 0) { 138 b = 256 + b; 139 } 140 if (urlsafe.get(b)) { 141 if (b == ' ') { 142 b = '+'; 143 } 144 buffer.write(b); 145 } else { 146 buffer.write(ESCAPE_CHAR); 147 final char hex1 = Utils.hexDigit(b >> 4); 148 final char hex2 = Utils.hexDigit(b); 149 buffer.write(hex1); 150 buffer.write(hex2); 151 } 152 } 153 return buffer.toByteArray(); 154 } 155 156 /** 157 * Decodes an array of URL safe 7-bit characters into an array of original bytes. Escaped characters are converted 158 * back to their original representation. 159 * 160 * @param bytes 161 * array of URL safe characters 162 * @return array of original bytes 163 * @throws DecoderException 164 * Thrown if URL decoding is unsuccessful 165 */ 166 public static final byte[] decodeUrl(final byte[] bytes) throws DecoderException { 167 if (bytes == null) { 168 return null; 169 } 170 final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); 171 for (int i = 0; i < bytes.length; i++) { 172 final int b = bytes[i]; 173 if (b == '+') { 174 buffer.write(' '); 175 } else if (b == ESCAPE_CHAR) { 176 try { 177 final int u = Utils.digit16(bytes[++i]); 178 final int l = Utils.digit16(bytes[++i]); 179 buffer.write((char) ((u << 4) + l)); 180 } catch (final ArrayIndexOutOfBoundsException e) { 181 throw new DecoderException("Invalid URL encoding: ", e); 182 } 183 } else { 184 buffer.write(b); 185 } 186 } 187 return buffer.toByteArray(); 188 } 189 190 /** 191 * Encodes an array of bytes into an array of URL safe 7-bit characters. Unsafe characters are escaped. 192 * 193 * @param bytes 194 * array of bytes to convert to URL safe characters 195 * @return array of bytes containing URL safe characters 196 */ 197 @Override 198 public byte[] encode(final byte[] bytes) { 199 return encodeUrl(WWW_FORM_URL_SAFE, bytes); 200 } 201 202 203 /** 204 * Decodes an array of URL safe 7-bit characters into an array of original bytes. Escaped characters are converted 205 * back to their original representation. 206 * 207 * @param bytes 208 * array of URL safe characters 209 * @return array of original bytes 210 * @throws DecoderException 211 * Thrown if URL decoding is unsuccessful 212 */ 213 @Override 214 public byte[] decode(final byte[] bytes) throws DecoderException { 215 return decodeUrl(bytes); 216 } 217 218 /** 219 * Encodes a string into its URL safe form using the specified string charset. Unsafe characters are escaped. 220 * 221 * @param str 222 * string to convert to a URL safe form 223 * @param charsetName 224 * the charset for str 225 * @return URL safe string 226 * @throws UnsupportedEncodingException 227 * Thrown if charset is not supported 228 */ 229 public String encode(final String str, final String charsetName) throws UnsupportedEncodingException { 230 if (str == null) { 231 return null; 232 } 233 return StringUtils.newStringUsAscii(encode(str.getBytes(charsetName))); 234 } 235 236 /** 237 * Encodes a string into its URL safe form using the default string charset. Unsafe characters are escaped. 238 * 239 * @param str 240 * string to convert to a URL safe form 241 * @return URL safe string 242 * @throws EncoderException 243 * Thrown if URL encoding is unsuccessful 244 * 245 * @see #getDefaultCharset() 246 */ 247 @Override 248 public String encode(final String str) throws EncoderException { 249 if (str == null) { 250 return null; 251 } 252 try { 253 return encode(str, getDefaultCharset()); 254 } catch (final UnsupportedEncodingException e) { 255 throw new EncoderException(e.getMessage(), e); 256 } 257 } 258 259 260 /** 261 * Decodes a URL safe string into its original form using the specified encoding. Escaped characters are converted 262 * back to their original representation. 263 * 264 * @param str 265 * URL safe string to convert into its original form 266 * @param charsetName 267 * the original string charset 268 * @return original string 269 * @throws DecoderException 270 * Thrown if URL decoding is unsuccessful 271 * @throws UnsupportedEncodingException 272 * Thrown if charset is not supported 273 */ 274 public String decode(final String str, final String charsetName) 275 throws DecoderException, UnsupportedEncodingException { 276 if (str == null) { 277 return null; 278 } 279 return new String(decode(StringUtils.getBytesUsAscii(str)), charsetName); 280 } 281 282 /** 283 * Decodes a URL safe string into its original form using the default string charset. Escaped characters are 284 * converted back to their original representation. 285 * 286 * @param str 287 * URL safe string to convert into its original form 288 * @return original string 289 * @throws DecoderException 290 * Thrown if URL decoding is unsuccessful 291 * @see #getDefaultCharset() 292 */ 293 @Override 294 public String decode(final String str) throws DecoderException { 295 if (str == null) { 296 return null; 297 } 298 try { 299 return decode(str, getDefaultCharset()); 300 } catch (final UnsupportedEncodingException e) { 301 throw new DecoderException(e.getMessage(), e); 302 } 303 } 304 305 /** 306 * Encodes an object into its URL safe form. Unsafe characters are escaped. 307 * 308 * @param obj 309 * string to convert to a URL safe form 310 * @return URL safe object 311 * @throws EncoderException 312 * Thrown if URL encoding is not applicable to objects of this type or if encoding is unsuccessful 313 */ 314 @Override 315 public Object encode(final Object obj) throws EncoderException { 316 if (obj == null) { 317 return null; 318 } 319 if (obj instanceof byte[]) { 320 return encode((byte[])obj); 321 } 322 if (obj instanceof String) { 323 return encode((String)obj); 324 } 325 throw new EncoderException("Objects of type " + obj.getClass().getName() + " cannot be URL encoded"); 326 } 327 328 /** 329 * Decodes a URL safe object into its original form. Escaped characters are converted back to their original 330 * representation. 331 * 332 * @param obj 333 * URL safe object to convert into its original form 334 * @return original object 335 * @throws DecoderException 336 * Thrown if the argument is not a {@code String} or {@code byte[]}. Thrown if a failure 337 * condition is encountered during the decode process. 338 */ 339 @Override 340 public Object decode(final Object obj) throws DecoderException { 341 if (obj == null) { 342 return null; 343 } 344 if (obj instanceof byte[]) { 345 return decode((byte[]) obj); 346 } 347 if (obj instanceof String) { 348 return decode((String) obj); 349 } 350 throw new DecoderException("Objects of type " + obj.getClass().getName() + " cannot be URL decoded"); 351 } 352 353 /** 354 * The default charset used for string decoding and encoding. 355 * 356 * @return the default string charset. 357 */ 358 public String getDefaultCharset() { 359 return this.charset; 360 } 361 362 /** 363 * The {@code String} encoding used for decoding and encoding. 364 * 365 * @return Returns the encoding. 366 * 367 * @deprecated Use {@link #getDefaultCharset()}, will be removed in 2.0. 368 */ 369 @Deprecated 370 public String getEncoding() { 371 return this.charset; 372 } 373 374}