XmlBlaster Logo

REQUIREMENT

mime.plugin.access.sql92

XmlBlaster Logo


Type NEW
Priority MEDIUM
Status CLOSED
Topic XmlBlaster allows to access messages filtered with statements conform to the search conditions of defined in sql92.
Des
cription

XmlBlaster allows you to query messages based on their meta information with a syntax conform to the search conditions defined by sql92. This syntax is the same as the one adopted by the JMS specification (ver. 1.1).

This plugin does a search on the client properties of the qos used to publish a given message. Note that the content of the message is not checked, please use the mime.plugin.access.xpath or mime.plugin.access.regex plugins for such full text filter tasks.

A typical use case would be the same as you have for a message selector in jms. Suppose for example you have designed a solution to manage a taxi center in a town. The taxis are motorcycles, small cars, big cars, mini-vans and limousines. The town is divided into several geographical areas. Every GUI is associated with one of these areas. You would choose an approach where each of the taxis is a topic (a given oid). Additionally you would give the topic's keys a structure similar to the following: 

<taxi type='motorcycle|small car|big car|mini-van|limousine'/>
.
Every unit would publish a message with a key 
<key oid='ti4747'><taxi type='limousine' /></key>
(in this case a limo) and in the qos it would add a client property xPos=100 and yPos=120. Let's say your GUI is interested in all limos in a limited area. Then it would subscribe with XPATH to 
//taxi[@type='limousine']
and with the query for the Sql92Filter to be 
xPos BETWEEN 0 AND 100 AND yPos BETWEEN 20 AND 130
.

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 message types. If now real messages arrive, the filter plugin is additionally filtering messages away. The same applies for get() invocations.

