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

java.lang.Object
  extended by org.xml.sax.helpers.XMLFilterImpl
      extended by org.inria.ns.reflex.xml.sax.SAXFilter
          extended by 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()