1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/com/sun/xml/internal/txw2/TypedXmlWriter.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,266 @@
1.4 +/*
1.5 + * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package com.sun.xml.internal.txw2;
1.30 +
1.31 +import com.sun.xml.internal.txw2.annotation.XmlElement;
1.32 +import com.sun.xml.internal.txw2.output.XmlSerializer;
1.33 +
1.34 +import javax.xml.namespace.QName;
1.35 +
1.36 +/**
1.37 + * Defines common operations for all typed XML writers.
1.38 + * Root of all typed XML writer interfaces.
1.39 + *
1.40 + * <p>
1.41 + * This interface defines a series of methods to allow client applications
1.42 + * to write arbitrary well-formed documents.
1.43 + *
1.44 + * @author Kohsuke Kawaguchi
1.45 + */
1.46 +public interface TypedXmlWriter {
1.47 + /**
1.48 + * Commits this element (and all its descendants) to the output.
1.49 + *
1.50 + * <p>
1.51 + * Short for <tt>_commit(true)</tt>.
1.52 + */
1.53 + void commit();
1.54 +
1.55 + /**
1.56 + * Commits this element (and all its descendants) to the output.
1.57 + *
1.58 + * <p>
1.59 + * Once a writer is committed, nothing can be added to it further.
1.60 + * Committing allows TXW to output a part of the document even
1.61 + * if the rest has not yet been written.
1.62 + *
1.63 + * @param includingAllPredecessors
1.64 + * if false, this operation will _commit this writer and all its
1.65 + * descendants writers. If true, in addition to those writers,
1.66 + * this operation will close all the writers before this writer
1.67 + * in the document order.
1.68 + */
1.69 + void commit(boolean includingAllPredecessors);
1.70 +
1.71 + /**
1.72 + * Blocks the writing of the start tag so that
1.73 + * new attributes can be added even after child
1.74 + * elements are appended.
1.75 + *
1.76 + * <p>
1.77 + * This blocks the output at the token before the start tag until
1.78 + * the {@link #commit()} method is called to _commit this element.
1.79 + *
1.80 + * <p>
1.81 + * For more information, see the TXW documentation.
1.82 + */
1.83 + void block();
1.84 +
1.85 + /**
1.86 + * Gets the {@link Document} object that this writer is writing to.
1.87 + *
1.88 + * @return
1.89 + * always non-null.
1.90 + */
1.91 + Document getDocument();
1.92 +
1.93 + /**
1.94 + * Adds an attribute of the given name and the value.
1.95 + *
1.96 + * <p>
1.97 + * Short for <pre>_attribute("",localName,value);</pre>
1.98 + *
1.99 + * @see #_attribute(String, String, Object)
1.100 + */
1.101 + void _attribute( String localName, Object value );
1.102 +
1.103 + /**
1.104 + * Adds an attribute of the given name and the value.
1.105 + *
1.106 + * <p>
1.107 + * Short for <pre>_attribute(new QName(nsUri,localName),value);</pre>
1.108 + *
1.109 + * @see #_attribute(QName, Object)
1.110 + */
1.111 + void _attribute( String nsUri, String localName, Object value );
1.112 +
1.113 + /**
1.114 + * Adds an attribute of the given name and the value.
1.115 + *
1.116 + * @param attributeName
1.117 + * must not be null.
1.118 + * @param value
1.119 + * value of the attribute.
1.120 + * must not be null.
1.121 + * See the documentation for the conversion rules.
1.122 + */
1.123 + void _attribute( QName attributeName, Object value );
1.124 +
1.125 + /**
1.126 + * Declares a new namespace URI on this element.
1.127 + *
1.128 + * <p>
1.129 + * The runtime system will assign an unique prefix for the URI.
1.130 + *
1.131 + * @param uri
1.132 + * can be empty, but must not be null.
1.133 + */
1.134 + void _namespace( String uri );
1.135 +
1.136 + /**
1.137 + * Declares a new namespace URI on this element to
1.138 + * a specific prefix.
1.139 + *
1.140 + * @param uri
1.141 + * can be empty, but must not be null.
1.142 + * @param prefix
1.143 + * If non-empty, this prefix is bound to the URI
1.144 + * on this element. If empty, then the runtime will still try to
1.145 + * use the URI as the default namespace, but it may fail to do so
1.146 + * because of the constraints in the XML.
1.147 + *
1.148 + * @throws IllegalArgumentException
1.149 + * if the same prefix is already declared on this element.
1.150 + */
1.151 + void _namespace( String uri, String prefix );
1.152 +
1.153 + /**
1.154 + * Declares a new namespace URI on this element.
1.155 + *
1.156 + * <p>
1.157 + * The runtime system will assign an unique prefix for the URI.
1.158 + *
1.159 + * @param uri
1.160 + * can be empty, but must not be null.
1.161 + * @param requirePrefix
1.162 + * if false, this method behaves just like {@link #_namespace(String)}.
1.163 + * if true, this guarantees that the URI is bound to a non empty prefix.
1.164 + */
1.165 + void _namespace( String uri, boolean requirePrefix );
1.166 +
1.167 + /**
1.168 + * Appends text data.
1.169 + *
1.170 + * @param value
1.171 + * must not be null.
1.172 + * See the documentation for the conversion rules.
1.173 + */
1.174 + void _pcdata( Object value );
1.175 +
1.176 + /**
1.177 + * Appends CDATA section.
1.178 + *
1.179 + * @param value
1.180 + * must not be null.
1.181 + * See the documentation for the conversion rules.
1.182 + */
1.183 + void _cdata( Object value );
1.184 +
1.185 + /**
1.186 + * Appends a comment.
1.187 + *
1.188 + * @param value
1.189 + * must not be null.
1.190 + * See the documentation for the conversion rules.
1.191 + *
1.192 + * @throws UnsupportedOperationException
1.193 + * if the underlying {@link XmlSerializer} does not support
1.194 + * writing comments, this exception can be thrown.
1.195 + */
1.196 + void _comment( Object value ) throws UnsupportedOperationException;
1.197 +
1.198 + /**
1.199 + * Appends a new child element.
1.200 + *
1.201 + * <p>
1.202 + * Short for <pre>_element(<i>URI of this element</i>,localName,contentModel);</pre>
1.203 + *
1.204 + * <p>
1.205 + * The namespace URI will be inherited from the parent element.
1.206 + *
1.207 + * @see #_element(String, String, Class)
1.208 + */
1.209 + <T extends TypedXmlWriter> T _element( String localName, Class<T> contentModel );
1.210 +
1.211 + /**
1.212 + * Appends a new child element.
1.213 + *
1.214 + * <p>
1.215 + * The newly created child element is appended at the end of the children.
1.216 + *
1.217 + * @param nsUri
1.218 + * The namespace URI of the newly created element.
1.219 + * @param localName
1.220 + * The local name of the newly created element.
1.221 + * @param contentModel
1.222 + * The typed XML writer interface used to write the children of
1.223 + * the new child element.
1.224 + *
1.225 + * @return
1.226 + * always return non-null {@link TypedXmlWriter} that can be used
1.227 + * to write the contents of the newly created child element.
1.228 + */
1.229 + <T extends TypedXmlWriter> T _element( String nsUri, String localName, Class<T> contentModel );
1.230 +
1.231 + /**
1.232 + * Appends a new child element.
1.233 + *
1.234 + * <p>
1.235 + * Short for <pre>_element(tagName.getNamespaceURI(),tagName.getLocalPart(),contentModel);</pre>
1.236 + *
1.237 + * @see #_element(String, String, Class)
1.238 + */
1.239 + <T extends TypedXmlWriter> T _element( QName tagName, Class<T> contentModel );
1.240 +
1.241 + /**
1.242 + * Appends a new child element.
1.243 + *
1.244 + * <p>
1.245 + * This version of the _element method requires the <i>T</i> class to be
1.246 + * annotated with {@link XmlElement} annotation. The element name will be
1.247 + * taken from there.
1.248 + *
1.249 + * @see #_element(String, String, Class)
1.250 + */
1.251 + <T extends TypedXmlWriter> T _element( Class<T> contentModel );
1.252 +
1.253 + /**
1.254 + * Returns a different interface for this typed XML Writer.
1.255 + *
1.256 + * <p>
1.257 + * Semantically, this operation is a 'cast' --- it returns the same underlying
1.258 + * writer in a different interface. The returned new writer and the current writer
1.259 + * will write to the same element.
1.260 + *
1.261 + * <p>
1.262 + * But this is different from Java's ordinary cast because the returned object
1.263 + * is not always the same as the current object.
1.264 + *
1.265 + * @return
1.266 + * always return non-null.
1.267 + */
1.268 + <T extends TypedXmlWriter> T _cast( Class<T> targetInterface );
1.269 +}
