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  }