Package eu.bandm.tools.util.xml

Class SAXEventQueue

java.lang.Object

eu.bandm.tools.util.xml.SAXEventQueue

All Implemented Interfaces:

SAXEventStream, ContentHandler, ErrorHandler, LexicalHandler

public class SAXEventQueue
extends Object
implements ContentHandler, LexicalHandler, ErrorHandler, SAXEventStream

This class operates as a dynamic storage for SAX events.
It acts passively on both sides:
For receiving, it implements ContentHandler (for receiving open tags, close tags, character data and processing instructions), LexicalHandler (for receiving comments), and ErrorHandler.
On the consumer side it implements SAXEventStream, which must be actively polled by a consumer process, and supports to set a ErrorHandler, to which the incoming errors are transparently propagated.

ATTENTION There is a constructor with and one without (final, not initial!) capacity. The first creates an ArrayBlockingQueue, the other a LinkedBlockingQueue.
Originally, this class was intended for realizing a "buffered pipe" between a producer and a consumer running in two different threads. The producer uses the ContentHandler interface, the consumer the SAXEventStream interface.

It has successfully been "abused" also as a storage for SAX events, ie. producer and consumer running in the same thread, subsequently. Then the accumulated contents is sent to the consumer by a call to drainTo().
In this case it must be well observed that only the LinkedBlockingQueue will expand automatically.
Choosing the ArrayBlockingQueue with too small a capacity will hang the producer process!

Nested Class Summary

Nested classes/interfaces inherited from interface eu.bandm.tools.util.xml.SAXEventStream

SAXEventStream.EtherealMatcher, SAXEventStream.MatchException

Constructor Summary

Constructors

Constructor	Description
SAXEventQueue()	Uses a queue without limitation of size or capacity.
SAXEventQueue(int size)	Uses a queue with permatent limitation of capacity = max size..

Method Summary

Modifier and Type	Method	Description
(package private) @Opt XMLDocumentIdentifier	_getDocumentId(eu.bandm.tools.util.xml.SAXEventQueue.Item item)
void	characters(char[] data, int offset, int length)
void	comment(char[] ch, int start, int length)
final void	consume()	Must only be called after (at least) one invocation of lookahead().
String	consumeCharacters()	Consumes any chararcter data event, and returns the data.
void	consumedEthereals(SAXEventStream.EtherealMatcher matcher)	Visits all ethereals which have been collected immediately PRECEDING the last consumed event (start tag/end tag/char data/end of document) Visit them in source text order (=reverse order of the linked list).
void	drainTo(ContentHandler drain)	Write all stored SAX events to one receiver.
void	dump(PrintStream os)	For Debugging: print all events currently in queue.
void	endCDATA()
void	endDocument()	Write the very last tag (a special "end document" tag) to the queue, because now it must have all its Ethereals.
void	endDTD()
void	endElement(String uri, String name, String qName)
void	endEntity(String name)
void	endPrefixMapping(String prefix)
void	error(SAXParseException e)	Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.
void	fatalError(SAXParseException e)	Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.
Attributes	getAttributes()
@Opt XMLDocumentIdentifier	getDocumentId()	CHECK FIXME ist das wirklich "public" notwendig?
ErrorHandler	getErrorHandler()	Get the outgoing error handler.
String	getLocalName()	Returns the local name of the current head, i.e.
Location<XMLDocumentIdentifier>	getLocation()	Delivers the location of the current NEXT Event, i.e.
NamespaceName	getNamespaceName()	Get the NamespaceName of the next element to deliver (=the head of the queue=the result of look-ahead).
String	getNamespaceURI()	Returns the namespace URI of the current head, i.e.
String	getQualifiedName()	Returns the qualified name of the current head, i.e.
String	headToString()	Returns the conventional textual representation of the current head.
void	ignorableWhitespace(char[] data, int offset, int length)
boolean	lookaheadCharacters()	Returns whether the next SAX event represents character data.
boolean	lookaheadEndDocument()	Returns whether the next SAX event is the "End of Document" element.
boolean	lookaheadEndElement()	Returns whether the next SAX event is any end element event (= close element tag)
boolean	lookaheadEndElement(NamespaceName name)	Returns whether the next SAX event is a certain end element event (= close element tag)
boolean	lookaheadEndElement(String qname)	Returns whether the next SAX event is a certain end element event (= close element tag)
boolean	lookaheadStartElement()	Returns whether the next SAX event is any start element event (= open element tag)
boolean	lookaheadStartElement(NamespaceName name)	Returns whether the next SAX event is a certain start element event (= open element tag)
boolean	lookaheadStartElement(String qname)	Returns whether the next SAX event is a certain start element event (= open element tag)
Location<XMLDocumentIdentifier>	matchedEtherealLocation()
void	matchEndDocument()	Consumes the first element (if it is the indicated end document element).
void	matchEndElement(NamespaceName name)	Consumes the first element (if it is the indicated end element).
void	matchEndElement(String name)	Consumes the first element (if it is the indicated end element).
Attributes	matchStartElement(NamespaceName name)	Consumes the first element (if it is the indicated start element) and returns its attribute set.
Attributes	matchStartElement(String qname)	Consumes the first element (if it is the indicated start element) and returns its attribute set.
void	processingInstruction(String target, String body)
protected void	readInterrupted()	Can be overwritten by a sub-class when an interrupt is received with blocked writing.
void	setDocumentLocator(Locator locator)	According to SAX documentation, this is called-back automatically by any standard XML parser when this ContentHandler is declared to it by its "setContentHandler()" method.
void	setErrorHandler(ErrorHandler errorHandler)	Set the outgoing error handler.
void	sink()	Set sink flag so that from now on all incoming data is ingonred.
void	skippedEntity(String name)
void	startCDATA()
void	startDocument()
void	startDTD(String name, String publicId, String systemId)
void	startElement(String uri, String name, String qName, Attributes atts)
void	startEntity(String name)
void	startPrefixMapping(String prefix, String uri)
void	warning(SAXParseException e)	Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.
protected void	writeInterrupted()	Can be overwritten by a sub-class when an interrupt is received with blocked reading.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xml.sax.ContentHandler

