DefaultMatchRuleParser (PF-All 7.4.0 API)

java.lang.Object
- org.pfsw.text.BaseMatchRuleParser
- - org.pfsw.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,Rso?,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 ) ;

Constructor Summary

Constructors
Constructor and Description
`DefaultMatchRuleParser()` Initialize the new instance with default values.
`DefaultMatchRuleParser(MatchRuleChars ruleCharacters)` Initialize the new instance with a set of rule characters.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static DefaultMatchRuleParser`	`create()` Returns a new parser that generates rules which treat the multi-char wildcard (i.e.
`static DefaultMatchRuleParser`	`create(MatchRuleChars chars)` Returns a new parser that generates rules which treat the multi-char wildcard (i.e.
`protected MatchRule`	`createMatchRuleOn(MatchGroup group)`
`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 = '\|' )
`protected MatchRuleChars`	`getRuleChars()`
`protected java.lang.String`	`getSpecialNameCharacters()` Returns the special character allowed in attribute names
`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 = '{' )
`protected boolean`	`isGroupEnd(char ch)`
`protected boolean`	`isOperator(char ch)`
`protected boolean`	`isPartOfValue(char ch)` Returns true if the given character can be part of a value.
`protected boolean`	`isValidCompareOperator(char ch)`
`protected boolean`	`isValidNameCharacter(char ch)`
`protected boolean`	`nextIsGroupElement()`
`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.
`protected MatchAttribute`	`parseAttribute()`
`protected MatchGroup`	`parseGroup()`
`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.
`protected MatchGroup`	`parseToGroup(java.lang.String rule)` Parse the given rule string to a MatchGroup which can be used to create a MatchRule.
`MatchRule`	`parseTypedRule(java.lang.String rule, java.util.Map<java.lang.String,java.lang.Class<?>> datatypes)` Parse the given rule string to a MatchRule and apply the given datatypes to it.
`protected void`	`readAttributeName(MatchAttribute attribute)`
`protected char`	`readCompareOperator(MatchAttribute attribute)`
`protected java.lang.String`	`readDelimitedMatchValue()`
`protected MatchElement`	`readElement()`
`protected void`	`readElements(MatchGroup group)`
`protected StringPattern`	`readMatchValue()`
`protected void`	`readMatchValue(MatchAttribute attribute)`
`protected void`	`readMatchValues(MatchAttribute attribute)`
`protected void`	`readOperators(MatchElement element)` Return two operator flags depending on the next characters in the scanner.
`protected java.lang.String`	`readUndelimitedMatchValue(char character)`
`protected java.lang.String`	`readUpTo(char exitChar)`
`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
`protected void`	`setRuleChars(MatchRuleChars newValue)`
`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 org.pfsw.text.BaseMatchRuleParser
atEnd, checkExpectedEnd, checkUnexpectedEnd, scanner, scanner, str, throwException

Methods inherited from class java.lang.Object
clone, equals, finalize, 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
  - 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.
  - 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.
  - 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<java.lang.String,java.lang.Class<?>> 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
  - parseToGroup
```
protected MatchGroup parseToGroup(java.lang.String rule)
                           throws MatchRuleParseException
```
    Parse the given rule string to a MatchGroup which can be used to create a MatchRule.
    
    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
  - parseGroup
```
protected MatchGroup parseGroup()
                         throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readElements
```
protected void readElements(MatchGroup group)
                     throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readElement
```
protected MatchElement readElement()
                            throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - nextIsGroupElement
```
protected boolean nextIsGroupElement()
```
  - parseAttribute
```
protected MatchAttribute parseAttribute()
                                 throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readAttributeName
```
protected void readAttributeName(MatchAttribute attribute)
                          throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - isValidCompareOperator
```
protected boolean isValidCompareOperator(char ch)
```
  - readCompareOperator
```
protected char readCompareOperator(MatchAttribute attribute)
                            throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readMatchValues
```
protected void readMatchValues(MatchAttribute attribute)
                        throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readMatchValue
```
protected void readMatchValue(MatchAttribute attribute)
                       throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readMatchValue
```
protected StringPattern readMatchValue()
                                throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readDelimitedMatchValue
```
protected java.lang.String readDelimitedMatchValue()
                                            throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - readUndelimitedMatchValue
```
protected java.lang.String readUndelimitedMatchValue(char character)
```
  - isPartOfValue
```
protected boolean isPartOfValue(char ch)
```
    Returns true if the given character can be part of a value. Returns false if the character is a special character that terminates a value.
  - readOperators
```
protected void readOperators(MatchElement element)
```
    Return two operator flags depending on the next characters in the scanner. The first value defines if the operator is an AND (true) or an OR (false). The second value defines if NOT is set (true) or not (false).
  - readUpTo
```
protected java.lang.String readUpTo(char exitChar)
                             throws MatchRuleParseException
```
    Throws:
    
    MatchRuleParseException
  - isOperator
```
protected boolean isOperator(char ch)
```
  - isValidNameCharacter
```
protected boolean isValidNameCharacter(char ch)
```
  - isGroupEnd
```
protected boolean isGroupEnd(char ch)
```
  - getSpecialNameCharacters
```
protected java.lang.String getSpecialNameCharacters()
```
    Returns the special character allowed in attribute names
  - createMatchRuleOn
```
protected MatchRule createMatchRuleOn(MatchGroup group)
```
  - getRuleChars
```
protected MatchRuleChars getRuleChars()
```
  - setRuleChars
```
protected void setRuleChars(MatchRuleChars newValue)
```

Class DefaultMatchRuleParser

Example 1

Example 2:

Constructor Summary

Method Summary

Methods inherited from class org.pfsw.text.BaseMatchRuleParser

Methods inherited from class java.lang.Object

Constructor Detail

DefaultMatchRuleParser

DefaultMatchRuleParser

Method Detail

parseRule

create

create

getIgnoreCaseInNames

setIgnoreCaseInNames

getIgnoreCaseInValues

setIgnoreCaseInValues

getMultiCharWildcardMatchesEmptyString

setMultiCharWildcardMatchesEmptyString

parse

parseTypedRule

getAndChar

setAndChar

getOrChar

setOrChar

getNotChar

setNotChar

getValueSeparatorChar

setValueSeparatorChar

getValueDelimiterChar

getValueStartChar

setValueStartChar

getValueEndChar

setValueEndChar

getGroupStartChar

setGroupStartChar

getGroupEndChar

setGroupEndChar

getGreaterChar

setGreaterChar

getLessChar

setLessChar

getEqualsChar

setEqualsChar

parseToGroup

parseGroup

readElements

readElement

nextIsGroupElement

parseAttribute

readAttributeName

isValidCompareOperator

readCompareOperator

readMatchValues

readMatchValue

readMatchValue

readDelimitedMatchValue

readUndelimitedMatchValue

isPartOfValue

readOperators

readUpTo

isOperator

isValidNameCharacter

isGroupEnd

getSpecialNameCharacters

createMatchRuleOn

getRuleChars

setRuleChars