org.xmlBlaster.engine.mime.xpath
Class XPathFilter

java.lang.Object
  org.xmlBlaster.engine.mime.xpath.XPathFilter

All Implemented Interfaces:

I_AccessFilter, I_Plugin

public class XPathFilter
extends java.lang.Object
implements I_Plugin, I_AccessFilter

Filter content on an XPath expression.

Filter on the content of an xml mime message.
The applicable mime types for this filter can be specified using the engine.mime.xpath.types parameter with semi-colon separated mime types e.g. engine.mime.xpath.types=text/xml;image/svg+xml;application/xml
The filter will cache the message dom tree it produces, keyd on message oid and message timestamp, and reuse it. For example if there is 1000 subscribers with an XPathFilter, it will not create 1000 DOM trees for each message, but one that will be reused in each match(). The backlog is 10 by default, and old entries will be discarded. This is settable with the paramater engine.mime.xpath.maxcachesize.

For example:

 MimeAccessPlugin[XPathFilter][1.0]=org.xmlBlaster.engine.mime.xpath.XPathFilter,engine.mime.xpath.maxcachesize=20.
 

Additional xpath functions can be loaded by setting the parameter engine.mime.xpath.extension_functions. For a description of the parameter syntax and implementation requirements, see loadXPathExtensionFunctions

Author:

Peter Antman, Jens Askengren, Robert Leftwich , Marcel Ruff

See Also:

The mime.plugin.access.xpath requirement

Nested Class Summary

(package private) class

XPathFilter.Entry An entry in the domCache.

Field Summary

static java.lang.String	DEFAULT_MAX_CACHE_SIZE
private javax.xml.parsers.DocumentBuilderFactory	docBuilderFactory
private java.util.LinkedList	domCache
private Global	glob
private static java.util.logging.Logger	log
static java.lang.String	MATCH_AGAINST_QOS
private boolean	matchAgainstQos
static java.lang.String	MAX_DOM_CACHE_SIZE
private int	maxCacheSize
private java.lang.String	ME
private java.lang.String[]	mimeTypes
private PluginInfo	pluginInfo
static java.lang.String	XPATH_EXTENSTION_FUNCTIONS
static java.lang.String	XPATH_MIME_TYPES
static java.lang.String	XSL_CONTENT_TRANSFORMER_FILE_NAME
private java.lang.String	xslContentTransformerFileName

Constructor Summary

XPathFilter()

Method Summary

private org.w3c.dom.Document	getDocument(byte[] xml) Create a new dom document.
private org.w3c.dom.Document	getDocument(MsgUnit msg) Get a dom document for message, from cache or create a new one.
private javax.xml.parsers.DocumentBuilderFactory	getDocumentBuilderFactory()
java.lang.String[]	getMimeExtended() Get the content MIME version number for which this plugin applies
java.lang.String[]	getMimeTypes() Get the content MIME type for which this plugin applies, currently "text/xml" and "image/svg+xml".
java.lang.String	getName() Get a human readable name of this filter implementation
java.lang.String	getType() Return plugin type for Plugin loader
java.lang.String	getVersion() Return plugin version for Plugin loader
private byte[]	getXml(MsgUnit msg) Access the XML string (from QoS or content).
void	init(Global glob, PluginInfo pluginInfo) This method is called by the PluginManager (enforced by I_Plugin).
void	initialize(ServerScope glob) This is called after instantiation of the plugin
protected void	loadXPathExtensionFunctions(java.lang.String extensionClassList) Load xpath extension functions from a semicolon separated list of classes.
static void	main(java.lang.String[] args) Command line helper to test your XPath syntax.
boolean	match(SessionInfo receiver, MsgUnit msgUnit, Query query) Check if the filter rule matches for this message.
void	shutdown() Cleans up the resource.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_DOM_CACHE_SIZE

public static final java.lang.String MAX_DOM_CACHE_SIZE

See Also:

Constant Field Values

DEFAULT_MAX_CACHE_SIZE

public static final java.lang.String DEFAULT_MAX_CACHE_SIZE

See Also:

Constant Field Values

MATCH_AGAINST_QOS

public static final java.lang.String MATCH_AGAINST_QOS

See Also:

Constant Field Values

XSL_CONTENT_TRANSFORMER_FILE_NAME

public static final java.lang.String XSL_CONTENT_TRANSFORMER_FILE_NAME

See Also:

Constant Field Values

XPATH_EXTENSTION_FUNCTIONS

public static final java.lang.String XPATH_EXTENSTION_FUNCTIONS

See Also:

Constant Field Values

XPATH_MIME_TYPES

public static final java.lang.String XPATH_MIME_TYPES

See Also:

Constant Field Values

ME

private final java.lang.String ME

See Also:

Constant Field Values

glob

private Global glob

log

private static java.util.logging.Logger log

maxCacheSize

private int maxCacheSize

domCache

private java.util.LinkedList domCache

mimeTypes

private java.lang.String[] mimeTypes

pluginInfo

private PluginInfo pluginInfo

matchAgainstQos

private boolean matchAgainstQos

xslContentTransformerFileName

private java.lang.String xslContentTransformerFileName

docBuilderFactory

private javax.xml.parsers.DocumentBuilderFactory docBuilderFactory

Constructor Detail

