001/*
002 * Copyright (C) 2009 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.net;
016
017import com.google.common.annotations.GwtCompatible;
018import com.google.common.escape.Escaper;
019
020/**
021 * {@code Escaper} instances suitable for strings to be included in particular sections of URLs.
022 *
023 * <p>If the resulting URLs are inserted into an HTML or XML document, they will require additional
024 * escaping with {@link com.google.common.html.HtmlEscapers} or
025 * {@link com.google.common.xml.XmlEscapers}.
026 *
027 *
028 * @author David Beaumont
029 * @author Chris Povirk
030 * @since 15.0
031 */
032@GwtCompatible
033public final class UrlEscapers {
034  private UrlEscapers() {}
035
036  // For each xxxEscaper() method, please add links to external reference pages
037  // that are considered authoritative for the behavior of that escaper.
038
039  static final String URL_FORM_PARAMETER_OTHER_SAFE_CHARS = "-_.*";
040
041  static final String URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS =
042      "-._~" +        // Unreserved characters.
043      "!$'()*,;&=" +  // The subdelim characters (excluding '+').
044      "@:";           // The gendelim characters permitted in paths.
045
046  /**
047   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in
048   * <a href="https://goo.gl/MplK6I">URL form parameter names and values</a>. Escaping is performed
049   * with the UTF-8 character encoding. The caller is responsible for
050   * <a href="https://goo.gl/9EfkM1">replacing any unpaired carriage return or line feed characters
051   * with a CR+LF pair</a> on any non-file inputs before escaping them with this escaper.
052   *
053   * <p>When escaping a String, the following rules apply:
054   * <ul>
055   * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the
056   *     same.
057   * <li>The special characters ".", "-", "*", and "_" remain the same.
058   * <li>The space character " " is converted into a plus sign "+".
059   * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
060   *     byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
061   *     uppercase, hexadecimal representation of the byte value.
062   * </ul>
063   *
064   * <p>This escaper is suitable for escaping parameter names and values even when
065   * <a href="https://goo.gl/utn6M">using the non-standard semicolon</a>, rather than the ampersand,
066   * as a parameter delimiter. Nevertheless, we recommend using the ampersand unless you must
067   * interoperate with systems that require semicolons.
068   *
069   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
070   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
071   *
072   */
073  public static Escaper urlFormParameterEscaper() {
074    return URL_FORM_PARAMETER_ESCAPER;
075  }
076
077  private static final Escaper URL_FORM_PARAMETER_ESCAPER =
078      new PercentEscaper(URL_FORM_PARAMETER_OTHER_SAFE_CHARS, true);
079
080  /**
081   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in
082   * <a href="https://goo.gl/m2MIf0">URL path segments</a>. The returned escaper escapes all
083   * non-ASCII characters, even though <a href="https://goo.gl/e7E0In">many of these are accepted in
084   * modern URLs</a>. (<a href="https://goo.gl/jfVxXW">If the escaper were to leave these characters
085   * unescaped, they would be escaped by the consumer at parse time, anyway.</a>) Additionally, the
086   * escaper escapes the slash character ("/"). While slashes are acceptable in URL paths, they are
087   * considered by the specification to be separators between "path segments." This implies that, if
088   * you wish for your path to contain slashes, you must escape each segment separately and then
089   * join them.
090   *
091   * <p>When escaping a String, the following rules apply:
092   * <ul>
093   * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the
094   *     same.
095   * <li>The unreserved characters ".", "-", "~", and "_" remain the same.
096   * <li>The general delimiters "@" and ":" remain the same.
097   * <li>The subdelimiters "!", "$", "&amp;", "'", "(", ")", "*", "+", ",", ";", and "=" remain the
098   *     same.
099   * <li>The space character " " is converted into %20.
100   * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
101   *     byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
102   *     uppercase, hexadecimal representation of the byte value.
103   * </ul>
104   *
105   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
106   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
107   */
108  public static Escaper urlPathSegmentEscaper() {
109    return URL_PATH_SEGMENT_ESCAPER;
110  }
111
112  private static final Escaper URL_PATH_SEGMENT_ESCAPER =
113      new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+", false);
114
115  /**
116   * Returns an {@link Escaper} instance that escapes strings so they can be safely included in a
117   * <a href="https://goo.gl/xXEq4p">URL fragment</a>. The returned escaper escapes all non-ASCII
118   * characters, even though <a href="https://goo.gl/e7E0In">many of these are accepted in modern
119   * URLs</a>.
120   *
121   * <p>When escaping a String, the following rules apply:
122   * <ul>
123   * <li>The alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the
124   *     same.
125   * <li>The unreserved characters ".", "-", "~", and "_" remain the same.
126   * <li>The general delimiters "@" and ":" remain the same.
127   * <li>The subdelimiters "!", "$", "&amp;", "'", "(", ")", "*", "+", ",", ";", and "=" remain the
128   *     same.
129   * <li>The space character " " is converted into %20.
130   * <li>Fragments allow unescaped "/" and "?", so they remain the same.
131   * <li>All other characters are converted into one or more bytes using UTF-8 encoding and each
132   *     byte is then represented by the 3-character string "%XY", where "XY" is the two-digit,
133   *     uppercase, hexadecimal representation of the byte value.
134   * </ul>
135   *
136   * <p><b>Note:</b> Unlike other escapers, URL escapers produce <a
137   * href="https://url.spec.whatwg.org/#percent-encode">uppercase</a> hexadecimal sequences.
138   */
139  public static Escaper urlFragmentEscaper() {
140    return URL_FRAGMENT_ESCAPER;
141  }
142
143  private static final Escaper URL_FRAGMENT_ESCAPER =
144      new PercentEscaper(URL_PATH_OTHER_SAFE_CHARS_LACKING_PLUS + "+/?", false);
145}