declaration

Constructor Details

SAXEventQueue

public SAXEventQueue()

Uses a queue without limitation of size or capacity.

SAXEventQueue

public SAXEventQueue(int size)

Uses a queue with permatent limitation of capacity = max size..

Method Details

setErrorHandler

public void setErrorHandler(@Opt
 ErrorHandler errorHandler)

Set the outgoing error handler. May be null.

getErrorHandler

@Opt
public ErrorHandler getErrorHandler()

Get the outgoing error handler. May be null.

sink

public void sink()

Set sink flag so that from now on all incoming data is ingonred.

dump

public void dump(PrintStream os)

For Debugging: print all events currently in queue.

readInterrupted

protected void readInterrupted()

Can be overwritten by a sub-class when an interrupt is received with blocked writing.

writeInterrupted

protected void writeInterrupted()

Can be overwritten by a sub-class when an interrupt is received with blocked reading.

characters

public void characters(char[] data,
 int offset,
 int length)

Specified by:

characters in interface ContentHandler

startDocument

public void startDocument()

Specified by:

startDocument in interface ContentHandler

endDocument

public void endDocument()

Write the very last tag (a special "end document" tag) to the queue, because now it must have all its Ethereals.

Specified by:

endDocument in interface ContentHandler

startPrefixMapping

public void startPrefixMapping(String prefix,
 String uri)

Specified by:

startPrefixMapping in interface ContentHandler

endPrefixMapping

public void endPrefixMapping(String prefix)

Specified by:

endPrefixMapping in interface ContentHandler

ignorableWhitespace

public void ignorableWhitespace(char[] data,
 int offset,
 int length)

Specified by:

ignorableWhitespace in interface ContentHandler

processingInstruction

public void processingInstruction(String target,
 String body)

Specified by:

processingInstruction in interface ContentHandler

skippedEntity

public void skippedEntity(String name)

Specified by:

skippedEntity in interface ContentHandler

setDocumentLocator

public void setDocumentLocator(@Opt
 Locator locator)

