1 /*
2 * Copyright (c) 2012, 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 */
25
26 package jdk.internal.util.xml.impl;
27
28 /**
29 * Basic XMLStreamWriter for writing simple XML files such as those
30 * defined in java.util.Properties
31 *
32 * This is a subset of javax.xml.stream.XMLStreamWriter
33 *
34 * @author Joe Wang
35 */
36 public interface XMLStreamWriter {
37 //Defaults the XML version to 1.0, and the encoding to utf-8
38 public final static String DEFAULT_XML_VERSION = "1.0";
39 public final static String DEFAULT_ENCODING = "UTF-8";
40
41 /**
42 * Writes a start tag to the output. All writeStartElement methods
43 * open a new scope in the internal namespace context. Writing the
44 * corresponding EndElement causes the scope to be closed.
45 * @param localName local name of the tag, may not be null
46 * @throws XMLStreamException
47 */
48 public void writeStartElement(String localName)
49 throws XMLStreamException;
50
51 /**
52 * Writes an empty element tag to the output
53 * @param localName local name of the tag, may not be null
54 * @throws XMLStreamException
55 */
56 public void writeEmptyElement(String localName)
57 throws XMLStreamException;
58
59 /**
60 * Writes an end tag to the output relying on the internal
61 * state of the writer to determine the prefix and local name
62 * of the event.
63 * @throws XMLStreamException
64 */
65 public void writeEndElement()
66 throws XMLStreamException;
67
68 /**
69 * Closes any start tags and writes corresponding end tags.
70 * @throws XMLStreamException
71 */
72 public void writeEndDocument()
73 throws XMLStreamException;
74
75 /**
76 * Close this writer and free any resources associated with the
77 * writer. This must not close the underlying output stream.
78 * @throws XMLStreamException
79 */
80 public void close()
81 throws XMLStreamException;
82
83 /**
84 * Write any cached data to the underlying output mechanism.
85 * @throws XMLStreamException
86 */
87 public void flush()
88 throws XMLStreamException;
89
90 /**
91 * Writes an attribute to the output stream without
92 * a prefix.
93 * @param localName the local name of the attribute
94 * @param value the value of the attribute
95 * @throws IllegalStateException if the current state does not allow Attribute writing
96 * @throws XMLStreamException
97 */
98 public void writeAttribute(String localName, String value)
99 throws XMLStreamException;
100
101 /**
102 * Writes a CData section
103 * @param data the data contained in the CData Section, may not be null
104 * @throws XMLStreamException
105 */
106 public void writeCData(String data)
107 throws XMLStreamException;
108
109 /**
110 * Write a DTD section. This string represents the entire doctypedecl production
111 * from the XML 1.0 specification.
112 *
113 * @param dtd the DTD to be written
114 * @throws XMLStreamException
115 */
116 public void writeDTD(String dtd)
117 throws XMLStreamException;
118
119 /**
120 * Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
121 * @throws XMLStreamException
122 */
123 public void writeStartDocument()
124 throws XMLStreamException;
125
126 /**
127 * Write the XML Declaration. Defaults the the encoding to utf-8
128 * @param version version of the xml document
129 * @throws XMLStreamException
130 */
131 public void writeStartDocument(String version)
132 throws XMLStreamException;
133
134 /**
135 * Write the XML Declaration. Note that the encoding parameter does
136 * not set the actual encoding of the underlying output. That must
137 * be set when the instance of the XMLStreamWriter is created using the
138 * XMLOutputFactory
139 * @param encoding encoding of the xml declaration
140 * @param version version of the xml document
141 * @throws XMLStreamException If given encoding does not match encoding
142 * of the underlying stream
143 */
144 public void writeStartDocument(String encoding,
145 String version)
146 throws XMLStreamException;
147
148 /**
149 * Write text to the output
150 * @param text the value to write
151 * @throws XMLStreamException
152 */
153 public void writeCharacters(String text)
154 throws XMLStreamException;
155
156 /**
157 * Write text to the output
158 * @param text the value to write
159 * @param start the starting position in the array
160 * @param len the number of characters to write
161 * @throws XMLStreamException
162 */
163 public void writeCharacters(char[] text, int start, int len)
164 throws XMLStreamException;
165
166 }