net.sf.saxon.event

Class StreamWriterToReceiver

java.lang.Object

net.sf.saxon.event.StreamWriterToReceiver

All Implemented Interfaces:

XMLStreamWriter

Direct Known Subclasses:

BuildingStreamWriterImpl

public class StreamWriterToReceiver
extends Object
implements XMLStreamWriter

This class implements the XmlStreamWriter interface, translating the events into Saxon Receiver events. The Receiver can be anything: a serializer, a schema validator, a tree builder.

This class does not itself perform "namespace repairing" as defined in the interface Javadoc (also referred to as "prefix defaulting" in the StaX JSR specification). In normal use, however, the events emitted by this class are piped into a NamespaceReducer which performs a function very similar to namespace repairing; specifically, it ensures that when elements and attribute are generated with a given namespace URI and local name, then namespace declarations are generated automatically without any explicit need to call the writeNamespace(String, String) method.

The class will check all names, URIs, and character content for conformance against XML well-formedness rules unless the checkValues option is set to false.

The implementation of this class is influenced not only by the Javadoc documentation of the XMLStreamWriter interface (which is woefully inadequate), but also by the helpful but unofficial interpretation of the spec to be found at http://veithen.github.io/2009/11/01/understanding-stax.html

Since:

9.3. Rewritten May 2015 to fix bug 2357. Further modified in 9.7.0.2 in light of the discussion of bug 2398, and the interpretation of the spec cited above.

Constructor Summary

Constructors

Constructor and Description
StreamWriterToReceiver(Receiver receiver) Constructor.

Method Summary

Modifier and Type	Method and Description
void	close()
void	flush()
void	flushStartTag()
NamespaceContext	getNamespaceContext() Return the current namespace context.
String	getPrefix(String uri)
Object	getProperty(String name)
Receiver	getReceiver() Get the Receiver to which this StreamWriterToReceiver is writing events
boolean	isCheckValues() Ask whether names and values are to be checked for conformance with XML rules
boolean	isInventPrefixes() Deprecated. since 9.7.0.2
void	setCheckValues(boolean check) Say whether names and values are to be checked for conformance with XML rules
void	setDefaultNamespace(String uri)
void	setInventPrefixes(boolean invent) Deprecated. since 9.7.0.2. In normal use this class feeds its output into a NamespaceReducer which performs the equivalent of "namespace repairing" or "prefix invention": that is, it ensures that when elements or attributes are written in a specific namespace, there is no need for an explicit writeNamespace(String, String) call to create the namespace declaration.
void	setNamespaceContext(NamespaceContext context)
void	setPrefix(String prefix, String uri)
void	writeAttribute(String localName, String value)
void	writeAttribute(String namespaceURI, String localName, String value)
void	writeAttribute(String prefix, String namespaceURI, String localName, String value)
void	writeCData(String data)
void	writeCharacters(char[] text, int start, int len)
void	writeCharacters(String text)
void	writeComment(String data)
void	writeDefaultNamespace(String namespaceURI) Emits a default namespace declaration
void	writeDTD(String dtd)
void	writeEmptyElement(String localName)
void	writeEmptyElement(String namespaceURI, String localName)
void	writeEmptyElement(String prefix, String localName, String namespaceURI)
void	writeEndDocument()
void	writeEndElement()
void	writeEntityRef(String name)
void	writeNamespace(String prefix, String namespaceURI) Emits a namespace declaration event.
void	writeProcessingInstruction(String target)
void	writeProcessingInstruction(String target, String data)
void	writeStartDocument()
void	writeStartDocument(String version)
void	writeStartDocument(String encoding, String version)
void	writeStartElement(String localName) Generate a start element event for an element in no namespace.
void	writeStartElement(String namespaceURI, String localName) Generate a start element event.
void	writeStartElement(String prefix, String localName, String namespaceURI) Generate a start element event.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamWriterToReceiver

public StreamWriterToReceiver(Receiver receiver)

Constructor. Creates a StreamWriter as a front-end to a given Receiver.

Parameters:

receiver - the Receiver that is to receive the events generated by this StreamWriter.

Method Detail

getReceiver

public Receiver getReceiver()

Get the Receiver to which this StreamWriterToReceiver is writing events

Returns:

the destination Receiver

setInventPrefixes

public void setInventPrefixes(boolean invent)

Deprecated. since 9.7.0.2. In normal use this class feeds its output into a NamespaceReducer which performs the equivalent of "namespace repairing" or "prefix invention": that is, it ensures that when elements or attributes are written in a specific namespace, there is no need for an explicit writeNamespace(String, String) call to create the namespace declaration.

Say whether prefixes are to be invented when none is specified by the user. This method has no effect, and is deprecated

Parameters:

invent - true if prefixes are to be invented.

isInventPrefixes

