Class WildcardExpression

In this topic

Package com.ms.util Previous This
Package Next

Class WildcardExpression

public class WildcardExpression implements 
            java.io.FilenameFilter, Cloneable, SetComparison
{
  // Fields
  public static int CASE_SENSITIVE;
  public static final int COMPARE_FL_ALL;
  public static final int COMPARE_FL_REJECT;
  public static final int COMPARE_FL_STOP1;
  public static final int COMPARE_FL_STOP2;
  public static int ESCAPED;
  public static int EXACT;
  public static int NO_DELIMITERS;
  public static int NO_WILDCARDS;

  // Constructors
  public WildcardExpression ();
  public WildcardExpression (String expr);
  public WildcardExpression (String expr, int flags);

  // Methods
  public boolean accept (java.io.File dir, String name);
  public synchronized void append (WildcardExpression other);
  public synchronized void append (WildcardExpression[] list);
  public synchronized void append (String expr, int flags);
  public void append (String expr);
  protected Object clone ();
  public int compare (WildcardExpression other,
        IWildcardExpressionComparator judge,
        boolean requireEquality);
  public int compare (WildcardExpression other);
  public int compare (WildcardExpression other,
        IWildcardExpressionComparator judge);
  public int compareSet (Object other);
  public static String ComparisonResulttoString (int cmp);
  public synchronized void compile (String expr, int flags);
  public void compile (String expr);
  public WildcardExpression condense ();
  public synchronized WildcardExpression condense (
        IWildcardExpressionComparator judge);
  public WildcardExpression copy ();
  public boolean equals (Object obj);
  public WildcardExpression[] getSubexpressions ();
  public WildcardExpression intersect (WildcardExpression other,
        IWildcardExpressionComparator judge);
  public WildcardExpression intersect (WildcardExpression other);
  public static int InvertComparisonResult (int cmp);
  public boolean isCaseSensitive ();
  public boolean isEmpty ();
  public boolean match (String s);
  public int matchex (String s);
  public static int matchOne (WildcardExpression[] exprs, int ofs,
        int len, String s);
  public static int matchOne (WildcardExpression[] exprs, String s);
  public int resume (String s);
  public WildcardExpression selectSubexpressions (
        WildcardExpression other, int[] criteria,
        IWildcardExpressionComparator judge);
  public WildcardExpression selectSubexpressions (
        WildcardExpression other, int[] criteria);
  public void setCaseInsensitive ();
  public String toString ();
  public String toString (boolean escaped);
}

This class matches simple wildcard expressions, such as *.txt or report?.doc commonly recognized by users on most platforms. The nonterminals "*" and "?" can be combined any number of times in any conceivable manner. Multiple expressions can be matched by separating the expressions with a semicolon; for example, "*.txt;*.doc" will match Strings ending with .txt or .doc. The special expression tokens can be matched by escaping them with '\'; for example, "clear\*sky" will match the string "clear*sky", but not "clearbluesky". Expressions can be case-sensitive or case-insensitive; this is selected when the expression is constructed.

This is very similar to DOS wildcards, but is in no way confined to filenames. The expression '*' will match a path in any subdirectory, and "*.*" does not match a file with no extension. For example, unlike DOS, "c:\\windows\\*" will match "c:\\windows\\system\\blue.vxd" and "*.*" will not match "notes".

WildcardExpression implements FilenameFilter, so it can readily be used with FileDialog, File.list, or ClientStore.listFiles.

The equals method has been overridden to special-case equality with strings. When invoked with a string, it will perform a match instead of comparing the pattern string. This allows it to be more easily used in a container, such as Vector, to find an expression matching a string. To find a matching expression in a string array, use the matchOne method.

While this may have its uses, the preferred method of matching a string against a series of expressions is to combine the expressions into a single expression using the append operator. The matchex function will return the sub-expression number of the first matching expression, and the resume function will continue searching for matching expressions. The use of matchex and resume should be externally synchronized, if there is the possibility that match, matchex, or resume may be used on the same expression simultaneously from another thread. For example:


 WildcardExpression expr = new WildcardExpression();
 expr.append("*.java");
 expr.append("*.txt");
 expr.append("*.doc");
 expr.append("c:\\docs\\*");
 // Resulting expression: "*.java;*.txt;*.doc;c:\\docs\\*"
 
 String filename = "c:\\docs\\foo.txt";
 synchronized (expr)
 {
     int exprnum;
     exprnum = expr.matchex(filename);   // returns 1
     exprnum = expr.resume(filename);    // returns 3
     exprnum = expr.resume(filename);    // returns -1
 }

