1 /*
2 * Copyright (C) 2009 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.net;
16
17 import com.google.common.annotations.GwtCompatible;
18 import com.google.common.escape.Escaper;
19
20 /**
21 * {@code Escaper} instances suitable for strings to be included in particular sections of URLs.
22 *
23 * <p>If the resulting URLs are inserted into an HTML or XML document, they will require additional
24 * escaping with {@link com.google.common.html.HtmlEscapers} or {@link
25 * com.google.common.xml.XmlEscapers}.
26 *
27 * @author David Beaumont
28 * @author Chris Povirk
29 * @since 15.0
30 */
31 @GwtCompatible
32 @ElementTypesAreNonnullByDefault
33 public final class UrlEscapers {
34 private UrlEscapers() {}
35
36 // For each xxxEscaper() method, please add links to external reference pages
37 // that are considered authoritative for the behavior of that escaper.
38
39 static final String URL_FORM_PARAMETER_OTHER_SAFE_CHARS = "-_.*";
40
41 static final String URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS =
42 "-._~" // Unreserved characters.
43 + "!$'()*,;&=" // The subdelim characters (excluding '+').
44 + "@:"; // The gendelim characters permitted in paths.
45
46 /**
47 * Returns an {@link Escaper} instance that escapes strings so they can be safely included in <a
48 * href="https://goo.gl/MplK6I">URL form parameter names and values</a>. Escaping is performed
49 * with the UTF-8 character encoding. The caller is responsible for <a
50 * href="https://goo.gl/9EfkM1">replacing any unpaired carriage return or line feed characters
51 * with a CR+LF pair</a> on any non-file inputs before escaping them with this escaper.
52 *
53 * <p>When escaping a String, the following rules apply:
54 *
55 * <ul>
56 * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
57 * the same.
58 * <li>The special characters ".", "-", "*", and "_" remain the same.
59 * <li>The space character " " is converted into a plus sign "+".
60 * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
61 * byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
62 * uppercase, hexadecimal representation of the byte value.
63 * </ul>
64 *
65 * <p>This escaper is suitable for escaping parameter names and values even when <a
66 * href="https://goo.gl/utn6M">using the non-standard semicolon</a>, rather than the ampersand, as
67 * a parameter delimiter. Nevertheless, we recommend using the ampersand unless you must
68 * interoperate with systems that require semicolons.
69 *
70 * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
71 * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
72 *
73 */
74 public static Escaper urlFormParameterEscaper() {
75 return URL_FORM_PARAMETER_ESCAPER;
76 }
77
78 private static final Escaper URL_FORM_PARAMETER_ESCAPER =
79 new PercentEscaper(URL_FORM_PARAMETER_OTHER_SAFE_CHARS, true);
80
81 /**
82 * Returns an {@link Escaper} instance that escapes strings so they can be safely included in <a
83 * href="https://goo.gl/m2MIf0">URL path segments</a>. The returned escaper escapes all non-ASCII
84 * characters, even though <a href="https://goo.gl/e7E0In">many of these are accepted in modern
85 * URLs</a>. (<a href="https://goo.gl/jfVxXW">If the escaper were to leave these characters
86 * unescaped, they would be escaped by the consumer at parse time, anyway.</a>) Additionally, the
87 * escaper escapes the slash character ("/"). While slashes are acceptable in URL paths, they are
88 * considered by the specification to be separators between "path segments." This implies that, if
89 * you wish for your path to contain slashes, you must escape each segment separately and then
90 * join them.
91 *
92 * <p>When escaping a String, the following rules apply:
93 *
94 * <ul>
95 * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
96 * the same.
97 * <li>The unreserved characters ".", "-", "~", and "_" remain the same.
98 * <li>The general delimiters "@" and ":" remain the same.
99 * <li>The subdelimiters "!", "$", "&", "'", "(", ")", "*", "+", ",", ";", and "=" remain
100 * the same.
101 * <li>The space character " " is converted into %20.
102 * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
103 * byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
104 * uppercase, hexadecimal representation of the byte value.
105 * </ul>
106 *
107 * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
108 * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
109 */
110 public static Escaper urlPathSegmentEscaper() {
111 return URL_PATH_SEGMENT_ESCAPER;
112 }
113
114 private static final Escaper URL_PATH_SEGMENT_ESCAPER =
115 new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+", false);
116
117 /**
118 * Returns an {@link Escaper} instance that escapes strings so they can be safely included in a <a
119 * href="https://goo.gl/xXEq4p">URL fragment</a>. The returned escaper escapes all non-ASCII
120 * characters, even though <a href="https://goo.gl/e7E0In">many of these are accepted in modern
121 * URLs</a>.
122 *
123 * <p>When escaping a String, the following rules apply:
124 *
125 * <ul>
126 * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain
127 * the same.
128 * <li>The unreserved characters ".", "-", "~", and "_" remain the same.
129 * <li>The general delimiters "@" and ":" remain the same.
130 * <li>The subdelimiters "!", "$", "&", "'", "(", ")", "*", "+", ",", ";", and "=" remain
131 * the same.
132 * <li>The space character " " is converted into %20.
133 * <li>Fragments allow unescaped "/" and "?", so they remain the same.
134 * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
135 * byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
136 * uppercase, hexadecimal representation of the byte value.
137 * </ul>
138 *
139 * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
140 * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
141 */
142 public static Escaper urlFragmentEscaper() {
143 return URL_FRAGMENT_ESCAPER;
144 }
145
146 private static final Escaper URL_FRAGMENT_ESCAPER =
147 new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+/?", false);
148 }