XmlBlaster Logo

REQUIREMENT

mime.plugin.access.xpath

XmlBlaster Logo


Type NEW
Priority MEDIUM
Status CLOSED
Topic XmlBlaster allows to access message instances filtered with XPath expressions
Des
cription

XmlBlaster allows you to query topics based on their meta information with XPath. Sometimes this is not enough and you want to do sort of a full text search over the message content, also with XPath, thereby supplying full XML/XPath content based routing of messages.

For this frequent use case we deliver a plugin using XPath expressions to check the message content, optionally, by setting the property matchAgainstQos=true you can match against the QoS of the published message instead of the content.

The plugin is registered for the text/xml mime type.

This filter is available for synchronous access with get() and asynchronous access with subscribe() and as a filter for xmlBlaster cluster support.
You can specify the filter rules with two xmlBlaster methods:

  1. Synchronous access with the get() invocation:
    Specify the filter rule in the QoS of the get() method to filter the desired messages. The messages are returned as the get() return value.
  2. Asynchronous access with the subscribe() invocation
    Specify the filter rule in the QoS of the subscribe() method to filter the desired messages. The messages are returned with the asynchronous update() callback.

Multiple filters can be specified in one subscribe/get invocation. Each of them may address another plugin. They are sequentially executed and if one filter denies access (the match() method returns 'false') the message is not delivered. The filters are logically AND connected.

The cascading approach for XPath/exact query and filters:
On subscribe first the usual XPATH or exact subscription is checked. The client is added as subscriber to all matching topics. If now message instances arrive, the filter plugin is additionally filtering messages away. The same applies for get() invocations. With the XPath filter is therefore possible to emulate a JMS like topic destination: send messages with the same OID. Subscribe with an exact query on the messages, and filter with the XPathFilter on the content or QoS.

The XPathFilter is currently based on the Jaxen xpath engine. It is also possible to register Jaxen extension functions by specifying them in the property engine.mime.xpath.extension_functions. The functions must implement the org.jaxen.Function interface.

Example
any

Example key and QoS of a get() or subscribe() invocation:

      
      <key oid="News/>

      <qos>
         <filter type='XPathFilter'>
            /news[@type='sport']
         </filter>
      </qos>

All messages of the topic oid=News are first selected. Those message are further filtered to contain the attribute type equals sport in the news element.

Don't forget to put your query in a <![CDATA[ ... ]]> section if you use "<" in your query string.

Example
Java

Code snippet in Java with the get() method

      
   import org.xmlBlaster.client.qos.GetQos;
   import org.xmlBlaster.util.MsgUnit;
   import org.xmlBlaster.util.qos.AccessFilterQos;

   GetQos qos = new GetQos(glob);

   qos.addAccessFilter(
       new AccessFilterQos(glob, "XPathFilter",
                           "1.0", "/news[@type='sport']"));

   MsgUnit[] msgUnits = con.get(
            "<key oid='News'/>",
            qos.toXml());

The code snippet new AccessFilterQos(...) adds the above raw <filter> xml ASCII string, so we don't need to do it our self. The second and third parameters "XPathFilter", "1.0" choose the plugin (in this case the XPath plugin) and the fourth parameter add the query rule for the plugin (in this case an XPath expression).

Example
Java

Command line example: Testing your XPath syntax

This example allows you to test your XPath queries on command line, first set the CLASSPATH to contain the JAXEN libraries

export CLASSPATH=$CLASSPATH:$XMLBLASTER_HOME/lib/jaxen.jar

now create a file test.xml with following content

<qos>
   <clientProperty name='corrId' type='int'>120001</clientProperty>

   <clientProperty name='SayHello'>Hello World</clientProperty>

   <clientProperty name='aKey'>aValue</clientProperty>

   <clientProperty name='MyXmlString' type='String' encoding='base64'>
      QmxhPEJsYUJsYQ==
   </clientProperty>
</qos>

and then start the command line test

java org.xmlBlaster.engine.mime.xpath.XPathFilter -inFile test.xml 
xpath> /qos/clientProperty/@name='corrId'
Match: true

xpath> /qos/clientProperty/@name='corYX'
Match: false

You can now play further with the XPath query as shown above.
Example
Java

Command line example: Test the plugin with xmlBlaster

Assure that the plugin is registered in xmlBlaster.properties

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

Start the server

java -jar lib/xmlBlaster.jar

Start a subscriber

java -cp lib/xmlBlaster.jar javaclients.HelloWorldSubscribe -oid Hello -filter.type XPathFilter -filter.query "//tomato"

Start a publisher with matching content

java -cp lib/xmlBlaster.jar javaclients.HelloWorldPublish -numPublish 10 -oid Hello -content "<tomato/>"

Start a publisher with NO matching content

java -cp lib/xmlBlaster.jar javaclients.HelloWorldPublish -numPublish 10 -oid Hello -content "<apple/>"

Now you can play with the full text filtering feature
Configure

If you make a xmlBlaster distribution you must make shure to copy 

   xmlBlaster/lib/jaxen.jar

and add the jar files to the CLASSPATH.

These parameters allow to configure the XPath plugin.

Property Default Description Impl
MimeAccessPlugin[XPathFilter][1.0] org.xmlBlaster.engine.mime.xpath.XPathFilter Loads the xpath plugin on demand. yes
engine.mime.xpath.types text/xml;image/svg+xml List of mime type which will trigger this plugin. yes
engine.mime.xpath.maxcachesize 10 Max cache of loaded DOM trees for messages. yes
engine.mime.xpath.extension_functions :contains-ignore-case: org.xmlBlaster.engine.mime.xpath.ContainsIgnoreCaseFunction;: recursive-text: org.xmlBlaster.engine.mime.xpath.RecursiveTextFunction A semicolon separated list of function definitions. yes
matchAgainstQos false In the default setting the XPath runs against the message content. If you set this property to 'true' the XPath runs against the publish QoS of the message. yes
xslContentTransformerFileName /tmp/myTransform.xsl
http://www.xmlblaster.org/transformTest.xsl
ftp://somewhere/xy.xsl 		As default there is no XSL file specified. If you name an XSL file it will be looked up in the CLASSPATH and all other locations where xmlBlaster looks for configuration files. If, and only if, the filter match was successful the message content will be transformed with the given XSLT transformation. yes

Example for xmlBlaster.properties:

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

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See API org.xmlBlaster.engine.mime.xpath.XPathFilter
See API org.xmlBlaster.engine.mime.xpath.ContainsIgnoreCaseFunction
See API org.xmlBlaster.engine.mime.xpath.RecursiveTextFunction
See API org.xmlBlaster.util.qos.AccessFilterQos
See API org.xmlBlaster.engine.mime.I_AccessFilter
See API org.xmlBlaster.util.plugin.I_Plugin
See REQ mime.plugin.accessfilter.howto
See REQ mime.plugin.accessfilter
See REQ cluster
See JAXEN homepage
See TEST org.xmlBlaster.test.mime.TestXPathSubscribeFilter
See TEST org.xmlBlaster.test.mime.TestXPathTransformer

This page is generated from the requirement XML file xmlBlaster/doc/requirements/mime.plugin.access.xpath.xml

Back to overview