org.pf.text
Class DefaultMatchRuleParser

java.lang.Object
  org.pf.text.BaseMatchRuleParser
      org.pf.text.DefaultMatchRuleParser

public class DefaultMatchRuleParser
extends BaseMatchRuleParser

This parser translates the match-rule syntax to a MatchRule object.

It is recommended to use the static create() methods rather than the constructors to get a new parser instance.

Example 1

Here is a sample rule:

firstName=John & lastName=M*

It means that attribute ‘firstName‘ must have the value "John" and that the attribute ‘lastName‘ must match "M*", that is all values starting with a capital ‘M‘ will evaluate to true.

A slightly different syntax for the above rule is:

firstName{John} & lastName{M*}

Using the following dictionary will evaluate the rules from above to false:

 Map map = new HashMap() ;
 map.put( "firstName", "Conner" ) ;
 map.put( "lastName", "McLeod" ) ;
 MatchRule mr = DefaultMatchRuleParser.parseRule( "firstName{John} & lastName{M*}" ) ;
 boolean found = mr.matches(map) ; // returns false
 

The next dictionary will evaluate the rule to true:

 Map map = new HashMap() ;
 map.put( "firstName", "John" ) ;
 map.put( "lastName", "Miles" ) ;
 MatchRule mr = DefaultMatchRuleParser.parseRule( "firstName{John} & lastName{M*}" ) ;
 boolean found = mr.matches(map) ; // returns true
 

The parser generally supports the following comparisons in rules:

Comparison	Description	Example(s)
equals	Compares if the value of the attribute is equal to the specified value	name=Roger
equals any	Compares if the value of the attribute is equal to any of a list of specified values	name{Fred,Peter,John,Mike}
matches	Compares if the value of the attribute matches the specified pattern	name=J*y
matches any	Compares if the value of the attribute matches any of a list of specified values	name{Fred,A*,B?n,R*so?,Carl}
less	Compares if the value of the attribute is less than the specified value	name<Henderson age<20
greater	Compares if the value of the attribute is greater than the specified value	name>Franklin age>15
less or equal	Compares if the value of the attribute is less or equal to the specified value	name<=Anderson age<=50
greater or equal	Compares if the value of the attribute is greater or equal to the specified value	name>=Franklin age>=3

There are some characters with special purpose in a rule. The table below describes each of them and lists the method that can be used to change the character.

char	Description	Method to change in MatchRuleChars
&	AND operator	setAndChar()
|	OR operator	setOrChar( )
!	NOT operator	setNotChar()
{	Starts a list of values	setValueStartChar()
,	Separator of values in a value list	setValueSeparatorChar()
}	Ends a list of values	setValueEndChar()
(	Starts a group of attribute rules	setGroupStartChar()
)	Ends a group of attribute rules	setGroupEndChar()
=	Compares equality of the attribute's value	setEqualsChar()
<	Compares the attribute's value to be less than the specified value	setLessChar()
>	Compares the attribute's value to be greater zhan the specified value	setGreaterChar()
?	Wildcard for a single character in a value	---
*	Wildcard for any count of characters in a value	---

Any rule must comply to the following restrictions:

• A rule must not contain any carriage-return or line-feed characters!
• The NOT operator is only allowed after an AND or an OR operator!
• There might be any amount of spaces in front or after operators
• There might be any amount of spaces in front or after group parenthesis
• Attribute names must only consist of characters ( A-Z, a-z ) and/or digits ( 0-9 ) and any additional characters that are specified in MatchRuleChars.setSpecialNameCharacters()
• Between an attribute name and the value list starting bracket might be any amount of whitespace characters.
• Between an attribute name and a compare operator might be any amount of whitespace characters.
• Any character inside a value list is treated as part of a value except the VALUE SEPARATOR, the VALUE LIST END CHARACTER and the two WILDCARD characters.

Example 2:

A more complex rule could look like this:

( city{P*,Ch*} & ! city{Paris,Pretoria} ) | ( language{en,de,fr,it,es} & currency{??D} )