According to SAX documentation, this is called-back automatically by any standard XML parser when this ContentHandler is declared to it by its "setContentHandler()" method. The locator object can be asked for location information whenever a SAX callback (for tags, CDATA, etc.) is instantiated. Argument may be null. If it is != null, every incoming tag, PCDATA, etc., will ask for location info.

Specified by:

setDocumentLocator in interface ContentHandler

startElement

public void startElement(String uri,
 String name,
 String qName,
 Attributes atts)

Specified by:

startElement in interface ContentHandler

endElement

public void endElement(String uri,
 String name,
 String qName)

Specified by:

endElement in interface ContentHandler

comment

public void comment(char[] ch,
 int start,
 int length)

Specified by:

comment in interface LexicalHandler

endCDATA

public void endCDATA()

Specified by:

endCDATA in interface LexicalHandler

endDTD

public void endDTD()

Specified by:

endDTD in interface LexicalHandler

endEntity

public void endEntity(String name)

Specified by:

endEntity in interface LexicalHandler

startCDATA

public void startCDATA()

Specified by:

startCDATA in interface LexicalHandler

startDTD

public void startDTD(String name,
 String publicId,
 String systemId)

Specified by:

startDTD in interface LexicalHandler

startEntity

public void startEntity(String name)

Specified by:

startEntity in interface LexicalHandler

warning

public void warning(SAXParseException e)
             throws SAXException

Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.

Specified by:

warning in interface ErrorHandler

Throws:

SAXException

error

public void error(SAXParseException e)
           throws SAXException

Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.

Specified by:

error in interface ErrorHandler

Throws:

SAXException

fatalError

public void fatalError(SAXParseException e)
                throws SAXException

Pass through the error message immediately to errorHandler, if any; not in sync with the queue throughput.

Specified by:

fatalError in interface ErrorHandler

Throws:

SAXException

lookaheadCharacters

public boolean lookaheadCharacters()

Description copied from interface: SAXEventStream

Returns whether the next SAX event represents character data.

Specified by:

lookaheadCharacters in interface SAXEventStream

lookaheadStartElement

public boolean lookaheadStartElement(NamespaceName name)

Description copied from interface: SAXEventStream

Returns whether the next SAX event is a certain start element event (= open element tag)

Specified by:

lookaheadStartElement in interface SAXEventStream

lookaheadStartElement

public boolean lookaheadStartElement(String qname)

Description copied from interface: SAXEventStream

Returns whether the next SAX event is a certain start element event (= open element tag)

Specified by:

lookaheadStartElement in interface SAXEventStream

lookaheadStartElement

public boolean lookaheadStartElement()

Description copied from interface: SAXEventStream

Returns whether the next SAX event is any start element event (= open element tag)

Specified by:

lookaheadStartElement in interface SAXEventStream

matchStartElement

public Attributes matchStartElement(NamespaceName name)
                             throws SAXEventStream.MatchException

Description copied from interface: SAXEventStream

Consumes the first element (if it is the indicated start element) and returns its attribute set.

Specified by:

matchStartElement in interface SAXEventStream

Throws:

SAXEventStream.MatchException

matchStartElement

public Attributes matchStartElement(String qname)
                             throws SAXEventStream.MatchException

Description copied from interface: SAXEventStream

Consumes the first element (if it is the indicated start element) and returns its attribute set.

Specified by:

matchStartElement in interface SAXEventStream

Throws:

SAXEventStream.MatchException

lookaheadEndElement

public boolean lookaheadEndElement(NamespaceName name)

Description copied from interface: SAXEventStream

Returns whether the next SAX event is a certain end element event (= close element tag)

Specified by:

lookaheadEndElement in interface SAXEventStream

lookaheadEndElement

public boolean lookaheadEndElement(String qname)

Description copied from interface: SAXEventStream

Returns whether the next SAX event is a certain end element event (= close element tag)

Specified by:

lookaheadEndElement in interface SAXEventStream

lookaheadEndElement

public boolean lookaheadEndElement()

Description copied from interface: SAXEventStream

