/*
* Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.xml.stream;
import javax.xml.stream.events.*;
import javax.xml.stream.util.XMLEventConsumer;
import javax.xml.namespace.NamespaceContext;
This is the top level interface for writing XML documents.
Instances of this interface are not required to validate the
form of the XML.
Author: Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. See Also: Version: 1.0 Since: 1.6
/**
*
* This is the top level interface for writing XML documents.
*
* Instances of this interface are not required to validate the
* form of the XML.
*
* @version 1.0
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
* @see XMLEventReader
* @see javax.xml.stream.events.XMLEvent
* @see javax.xml.stream.events.Characters
* @see javax.xml.stream.events.ProcessingInstruction
* @see javax.xml.stream.events.StartElement
* @see javax.xml.stream.events.EndElement
* @since 1.6
*/
public interface XMLEventWriter extends XMLEventConsumer {
Writes any cached events to the underlying output mechanism
Throws: - XMLStreamException –
/**
* Writes any cached events to the underlying output mechanism
* @throws XMLStreamException
*/
public void flush() throws XMLStreamException;
Frees any resources associated with this stream
Throws: - XMLStreamException –
/**
* Frees any resources associated with this stream
* @throws XMLStreamException
*/
public void close() throws XMLStreamException;
Add an event to the output stream
Adding a START_ELEMENT will open a new namespace scope that
will be closed when the corresponding END_ELEMENT is written.
Required and optional fields for events added to the writer
Event Type
Required Fields
Optional Fields
Required Behavior
START_ELEMENT
QName name
namespaces , attributes
A START_ELEMENT will be written by writing the name,
namespaces, and attributes of the event in XML 1.0 valid
syntax for START_ELEMENTs.
The name is written by looking up the prefix for
the namespace uri. The writer can be configured to
respect prefixes of QNames. If the writer is respecting
prefixes it must use the prefix set on the QName. The
default behavior is to lookup the value for the prefix
on the EventWriter's internal namespace context.
Each attribute (if any)
is written using the behavior specified in the attribute
section of this table. Each namespace (if any) is written
using the behavior specified in the namespace section of this
table.
END_ELEMENT
Qname name
None
A well formed END_ELEMENT tag is written.
The name is written by looking up the prefix for
the namespace uri. The writer can be configured to
respect prefixes of QNames. If the writer is respecting
prefixes it must use the prefix set on the QName. The
default behavior is to lookup the value for the prefix
on the EventWriter's internal namespace context.
If the END_ELEMENT name does not match the START_ELEMENT
name an XMLStreamException is thrown.
ATTRIBUTE
QName name , String value
QName type
An attribute is written using the same algorithm
to find the lexical form as used in START_ELEMENT.
The default is to use double quotes to wrap attribute
values and to escape any double quotes found in the
value. The type value is ignored.
NAMESPACE
String prefix, String namespaceURI,
boolean isDefaultNamespaceDeclaration
None
A namespace declaration is written. If the
namespace is a default namespace declaration
(isDefault is true) then xmlns="$namespaceURI"
is written and the prefix is optional. If
isDefault is false, the prefix must be declared
and the writer must prepend xmlns to the prefix
and write out a standard prefix declaration.
PROCESSING_INSTRUCTION
None
String target, String data
The data does not need to be present and may be
null. Target is required and many not be null.
The writer
will write data section
directly after the target,
enclosed in appropriate XML 1.0 syntax
COMMENT
None
String comment
If the comment is present (not null) it is written, otherwise an
an empty comment is written
START_DOCUMENT
None
String encoding , boolean standalone, String version
A START_DOCUMENT event is not required to be written to the
stream. If present the attributes are written inside
the appropriate XML declaration syntax
END_DOCUMENT
None
None
Nothing is written to the output
DTD
String DocumentTypeDefinition
None
The DocumentTypeDefinition is written to the output
Params: - event – the event to be added
Throws:
/**
* Add an event to the output stream
* Adding a START_ELEMENT will open a new namespace scope that
* will be closed when the corresponding END_ELEMENT is written.
* <table class="striped">
* <caption>Required and optional fields for events added to the writer</caption>
* <thead>
* <tr>
* <th scope="col">Event Type</th>
* <th scope="col">Required Fields</th>
* <th scope="col">Optional Fields</th>
* <th scope="col">Required Behavior</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <th scope="row"> START_ELEMENT </th>
* <td> QName name </td>
* <td> namespaces , attributes </td>
* <td> A START_ELEMENT will be written by writing the name,
* namespaces, and attributes of the event in XML 1.0 valid
* syntax for START_ELEMENTs.
* The name is written by looking up the prefix for
* the namespace uri. The writer can be configured to
* respect prefixes of QNames. If the writer is respecting
* prefixes it must use the prefix set on the QName. The
* default behavior is to lookup the value for the prefix
* on the EventWriter's internal namespace context.
* Each attribute (if any)
* is written using the behavior specified in the attribute
* section of this table. Each namespace (if any) is written
* using the behavior specified in the namespace section of this
* table.
* </td>
* </tr>
* <tr>
* <th scope="row"> END_ELEMENT </th>
* <td> Qname name </td>
* <td> None </td>
* <td> A well formed END_ELEMENT tag is written.
* The name is written by looking up the prefix for
* the namespace uri. The writer can be configured to
* respect prefixes of QNames. If the writer is respecting
* prefixes it must use the prefix set on the QName. The
* default behavior is to lookup the value for the prefix
* on the EventWriter's internal namespace context.
* If the END_ELEMENT name does not match the START_ELEMENT
* name an XMLStreamException is thrown.
* </td>
* </tr>
* <tr>
* <th scope="row"> ATTRIBUTE </th>
* <td> QName name , String value </td>
* <td> QName type </td>
* <td> An attribute is written using the same algorithm
* to find the lexical form as used in START_ELEMENT.
* The default is to use double quotes to wrap attribute
* values and to escape any double quotes found in the
* value. The type value is ignored.
* </td>
* </tr>
* <tr>
* <th scope="row"> NAMESPACE </th>
* <td> String prefix, String namespaceURI,
* boolean isDefaultNamespaceDeclaration
* </td>
* <td> None </td>
* <td> A namespace declaration is written. If the
* namespace is a default namespace declaration
* (isDefault is true) then xmlns="$namespaceURI"
* is written and the prefix is optional. If
* isDefault is false, the prefix must be declared
* and the writer must prepend xmlns to the prefix
* and write out a standard prefix declaration.
* </td>
* </tr>
* <tr>
* <th scope="row"> PROCESSING_INSTRUCTION </th>
* <td> None</td>
* <td> String target, String data</td>
* <td> The data does not need to be present and may be
* null. Target is required and many not be null.
* The writer
* will write data section
* directly after the target,
* enclosed in appropriate XML 1.0 syntax
* </td>
* </tr>
* <tr>
* <th scope="row"> COMMENT </th>
* <td> None </td>
* <td> String comment </td>
* <td> If the comment is present (not null) it is written, otherwise an
* an empty comment is written
* </td>
* </tr>
* <tr>
* <th scope="row"> START_DOCUMENT </th>
* <td> None </td>
* <td> String encoding , boolean standalone, String version </td>
* <td> A START_DOCUMENT event is not required to be written to the
* stream. If present the attributes are written inside
* the appropriate XML declaration syntax
* </td>
* </tr>
* <tr>
* <th scope="row"> END_DOCUMENT </th>
* <td> None </td>
* <td> None </td>
* <td> Nothing is written to the output </td>
* </tr>
* <tr>
* <th scope="row"> DTD </th>
* <td> String DocumentTypeDefinition </td>
* <td> None </td>
* <td> The DocumentTypeDefinition is written to the output </td>
* </tr>
* </tbody>
* </table>
* @param event the event to be added
* @throws XMLStreamException
*/
public void add(XMLEvent event) throws XMLStreamException;
Adds an entire stream to an output stream,
calls next() on the inputStream argument until hasNext() returns false
This should be treated as a convenience method that will
perform the following loop over all the events in an
event reader and call add on each event.
Params: - reader – the event stream to add to the output
Throws:
/**
* Adds an entire stream to an output stream,
* calls next() on the inputStream argument until hasNext() returns false
* This should be treated as a convenience method that will
* perform the following loop over all the events in an
* event reader and call add on each event.
*
* @param reader the event stream to add to the output
* @throws XMLStreamException
*/
public void add(XMLEventReader reader) throws XMLStreamException;
Gets the prefix the uri is bound to
Params: - uri – the uri to look up
Throws:
/**
* Gets the prefix the uri is bound to
* @param uri the uri to look up
* @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.
Params: - prefix – the prefix to bind to the uri
- uri – the uri to bind to the prefix
Throws:
/**
* 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
* @param uri the uri to bind to the prefix
* @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.
Params: - uri – the uri to bind to the default namespace
Throws:
/**
* 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
* @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.
Params: - context – the namespace context to use for this writer
Throws:
/**
* 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.
* @param context the namespace context to use for this writer
* @throws XMLStreamException
*/
public void setNamespaceContext(NamespaceContext context)
throws XMLStreamException;
Returns the current namespace context.
Returns: the current namespace context
/**
* Returns the current namespace context.
* @return the current namespace context
*/
public NamespaceContext getNamespaceContext();
}