Module org.tquadrat.foundation.xml

Package org.tquadrat.foundation.xml.parse.spi

Class StAXParserBase<T>

java.lang.Object

org.tquadrat.foundation.xml.parse.spi.StAXParserBase<T>

Type Parameters:

T - The type of the target data structure.

Direct Known Subclasses:

StAXParser

@ClassVersion(sourceVersion="$Id: StAXParserBase.java 1071 2023-09-30 01:49:32Z tquadrat $")
@API(status=EXPERIMENTAL,
     since="0.0.5")
public abstract class StAXParserBase<T>
extends Object

The abstract base class for StAX based XML parsers.

An implementation of this class will parse an XML stream to an object of type T that is either provided with the constructor StAXParserBase(Object) or will be created by an instance of XMLParseEventHandler.

The parse event handler can be provided either programmatically, as shown in StAXParser, or as methods in an implementation of this class.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: StAXParserBase.java 1071 2023-09-30 01:49:32Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.xml.parse.spi.StAXParserBase"

⁠

Field Summary

Fields

Modifier and Type	Field	Description
static final StAXParserBase[]	EMPTY_StAXParserBase_ARRAY	An empty array of StAXParserBase objects.
private Optional<String>	m_DocumentTag	The document element tag.
private final Map<String,XMLParseEventHandler<?>>	m_Handlers	The event handlers.
private T	m_Target	The target data structure.
static final String	MSG_NoHandler	The message for missing handlers: "No handler was registered for element \'%s\'".
static final String	MSG_UnexpectedTag	The message for an unexpected tag: "The element tag \'%s\' is unexpected here".

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	StAXParserBase()	Creates a new StAXParserBase instance.
protected	StAXParserBase(T target)	Creates a new StAXParser instance.

Method Summary

Modifier and Type	Method	Description
protected T	parse(XMLEventReader eventReader)	Processes the given event reader.
protected final void	registerElementHandler(String elementName, boolean isDocument, XMLParseEventHandler<?> handler)	Registers an element handler.
protected static final void	reportUnexpectedTag(String elementName, Location location)	Throws an XMLStreamException that indicates an unexpected tag at the given location.
private final XMLParseEventHandler<?>	retrieveHandler(String elementName)	Retrieves the XML parse event handler for the given element name.
private final void	setTarget(T target)	Sets the target data structure.

Methods inherited from class java.lang.Object

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

Field Details

EMPTY_StAXParserBase_ARRAY

public static final StAXParserBase[] EMPTY_StAXParserBase_ARRAY

An empty array of StAXParserBase objects.

MSG_NoHandler

public static final String MSG_NoHandler

The message for missing handlers: "No handler was registered for element \'%s\'".

See Also:

• Constant Field Values

MSG_UnexpectedTag

public static final String MSG_UnexpectedTag

The message for an unexpected tag: "The element tag \'%s\' is unexpected here".

See Also:

• Constant Field Values

m_DocumentTag

private Optional<String> m_DocumentTag

The document element tag.

m_Handlers

private final Map<String,XMLParseEventHandler<?>> m_Handlers

The event handlers.

m_Target

private T m_Target

The target data structure.

Constructor Details

StAXParserBase

protected StAXParserBase()

Creates a new StAXParserBase instance.

StAXParserBase

protected StAXParserBase(T target)

Creates a new StAXParser instance.

Parameters:

target - The target data structure.

Method Details

parse

@API(status=EXPERIMENTAL,
     since="0.0.7")
protected T parse(XMLEventReader eventReader)
           throws SAXException

Processes the given event reader.

Parameters:

eventReader - The XML stream.

Returns:

The target data structure.

Throws:

SAXException - Something went wrong.

registerElementHandler

protected final void registerElementHandler(String elementName,
 boolean isDocument,
 XMLParseEventHandler<?> handler)

Registers an element handler.

Parameters:

elementName - The element name.

isDocument - true if the element name is the document name.

handler - The parse event handler.

reportUnexpectedTag

@API(status=EXPERIMENTAL,
     since="0.0.7")
protected static final void reportUnexpectedTag(String elementName,
 Location location)
                                         throws XMLStreamException

Throws an XMLStreamException that indicates an unexpected tag at the given location.

Parameters:

elementName - The encountered tag.

location - The location.

Throws:

XMLStreamException - Always.

retrieveHandler

private final XMLParseEventHandler<?> retrieveHandler(String elementName)
                                               throws XMLStreamException

Retrieves the XML parse event handler for the given element name.

Parameters:

elementName - The name of the element to handle.

Returns:

The requested instance of XMLParseEventHandler.

Throws:

XMLStreamException - There is no registered handler for the given element name.

setTarget

private final void setTarget(T target)

Sets the target data structure.

Parameters:

target - The target data structure.