simple.util
Class Resolver

java.lang.Object
  extended by simple.util.Resolver
All Implemented Interfaces:
java.io.Serializable

public class Resolver
extends java.lang.Object
implements java.io.Serializable

This is used to match String's with the first pattern that String matches. A pattern consists of characters with either the '*' or '?' characters as wild characters. The '*' character is completely wild meaning that is will match nothing or a long sequence of characters. The '?' character matches a single character.

If the '?' character immediately follows the '*' character then the match is made as any sequence of characters up to the first match of the next character. For example "/*?/index.jsp" will match all files preceeded by only a single path. So "/pub/index.jsp" will match, however "/pub/bin/index.jsp" will not, as it has two paths. So, in effect the '*?' sequence will match anything or nothing up to the first occurence of the next character in the pattern.

A design goal of the Resolver was to make it capable of high performance in a multithreaded environment. In order to achieve a high performance the Resolver can cache the resolutions it makes so that if the same text is given to the Resolver.resolve method a cached result can be retrived quickly which will decrease the length of time a thread occupies the synchronized method. The cache used is a CacheList.

The semantics of the resolver are such that the last pattern inserted with a wild string is the first one checked for a match. This means that if a sequence of insertions like insert(a,b) insert(x,y) is made and then a resolve(z) is attemped then z will be compared to x first and then a, if z matches x then y is given as the result and if z matches a then b will be returned, remember if z matches both a and x then y will be the result due to the fact that is was the last pattern inserted.

Author:
Niall Gallagher
See Also:
CacheList, Serialized Form

Constructor Summary
Resolver()
          The default constructor will create a Resolver without a large cache size.
Resolver(int size)
          This constructor allows resolves to be cached for increased performance.
 
Method Summary
 void clear()
          This is used to clear all matches from the resolver.
 boolean contains(Match match)
          This will check this Resolver to see if the match given is used by this Resolver, if it is this will return true.
 boolean contains(java.lang.String pattern)
          This will check this Resolver to see if the pattern given is used by this Resolver, if it is this will return true.
 Match getMatch(int pos)
          This will return the corrosponding Match at the specified position.
 Match getMatch(java.lang.String pattern)
          This will return the corrosponding Match at the specified position.
 Match[] getMatches()
          Retrives an array of Match's of each pair that was entered into this Resolver.
 int indexOf(java.lang.String pattern)
          Used to find the position of the Match stored using the specified pattern.
 int indexOf(java.lang.String pattern, int from)
          Used to find the position of the Match stored using the specified pattern.
 void insert(java.lang.String pattern, java.lang.String match)
          This will add a new pattern with its resolution.
 void insert(java.lang.String pattern, java.lang.String match, int pos)
          This will add a new pattern with its resolution.
 boolean isEmpty()
          This can be used to determine wheather or not there is any entrys in the Resolver.
 void remove(int pos)
          This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more.
 void remove(Match match)
          This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more.
 void remove(java.lang.String pattern)
          This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more.
 java.lang.String resolve(java.lang.String text)
          This will search the patterns in this Resolver to see if there is a pattern in it that matches the string given.
 int size()
          This will return the number of entrys that have been inserted into this Resolver.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Resolver

public Resolver()
The default constructor will create a Resolver without a large cache size. This is intended for use when the requests for resolve tend to use strings that are reasonably similar. If the strings issued to this instance are dramatically different then the cache tends to be an overhead rather than a bonus.


Resolver

public Resolver(int size)
This constructor allows resolves to be cached for increased performance. When strings tend to be reused for pattern matching then this constructor should be used. The cache is a simple Least Recently Used List. So only patterns that have a high 'hit' rate will remain in the cache.

If a caching is done then an CacheList is used. This is a transient object so that when this instance of the Resolver is serialized list is cleared.

Parameters:
size - if this is true the caching of resolves is done using a CacheList
Method Detail

resolve

public java.lang.String resolve(java.lang.String text)
This will search the patterns in this Resolver to see if there is a pattern in it that matches the string given. This will search the patterns from the last entered pattern to the first entered. So that the last entered patterns are the most searched patterns and will resolve it first if it matches.

Although it is criticial that this perform well this method is synchronized. The reasnon for this is that if there was several threads modifing the Resolver at the same time ConcurrentModificationException exceptions would be thrown this would reduce the usefulness of this object.

