org.inria.ns.reflex.xml.sax
Class XPathFilter

java.lang.Object
  org.xml.sax.helpers.XMLFilterImpl
      org.inria.ns.reflex.xml.sax.SAXFilter
          org.inria.ns.reflex.xml.sax.XPathFilter

All Implemented Interfaces:

Anticipable, Localizable, Lockable, ContentHandler, DTDHandler, EntityResolver, ErrorHandler, DeclHandler, LexicalHandler, XMLFilter, XMLReader

public class XPathFilter
extends SAXFilter
implements Anticipable, Lockable

A SAX filter that support XPath patterns and expressions in a very acceptable way.

A single branch of the XML tree is maintained by this class in order to cross forward axis. For each node of the branch, one can retrieve its attributes, namespaces, ancestors, and the index and size counters necessary when using the position(), last() and count() functions.

The datas that has been read previously can't be used in XPath expressions : preceding-sibling:: can't be used but ancestor:: can. More formally, the preceding:: axis is no longer reachable.

When a forward-axis is involved (when using following-sibling:: or count() or whatever that expect further reading), a cache is used to store events until the XPath expression becomes resolvable. Once done, the stored events are fired before the reading goes on.

Detailed strategy

Read this article.

An internal coroutine implements AbstractFilter for applying rules.

SAX filter

Received SAX events are tested upon rules ; the rule with the highest priority is applied. Default rules are passing the non-matched events to the handler unmodified.

Author:

Philippe Poulard

See Also:

SAXNode

Nested Class Summary

Nested classes/interfaces inherited from interface org.inria.ns.reflex.structures.Lockable

Lockable.Monitor

Constructor Summary

XPathFilter(List rules, boolean normalize, PatternContext context, FilterContextFactory filterContextFactory)
Create a new XPath filter.

XPathFilter(ParserConfiguration parserConfiguration, List rules, boolean normalize, PatternContext context, FilterContextFactory filterContextFactory)
Create a new XPath filter.

XPathFilter(RuleBasedFilter filterDef, PatternContext context)
Create a new XPath filter.

XPathFilter(XPathFilter model, PatternContext context, FilterContextFactory filterContextFactory)
Create a new XPath filter.

Method Summary

void	characters(char[] ch, int start, int length) Bufferize adjacent character events.
void	comment(char[] ch, int start, int length) Process an event : lookup for a rule and apply it, or fire the event.
void	endAnticipate() This method is called by the 2nd thread when further parsing is no longer needed.
void	endCDATA() This event is ignored, as adjacent text nodes must be merged.
void	endDocument() Process an event.
void	endDTD() Fire or ignore this event according to the class of filters.
void	endElement(String uri, String localName, String qName) Process an event.
void	endPrefixMapping(String prefix) Remove a stored prefix mapping.
void	ignorableWhitespace(char[] ch, int start, int length) Fire character events.
boolean	isAnticipating() Indicates whether the cache is active or not.
boolean	isSleeping() Indicates whether the thread that owns this lockable is sleeping or not.
void	parse(InputSource input) Parse an input.
void	parse(String systemId) Parse an input.
void	processingInstruction(String target, String data) Process an event : lookup for a rule and apply it, or fire the event.
void	resumeThread() Wake up the thread locked by this lockable.
void	startAnticipate() This method is called by the 2nd thread when further parsing is needed.
void	startCDATA() This event is ignored, as adjacent text nodes must be merged.
void	startDocument() Process an event : lookup for a rule and apply it, or ignore the event.
void	startDTD(String name, String publicId, String systemId) Fire or ignore this event according to the class of filters.
void	startElement(String uri, String localName, String qName, Attributes atts) Process an event : lookup for a rule and apply it, or fire the event.
void	startPrefixMapping(String prefix, String uri) Store a prefix mapping.
void	suspendThread() Suspends this thread.
String	toString() Return the rules of this filter, sorted in reverse priority order.

Methods inherited from class org.inria.ns.reflex.xml.sax.SAXFilter

attributeDecl, elementDecl, endEntity, externalEntityDecl, getDeclHandler, getLexicalHandler, getLocation, getProperty, internalEntityDecl, isLocalizable, setDeclHandler, setLexicalHandler, setLocation, setProperty, startEntity