Case-sensitive and case-insensitive expressions cannot be combined.

There are three ways to construct expressions:

Use one of the constructors to create a set of subexpressions from a string delimited by ';'.
Use the append methods to add subexpressions to an existing expression (which can be an empty expression). The new pattern string can optionally have ';' delimiters ignored. Both single WildcardExpression objects and arrays of WildcardExpression objects can be appended to existing expressions.
Use the compile methods, which replace an existing expression with a new one using the same semantics as the constructors.

To improve performance, nothing in this class is synchronized. The typical use is that an expression is compiled once by the constructor. The compile and append methods are the only operators that change the state of the expression. Callers are responsible for synchronizing these operations with callers of the other methods. Note that matchex and resume also change state of the expression but not the expression itself. These operations also may need to be synchronized, but not with the others.

WildcardExpressions are not immutable, so security-critical code should be careful to pass copies of the expression to less-trusted code using the copy method. Some of the contents of the copy will be shared with the original until one of them changes.

Constructors

WildcardExpression

public WildcardExpression ();
Creates an empty expression. (An expression must be compiled before matches can be made.)
See Also: compile

WildcardExpression

public WildcardExpression (String expr);
Creates an expression that follows the typical wildcard convention.

Parameter Description

expr The expression evaluate.

WildcardExpression

public WildcardExpression (String expr, int flags);
Creates a case-sensitive expression from a string and allows for escaped wildcards.

Parameter Description

expr The expression to compile.
flags Combination of one or more of the following flags:
CASE_SENSITIVE
NO_DELIMITERS
ESCAPED

See Also: compile

Methods

accept

public boolean accept (java.io.File dir, String name);
Determines if a filename is valid.
Return Value:
Returns true if name matches a real path; otherwise, returns false.

Parameter Description

dir The directory that contains the file.
name The name of the file.

append

public synchronized void append (WildcardExpression other);
Appends another expression to this expression.
Return Value:
No return value

Parameter Description

other The expression to append.

Exceptions:
IllegalArgumentException if the expressions are incompatible.

append

public synchronized void append (WildcardExpression[] list);
Adds a list of expressions to the expression. If any expressions fail to be added, the original expression is not affected.

Parameter Description

list The list of expressions to add.

append

public synchronized void append (String expr, int flags);
Appends another expression to this expression.

Parameter Description

expr The expression to append.
flags Combination of one or more of the following flags for controlling constructing of the expression:
NO_WILDCARDS
NO_DELIMITERS
ESCAPED

Note that CASE_SENSITIVE is not valid. The case-sensitivity of matching the new pattern is controlled by the existing case-sensitivity of the expression.

Exceptions:
IllegalArgumentException if the expression is invalid.

append

public void append (String expr);
Appends another expression to this expression.
Return Value:
No return value

Parameter Description

expr The expression to append.

Exceptions:
IllegalArgumentException if the expression is invalid.

clone

protected Object clone ();
Creates a copy of the this object.
Return Value:
Returns the cloned copy.

compare

public int compare (WildcardExpression other, IWildcardExpressionComparator
        judge, boolean requireEquality);
Compares the set of strings matched by this expression to the set matched by another. This variant of this method should be used for continued expressions.
Return Value:
Returns one of the SetComparison field values to indicate the relationship between the sets.

Parameter Description

other The object containing the other set of strings.
judge Used for deciding what to do with two expressions.
requireEquality Set to true if the comparator should time-out if it becomes impossible for an EQUAL result to be returned.

Exceptions:
IllegalArgumentException if the expressions cannot be compared.

compare

public int compare (WildcardExpression other);
Compares the set of strings matched by this expression to the set matched by another.
Return Value:
Returns one of the SetComparison field values to indicate the relationship between the sets. The result reflects the action of matching non-continuable expressions.

Parameter Description

other The object containing the other set of strings.

Exceptions:
IllegalArgumentException if the expressions cannot be compared.

compare

public int compare (WildcardExpression other, IWildcardExpressionComparator
        judge);
Compares the set of strings matched by this expression to the set matched by another. This variant of this method should be used for continued expressions.
Return Value:
Returns one of the SetComparison field values to indicate the relationship between the sets.

