1 /*
2 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.net;
27
28 import java.io.ByteArrayOutputStream;
29 import java.io.BufferedWriter;
30 import java.io.OutputStreamWriter;
31 import java.io.IOException;
32 import java.io.UnsupportedEncodingException;
33 import java.io.CharArrayWriter;
34 import java.nio.charset.Charset;
35 import java.nio.charset.IllegalCharsetNameException;
36 import java.nio.charset.UnsupportedCharsetException ;
37 import java.util.BitSet;
38 import java.security.AccessController;
39 import java.security.PrivilegedAction;
40 import sun.security.action.GetBooleanAction;
41 import sun.security.action.GetPropertyAction;
42
43 /**
44 * Utility class for HTML form encoding. This class contains static methods
45 * for converting a String to the <CODE>application/x-www-form-urlencoded</CODE> MIME
46 * format. For more information about HTML form encoding, consult the HTML
47 * <A HREF="http://www.w3.org/TR/html4/">specification</A>.
48 *
49 * <p>
50 * When encoding a String, the following rules apply:
51 *
52 * <ul>
53 * <li>The alphanumeric characters "{@code a}" through
54 * "{@code z}", "{@code A}" through
55 * "{@code Z}" and "{@code 0}"
56 * through "{@code 9}" remain the same.
57 * <li>The special characters "{@code .}",
58 * "{@code -}", "{@code *}", and
59 * "{@code _}" remain the same.
60 * <li>The space character " " is
61 * converted into a plus sign "{@code +}".
62 * <li>All other characters are unsafe and are first converted into
63 * one or more bytes using some encoding scheme. Then each byte is
64 * represented by the 3-character string
65 * "<i>{@code %xy}</i>", where <i>xy</i> is the
66 * two-digit hexadecimal representation of the byte.
67 * The recommended encoding scheme to use is UTF-8. However,
68 * for compatibility reasons, if an encoding is not specified,
69 * then the default encoding of the platform is used.
70 * </ul>
71 *
72 * <p>
73 * For example using UTF-8 as the encoding scheme the string "The
74 * string ü@foo-bar" would get converted to
75 * "The+string+%C3%BC%40foo-bar" because in UTF-8 the character
76 * ü is encoded as two bytes C3 (hex) and BC (hex), and the
77 * character @ is encoded as one byte 40 (hex).
78 *
79 * @author Herb Jellinek
80 * @since JDK1.0
81 */
82 public class URLEncoder {
83 static BitSet dontNeedEncoding;
84 static final int caseDiff = ('a' - 'A');
85 static String dfltEncName = null;
86
87 static {
88
89 /* The list of characters that are not encoded has been
90 * determined as follows:
91 *
92 * RFC 2396 states:
93 * -----
94 * Data characters that are allowed in a URI but do not have a
95 * reserved purpose are called unreserved. These include upper
96 * and lower case letters, decimal digits, and a limited set of
97 * punctuation marks and symbols.
98 *
99 * unreserved = alphanum | mark
100 *
101 * mark = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
102 *
103 * Unreserved characters can be escaped without changing the
104 * semantics of the URI, but this should not be done unless the
105 * URI is being used in a context that does not allow the
106 * unescaped character to appear.
107 * -----
108 *
109 * It appears that both Netscape and Internet Explorer escape
110 * all special characters from this list with the exception
111 * of "-", "_", ".", "*". While it is not clear why they are
112 * escaping the other characters, perhaps it is safest to
113 * assume that there might be contexts in which the others
114 * are unsafe if not escaped. Therefore, we will use the same
115 * list. It is also noteworthy that this is consistent with
116 * O'Reilly's "HTML: The Definitive Guide" (page 164).
117 *
118 * As a last note, Intenet Explorer does not encode the "@"
119 * character which is clearly not unreserved according to the
120 * RFC. We are being consistent with the RFC in this matter,
121 * as is Netscape.
122 *
123 */
124
125 dontNeedEncoding = new BitSet(256);
126 int i;
127 for (i = 'a'; i <= 'z'; i++) {
128 dontNeedEncoding.set(i);
129 }
130 for (i = 'A'; i <= 'Z'; i++) {
131 dontNeedEncoding.set(i);
132 }
133 for (i = '0'; i <= '9'; i++) {
134 dontNeedEncoding.set(i);
135 }
136 dontNeedEncoding.set(' '); /* encoding a space to a + is done
137 * in the encode() method */
138 dontNeedEncoding.set('-');
139 dontNeedEncoding.set('_');
140 dontNeedEncoding.set('.');
141 dontNeedEncoding.set('*');
142
143 dfltEncName = AccessController.doPrivileged(
144 new GetPropertyAction("file.encoding")
145 );
146 }
147
148 /**
149 * You can't call the constructor.
150 */
151 private URLEncoder() { }
152
153 /**
154 * Translates a string into {@code x-www-form-urlencoded}
155 * format. This method uses the platform's default encoding
156 * as the encoding scheme to obtain the bytes for unsafe characters.
157 *
158 * @param s {@code String} to be translated.
159 * @deprecated The resulting string may vary depending on the platform's
160 * default encoding. Instead, use the encode(String,String)
161 * method to specify the encoding.
162 * @return the translated {@code String}.
163 */
164 @Deprecated
165 public static String encode(String s) {
166
167 String str = null;
168
169 try {
170 str = encode(s, dfltEncName);
171 } catch (UnsupportedEncodingException e) {
172 // The system should always have the platform default
173 }
174
175 return str;
176 }
177
178 /**
179 * Translates a string into {@code application/x-www-form-urlencoded}
180 * format using a specific encoding scheme. This method uses the
181 * supplied encoding scheme to obtain the bytes for unsafe
182 * characters.
183 * <p>
184 * <em><strong>Note:</strong> The <a href=
185 * "http://www.w3.org/TR/html40/appendix/notes.html#non-ascii-chars">
186 * World Wide Web Consortium Recommendation</a> states that
187 * UTF-8 should be used. Not doing so may introduce
188 * incompatibilities.</em>
189 *
190 * @param s {@code String} to be translated.
191 * @param enc The name of a supported
192 * <a href="../lang/package-summary.html#charenc">character
193 * encoding</a>.
194 * @return the translated {@code String}.
195 * @exception UnsupportedEncodingException
196 * If the named encoding is not supported
197 * @see URLDecoder#decode(java.lang.String, java.lang.String)
198 * @since 1.4
199 */
200 public static String encode(String s, String enc)
201 throws UnsupportedEncodingException {
202
203 boolean needToChange = false;
204 StringBuffer out = new StringBuffer(s.length());
205 Charset charset;
206 CharArrayWriter charArrayWriter = new CharArrayWriter();
207
208 if (enc == null)
209 throw new NullPointerException("charsetName");
210
211 try {
212 charset = Charset.forName(enc);
213 } catch (IllegalCharsetNameException e) {
214 throw new UnsupportedEncodingException(enc);
215 } catch (UnsupportedCharsetException e) {
216 throw new UnsupportedEncodingException(enc);
217 }
218
219 for (int i = 0; i < s.length();) {
220 int c = (int) s.charAt(i);
221 //System.out.println("Examining character: " + c);
222 if (dontNeedEncoding.get(c)) {
223 if (c == ' ') {
224 c = '+';
225 needToChange = true;
226 }
227 //System.out.println("Storing: " + c);
228 out.append((char)c);
229 i++;
230 } else {
231 // convert to external encoding before hex conversion
232 do {
233 charArrayWriter.write(c);
234 /*
235 * If this character represents the start of a Unicode
236 * surrogate pair, then pass in two characters. It's not
237 * clear what should be done if a bytes reserved in the
238 * surrogate pairs range occurs outside of a legal
239 * surrogate pair. For now, just treat it as if it were
240 * any other character.
241 */
242 if (c >= 0xD800 && c <= 0xDBFF) {
243 /*
244 System.out.println(Integer.toHexString(c)
245 + " is high surrogate");
246 */
247 if ( (i+1) < s.length()) {
248 int d = (int) s.charAt(i+1);
249 /*
250 System.out.println("\tExamining "
251 + Integer.toHexString(d));
252 */
253 if (d >= 0xDC00 && d <= 0xDFFF) {
254 /*
255 System.out.println("\t"
256 + Integer.toHexString(d)
257 + " is low surrogate");
258 */
259 charArrayWriter.write(d);
260 i++;
261 }
262 }
263 }
264 i++;
265 } while (i < s.length() && !dontNeedEncoding.get((c = (int) s.charAt(i))));
266
267 charArrayWriter.flush();
268 String str = new String(charArrayWriter.toCharArray());
269 byte[] ba = str.getBytes(charset);
270 for (int j = 0; j < ba.length; j++) {
271 out.append('%');
272 char ch = Character.forDigit((ba[j] >> 4) & 0xF, 16);
273 // converting to use uppercase letter as part of
274 // the hex value if ch is a letter.
275 if (Character.isLetter(ch)) {
276 ch -= caseDiff;
277 }
278 out.append(ch);
279 ch = Character.forDigit(ba[j] & 0xF, 16);
280 if (Character.isLetter(ch)) {
281 ch -= caseDiff;
282 }
283 out.append(ch);
284 }
285 charArrayWriter.reset();
286 needToChange = true;
287 }
288 }
289
290 return (needToChange? out.toString() : s);
291 }
292 }