public boolean isInventPrefixes()

Deprecated. since 9.7.0.2

Ask whether prefixes are to be invented when none is specified by the user. This method is deprecated.

Returns:

true if the next receiver in the pipeline is a NamespaceReducer; this is an approximation of the result in earlier releases.

setCheckValues

public void setCheckValues(boolean check)

Say whether names and values are to be checked for conformance with XML rules

Parameters:

check - true if names and values are to be checked. Default is false;

isCheckValues

public boolean isCheckValues()

Ask whether names and values are to be checked for conformance with XML rules

Returns:

true if names and values are to be checked. Default is false;

flushStartTag

public void flushStartTag()
                   throws XMLStreamException

Throws:

XMLStreamException

writeStartElement

public void writeStartElement(String localName)
                       throws XMLStreamException

Generate a start element event for an element in no namespace. Note: the element will be in no namespace, even if setDefaultNamespace(String) has been called; this is Saxon's interpretation of the intended effect of the StAX specification.

Specified by:

writeStartElement in interface XMLStreamWriter

Parameters:

localName - local name of the tag, may not be null

Throws:

XMLStreamException - if names are being checked and the name is invalid, or if an error occurs downstream

NullPointerException - if the supplied local name is null

writeStartElement

public void writeStartElement(String namespaceURI,
                              String localName)
                       throws XMLStreamException

Generate a start element event. The name of the element is determined by the supplied namespace URI and local name. The prefix used for the element is determined by the in-scope prefixes established using setPrefix(String, String) and/or setDefaultNamespace(String) if these include the specified namespace URI; otherwise the namespace will become the default namespace and there will therefore be no prefix.

Specified by:

writeStartElement in interface XMLStreamWriter

Parameters:

namespaceURI - the namespace URI of the element name. Must not be null. A zero-length string means the element is in no namespace.

localName - local part of the element name. Must not be null

Throws:

XMLStreamException - if names are being checked and are found to be invalid, or if an error occurs downstream in the pipeline.

NullPointerException - if either argument is null

writeStartElement

public void writeStartElement(String prefix,
                              String localName,
                              String namespaceURI)
                       throws XMLStreamException

Generate a start element event. The name of the element is determined by the supplied namespace URI and local name, and the prefix will be as supplied in the call.

Specified by:

writeStartElement in interface XMLStreamWriter

Parameters:

prefix - the prefix of the element, must not be null. If the prefix is supplied as a zero-length string, the element will nave no prefix (that is, the namespace URI will become the default namespace).

localName - local name of the element, must not be null

namespaceURI - the uri to bind the prefix to, must not be null. If the value is a zero-length string, the element will be in no namespace; in this case any prefix is ignored.

Throws:

NullPointerException - if any of the arguments is null.

XMLStreamException - if names are being checked and are found to be invalid, or if an error occurs downstream in the pipeline.

writeEmptyElement

public void writeEmptyElement(String namespaceURI,
                              String localName)
                       throws XMLStreamException

Specified by:

writeEmptyElement in interface XMLStreamWriter

Throws:

XMLStreamException

writeEmptyElement

public void writeEmptyElement(String prefix,
                              String localName,
                              String namespaceURI)
                       throws XMLStreamException

Specified by:

writeEmptyElement in interface XMLStreamWriter

Throws:

XMLStreamException

writeEmptyElement

public void writeEmptyElement(String localName)
                       throws XMLStreamException

Specified by:

writeEmptyElement in interface XMLStreamWriter

Throws:

XMLStreamException

writeEndElement

public void writeEndElement()
                     throws XMLStreamException

Specified by:

writeEndElement in interface XMLStreamWriter

Throws:

XMLStreamException

writeEndDocument

public void writeEndDocument()
                      throws XMLStreamException

Specified by:

writeEndDocument in interface XMLStreamWriter

Throws:

XMLStreamException

close

public void close()
           throws XMLStreamException

Specified by:

close in interface XMLStreamWriter

Throws:

XMLStreamException

flush

public void flush()
           throws XMLStreamException

Specified by:

flush in interface XMLStreamWriter

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(String localName,
                           String value)
                    throws XMLStreamException

Specified by:

writeAttribute in interface XMLStreamWriter

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(String prefix,
                           String namespaceURI,
                           String localName,
                           String value)
                    throws XMLStreamException

Specified by:

writeAttribute in interface XMLStreamWriter

Throws:

XMLStreamException

writeAttribute

public void writeAttribute(String namespaceURI,
                           String localName,
                           String value)
                    throws XMLStreamException

Specified by:

writeAttribute in interface XMLStreamWriter

Throws:

XMLStreamException

writeNamespace

public void writeNamespace(String prefix,
                           String namespaceURI)
                    throws XMLStreamException

Emits a namespace declaration event.