Parameter Description

other The object containing the other set of strings.
judge Used for deciding what to do with two expressions.

Exceptions:
IllegalArgumentException if the expressions cannot be compared.

compareSet

public int compareSet (Object other);
Compares the set of strings matched by this expression to the set matched by another.
Return Value:
Returns one of the SetComparison field values to indicate the relationship between the sets. If other is not a WildcardExpression object, returns DISJOINT. The result reflects the action of matching non-continuable expressions.

Parameter Description

other The object containing the other set of strings.

Exceptions:
IllegalArgumentException if the expressions cannot be compared.

ComparisonResulttoString

public static String ComparisonResulttoString (int cmp);
Converts comparison result flags to a string format.
Return Value:
Returns the result string as follows:
"equal" (SetComparison.EQUAL)
"notequal" (SetComparison.DISJOINT)
"overlap" (SetComparison.OVERLAP)
"subset" (SetComparison.SUBSET)
"superset" (SetComparison.SUPERSET)

Parameter Description

cmp A comparison result from the compare method.

compile

public synchronized void compile (String expr, int flags);
Compiles the expression for faster evaluation. The previously compiled expression is lost when this method is called.
Return Value:
No return value.

Parameter Description

expr The expression to compile.
flags Combination of one or more of the following flags:
NO_WILDCARDS
CASE_SENSITIVE
NO_DELIMITERS
ESCAPED

See Also: match

compile

public void compile (String expr);
Compiles the expression for faster evaluation with default values.
Return Value:
No return value.

Parameter Description

expr The expression to compile.

Remarks:
The previously compiled expression is lost when this method is called. Case-sensitive matching and the evaluation of escaped wildcards are disabled for the compilation.
See Also: match

condense

public WildcardExpression condense ();
Removes redundant subexpressions. The new subexpressions may match overlapping sets of strings, but will not be equal or entirely match the set of strings of any other subexpressions.
Return Value:
Returns a new WildcardExpression object containing the unique expressions of the expression. If there are no redundant expressions, the original expression is returned.

condense

public synchronized WildcardExpression condense (
        IWildcardExpressionComparator judge);
Removes redundant subexpressions. The new subexpressions may match overlapping sets of strings, but will not be equal or entirely match the set of strings of any other subexpressions.
Return Value:
Returns a new WildcardExpression object containing the unique expressions of the expression. If there are no redundant expressions, the original expression is returned.

Parameter Description

judge Used for comparing any auxiliary data that may be associated with each subexpression.

copy

public WildcardExpression copy ();
Retrieves a copy of the currently compiled expression.
Return Value:
Returns a copy of the expression.

equals

public boolean equals (Object obj);
Determines if this object is equivalent to another object.
Return Value:
Returns true if obj is equivalent or matched by this object; otherwise, returns false.

Parameter Description

obj A String to match against this expression or a WildcardExpression to compare for equivalence.

getSubexpressions

public WildcardExpression[] getSubexpressions ();
Splits the expression into its subexpressions.
Return Value:
Returns an array of expressions that make up the subexpressions.

intersect

public WildcardExpression intersect (WildcardExpression other,
        IWildcardExpressionComparator judge);
Constructs an expression that matches any strings that this and another expression both match.
Return Value:
Returns an expression that is the intersection of the two expressions.

Parameter Description

other The other expression.
judge A helper interface.

Remarks:
If either expression contains redundant subexpressions, the resulting expression will also contain redundant intersections. Calling condense beforehand on both expressions may improve the efficiency of this operation. Redundant expressions may be returned even if the source expressions contain no redundant expressions.

intersect

public WildcardExpression intersect (WildcardExpression other);
Constructs an expression that matches any strings that this and another expression both match.
Return Value:
Returns an expression that is the intersection of the two expressions.

Parameter Description

other The other expression.

InvertComparisonResult

public static int InvertComparisonResult (int cmp);
Inverts comparison results.
Return Value:
Returns the inverted comparison result.

Parameter Description

cmp Any comparison result of the compare method, which is inverted as follows:
SUBSET returns SUPERSET.
SUPERSET returns SUBSET.
any other result is not affected and is simply returned. Note that EQUAL and DISJOINT are not inverted by this function.

isCaseSensitive

public boolean isCaseSensitive ();
Determines if the expression is case-sensitive.

isEmpty

