org.apache.axiom.util.stax.dialect
Interface StAXDialect


public interface StAXDialect

Encapsulates the specific characteristics of a particular StAX implementation. In particular, an implementation of this interface is able to wrap (if necessary) the readers and writers produced by the StAX implementation to make them conform to the StAX specifications. This is called normalization.

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:

Note that there are several ambiguities in the StAX specification which are not addressed by the different dialect implementations:


Method Summary
 XMLInputFactory disallowDoctypeDecl(XMLInputFactory factory)
          Configure the given factory to disallow DOCTYPE declarations.
 XMLInputFactory enableCDataReporting(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.
 XMLInputFactory makeThreadSafe(XMLInputFactory factory)
          Make an XMLInputFactory object thread safe.
 XMLOutputFactory makeThreadSafe(XMLOutputFactory factory)
          Make an XMLOutputFactory object thread safe.
 XMLInputFactory normalize(XMLInputFactory factory)
          Normalize an XMLInputFactory.
 XMLOutputFactory normalize(XMLOutputFactory factory)
          Normalize an XMLOutputFactory.
 

Method Detail

getName

String getName()
Get the name of this dialect.

Returns:
the name of the dialect

enableCDataReporting

XMLInputFactory enableCDataReporting(XMLInputFactory factory)
Configure the given factory to enable reporting of CDATA sections by stream readers created from it. The example in the documentation of the 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.

Parameters:
factory - the factory to configure; this may be an already normalized factory or a "raw" factory object
Returns:
the factory with CDATA reporting enabled; this may be the original factory instance or a wrapper
Throws:
UnsupportedOperationException - if reporting of CDATA sections is not supported

disallowDoctypeDecl

XMLInputFactory disallowDoctypeDecl(XMLInputFactory factory)
Configure the given factory to disallow DOCTYPE declarations. The effect of this is similar to the http://apache.org/xml/features/disallow-doctype-decl feature in Xerces. The factory instance returned by this method MUST satisfy the following requirements: This method is typically useful in the context of SOAP processing since a SOAP message must not contain a Document Type Declaration.

Parameters:
factory - the factory to configure; this may be an already normalized factory or a "raw" factory object
Returns:
the factory that disallows DOCTYPE declarations; this may be the original factory instance or a wrapper

makeThreadSafe

XMLInputFactory makeThreadSafe(XMLInputFactory factory)
Make an 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).

Parameters:
factory - the factory to make thread safe
Returns:
the thread safe factory

makeThreadSafe

XMLOutputFactory makeThreadSafe(XMLOutputFactory factory)
Make an 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.

Parameters:
factory - the factory to make thread safe
Returns:
the thread safe factory

normalize

XMLInputFactory normalize(XMLInputFactory factory)
Normalize an XMLInputFactory. This will make sure that the readers created from the factory conform to the StAX specifications.

Parameters:
factory - the factory to normalize
Returns:
the normalized factory

normalize

XMLOutputFactory normalize(XMLOutputFactory factory)
Normalize an XMLOutputFactory. This will make sure that the writers created from the factory conform to the StAX specifications.

Parameters:
factory - the factory to normalize
Returns:
the normalized factory


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.