If the prefix argument to this method is the empty string, "xmlns", or null this method will delegate to writeDefaultNamespace.

This method does not change the name of any element or attribute; its only use is to write additional or redundant namespace declarations. With this implementation of XMLStreamWriter, this method is needed only to generate namespace declarations for prefixes that do not appear in element or attribute names. If an attempt is made to generate a namespace declaration that conflicts with the prefix-uri bindings in scope for element and attribute names, an exception occurs.

Specified by:

writeNamespace in interface XMLStreamWriter

Parameters:

prefix - the prefix to bind this namespace to

namespaceURI - the uri to bind the prefix to

Throws:

IllegalStateException - if the current state does not allow Namespace writing

XMLStreamException

writeDefaultNamespace

public void writeDefaultNamespace(String namespaceURI)
                           throws XMLStreamException

Emits a default namespace declaration

This method does not change the name of any element or attribute; its only use is to write additional or redundant namespace declarations. With this implementation of XMLStreamWriter, this method is needed only to generate namespace declarations for prefixes that do not appear in element or attribute names. If an attempt is made to generate a namespace declaration that conflicts with the prefix-uri bindings in scope for element and attribute names, an exception occurs.

Specified by:

writeDefaultNamespace in interface XMLStreamWriter

Parameters:

namespaceURI - the uri to bind the default namespace to

Throws:

IllegalStateException - if the current state does not allow Namespace writing

XMLStreamException

writeComment

public void writeComment(String data)
                  throws XMLStreamException

Specified by:

writeComment in interface XMLStreamWriter

Throws:

XMLStreamException

writeProcessingInstruction

public void writeProcessingInstruction(String target)
                                throws XMLStreamException

Specified by:

writeProcessingInstruction in interface XMLStreamWriter

Throws:

XMLStreamException

writeProcessingInstruction

public void writeProcessingInstruction(String target,
                                       String data)
                                throws XMLStreamException

Specified by:

writeProcessingInstruction in interface XMLStreamWriter

Throws:

XMLStreamException

writeCData

public void writeCData(String data)
                throws XMLStreamException

Specified by:

writeCData in interface XMLStreamWriter

Throws:

XMLStreamException

writeDTD

public void writeDTD(String dtd)
              throws XMLStreamException

Specified by:

writeDTD in interface XMLStreamWriter

Throws:

XMLStreamException

writeEntityRef

public void writeEntityRef(String name)
                    throws XMLStreamException

Specified by:

writeEntityRef in interface XMLStreamWriter

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument()
                        throws XMLStreamException

Specified by:

writeStartDocument in interface XMLStreamWriter

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument(String version)
                        throws XMLStreamException

Specified by:

writeStartDocument in interface XMLStreamWriter

Throws:

XMLStreamException

writeStartDocument

public void writeStartDocument(String encoding,
                               String version)
                        throws XMLStreamException

Specified by:

writeStartDocument in interface XMLStreamWriter

Throws:

XMLStreamException

writeCharacters

public void writeCharacters(String text)
                     throws XMLStreamException

Specified by:

writeCharacters in interface XMLStreamWriter

Throws:

XMLStreamException

writeCharacters

public void writeCharacters(char[] text,
                            int start,
                            int len)
                     throws XMLStreamException

Specified by:

writeCharacters in interface XMLStreamWriter

Throws:

XMLStreamException

getPrefix

public String getPrefix(String uri)

Specified by:

getPrefix in interface XMLStreamWriter

setPrefix

public void setPrefix(String prefix,
                      String uri)

Specified by:

setPrefix in interface XMLStreamWriter

setDefaultNamespace

public void setDefaultNamespace(String uri)
                         throws XMLStreamException

Specified by:

setDefaultNamespace in interface XMLStreamWriter

Throws:

XMLStreamException

setNamespaceContext

public void setNamespaceContext(NamespaceContext context)
                         throws XMLStreamException

Specified by:

setNamespaceContext in interface XMLStreamWriter

Throws:

XMLStreamException

getNamespaceContext

public NamespaceContext getNamespaceContext()

Return the current namespace context.

The specification of this method is hopelessly vague. This method returns a namespace context that contains the namespaces declared using setPrefix(String, String) calls that are in-scope at the time, overlaid on the root namespace context that was defined using setNamespaceContext(NamespaceContext). The namespaces bound using setPrefix(String, String) are copied, and are therefore unaffected by subsequent changes, but the root namespace context is not copied, because the NamespaceContext interface provides no way of doing so.

Specified by:

getNamespaceContext in interface XMLStreamWriter

Returns:

a copy of the current namespace context.

getProperty

public Object getProperty(String name)
                   throws IllegalArgumentException

Specified by:

getProperty in interface XMLStreamWriter

Throws:

IllegalArgumentException