Methods inherited from class org.xml.sax.helpers.XMLFilterImpl

error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, notationDecl, resolveEntity, setContentHandler, setDocumentLocator, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, skippedEntity, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.xml.sax.ContentHandler

setDocumentLocator, skippedEntity

Methods inherited from interface org.xml.sax.DTDHandler

notationDecl, unparsedEntityDecl

Constructor Detail

XPathFilter

public XPathFilter(ParserConfiguration parserConfiguration,
                   List rules,
                   boolean normalize,
                   PatternContext context,
                   FilterContextFactory filterContextFactory)

Create a new XPath filter.

*** The variable context MUST NOT be shared by filters. If it is backed by a DataSet, the local properties MUST NOT be shared. Each filter has to manage its own private properties ; this is critical for some properties used internally. ***

Parameters:

parserConfiguration - The configuration of the parser.

rules - The list of rules used for event filtering.

normalize - The default value for text normalization if not specified at rule level.

context - The context that can resolve XPath functions, variables, and namespaces.

filterContextFactory - The factory that create a filter context for each matched node.

See Also:

Rule, AbstractFilter

XPathFilter

public XPathFilter(XPathFilter model,
                   PatternContext context,
                   FilterContextFactory filterContextFactory)

Create a new XPath filter.

*** See {@link #XPathFilter(ParserConfiguration, List, PatternContext)} ***

Parameters:

model - The new XPath filter will be the same as those one. The parser configuration and the rules are shared by both filters.

context - The context that can resolve XPath functions, variables, and namespaces.

filterContextFactory - The factory that create a filter context for each matched node.

See Also:

Rule, AbstractFilter

XPathFilter

public XPathFilter(List rules,
                   boolean normalize,
                   PatternContext context,
                   FilterContextFactory filterContextFactory)

Create a new XPath filter. A default namespace aware parser might be used.

*** See {@link #XPathFilter(ParserConfiguration, List, PatternContext)} ***

Parameters:

rules - The list of rules used for event filtering.

normalize - The default value for text normalization if not specified at rule level.

context - The context that can resolve XPath functions, variables, and namespaces.

filterContextFactory - The factory that create a filter context for each matched node.

See Also:

Rule, AbstractFilter, ParserConfiguration.NAMESPACEAWARE_PARSER_CONFIGURATION

XPathFilter

public XPathFilter(RuleBasedFilter filterDef,
                   PatternContext context)

Create a new XPath filter. A default namespace aware parser might be used.

*** See {@link #XPathFilter(ParserConfiguration, List, PatternContext)} ***

Parameters:

filterDef - The rule-based filter.

context - The context that can resolve XPath functions, variables, and namespaces.

filterContextFactory - The factory that create a filter context for each matched node.

See Also:

Rule, AbstractFilter, ParserConfiguration.NAMESPACEAWARE_PARSER_CONFIGURATION

Method Detail

parse

public void parse(InputSource input)
           throws SAXException,
                  IOException

Parse an input.

Specified by:

parse in interface XMLReader

Overrides:

parse in class XMLFilterImpl

Parameters:

input - The input to parse.

Throws:

SAXException

IOException

See Also:

XMLFilterImpl.parse(org.xml.sax.InputSource)

parse

public void parse(String systemId)
           throws SAXException,
                  IOException

Parse an input.

Specified by:

parse in interface XMLReader

Overrides:

parse in class SAXFilter

Parameters:

systemId - The system ID of the input to parse.

Throws:

SAXException

IOException

See Also:

SAXFilter.parse(java.lang.String)

startAnticipate

public void startAnticipate()
                     throws IllegalStateException

This method is called by the 2nd thread when further parsing is needed.

Specified by:

startAnticipate in interface Anticipable

Throws:

IllegalStateException - When the end of the document is reached.

See Also:

Anticipable.startAnticipate()

isAnticipating

public boolean isAnticipating()

Indicates whether the cache is active or not.

Specified by:

isAnticipating in interface Anticipable

Returns:

true if the cache is active, false otherwise.

See Also:

Anticipable.isAnticipating()

endAnticipate

public void endAnticipate()

This method is called by the 2nd thread when further parsing is no longer needed.

Specified by:

endAnticipate in interface Anticipable

See Also:

Anticipable.endAnticipate()

startDocument

public void startDocument()
                   throws SAXException

Process an event : lookup for a rule and apply it, or ignore the event.

Specified by:

startDocument in interface ContentHandler

Overrides:

startDocument in class SAXFilter

Throws:

SAXException - The client may throw an exception during processing.

See Also:

XMLFilterImpl.startDocument()

endDocument

public void endDocument()
                 throws SAXException

Process an event.

Specified by:

endDocument in interface ContentHandler

Overrides:

endDocument in class SAXFilter

Throws:

SAXException - The client may throw an exception during processing.

See Also:

XMLFilterImpl.endDocument()

comment

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

Process an event : lookup for a rule and apply it, or fire the event.

Specified by:

comment in interface LexicalHandler

Overrides:

comment in class SAXFilter

Throws:

SAXException

See Also:

SAXFilter.comment(char[], int, int), pushEvent(NamedEvent)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException

Process an event : lookup for a rule and apply it, or fire the event.

Specified by:

processingInstruction in interface ContentHandler

Overrides:

processingInstruction in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.processingInstruction(java.lang.String, java.lang.String), pushEvent(NamedEvent)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Bufferize adjacent character events.

Specified by:

characters in interface ContentHandler

Overrides:

characters in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.characters(char[], int, int)

startCDATA

public void startCDATA()
                throws SAXException

This event is ignored, as adjacent text nodes must be merged.

Specified by:

startCDATA in interface LexicalHandler

Overrides:

startCDATA in class SAXFilter

Throws:

SAXException

See Also:

SAXFilter.startCDATA()

endCDATA

public void endCDATA()
              throws SAXException

This event is ignored, as adjacent text nodes must be merged.

Specified by:

endCDATA in interface LexicalHandler

Overrides:

endCDATA in class SAXFilter

Throws:

SAXException

See Also:

SAXFilter.endCDATA()

startDTD

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

Fire or ignore this event according to the class of filters.

Specified by:

startDTD in interface LexicalHandler

Overrides:

startDTD in class SAXFilter

Throws:

SAXException

See Also:

FilterContextFactory.processDTD(), LexicalHandler.startDTD(java.lang.String, java.lang.String, java.lang.String)

endDTD

public void endDTD()
            throws SAXException

Fire or ignore this event according to the class of filters.

Specified by:

endDTD in interface LexicalHandler

Overrides:

endDTD in class SAXFilter

Throws:

SAXException

See Also:

FilterContextFactory.processDTD(), LexicalHandler.endDTD()

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException

Fire character events.

Specified by:

ignorableWhitespace in interface ContentHandler

Overrides:

ignorableWhitespace in class XMLFilterImpl

Throws:

SAXException

See Also:

characters(char[], int, int), XMLFilterImpl.ignorableWhitespace(char[], int, int)

endElement

public void endElement(String uri,
                       String localName,
                       String qName)
                throws SAXException

Process an event.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException

Process an event : lookup for a rule and apply it, or fire the event.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes), pushEvent(NamedEvent)

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Store a prefix mapping.

Specified by:

startPrefixMapping in interface ContentHandler

Overrides:

startPrefixMapping in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Remove a stored prefix mapping.

Specified by:

endPrefixMapping in interface ContentHandler

Overrides:

endPrefixMapping in class XMLFilterImpl

Throws:

SAXException

See Also:

XMLFilterImpl.endPrefixMapping(java.lang.String)

isSleeping

public boolean isSleeping()

Indicates whether the thread that owns this lockable is sleeping or not.

Specified by:

isSleeping in interface Lockable

Returns:

true if the thread is sleeping, false otherwise.

See Also:

Lockable.isSleeping()

suspendThread

public void suspendThread()
                   throws InterruptedException

Suspends this thread.

Specified by:

suspendThread in interface Lockable

Throws:

InterruptedException

See Also:

Lockable.suspendThread()

resumeThread

public void resumeThread()

Wake up the thread locked by this lockable.

Specified by:

resumeThread in interface Lockable

See Also:

Lockable.resumeThread()

toString

public String toString()

Return the rules of this filter, sorted in reverse priority order.

Overrides:

toString in class Object

Returns:

The list of rules.

See Also:

Object.toString()