XPathFilter

public XPathFilter()

Method Detail

getDocumentBuilderFactory

private javax.xml.parsers.DocumentBuilderFactory getDocumentBuilderFactory()
                                                                    throws XmlBlasterException

Returns:

Throws:

XmlBlasterException

initialize

public void initialize(ServerScope glob)

This is called after instantiation of the plugin

Specified by:

initialize in interface I_AccessFilter

Parameters:

glob - The Global handle of this xmlBlaster server instance.

init

public void init(Global glob,
                 PluginInfo pluginInfo)
          throws XmlBlasterException

This method is called by the PluginManager (enforced by I_Plugin).

Specified by:

init in interface I_Plugin

Throws:

XmlBlasterException

See Also:

I_Plugin.init(org.xmlBlaster.util.Global,org.xmlBlaster.util.plugin.PluginInfo)

getType

public java.lang.String getType()

Return plugin type for Plugin loader

Specified by:

getType in interface I_Plugin

Returns:

"GnuRegexFilter"

getVersion

public java.lang.String getVersion()

Return plugin version for Plugin loader

Specified by:

getVersion in interface I_Plugin

Returns:

"1.0"

getName

public java.lang.String getName()

Get a human readable name of this filter implementation

Specified by:

getName in interface I_AccessFilter

Returns:

"GnuRegexFilter"

getMimeTypes

public java.lang.String[] getMimeTypes()

Get the content MIME type for which this plugin applies, currently "text/xml" and "image/svg+xml". Is configurable with engine.mime.xpath.types=text/xml;image/svg+xml;application/xml

Specified by:

getMimeTypes in interface I_AccessFilter

Returns:

"*" This plugin handles all mime types

getMimeExtended

public java.lang.String[] getMimeExtended()

Get the content MIME version number for which this plugin applies

Specified by:

getMimeExtended in interface I_AccessFilter

Returns:

"1.0" (this is the default version number)

match

public boolean match(SessionInfo receiver,
                     MsgUnit msgUnit,
                     Query query)
              throws XmlBlasterException

Check if the filter rule matches for this message.

The dom tree generated will be cached for each message, to be used for other queries against the same message.

Specified by:

match in interface I_AccessFilter

Parameters:

publisher - The subject object describing the publisher

receiver - The subject object describing the receiver

msgUnit - The message to check

query - The Query instance holding the xpath expression from your filter.

Returns:

true The filter xpath expression matches the message content.

Throws:

XmlBlasterException - Is thrown on problems, for example if the MIME type does not fit to message content.
Take care throwing an exception, as the exception is routed back to the publisher. Subscribers which where served before may receive the update, subscribers which are served after us won't get it. For the publisher it looks as if the publish failed completely. Probably it is best to return 'false' instead and log the situation. Further the current subscription is destroyed when exception is thrown.

shutdown

public void shutdown()

Description copied from interface: I_Plugin

Cleans up the resource.

Specified by:

shutdown in interface I_AccessFilter

Specified by:

shutdown in interface I_Plugin

loadXPathExtensionFunctions

protected void loadXPathExtensionFunctions(java.lang.String extensionClassList)
                                    throws XmlBlasterException

Load xpath extension functions from a semicolon separated list of classes.

List syntax:

  function := prefix ":" function-name ":" class-name
  extensionClassList := ( function (";" function)* )?
 

The prefix may be the empty string. The class must implement the org.jaxen.Function interface.

Example string: engine.mime.xpath.extension_functions=:recursive-text:org.xmlBlaster.engine.mime.xpath.RecursiveTextFunction

Parameters:

extensionClassList - semicolon separated list of function definitions

Throws:

XmlBlasterException - if the syntax is incorrect, or the class could not be loaded

getDocument

private org.w3c.dom.Document getDocument(MsgUnit msg)
                                  throws XmlBlasterException

Get a dom document for message, from cache or create a new one.

Throws:

XmlBlasterException

getXml

private byte[] getXml(MsgUnit msg)

Access the XML string (from QoS or content).

Parameters:

msg -

Returns:

Is never null

getDocument

private org.w3c.dom.Document getDocument(byte[] xml)
                                  throws XmlBlasterException

Create a new dom document.

Throws:

XmlBlasterException

main

public static void main(java.lang.String[] args)

Command line helper to test your XPath syntax.

Please pass on command line the XML of the message content, you then can interactively test your XPath query. Type 'q' to quit.

export CLASSPATH=$CLASSPATH:$XMLBLASTER_HOME/lib/jaxen.jar
java org.xmlBlaster.engine.mime.xpath.XPathFilter -inFile [someFile.xml]
java org.xmlBlaster.engine.mime.xpath.XPathFilter -inFile [someFile.xml] -xslContentTransformerFileName [someFile.xsl]
Example:
cd xmlBlaster/testsuite/data/xml
java org.xmlBlaster.engine.mime.xpath.XPathFilter -inFile Airport.xml -xslContentTransformerFileName transformToKeyValue.xsl

todo: Using http://jline.sourceforge.net/ for nicer command line input handling
Example: java -cp /opt/download/jline-demo.jar:/opt/download/jline-0_9_5-demo.jar jline.example.Example simple

Parameters:

args - -inFile [fileName.xml] OR -xml [the xml string]