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 * 28 * @author David Beaumont 29 * @author Chris Povirk 30 * @since 15.0 31 */ 32 @GwtCompatible 33 public final class UrlEscapers { 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 */ urlFormParameterEscaper()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 */ urlPathSegmentEscaper()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 */ urlFragmentEscaper()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 } 149