public boolean isEmpty ();
Determines if the expression has an expression compiled into it. An empty expression cannot be used for matching.
Return Value:
Returns true if the expression does not contain a compiled expression; otherwise, returns false.

match

public boolean match (String s);
Evaluates the expression on a string.
Return Value:
Returns true if the expression accepts the string.

Parameter Description

s The string to evaluate the expression on.

matchex

public int matchex (String s);
Evaluates the expression on a string.
Return Value:
Returns the subexpression number if the expression accepts the string; returns -1 if the string was not accepted.

Parameter Description

s The string to evaluate the expression on.

matchOne

public static int matchOne (WildcardExpression[] exprs, int ofs, int len,
        String s);
Evaluates a list of expressions on a string.
Return Value:
Returns the index of the expression that matched; returns -1 if no match occurred.

Parameter Description

exprs A list of expressions.
ofs The offset into the list to begin matching
len The number of elements to match against.
s The string to evaluate the expressions on.

matchOne

public static int matchOne (WildcardExpression[] exprs, String s);
Evaluates a list of expressions on a string.
Return Value:
Returns the index of the expression that matched; returns -1 if no match occurred.

Parameter Description

exprs A list of expressions.
s The string to evaluate the expressions on.

resume

public int resume (String s);
Resumes a previous match that stopped at a subexpression.
Return Value:
Returns the subexpression number if the expression accepts the string; returns -1 if the string was not accepted.

Parameter Description

s The string to evaluate the expression on.

selectSubexpressions

public WildcardExpression selectSubexpressions (WildcardExpression other,
        int[] criteria, IWildcardExpressionComparator judge);
Constructs a new expression containing expressions from this expression that have any of the specified comparison results against any subexpressions of the target expression.
Return Value:
Returns the original expression if all are selected; returns a new expression containing only the subexpressions of this expression that meet the selection criteria.

Parameter Description

other The target expression to compare against.
criteria The selection criteria determining inclusion in the returned expression.
judge An IWildcardExpressionComparator hook interface to compare any extra data associated with the subexpressions.

selectSubexpressions

public WildcardExpression selectSubexpressions (WildcardExpression other,
        int[] criteria);
Constructs a new expression containing expressions from this expression that have any of the specified comparison results against any subexpressions of the target expression.
Return Value:
Returns the original expression if all are selected; returns a new expression containing only the subexpressions of this expression that meet the selection criteria.

Parameter Description

other The other target expression to compare against.
criteriaThe selection criteria determining inclusion in the returned expression.

setCaseInsensitive

public void setCaseInsensitive ();
Destructively changes the expression to perform case-insensitive matching. This change cannot be reversed.

toString

public String toString ();
Reconstructs the original expression in extended, non-escaped form. Case-insensitive expressions are reconstructed in lowercase.
Return Value:
Returns the original expression.

toString

public String toString (boolean escaped);
Reconstructs the original expression, optionally in escaped form. Case-insensitive expressions are reconstructed in lowercase.
Return Value:
Returns the original expression.

Parameter Description

escaped True if string is to include escape characters; false, otherwise.

Fields

CASE_SENSITIVE: Specifies that the resulting expression should perform case-sensitive matching.
COMPARE_FL_ALL: A IWildCardExpressionComparator result flag, used in conjunction with COMPARE_XXX, by IWildcardExpressionComparator.compareSubexpressions. Combines flags COMPARE_FL_REJECT, COMPARE_FL_STOP1, and COMPARE_FL_STOP2.
COMPARE_FL_REJECT: A Comparison result flag, used by IWildcardExpressionComparator.compareSubexpressions to stop the comparison.
COMPARE_FL_STOP1: A SetComparison result flag, used by IWildcardExpressionComparator.compareSubexpressions to disregard further elements of the first expression because they will not be considered during matching.
COMPARE_FL_STOP2: A SetComparison result flag, used in conjunction with COMPARE_XXX, by IWildcardExpressionComparator.compareSubexpressions to disregard further elements of the second expression because they will not be considered during matching.
ESCAPED: Specifies that the added string contains escaped expression characters. For example, "\*" will match a '*'.
EXACT: Specifies that the added string will be matched "as is," with no interpretation of delimiters or wildcards.
NO_DELIMITERS: Specifies that the string being added or compiled into the expression should be added as a single subexpression. Subexpression delimiters within the added string will be ignored.
NO_WILDCARDS: Specifies that wildcard characters in the added string will be ignored.