The dictonary below will evaluate to true if checked against the above rule:

 DefaultMatchRuleParser parser = new DefaultMatchRuleParser() ;
 MatchRule rule = parser.parse("( city{P*,Ch*} & ! city{Paris,Pretoria} ) | " +
  ( language{en,de,fr,it,es} & currency{??D} )" ) ;
 Map map = new HashMap() ; 
 map.put( "city", "Pittsburg" ) ;
 map.put( "language", "en" ) ;
 map.put( "currency", "USD" ) ;
 boolean ok = rule.matches( map ) ;
 

Whereas the following values produce a false:

 MatchRuleChars chars = new  MatchRuleChars() ;
 chars.setValueSeparatorChar( ';' ) ;
 DefaultMatchRuleParser parser = new DefaultMatchRuleParser(chars) ;
 MatchRule rule = parser.parse( "( city{P*;Ch*} & ! city{Paris;Pretoria} ) | " +
   ( language{en;de;fr;it;es} & currency{??D} )" ) ;
 Map map = new HashMap() ;
 map.put( "city", "Pretoria" ) ;
 map.put( "language", "de" ) ;
 map.put( "currency", "USD" ) ;
 boolean ok = rule.matches( map ) ;
 

Version:

1.4

Author:

Manfred Duchrow

Constructor Summary

DefaultMatchRuleParser()
Initialize the new instance with default values.

DefaultMatchRuleParser(MatchRuleChars ruleCharacters)
Initialize the new instance with a set of rule characters.

Method Summary

static DefaultMatchRuleParser	create() Returns a new parser that generates rules which treat the multi-char wildcard (i.e. '*') in a way that it matches empty strings.
static DefaultMatchRuleParser	create(MatchRuleChars chars) Returns a new parser that generates rules which treat the multi-char wildcard (i.e. '*') in a way that it matches empty strings.
char	getAndChar() Returns the character for AND operations ( DEFAULT = '&' )
char	getEqualsChar() Returns the character for equals comparisons ( DEFAULT = '=' )
char	getGreaterChar() Returns the character for greater than comparisons ( DEFAULT = '>' )
char	getGroupEndChar() Returns the character that ends a logical group ( DEFAULT = ')' )
char	getGroupStartChar() Returns the character that starts a logical group ( DEFAULT = '(' )
boolean	getIgnoreCaseInNames() Returns true, if the parser produces MatchRules that treat attribute names case-insensitive.
boolean	getIgnoreCaseInValues() Returns true, if the parser produces MatchRules that are case-insensitive when comparing values.
char	getLessChar() Returns the character for less than comparisons ( DEFAULT = '<' )
boolean	getMultiCharWildcardMatchesEmptyString() Returns true, if this parser creates match rules that allow empty strings at the position of the multi character wildcard ('*').
char	getNotChar() Returns the character for NOT operations ( DEFAULT = '!'
char	getOrChar() Returns the character for OR operations ( DEFAULT = '|' )
char	getValueDelimiterChar() Returns the character that is used to enclose a value ( DEFAULT = '\'' )
char	getValueEndChar() Returns the character ends a list of values ( DEFAULT = '}' )
char	getValueSeparatorChar() Returns the character for separation of values ( DEFAULT = ',' )
char	getValueStartChar() Returns the character that starts a list of values ( DEFAULT = '{' )
MatchRule	parse(java.lang.String rule) Parse the given rule string to a MatchRule object that can be used to check attributes in a Map, if they match the rule.
static MatchRule	parseRule(java.lang.String rule) Parse the given rule string to a MatchRule object that can be used to check attributes in a Map, if they match the rule.
MatchRule	parseTypedRule(java.lang.String rule, java.util.Map datatypes) Parse the given rule string to a MatchRule and apply the given datatypes to it.
void	setAndChar(char newValue) Sets the character for AND operations
void	setEqualsChar(char newValue) Sets the character that is used to compare if two values are equal
void	setGreaterChar(char newValue) Sets the character that is used to compare if a value is greater than another
void	setGroupEndChar(char newValue) Sets the character that ends a group
void	setGroupStartChar(char newValue) Sets the character that starts a group
void	setIgnoreCaseInNames(boolean newValue) Sets whether or not the parser produces MatchRules that treat attribute names case-insensitive.
void	setIgnoreCaseInValues(boolean newValue) Sets whether or not the parser produces MatchRules that are case-insensitive when comparing values.
void	setLessChar(char newValue) Sets the character that is used to compare if a value is less than another
void	setMultiCharWildcardMatchesEmptyString(boolean newValue) Sets whether or not this parser creates match rules that allow empty strings at the position of the multi character wildcard ('*').
void	setNotChar(char newValue) Sets the character for NOT operations
void	setOrChar(char newValue) Sets the character for OR operations
void	setValueEndChar(char newValue) Sets the character that ends a value list
void	setValueSeparatorChar(char newValue) Sets the character that separates values in a value list
void	setValueStartChar(char newValue) Sets the character that starts a value list

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultMatchRuleParser

public DefaultMatchRuleParser()

Initialize the new instance with default values.

DefaultMatchRuleParser

public DefaultMatchRuleParser(MatchRuleChars ruleCharacters)

Initialize the new instance with a set of rule characters.

Method Detail

getIgnoreCaseInNames

public boolean getIgnoreCaseInNames()

Returns true, if the parser produces MatchRules that treat attribute names case-insensitive.

setIgnoreCaseInNames

public void setIgnoreCaseInNames(boolean newValue)

Sets whether or not the parser produces MatchRules that treat attribute names case-insensitive.

getIgnoreCaseInValues

public boolean getIgnoreCaseInValues()

Returns true, if the parser produces MatchRules that are case-insensitive when comparing values.

setIgnoreCaseInValues

public void setIgnoreCaseInValues(boolean newValue)

Sets whether or not the parser produces MatchRules that are case-insensitive when comparing values.

getMultiCharWildcardMatchesEmptyString

public boolean getMultiCharWildcardMatchesEmptyString()

Returns true, if this parser creates match rules that allow empty strings at the position of the multi character wildcard ('*').

The default value is false.

setMultiCharWildcardMatchesEmptyString

public void setMultiCharWildcardMatchesEmptyString(boolean newValue)

Sets whether or not this parser creates match rules that allow empty strings at the position of the multi character wildcard ('*').

The default value is false.

parseRule

public static MatchRule parseRule(java.lang.String rule)
                           throws MatchRuleParseException

Parse the given rule string to a MatchRule object that can be used to check attributes in a Map, if they match the rule. This method creates a new parser for each call by invocation of a constructor.

Parameters:

rule - The rule in a string compliant to the MatchRule syntax

Throws:

MatchRuleParseException - Each syntax error in the given rule causes this exception with a short description of what is wrong

create

public static DefaultMatchRuleParser create()

Returns a new parser that generates rules which treat the multi-char wildcard (i.e. '*') in a way that it matches empty strings.
Using the constructor is different. In that case a multi-char wildcard won't match an empty string!

create

public static DefaultMatchRuleParser create(MatchRuleChars chars)

Returns a new parser that generates rules which treat the multi-char wildcard (i.e. '*') in a way that it matches empty strings.
Using the constructor is different. In that case a multi-char wildcard won't match an empty string!

Parameters:

chars - The charscter set that is used for the rules operators etc.

parse

public MatchRule parse(java.lang.String rule)
                throws MatchRuleParseException

Parse the given rule string to a MatchRule object that can be used to check attributes in a Map, if they match the rule.

Parameters:

rule - The rule in a string compliant to the MatchRule syntax

Throws:

MatchRuleParseException - Each syntax error in the given rule causes this exception with a short description of what is wrong

parseTypedRule

public MatchRule parseTypedRule(java.lang.String rule,
                                java.util.Map datatypes)
                         throws MatchRuleException

Parse the given rule string to a MatchRule and apply the given datatypes to it. Such a rule will do attribute comparisons according to the corresponding datatype.

Parameters:

rule - The rule in a string compliant to the MatchRule syntax

datatypes - The attributes and their associated datatypes

Throws:

MatchRuleParseException - Each syntax error in the given rule causes this exception with a short description of what is wrong

MatchRuleException

See Also:

MatchRule.setDatatypes(Map)

getAndChar

public char getAndChar()

Returns the character for AND operations ( DEFAULT = '&' )

setAndChar

public void setAndChar(char newValue)

Sets the character for AND operations

getOrChar

public char getOrChar()

Returns the character for OR operations ( DEFAULT = '|' )

setOrChar

public void setOrChar(char newValue)

Sets the character for OR operations

getNotChar

public char getNotChar()

Returns the character for NOT operations ( DEFAULT = '!' )

setNotChar

public void setNotChar(char newValue)

Sets the character for NOT operations

getValueSeparatorChar

public char getValueSeparatorChar()

Returns the character for separation of values ( DEFAULT = ',' )

setValueSeparatorChar

public void setValueSeparatorChar(char newValue)

Sets the character that separates values in a value list

getValueDelimiterChar

public char getValueDelimiterChar()

Returns the character that is used to enclose a value ( DEFAULT = '\'' )

getValueStartChar

public char getValueStartChar()

Returns the character that starts a list of values ( DEFAULT = '{' )

setValueStartChar

public void setValueStartChar(char newValue)

Sets the character that starts a value list

getValueEndChar

public char getValueEndChar()

Returns the character ends a list of values ( DEFAULT = '}' )

setValueEndChar

public void setValueEndChar(char newValue)

Sets the character that ends a value list

getGroupStartChar

public char getGroupStartChar()

Returns the character that starts a logical group ( DEFAULT = '(' )

setGroupStartChar

public void setGroupStartChar(char newValue)

Sets the character that starts a group

getGroupEndChar

public char getGroupEndChar()

Returns the character that ends a logical group ( DEFAULT = ')' )

setGroupEndChar

public void setGroupEndChar(char newValue)

Sets the character that ends a group

getGreaterChar

public char getGreaterChar()

Returns the character for greater than comparisons ( DEFAULT = '>' )

setGreaterChar

public void setGreaterChar(char newValue)

Sets the character that is used to compare if a value is greater than another

getLessChar

public char getLessChar()

Returns the character for less than comparisons ( DEFAULT = '<' )

setLessChar

public void setLessChar(char newValue)

Sets the character that is used to compare if a value is less than another

getEqualsChar

public char getEqualsChar()

Returns the character for equals comparisons ( DEFAULT = '=' )

setEqualsChar

public void setEqualsChar(char newValue)

Sets the character that is used to compare if two values are equal