org.pfsw.text
Class DefaultMatchRuleParser

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

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:

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.

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 ) ;
 

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.

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)