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