1/* 2 * Copyright (c) 2005, 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 com.sun.xml.internal.txw2.output; 27 28import com.sun.xml.internal.txw2.TypedXmlWriter; 29 30 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 */ 60public interface XmlSerializer { 61 /** 62 * The first method to be called. 63 */ 64 void startDocument(); 65 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); 76 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); 91 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); 101 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); 112 113 /** 114 * Writes an end tag. 115 */ 116 void endTag(); 117 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); 126 127 /** 128 * Writes CDATA. 129 */ 130 void cdata(StringBuilder text); 131 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); 139 140 /** 141 * The last method to be called. 142 */ 143 void endDocument(); 144 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} 153