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