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; 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 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 }