Sun, 18 Jun 2017 23:18:45 +0100
8172297: In java 8, the marshalling with JAX-WS does not escape carriage return
Reviewed-by: lancea
1 /*
2 * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
26 package com.sun.xml.internal.txw2.output;
28 import com.sun.xml.internal.txw2.TypedXmlWriter;
31 /**
32 * Low-level typeless XML writer driven from {@link TypedXmlWriter}.
33 *
34 * <p>
35 * Applications can use one of the predefined implementations to
36 * send TXW output to the desired location/format, or they can
37 * choose to implement this interface for custom output.
38 *
39 * <p>
40 * One {@link XmlSerializer} instance is responsible for writing
41 * one XML document.
42 *
43 * <h2>Call Sequence</h2>
44 * TXW calls methods on this interface in the following order:
45 *
46 * <pre>
47 * WHOLE_SEQUENCE := startDocument ELEMENT endDocument
48 * ELEMENT := beginStartTag writeXmlns* writeAttribute* endStartTag CONTENT endTag
49 * CONTENT := (text|ELEMENT)*
50 * </pre>
51 *
52 * <p>
53 * TXW maintains all the in-scope namespace bindings and prefix allocation.
54 * The {@link XmlSerializer} implementation should just use the prefix
55 * specified.
56 * </p>
57 *
58 * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
59 */
60 public interface XmlSerializer {
61 /**
62 * The first method to be called.
63 */
64 void startDocument();
66 /**
67 * Begins writing a start tag.
68 *
69 * @param uri
70 * the namespace URI of the element. Can be empty but never be null.
71 * @param prefix
72 * the prefix that should be used for this element. Can be empty,
73 * but never null.
74 */
75 void beginStartTag(String uri,String localName,String prefix);
77 /**
78 * Writes an attribute.
79 *
80 * @param value
81 * The value of the attribute. It's the callee's responsibility to
82 * escape special characters (such as <, >, and &) in this buffer.
83 *
84 * @param uri
85 * the namespace URI of the attribute. Can be empty but never be null.
86 * @param prefix
87 * the prefix that should be used for this attribute. Can be empty,
88 * but never null.
89 */
90 void writeAttribute(String uri,String localName,String prefix,StringBuilder value);
92 /**
93 * Writes a namespace declaration.
94 *
95 * @param uri
96 * the namespace URI to be declared. Can be empty but never be null.
97 * @param prefix
98 * the prefix that is allocated. Can be empty but never be null.
99 */
100 void writeXmlns(String prefix,String uri);
102 /**
103 * Completes the start tag.
104 *
105 * @param uri
106 * the namespace URI of the element. Can be empty but never be null.
107 * @param prefix
108 * the prefix that should be used for this element. Can be empty,
109 * but never null.
110 */
111 void endStartTag(String uri,String localName,String prefix);
113 /**
114 * Writes an end tag.
115 */
116 void endTag();
118 /**
119 * Writes PCDATA.
120 *
121 * @param text
122 * The character data to be written. It's the callee's responsibility to
123 * escape special characters (such as <, >, and &) in this buffer.
124 */
125 void text(StringBuilder text);
127 /**
128 * Writes CDATA.
129 */
130 void cdata(StringBuilder text);
132 /**
133 * Writes a comment.
134 *
135 * @throws UnsupportedOperationException
136 * if the writer doesn't support writing a comment, it can throw this exception.
137 */
138 void comment(StringBuilder comment);
140 /**
141 * The last method to be called.
142 */
143 void endDocument();
145 /**
146 * Flush the buffer.
147 *
148 * This method is called when applications invoke {@link TypedXmlWriter#commit(boolean)}
149 * method. If the implementation performs any buffering, it should flush the buffer.
150 */
151 void flush();
152 }