View Javadoc

    1   /* Copyright (c) 2008 Google Inc.
    2    *
    3    * Licensed under the Apache License, Version 2.0 (the "License");
    4    * you may not use this file except in compliance with the License.
    5    * 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
    10   * distributed under the License is distributed on an "AS IS" BASIS,
    11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12   * See the License for the specific language governing permissions and
    13   * limitations under the License.
    14   */
    15
    16  package org.yaml.snakeyaml.external.com.google.gdata.util.common.base;
    17
    18  /**
    19   * An object that converts literal text into a format safe for inclusion in a
    20   * particular context (such as an XML document). Typically (but not always), the
    21   * inverse process of "unescaping" the text is performed automatically by the
    22   * relevant parser.
    23   *
    24   * <p>
    25   * For example, an XML escaper would convert the literal string
    26   * {@code "Foo<Bar>"} into {@code "Foo&lt;Bar&gt;"} to prevent {@code "<Bar>"}
    27   * from being confused with an XML tag. When the resulting XML document is
    28   * parsed, the parser API will return this text as the original literal string
    29   * {@code "Foo<Bar>"}.
    30   *
    31   * <p>
    32   * An {@code Escaper} instance is required to be stateless, and safe when used
    33   * concurrently by multiple threads.
    34   *
    35   * <p>
    36   * Several popular escapers are defined as constants in the class
    37   * {@link CharEscapers}. To create your own escapers, use
    38   * {@link CharEscaperBuilder}, or extend {@link CharEscaper} or
    39   * {@code UnicodeEscaper}.
    40   *
    41   *
    42   */
    43  public interface Escaper {
    44      /**
    45       * Returns the escaped form of a given literal string.
    46       *
    47       * <p>
    48       * Note that this method may treat input characters differently depending on
    49       * the specific escaper implementation.
    50       * <ul>
    51       * <li>{@link UnicodeEscaper} handles <a
    52       * href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> correctly,
    53       * including surrogate character pairs. If the input is badly formed the
    54       * escaper should throw {@link IllegalArgumentException}.
    55       * <li>{@link CharEscaper} handles Java characters independently and does
    56       * not verify the input for well formed characters. A CharEscaper should not
    57       * be used in situations where input is not guaranteed to be restricted to
    58       * the Basic Multilingual Plane (BMP).
    59       * </ul>
    60       *
    61       * @param string
    62       *            the literal string to be escaped
    63       * @return the escaped form of {@code string}
    64       * @throws NullPointerException
    65       *             if {@code string} is null
    66       * @throws IllegalArgumentException
    67       *             if {@code string} contains badly formed UTF-16 or cannot be
    68       *             escaped for any other reason
    69       */
    70      public String escape(String string);
    71
    72      /**
    73       * Returns an {@code Appendable} instance which automatically escapes all
    74       * text appended to it before passing the resulting text to an underlying
    75       * {@code Appendable}.
    76       *
    77       * <p>
    78       * Note that this method may treat input characters differently depending on
    79       * the specific escaper implementation.
    80       * <ul>
    81       * <li>{@link UnicodeEscaper} handles <a
    82       * href="http://en.wikipedia.org/wiki/UTF-16">UTF-16</a> correctly,
    83       * including surrogate character pairs. If the input is badly formed the
    84       * escaper should throw {@link IllegalArgumentException}.
    85       * <li>{@link CharEscaper} handles Java characters independently and does
    86       * not verify the input for well formed characters. A CharEscaper should not
    87       * be used in situations where input is not guaranteed to be restricted to
    88       * the Basic Multilingual Plane (BMP).
    89       * </ul>
    90       *
    91       * @param out
    92       *            the underlying {@code Appendable} to append escaped output to
    93       * @return an {@code Appendable} which passes text to {@code out} after
    94       *         escaping it.
    95       */
    96      public Appendable escape(Appendable out);
    97  }