net.sf.mmm.util.xml.impl.stax

Class XIncludeStreamReader

java.lang.Object

javax.xml.stream.util.StreamReaderDelegate

net.sf.mmm.util.xml.base.StreamReaderProxy

net.sf.mmm.util.xml.impl.stax.XIncludeStreamReader

All Implemented Interfaces:

XMLStreamConstants, XMLStreamReader

public class XIncludeStreamReader
extends StreamReaderProxy

This is an implementation of the XMLStreamReader interface that adapts an XMLStreamReader adding support for XInclude.
For details about XInclude see: http://www.w3.org/TR/xinclude/.
ATTENTION:
Please note that currently only plain XML inclusion is currently supported and no XPointer.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
private int	depth The current depth in the XML tree relative to the first "include" tag of the XInclude namespace that is currently active.
private XMLInputFactory	factory The factory used to create additional readers.
private boolean	fallback This flag indicates whether we are actively inside a fallback section.
private XMLStreamReader	includeReader The reader to the current XInclude document or null if we currently have no active XInclude.
private String	includeText The included text or null if currently no text is to be included.
private InputStream	inputStream The StAX resource management sucks: we need to manage the underlying input stream ourselves.
private static org.slf4j.Logger	LOGGER The Logger to use.
private XMLStreamReader	mainReader The reader to the main document.
private XIncludeStreamReader	parent the parent reader or null if this is the root.
private DataResource	resource The resource pointing to the main document.

Fields inherited from interface javax.xml.stream.XMLStreamConstants

ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT

Constructor Summary

Constructors

Modifier	Constructor and Description
	XIncludeStreamReader(XMLInputFactory factory, DataResource resource) The constructor.
protected	XIncludeStreamReader(XMLInputFactory factory, DataResource resource, XIncludeStreamReader parent) The constructor.

Method Summary

Modifier and Type	Method and Description
void	close() ATTENTION: This method violates the StAX API and closes the underlying input stream! The StAX API has a bad design mistake about the close() method NOT to close the underlying input stream.
protected void	closeInitialInclude() This method ascends the XML until the initial include is closed.
protected void	detectRecursiveInclusion(DataResource dataResource) This method detects if a recursive inclusion takes place.
String	getText()
char[]	getTextCharacters()
int	getTextLength()
int	getTextStart()
int	next()
protected int	resolveInclude() This method is called when an include tag of the XInclude namespace was started.

Methods inherited from class net.sf.mmm.util.xml.base.StreamReaderProxy

nextTag

Methods inherited from class javax.xml.stream.util.StreamReaderDelegate

getAttributeCount, getAttributeLocalName, getAttributeName, getAttributeNamespace, getAttributePrefix, getAttributeType, getAttributeValue, getAttributeValue, getCharacterEncodingScheme, getElementText, getEncoding, getEventType, getLocalName, getLocation, getName, getNamespaceContext, getNamespaceCount, getNamespacePrefix, getNamespaceURI, getNamespaceURI, getNamespaceURI, getParent, getPIData, getPITarget, getPrefix, getProperty, getTextCharacters, getVersion, hasName, hasNext, hasText, isAttributeSpecified, isCharacters, isEndElement, isStandalone, isStartElement, isWhiteSpace, require, setParent, standaloneSet

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

private static final org.slf4j.Logger LOGGER

The Logger to use.

parent

private final XIncludeStreamReader parent

the parent reader or null if this is the root.

factory

private final XMLInputFactory factory

The factory used to create additional readers.

mainReader

private final XMLStreamReader mainReader

The reader to the main document.

resource

private final DataResource resource

The resource pointing to the main document.

inputStream

private final InputStream inputStream

The StAX resource management sucks: we need to manage the underlying input stream ourselves.

includeReader

private XMLStreamReader includeReader

The reader to the current XInclude document or null if we currently have no active XInclude.

includeText

private String includeText

The included text or null if currently no text is to be included.

depth

private int depth

The current depth in the XML tree relative to the first "include" tag of the XInclude namespace that is currently active. Will be 0 if we are outside of an XInclude.

fallback

private boolean fallback

This flag indicates whether we are actively inside a fallback section.

Constructor Detail

XIncludeStreamReader

public XIncludeStreamReader(XMLInputFactory factory,
                            DataResource resource)

The constructor.

Parameters:

factory - is the XMLInputFactory required to create new XMLStreamReader instances for includes.

resource - is the DataResource pointing to the XML content.

XIncludeStreamReader

protected XIncludeStreamReader(XMLInputFactory factory,
                               DataResource resource,
                               XIncludeStreamReader parent)
                        throws XmlException,
                               RuntimeIoException

The constructor.

Parameters:

factory - is the input factory used to create raw XML-readers.

resource - is where to read the XML from.

parent - is the parent XMLStreamReader.

Throws:

XmlException - in case of an XML error.

RuntimeIoException - is case of an input/output error.

Method Detail

detectRecursiveInclusion

protected void detectRecursiveInclusion(DataResource dataResource)
                                 throws XMLStreamException

This method detects if a recursive inclusion takes place.
TODO: Potentially the same resource could cause an inclusion cycle without causing an infinity loop by using different XPointer expressions.

Parameters:

dataResource - is the current data-resource to include.

Throws:

XMLStreamException - if the given dataResource has already been included causing an infinity loop.

close

public void close()
           throws XMLStreamException

ATTENTION:
This method violates the StAX API and closes the underlying input stream!
The StAX API has a bad design mistake about the close() method NOT to close the underlying input stream. Besides the XMLStreamReader the user also has to manage the input stream what will lead in additional programming mistakes ending up with open file-handles. Since many XMLStreamReader implementations have an empty body for this method developers, may tend to take it NOT as serious as e.g. InputStream.close(). Since this implementation has to open new streams behind the scenes the only senseful implementation of this method is to close the underlying stream (and recursively closing all included streams). You have to ensure this reader is safely closed via this method so remaining open streams are closed.

Specified by:

close in interface XMLStreamReader

Overrides:

close in class StreamReaderDelegate

Throws:

XMLStreamException

resolveInclude

protected int resolveInclude()
                      throws XMLStreamException

This method is called when an include tag of the XInclude namespace was started. It resolves the include and finds a fallback on failure.

Returns:

the next event type.

Throws:

XMLStreamException - if the XML stream processing caused an error.

closeInitialInclude

protected void closeInitialInclude()
                            throws XMLStreamException

This method ascends the XML until the initial include is closed.

Throws:

XMLStreamException - if the XML stream processing caused an error.

next

public int next()
         throws XMLStreamException

Specified by:

next in interface XMLStreamReader

Overrides:

next in class StreamReaderDelegate

Throws:

XMLStreamException

getText

public String getText()

Specified by:

getText in interface XMLStreamReader

Overrides:

getText in class StreamReaderDelegate

getTextCharacters

public char[] getTextCharacters()

Specified by:

getTextCharacters in interface XMLStreamReader

Overrides:

getTextCharacters in class StreamReaderDelegate

getTextLength

public int getTextLength()

Specified by:

getTextLength in interface XMLStreamReader

Overrides:

getTextLength in class StreamReaderDelegate

getTextStart

public int getTextStart()

Specified by:

getTextStart in interface XMLStreamReader

Overrides:

getTextStart in class StreamReaderDelegate