Returns whether the next SAX event is any end element event (= close element tag)

Specified by:

lookaheadEndElement in interface SAXEventStream

matchEndElement

public void matchEndElement(NamespaceName name)
                     throws SAXEventStream.MatchException

Description copied from interface: SAXEventStream

Consumes the first element (if it is the indicated end element).

Specified by:

matchEndElement in interface SAXEventStream

Throws:

SAXEventStream.MatchException

matchEndElement

public void matchEndElement(String name)
                     throws SAXEventStream.MatchException

Description copied from interface: SAXEventStream

Consumes the first element (if it is the indicated end element).

Specified by:

matchEndElement in interface SAXEventStream

Throws:

SAXEventStream.MatchException

lookaheadEndDocument

public boolean lookaheadEndDocument()

Description copied from interface: SAXEventStream

Returns whether the next SAX event is the "End of Document" element.

Specified by:

lookaheadEndDocument in interface SAXEventStream

matchEndDocument

public void matchEndDocument()
                      throws SAXEventStream.MatchException

Description copied from interface: SAXEventStream

Consumes the first element (if it is the indicated end document element).

Specified by:

matchEndDocument in interface SAXEventStream

Throws:

SAXEventStream.MatchException

consumeCharacters

public String consumeCharacters()

Description copied from interface: SAXEventStream

Consumes any chararcter data event, and returns the data.

Specified by:

consumeCharacters in interface SAXEventStream

getAttributes

public Attributes getAttributes()

getNamespaceURI

public String getNamespaceURI()

Description copied from interface: SAXEventStream

Returns the namespace URI of the current head, i.e. the next element to consume.

Specified by:

getNamespaceURI in interface SAXEventStream

getLocalName

public String getLocalName()

Description copied from interface: SAXEventStream

Returns the local name of the current head, i.e. the next element to consume.

Specified by:

getLocalName in interface SAXEventStream

getQualifiedName

public String getQualifiedName()

Description copied from interface: SAXEventStream

Returns the qualified name of the current head, i.e. the next element to consume.

Specified by:

getQualifiedName in interface SAXEventStream

getNamespaceName

public NamespaceName getNamespaceName()

Get the NamespaceName of the next element to deliver (=the head of the queue=the result of look-ahead). Since NamespaceName objects are not cheap to construct, there is a cache nscache.

Specified by:

getNamespaceName in interface SAXEventStream

consume

public final void consume()

Must only be called after (at least) one invocation of lookahead(). Lookahead copies the head of the queue into the field head, and this method clears this field again. Afterwards, lookahead() may block again. GLO OUT consumedEthereals

Specified by:

consume in interface SAXEventStream

consumedEthereals

public void consumedEthereals(SAXEventStream.EtherealMatcher matcher)

Visits all ethereals which have been collected immediately PRECEDING the last consumed event (start tag/end tag/char data/end of document) Visit them in source text order (=reverse order of the linked list).

Specified by:

consumedEthereals in interface SAXEventStream

matchedEtherealLocation

public Location<XMLDocumentIdentifier> matchedEtherealLocation()

Specified by:

matchedEtherealLocation in interface SAXEventStream

getDocumentId

@Opt
public @Opt XMLDocumentIdentifier getDocumentId()

CHECK FIXME ist das wirklich "public" notwendig?

_getDocumentId

@Opt
@Opt XMLDocumentIdentifier _getDocumentId(eu.bandm.tools.util.xml.SAXEventQueue.Item item)

getLocation

public Location<XMLDocumentIdentifier> getLocation()

Delivers the location of the current NEXT Event, i.e. the event which will be considered when calling "lookahead(..)" and consumed when calling "match(..)".

Specified by:

getLocation in interface SAXEventStream

headToString

public String headToString()

Description copied from interface: SAXEventStream

Returns the conventional textual representation of the current head. Raises Nullpointer Exception if no such exists.

Specified by:

headToString in interface SAXEventStream

drainTo

public void drainTo(ContentHandler drain)
             throws SAXException

Write all stored SAX events to one receiver. Does currently NOT support Ethereals, FIXME.

Throws:

SAXException