You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
529 lines
19 KiB
529 lines
19 KiB
/*
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
|
|
/*
|
|
* Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
|
|
*/
|
|
|
|
package javax.xml.stream;
|
|
|
|
import javax.xml.namespace.NamespaceContext;
|
|
|
|
/**
|
|
* The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does
|
|
* not perform well formedness checking on its input. However
|
|
* the writeCharacters method is required to escape & , < and >
|
|
* For attribute values the writeAttribute method will escape the
|
|
* above characters plus " to ensure that all character content
|
|
* and attribute values are well formed.
|
|
*
|
|
* Each NAMESPACE
|
|
* and ATTRIBUTE must be individually written.
|
|
*
|
|
* <table border="1" cellpadding="2" cellspacing="0">
|
|
* <thead>
|
|
* <tr>
|
|
* <th colspan="5">XML Namespaces, <code>javax.xml.stream.isRepairingNamespaces</code> and write method behaviour</th>
|
|
* </tr>
|
|
* <tr>
|
|
* <th>Method</th> <!-- method -->
|
|
* <th colspan="2"><code>isRepairingNamespaces</code> == true</th>
|
|
* <th colspan="2"><code>isRepairingNamespaces</code> == false</th>
|
|
* </tr>
|
|
* <tr>
|
|
* <th></th> <!-- method -->
|
|
* <th>namespaceURI bound</th>
|
|
* <th>namespaceURI unbound</th>
|
|
* <th>namespaceURI bound</th>
|
|
* <th>namespaceURI unbound</th>
|
|
* </tr>
|
|
* </thead>
|
|
*
|
|
* <tbody>
|
|
* <tr>
|
|
* <th><code>writeAttribute(namespaceURI, localName, value)</code></th>
|
|
* <!-- isRepairingNamespaces == true -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* prefix:localName="value" <sup>[1]</sup>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* xmlns:{generated}="namespaceURI" {generated}:localName="value"
|
|
* </td>
|
|
* <!-- isRepairingNamespaces == false -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* prefix:localName="value" <sup>[1]</sup>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* <code>XMLStreamException</code>
|
|
* </td>
|
|
* </tr>
|
|
*
|
|
* <tr>
|
|
* <th><code>writeAttribute(prefix, namespaceURI, localName, value)</code></th>
|
|
* <!-- isRepairingNamespaces == true -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* bound to same prefix:<br />
|
|
* prefix:localName="value" <sup>[1]</sup><br />
|
|
* <br />
|
|
* bound to different prefix:<br />
|
|
* xmlns:{generated}="namespaceURI" {generated}:localName="value"
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[3]</sup>
|
|
* </td>
|
|
* <!-- isRepairingNamespaces == false -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* bound to same prefix:<br />
|
|
* prefix:localName="value" <sup>[1][2]</sup><br />
|
|
* <br />
|
|
* bound to different prefix:<br />
|
|
* <code>XMLStreamException</code><sup>[2]</sup>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* xmlns:prefix="namespaceURI" prefix:localName="value" <sup>[2][5]</sup>
|
|
* </td>
|
|
* </tr>
|
|
*
|
|
* <tr>
|
|
* <th><code>writeStartElement(namespaceURI, localName)</code><br />
|
|
* <br />
|
|
* <code>writeEmptyElement(namespaceURI, localName)</code></th>
|
|
* <!-- isRepairingNamespaces == true -->
|
|
* <td >
|
|
* <!-- namespaceURI bound -->
|
|
* <prefix:localName> <sup>[1]</sup>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* <{generated}:localName xmlns:{generated}="namespaceURI">
|
|
* </td>
|
|
* <!-- isRepairingNamespaces == false -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* <prefix:localName> <sup>[1]</sup>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* <code>XMLStreamException</code>
|
|
* </td>
|
|
* </tr>
|
|
*
|
|
* <tr>
|
|
* <th><code>writeStartElement(prefix, localName, namespaceURI)</code><br />
|
|
* <br />
|
|
* <code>writeEmptyElement(prefix, localName, namespaceURI)</code></th>
|
|
* <!-- isRepairingNamespaces == true -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* bound to same prefix:<br />
|
|
* <prefix:localName> <sup>[1]</sup><br />
|
|
* <br />
|
|
* bound to different prefix:<br />
|
|
* <{generated}:localName xmlns:{generated}="namespaceURI">
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* <prefix:localName xmlns:prefix="namespaceURI"> <sup>[4]</sup>
|
|
* </td>
|
|
* <!-- isRepairingNamespaces == false -->
|
|
* <td>
|
|
* <!-- namespaceURI bound -->
|
|
* bound to same prefix:<br />
|
|
* <prefix:localName> <sup>[1]</sup><br />
|
|
* <br />
|
|
* bound to different prefix:<br />
|
|
* <code>XMLStreamException</code>
|
|
* </td>
|
|
* <td>
|
|
* <!-- namespaceURI unbound -->
|
|
* <prefix:localName>
|
|
* </td>
|
|
* </tr>
|
|
* </tbody>
|
|
* <tfoot>
|
|
* <tr>
|
|
* <td colspan="5">
|
|
* Notes:
|
|
* <ul>
|
|
* <li>[1] if namespaceURI == default Namespace URI, then no prefix is written</li>
|
|
* <li>[2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written</li>
|
|
* <li>[3] if prefix == "" || null, then a prefix is randomly generated</li>
|
|
* <li>[4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound</li>
|
|
* <li>[5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown</li>
|
|
* </ul>
|
|
* </td>
|
|
* </tr>
|
|
* </tfoot>
|
|
* </table>
|
|
*
|
|
* @version 1.0
|
|
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
|
|
* @see XMLOutputFactory
|
|
* @see XMLStreamReader
|
|
* @since 1.6
|
|
*/
|
|
public interface XMLStreamWriter {
|
|
|
|
/**
|
|
* Writes a start tag to the output. All writeStartElement methods
|
|
* open a new scope in the internal namespace context. Writing the
|
|
* corresponding EndElement causes the scope to be closed.
|
|
* @param localName local name of the tag, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeStartElement(String localName)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a start tag to the output
|
|
* @param namespaceURI the namespaceURI of the prefix to use, may not be null
|
|
* @param localName local name of the tag, may not be null
|
|
* @throws XMLStreamException if the namespace URI has not been bound to a prefix and
|
|
* javax.xml.stream.isRepairingNamespaces has not been set to true
|
|
*/
|
|
public void writeStartElement(String namespaceURI, String localName)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a start tag to the output
|
|
* @param localName local name of the tag, may not be null
|
|
* @param prefix the prefix of the tag, may not be null
|
|
* @param namespaceURI the uri to bind the prefix to, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeStartElement(String prefix,
|
|
String localName,
|
|
String namespaceURI)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an empty element tag to the output
|
|
* @param namespaceURI the uri to bind the tag to, may not be null
|
|
* @param localName local name of the tag, may not be null
|
|
* @throws XMLStreamException if the namespace URI has not been bound to a prefix and
|
|
* javax.xml.stream.isRepairingNamespaces has not been set to true
|
|
*/
|
|
public void writeEmptyElement(String namespaceURI, String localName)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an empty element tag to the output
|
|
* @param prefix the prefix of the tag, may not be null
|
|
* @param localName local name of the tag, may not be null
|
|
* @param namespaceURI the uri to bind the tag to, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeEmptyElement(String prefix, String localName, String namespaceURI)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an empty element tag to the output
|
|
* @param localName local name of the tag, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeEmptyElement(String localName)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes string data to the output without checking for well formedness.
|
|
* The data is opaque to the XMLStreamWriter, i.e. the characters are written
|
|
* blindly to the underlying output. If the method cannot be supported
|
|
* in the currrent writing context the implementation may throw a
|
|
* UnsupportedOperationException. For example note that any
|
|
* namespace declarations, end tags, etc. will be ignored and could
|
|
* interfere with proper maintanence of the writers internal state.
|
|
*
|
|
* @param data the data to write
|
|
*/
|
|
// public void writeRaw(String data) throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an end tag to the output relying on the internal
|
|
* state of the writer to determine the prefix and local name
|
|
* of the event.
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeEndElement()
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Closes any start tags and writes corresponding end tags.
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeEndDocument()
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Close this writer and free any resources associated with the
|
|
* writer. This must not close the underlying output stream.
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void close()
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write any cached data to the underlying output mechanism.
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void flush()
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an attribute to the output stream without
|
|
* a prefix.
|
|
* @param localName the local name of the attribute
|
|
* @param value the value of the attribute
|
|
* @throws IllegalStateException if the current state does not allow Attribute writing
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeAttribute(String localName, String value)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an attribute to the output stream
|
|
* @param prefix the prefix for this attribute
|
|
* @param namespaceURI the uri of the prefix for this attribute
|
|
* @param localName the local name of the attribute
|
|
* @param value the value of the attribute
|
|
* @throws IllegalStateException if the current state does not allow Attribute writing
|
|
* @throws XMLStreamException if the namespace URI has not been bound to a prefix and
|
|
* javax.xml.stream.isRepairingNamespaces has not been set to true
|
|
*/
|
|
|
|
public void writeAttribute(String prefix,
|
|
String namespaceURI,
|
|
String localName,
|
|
String value)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an attribute to the output stream
|
|
* @param namespaceURI the uri of the prefix for this attribute
|
|
* @param localName the local name of the attribute
|
|
* @param value the value of the attribute
|
|
* @throws IllegalStateException if the current state does not allow Attribute writing
|
|
* @throws XMLStreamException if the namespace URI has not been bound to a prefix and
|
|
* javax.xml.stream.isRepairingNamespaces has not been set to true
|
|
*/
|
|
public void writeAttribute(String namespaceURI,
|
|
String localName,
|
|
String value)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a namespace to the output stream
|
|
* If the prefix argument to this method is the empty string,
|
|
* "xmlns", or null this method will delegate to writeDefaultNamespace
|
|
*
|
|
* @param prefix the prefix to bind this namespace to
|
|
* @param namespaceURI the uri to bind the prefix to
|
|
* @throws IllegalStateException if the current state does not allow Namespace writing
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeNamespace(String prefix, String namespaceURI)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes the default namespace to the stream
|
|
* @param namespaceURI the uri to bind the default namespace to
|
|
* @throws IllegalStateException if the current state does not allow Namespace writing
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeDefaultNamespace(String namespaceURI)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an xml comment with the data enclosed
|
|
* @param data the data contained in the comment, may be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeComment(String data)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a processing instruction
|
|
* @param target the target of the processing instruction, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeProcessingInstruction(String target)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a processing instruction
|
|
* @param target the target of the processing instruction, may not be null
|
|
* @param data the data contained in the processing instruction, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeProcessingInstruction(String target,
|
|
String data)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes a CData section
|
|
* @param data the data contained in the CData Section, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeCData(String data)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write a DTD section. This string represents the entire doctypedecl production
|
|
* from the XML 1.0 specification.
|
|
*
|
|
* @param dtd the DTD to be written
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeDTD(String dtd)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Writes an entity reference
|
|
* @param name the name of the entity
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeEntityRef(String name)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeStartDocument()
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write the XML Declaration. Defaults the XML version to 1.0
|
|
* @param version version of the xml document
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeStartDocument(String version)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write the XML Declaration. Note that the encoding parameter does
|
|
* not set the actual encoding of the underlying output. That must
|
|
* be set when the instance of the XMLStreamWriter is created using the
|
|
* XMLOutputFactory
|
|
* @param encoding encoding of the xml declaration
|
|
* @param version version of the xml document
|
|
* @throws XMLStreamException If given encoding does not match encoding
|
|
* of the underlying stream
|
|
*/
|
|
public void writeStartDocument(String encoding,
|
|
String version)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write text to the output
|
|
* @param text the value to write
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeCharacters(String text)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Write text to the output
|
|
* @param text the value to write
|
|
* @param start the starting position in the array
|
|
* @param len the number of characters to write
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void writeCharacters(char[] text, int start, int len)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Gets the prefix the uri is bound to
|
|
* @return the prefix or null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public String getPrefix(String uri)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Sets the prefix the uri is bound to. This prefix is bound
|
|
* in the scope of the current START_ELEMENT / END_ELEMENT pair.
|
|
* If this method is called before a START_ELEMENT has been written
|
|
* the prefix is bound in the root scope.
|
|
* @param prefix the prefix to bind to the uri, may not be null
|
|
* @param uri the uri to bind to the prefix, may be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void setPrefix(String prefix, String uri)
|
|
throws XMLStreamException;
|
|
|
|
|
|
/**
|
|
* Binds a URI to the default namespace
|
|
* This URI is bound
|
|
* in the scope of the current START_ELEMENT / END_ELEMENT pair.
|
|
* If this method is called before a START_ELEMENT has been written
|
|
* the uri is bound in the root scope.
|
|
* @param uri the uri to bind to the default namespace, may be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void setDefaultNamespace(String uri)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Sets the current namespace context for prefix and uri bindings.
|
|
* This context becomes the root namespace context for writing and
|
|
* will replace the current root namespace context. Subsequent calls
|
|
* to setPrefix and setDefaultNamespace will bind namespaces using
|
|
* the context passed to the method as the root context for resolving
|
|
* namespaces. This method may only be called once at the start of
|
|
* the document. It does not cause the namespaces to be declared.
|
|
* If a namespace URI to prefix mapping is found in the namespace
|
|
* context it is treated as declared and the prefix may be used
|
|
* by the StreamWriter.
|
|
* @param context the namespace context to use for this writer, may not be null
|
|
* @throws XMLStreamException
|
|
*/
|
|
public void setNamespaceContext(NamespaceContext context)
|
|
throws XMLStreamException;
|
|
|
|
/**
|
|
* Returns the current namespace context.
|
|
* @return the current NamespaceContext
|
|
*/
|
|
public NamespaceContext getNamespaceContext();
|
|
|
|
/**
|
|
* Get the value of a feature/property from the underlying implementation
|
|
* @param name The name of the property, may not be null
|
|
* @return The value of the property
|
|
* @throws IllegalArgumentException if the property is not supported
|
|
* @throws NullPointerException if the name is null
|
|
*/
|
|
public Object getProperty(java.lang.String name) throws IllegalArgumentException;
|
|
|
|
}
|