Parameters:
text - this is the String to be resolved
Returns:
will return the String that pattern resolves to

insert

public void insert(java.lang.String pattern,
                   java.lang.String match)
This will add a new pattern with its resolution. This will be added to the end of the list and will be the first pattern checked for a match when the resolve method is invoked. This inserts the pair at the end of the list and so it will be the first pattern checked. If the match is an empty string then there is not insertion made.

Parameters:
pattern - this is the pattern that will resolve this
match - the String returned when a correct match is made
Throws:
java.lang.NullPointerException - if either string is null

insert

public void insert(java.lang.String pattern,
                   java.lang.String match,
                   int pos)
This will add a new pattern with its resolution. This will be added to the end of the list and will be the first pattern checked for a match when the resolve method is invoked. This will insert the pair into the position specified. This behaves like the Vector.insertElementAt method, by bumping all entrys up one position. If the match is an empty string then there is not insertion made.

Parameters:
pattern - this is the pattern that will resolve this
match - the String returned when a correct match is made
pos - this is the position to insert the pair into
Throws:
java.lang.NullPointerException - if either string is null

remove

public void remove(int pos)
This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more. This behaves like the Vector.removeElementAt.

Parameters:
pos - this is the position that is removed from this

remove

public void remove(java.lang.String pattern)
This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more. If the wild string is parameter is null then there is a NullPointerException. This behaves like the Vector.removeElementAt method.

Parameters:
pattern - this is the pattern that is removed from this

remove

public void remove(Match match)
This will remove the entry in this Resolver so that the pattern will not be used to resolve String's any more. If the wild string is parameter is null then there is a NullPointerException. This will only use the Match.getPattern to remove the match. This is a convienence method that it can be used with getMatches.

Parameters:
match - this is the match that is removed from this

getMatches

public Match[] getMatches()
Retrives an array of Match's of each pair that was entered into this Resolver. The elements in the array are ordered to represent the order they were made.

Returns:
the array of Match objects that exist

getMatch

public Match getMatch(int pos)
This will return the corrosponding Match at the specified position. This can be used in conjunction with the indexOf method to remove matches.

Parameters:
pos - the position Match to retrive
Returns:
this will retrun the match object at that position

getMatch

public Match getMatch(java.lang.String pattern)
This will return the corrosponding Match at the specified position. This can be used in conjunction with the indexOf method to remove matches. This is a convienence method that avoids having to use the indexOf method.

Parameters:
pattern - the position Match to retrive
Returns:
returns the match object at that position

indexOf

public int indexOf(java.lang.String pattern)
Used to find the position of the Match stored using the specified pattern. This operates in a similar way to the Vector.indexOf method.

Parameters:
pattern - the pattern that the Match is stored using
Returns:
this will return the position of that pattern

indexOf

public int indexOf(java.lang.String pattern,
                   int from)
Used to find the position of the Match stored using the specified pattern. This operates in a similar way to the Vector.indexOf method.

Parameters:
pattern - the pattern that the Match is stored using
from - this starts checking from this position
Returns:
this will return the position of that pattern

contains

public boolean contains(java.lang.String pattern)
This will check this Resolver to see if the pattern given is used by this Resolver, if it is this will return true.

Parameters:
pattern - the pattern that is used resolving String's
Returns:
this will return true if this pattern exists in this Resolver

contains

public boolean contains(Match match)
This will check this Resolver to see if the match given is used by this Resolver, if it is this will return true.

Parameters:
match - this is a specific match and pattern pair
Returns:
this will return true if this match exists in this Resolver

isEmpty

public boolean isEmpty()
This can be used to determine wheather or not there is any entrys in the Resolver. If this Resolver is empty this will return true, there must be at least one entry in the Resolver.

Returns:
this returns true is there are no elements

size

public int size()
This will return the number of entrys that have been inserted into this Resolver. This uses the Vector's size implementation to determine the number of entrys.

Returns:
this returns the number of pattern/match pairs

clear

public void clear()
This is used to clear all matches from the resolver. This ensures that the resolver contains no matches and that the resolution cache is cleared. This is used to that the resolver can be reused and have new pattern matches inserted into it for resolution.