Query Syntax (based on the jms specification). It is practically the same as the jms specification with an additional REGEX keyword (see below) and a well defined behaviour for cases where the identifier is null (in jms the behaviour is undefined when an expression contains a null identifier (i.e. if the client property on which a query is made does not exist).

Literals:
  • A string literal is enclosed in single quotes with an included single quote represented by doubled single quote such as 'literal' and 'literal''s'; like Java String literals these use the unicode character encoding.
  • An exact numeric literal is a numeric value without a decimal point such as 57, -957, +62; numbers in the range of Java long are supported. Exact numeric literals use the Java integer literal syntax.
  • An approximate numeric literal is a numeric value in scientific notation such as 7E3, -57.9E2 or a numeric value with a decimal such as 7., -95.7, +6.2; numbers in the range of Java double are supported. Approximate literals use the Java floating point literal syntax.
  • The boolean literals TRUE and FALSE.
Identifiers:
  • Identifiers use the Java identifier syntax. They are case sensitive.
  • Identifiers cannot be the names NULL, TRUE, or FALSE.
  • Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, and IS.

Expressions:
  • A selector is a conditional expression; a selector that evaluates to true matches; a selector that evaluates to false or unknown does not match.
  • Arithmetic expressions are composed of themselves, arithmetic operations, identifiers with numeric values and numeric literals.
  • Conditional expressions are composed of themselves, comparison operations, logical operations, identifiers with boolean values and boolean literals.
  • Standard bracketing () for ordering expression evaluation is supported.
  • Logical operators in precedence order: NOT, AND, OR.
  • Comparison operators: =, >, >=, <, <=, <> (not equal). (for not equal we support also != and ^= which is not defined in jms)
    • Only like type values can be compared. One exception is that it is valid to compare exact numeric values and approximate numeric values (the type conversion required is defined by the rules of Java numeric promotion). If the comparison of non-like type values is attempted, the selector is always false.
    • In jms String and Boolean comparison is restricted to = and <>. Two strings are equal if and only if they contain the same sequence of characters. Here xmlBlaster has an own extention. Also comparisons between String is allowed. (For example 'London' < 'Paris': alphabetical comparison).
  • Arithmetic operators in precedence order:
    • +, - unary
    • *, / multiplication and division
    • +, - addition and subtraction
    • Arithmetic operations use Java numeric promotion.
    • For arithmetic operations a NULL term is considered 0 (zero).(own xmlBlaster non jms specification)
  • arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3 comparison operator
    • age BETWEEN 15 and 19 is equivalent to age >= 15 AND age <= 19
    • age NOT BETWEEN 15 and 19 is equivalent to age < 15 OR age > 19
  • identifier [NOT] IN (string-literal1, string-literal2,...)
    comparison operator where identifier has a String or NULL value.
    • Country IN ('UK', 'US', 'France') is true for 'UK' and false for 'Peru'. It is equivalent to the expression (Country = ' UK') OR (Country = ' US') OR (Country = ' France')
    • Country NOT IN (' UK', 'US', 'France') is false for 'UK' and true for 'Peru'. It is equivalent to the expression NOT ((Country = 'UK') OR (Country = 'US') OR (Country = 'France'))
    • If identifier of an IN or NOT IN operation is NULL the value of the operation is always false.
  • identifier [NOT] LIKE pattern-value [ESCAPEescape-character]
    comparison operator, where identifier has a String value; pattern-value is a string literal where '_' stands for any single character; '%' stands for any sequence of characters (including the empty sequence); and all other characters stand for themselves. The optional escape-character is a single character string literal whose character is used to escape the special meaning of the '_' and '%' in pattern-value.
    • phone LIKE '12%3' is true for '123', '12993' and false for '1234'
    • word LIKE 'l_se' is true for 'lose' and false for 'loose'
    • underscored LIKE '\_%' ESCAPE '\' is true for '_foo' and false for 'bar'
    • phone NOT LIKE '12%3' is false for '123' and '12993' and true for '1234'
    • If identifier of a LIKE or NOT LIKE operation is NULL the value of the operation is false.
  • Regex expressions,
    where identifier has a String.Note that this is an xmlBlaster specific extention not specified by jms.
    • phone REGEX '12.*3' is true for '123', '12993' and false for '1234'
    • word REGEX 'l.se' is true for 'lose' and false for 'loose'
  • identifier IS NULL
    comparison operator tests for a null header field value, or a missing property value.
    • prop_name IS NULL
    • identifier IS NOT NULL comparison operator tests for the existence of a non null header field value or property value.
    • prop_name IS NOT NULL

Example
XML 
      
<!-- cut and paste this text and save it in a file called     
 sql92.xml and then invoke in the same directory          
 java javaclients.script.XmlScript -requestFile sql92.xml 
 -->
<xmlBlaster>


  <connect/>

  <subscribe>
    <key queryType='XPATH'>//taxi[@type='limousine']</key>
    <qos>
       <filter type='Sql92Filter'>
         xPos BETWEEN 0 AND 100 AND yPos BETWEEN 20 AND 130
       </filter>
     </qos>
  </subscribe>
  
  <!-- you should become this one -->
  <publish>
    <key oid='ti4747'><taxi type='limousine'/></key>
    <content>just some content</content>
    <qos>
       <clientProperty type='Integer' name='xPos'>100</clientProperty>
       <clientProperty type='Integer' name='yPos'>120</clientProperty>
    </qos>
  </publish>

  <!-- this one should be rejected by the mime plugin -->
  <publish>
    <key oid='ti4747'><taxi type='limousine'/></key>
    <content>just some content</content>
    <qos>
       <clientProperty type='Integer' name='xPos'>110</clientProperty>
       <clientProperty type='Integer' name='yPos'>120</clientProperty>
    </qos>
  </publish>

  <unsubscribe><key queryType='XPATH'>//taxi[@type='limousine']</key></unsubscribe>
  <erase><key oid='ti4747'></erase>

  <disconnect />

</xmlBlaster>
Example
CPP

Here an example with the C++ command line clients: 

java org.xmlBlaster.Main

PublishDemo -clientProperty.key phone -clientProperty.value 1200003

SubscribeDemo -filter.type Sql92Filter -filter.query "phone LIKE '12%3'"

If you change the publisher -clientProperty.value to for example '1000003' the subscriber won't receive the message.

Configure

These parameters allow to configure the regex plugin.

Property Default Description Impl
MimeAccessPlugin[Sql92Filter][1.0] org.xmlBlaster.engine.mime.sql92.Sql92Filter Loads the sql92 plugin on demand. yes
cacheQuery false if set to true: The query statement is parsed the first time and then the prepared query is reused on further queries. This improves performance. Note that it is not clear if it is 100% supported by our cups implementation our test show however that it works fine. yes

Example entry in xmlBlaster.properties: 

MimeAccessPlugin[Sql92Filter][1.0]=org.xmlBlaster.engine.mime.sql92.Sql92Filter,cacheQuery=false

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 http://www.cacas.org/java/gnu/regexp/
See http://developer.java.sun.com/developer/technicalArticles/releases/1.4regex/
See API org.xmlBlaster.engine.mime.sql92.Sql92Filter
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 TEST org.xmlBlaster.test.mime.TestGetSql92Filter
See TEST org.xmlBlaster.test.classtest.Sql92SelectorTest

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

Back to overview