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