public interface StAXDialect
In addition to bugs in particular StAX implementations and clear violations of the StAX specifications, the following ambiguities and gray areas in the specifications are also addressed by the dialect implementations:
null
value
for the charset encoding parameter in the following methods:
XMLOutputFactory.createXMLEventWriter(java.io.OutputStream, String)
XMLOutputFactory.createXMLStreamWriter(java.io.OutputStream, String)
XMLStreamWriter.writeStartDocument(String, String)
null
values, while others throw an exception.
To make sure that code written to run with a normalized XMLOutputFactory
remains
portable, the dialect implementation normalizes the behavior of these methods so that they
consistently throw an exception when called with a null
encoding. Note that
the type of exception to be thrown remains unspecified.XMLStreamReader.getEncoding()
returns the "input encoding if known or null
if unknown". This requirement
is not precise enough to guarantee consistent behavior across different implementations.
In order to provide the consumer of the stream reader with complete and unambiguous information about
the encoding of the underlying stream, the dialect implementations normalize the
behavior of the XMLStreamReader.getEncoding()
method such that
it returns a non null value if and only if the reader was created from a byte stream, in
which case the return value is the effective charset encoding used by the parser to
decode the byte stream. According to the XML specifications, this value is determined
by one of the following means:
XMLInputFactory.createXMLStreamReader(java.io.InputStream, String)
method. This is referred to as "external encoding information" by the XML
specifications.XMLStreamReader
class, calls to
XMLStreamReader.getEncoding()
,
XMLStreamReader.getVersion()
,
XMLStreamReader.isStandalone()
,
XMLStreamReader.standaloneSet()
and
XMLStreamReader.getCharacterEncodingScheme()
are only allowed
in the XMLStreamConstants.START_DOCUMENT
state. On the other
hand, this requirement is not mentioned in the documentation of the individual methods
and the majority of StAX implementations support calls to these methods in any state.
However, to improve portability, the dialect implementations normalize these methods to
throw an IllegalStateException
if they are called in a state other than
XMLStreamConstants.START_DOCUMENT
.XMLStreamReader.isCharacters()
specifies
that this method "returns true if the cursor points to a character data event".
On the other hand, the documentation of XMLStreamReader
states that "parsing events are defined as the XML Declaration, a DTD, start tag,
character data, white space, end tag, comment, or processing instruction" and thus
makes a clear distinction between character data events and white space events.
This means that XMLStreamReader.isCharacters()
should return
true
if and only if the current event is
XMLStreamConstants.CHARACTERS
. This is the case for most parsers,
but some return true
for XMLStreamConstants.SPACE
events as well. Where necessary, the dialect implementations correct this behavior.
Note that there are several ambiguities in the StAX specification which are not addressed by the different dialect implementations:
XMLStreamReader.getAttributePrefix(int)
should return null
or an empty string if the attribute doesn't have a
prefix. Consistency with XMLStreamReader.getPrefix()
would
imply that it should return null
, but some implementations return an empty
string.XMLStreamReader.next()
about the exception that is thrown when
this method is called after XMLStreamReader.hasNext()
returns
false. It can either be IllegalStateException
or
NoSuchElementException
.
Note that some implementations (including the reference implementation) throw an
XMLStreamException
in this case. This is considered as a
violation of the specifications because this exception should only be used
"if there is an error processing the underlying XML source", which is not the case.
XMLStreamReader.getNamespaceURI(int)
should return null
or an empty string.XMLStreamWriter.setPrefix(String, String)
and XMLStreamWriter.setDefaultNamespace(String)
requires that
the namespace "is bound in the scope of the current START_ELEMENT / END_ELEMENT pair".
The meaning of this requirement is clear in the context of an element written using
the writeStartElement
and writeEndElement
methods. On the
other hand, the requirement is ambiguous in the context of an element written using
writeEmptyElement
and there are two competing interpretations:
writeEmptyElement
methods actually
doesn't write a complete element because it can be followed by invocations
of writeAttribute
, writeNamespace
or
writeDefaultNamespace
. The element is only completed by a
call to a write
method other than the aforementioned methods.
An element written using writeEmptyElement
therefore also
defines a scope and the namespace should be bound in that scope.writeEmptyElement
,
writeAttribute
, setPrefix
, writeCharacters
.
In this case, it is not clear if the scope of the empty element should end at the call to
writeAttribute
or writeCharacters
.
Because of these ambiguities, the dialect implementations don't attempt to normalize the
behavior of XMLStreamWriter.setPrefix(String, String)
and XMLStreamWriter.setDefaultNamespace(String)
in this particular
context, and their usage in conjunction with writeEmptyElement
should be
avoided.
Modifier and Type | Method and Description |
---|---|
javax.xml.stream.XMLInputFactory |
disallowDoctypeDecl(javax.xml.stream.XMLInputFactory factory)
Configure the given factory to disallow DOCTYPE declarations.
|
javax.xml.stream.XMLInputFactory |
enableCDataReporting(javax.xml.stream.XMLInputFactory factory)
Configure the given factory to enable reporting of CDATA sections by stream readers created
from it.
|
String |
getName()
Get the name of this dialect.
|
javax.xml.stream.XMLInputFactory |
makeThreadSafe(javax.xml.stream.XMLInputFactory factory)
Make an
XMLInputFactory object thread safe. |
javax.xml.stream.XMLOutputFactory |
makeThreadSafe(javax.xml.stream.XMLOutputFactory factory)
Make an
XMLOutputFactory object thread safe. |
javax.xml.stream.XMLInputFactory |
normalize(javax.xml.stream.XMLInputFactory factory)
Normalize an
XMLInputFactory . |
javax.xml.stream.XMLOutputFactory |
normalize(javax.xml.stream.XMLOutputFactory factory)
Normalize an
XMLOutputFactory . |
String getName()
javax.xml.stream.XMLInputFactory enableCDataReporting(javax.xml.stream.XMLInputFactory factory)
XMLStreamReader.next()
method suggests that even if the parser is non
coalescing, CDATA sections should be reported as CHARACTERS events. Some implementations
strictly follow the example, while for others it is sufficient to make the parser non
coalescing.factory
- the factory to configure; this may be an already normalized factory or a "raw"
factory objectUnsupportedOperationException
- if reporting of CDATA sections is not supportedjavax.xml.stream.XMLInputFactory disallowDoctypeDecl(javax.xml.stream.XMLInputFactory factory)
XMLStreamConstants.START_ELEMENT
event.
factory
- the factory to configure; this may be an already normalized factory or a "raw"
factory objectjavax.xml.stream.XMLInputFactory makeThreadSafe(javax.xml.stream.XMLInputFactory factory)
XMLInputFactory
object thread safe. The implementation may do this either by
configuring the factory or by creating a thread safe wrapper. The returned factory must be
thread safe for all method calls that don't change the (visible) state of the factory. This
means that thread safety is not required for
XMLInputFactory.setEventAllocator(javax.xml.stream.util.XMLEventAllocator)
,
XMLInputFactory.setProperty(String, Object)
,
XMLInputFactory.setXMLReporter(javax.xml.stream.XMLReporter)
and
XMLInputFactory.setXMLResolver(javax.xml.stream.XMLResolver)
.factory
- the factory to make thread safejavax.xml.stream.XMLOutputFactory makeThreadSafe(javax.xml.stream.XMLOutputFactory factory)
XMLOutputFactory
object thread safe. The implementation may do this either by
configuring the factory or by creating a thread safe wrapper. The returned factory must be
thread safe for all method calls that don't change the (visible) state, i.e. the properties,
of the factory.factory
- the factory to make thread safejavax.xml.stream.XMLInputFactory normalize(javax.xml.stream.XMLInputFactory factory)
XMLInputFactory
. This will make sure that the readers created from the
factory conform to the StAX specifications.factory
- the factory to normalizejavax.xml.stream.XMLOutputFactory normalize(javax.xml.stream.XMLOutputFactory factory)
XMLOutputFactory
. This will make sure that the writers created from the
factory conform to the StAX specifications.factory
- the factory to normalizeCopyright © 2004-2013 The Apache Software Foundation. All Rights Reserved.