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.
public WildcardExpression ();
Creates an empty expression. (An expression must be compiled before matches can be made.)
See Also: compile
public WildcardExpression (String expr);
Creates an expression that follows the typical wildcard convention.
Parameter | Description |
expr
| The expression evaluate.
|
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:
|
See Also: compile
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.
|
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.
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.
|
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:
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.
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.
protected Object clone ();
Creates a copy of the this object.
Return Value:
Returns the cloned copy.
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.
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.
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.
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.
public static String ComparisonResulttoString (int cmp);
Converts comparison result flags to a string format.
Return Value:
Returns the result string as follows:
Parameter | Description |
cmp
| A comparison result from the compare method.
|
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:
|
See Also: match
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
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.
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.
|
public WildcardExpression copy ();
Retrieves a copy of the currently compiled expression.
Return Value:
Returns a copy of the expression.
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.
|
public WildcardExpression[] getSubexpressions ();
Splits the expression into its subexpressions.
Return Value:
Returns an array of expressions that make up the subexpressions.
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.
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.
|
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:
|
public boolean isCaseSensitive ();
Determines if the expression is case-sensitive.
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.
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
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.
|
public void setCaseInsensitive ();
Destructively changes the expression to perform case-insensitive matching. This change cannot be reversed.
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.
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.
|
- 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.