org.eclipse.wst.jsdt.core.search

## Class SearchPattern

- java.lang.Object
- - org.eclipse.wst.jsdt.internal.core.search.matching.InternalSearchPattern
  - - org.eclipse.wst.jsdt.core.search.SearchPattern

    public abstract class SearchPattern
    extends org.eclipse.wst.jsdt.internal.core.search.matching.InternalSearchPattern

A search pattern defines how search results are found. Use `SearchPattern.createPattern` to create a search pattern.

Search patterns are used during the search phase to decode index entries that were added during the indexing phase (see `SearchDocument.addIndexEntry(char[], char[])`). When an index is queried, the index categories and keys to consider are retrieved from the search pattern using `getIndexCategories()` and `getIndexKey()`, as well as the match rule (see `getMatchRule()`). A blank pattern is then created (see `getBlankPattern()`). This blank pattern is used as a record as follows. For each index entry in the given index categories and that starts with the given key, the blank pattern is fed using `decodeIndexKey(char[])`. The original pattern is then asked if it matches the decoded key using `matchesDecodedKey(SearchPattern)`. If it matches, a search doument is created for this index entry using `SearchParticipant.getDocument(String)`.

This class is intended to be subclassed by clients. A default behavior is provided for each of the methods above, that clients can ovveride if they wish.

See Also:
  `createPattern(org.eclipse.wst.jsdt.core.IJavaScriptElement, int)`, `Provisional API: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.`

### Field Summary

Fields
`static int` `R_CAMELCASE_MATCH` Match rule: The search pattern contains a Camel Case expression.
`static int` `R_CASE_SENSITIVE` Match rule: The search pattern matches the search result only if cases are the same.
`static int` `R_EQUIVALENT_MATCH` Match rule: The search pattern matches search results as raw/parameterized types/methods with equivalent type parameters.
`static int` `R_ERASURE_MATCH` Match rule: The search pattern matches search results as raw/parameterized types/methods with same erasure.
`static int` `R_EXACT_MATCH` Match rule: The search pattern matches exactly the search result, that is, the source of the search result equals the search pattern.
`static int` `R_FULL_MATCH` Match rule: The search pattern matches exactly the search result, that is, the source of the search result equals the search pattern.
`static int` `R_PATTERN_MATCH` Match rule: The search pattern contains one or more wild cards ('*' or '?').
`static int` `R_PREFIX_MATCH` Match rule: The search pattern is a prefix of the search result.
`static int` `R_REGEXP_MATCH` Match rule: The search pattern contains a regular expression.

### Constructor Summary

Constructors
Constructor and Description
`SearchPattern(int matchRule)` Creates a search pattern with the rule to apply for matching index keys.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`static boolean` `camelCaseMatch(java.lang.String pattern, int patternStart, int patternEnd, java.lang.String name, int nameStart, int nameEnd)` Answers true if a sub-pattern matches the subpart of the given name using CamelCase rules, or false otherwise.
`static boolean` `camelCaseMatch(java.lang.String pattern, java.lang.String name)` Answers true if the pattern matches the given name using CamelCase rules, or false otherwise.
`static SearchPattern` `createAndPattern(SearchPattern leftPattern, SearchPattern rightPattern)` Returns a search pattern that combines the given two patterns into an "and" pattern.
`static SearchPattern` `createOrPattern(SearchPattern leftPattern, SearchPattern rightPattern)` Returns a search pattern that combines the given two patterns into an "or" pattern.
`static SearchPattern` `createPattern(IJavaScriptElement element, int limitTo)` Returns a search pattern based on a given JavaScript element.
`static SearchPattern` `createPattern(IJavaScriptElement element, int limitTo, int matchRule)` Returns a search pattern based on a given JavaScript element.
`static SearchPattern` `createPattern(java.lang.String stringPattern, int searchFor, int limitTo, int matchRule)` Returns a search pattern based on a given string pattern.
`void` `decodeIndexKey(char[] key)` Decode the given index key in this pattern.
`abstract SearchPattern` `getBlankPattern()` Returns a blank pattern that can be used as a record to decode an index key.
`char[][]` `getIndexCategories()` Returns an array of index categories to consider for this index query.
`char[]` `getIndexKey()` Returns a key to find in relevant index categories, if null then all index entries are matched.
`int` `getMatchRule()` Returns the rule to apply for matching index keys.
`static boolean` `isPatternMatch(java.lang.String pattern)` Returns whether the given pattern is a pattern case or not.
`boolean` `matchesDecodedKey(SearchPattern decodedPattern)` Returns whether this pattern matches the given pattern (representing a decoded index key).
`boolean` `matchesName(char[] pattern, char[] name)` Returns whether the given name matches the given pattern.
`static boolean` `matchesQualificationPattern(char[] thisQualifiedName, char[] otherQualifiedName, boolean isCaseSensitive)` Returns whether this pattern's prefix qualifier matches the other patterns qualified name.
`java.lang.String` `toString()`
`static int` `validateMatchRule(java.lang.String stringPattern, int matchRule)` Validate compatibility between given string pattern and match rule.

### Methods inherited from class org.eclipse.wst.jsdt.internal.core.search.matching.InternalSearchPattern

`findIndexMatches, setFocus`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### R_EXACT_MATCH

    public static final int R_EXACT_MATCH

Match rule: The search pattern matches exactly the search result, that is, the source of the search result equals the search pattern.

See Also:
  Constant Field Values

#### R_PREFIX_MATCH

    public static final int R_PREFIX_MATCH

Match rule: The search pattern is a prefix of the search result.

See Also:
  Constant Field Values

#### R_PATTERN_MATCH

    public static final int R_PATTERN_MATCH

Match rule: The search pattern contains one or more wild cards ('*' or '?'). A '*' wild-card can replace 0 or more characters in the search result. A '?' wild-card replaces exactly 1 character in the search result.

See Also:
  Constant Field Values

#### R_REGEXP_MATCH

    public static final int R_REGEXP_MATCH

Match rule: The search pattern contains a regular expression.

See Also:
  Constant Field Values

#### R_CASE_SENSITIVE

    public static final int R_CASE_SENSITIVE

Match rule: The search pattern matches the search result only if cases are the same. Can be combined to previous rules, e.g. `R_EXACT_MATCH` | `R_CASE_SENSITIVE`

See Also:
  Constant Field Values

#### R_ERASURE_MATCH

    public static final int R_ERASURE_MATCH

Match rule: The search pattern matches search results as raw/parameterized types/methods with same erasure. This mode has no effect on other javascript elements search.
Type search example:

- pattern: `List<Exception>`
- match: `List<Object>`

Method search example:

- declaration: `<T>foo(T t)`
- pattern: `<Exception>foo(new Exception())`
- match: `<Object>foo(new Object())`

Can be combined to all other match rules, e.g. `R_CASE_SENSITIVE` | `R_ERASURE_MATCH` This rule is not activated by default, so raw types or parameterized types with same erasure will not be found for pattern List<String>, Note that with this pattern, the match selection will be only on the erasure even for parameterized types.

See Also:
  Constant Field Values

#### R_EQUIVALENT_MATCH

    public static final int R_EQUIVALENT_MATCH

Match rule: The search pattern matches search results as raw/parameterized types/methods with equivalent type parameters. This mode has no effect on other javascript elements search.
Type search example:

- pattern: `List<Exception>`
- match:
  - `List<? extends Throwable>`
  - `List<? super RuntimeException>`
  - `List<?>`

Method search example:

- declaration: `<T>foo(T t)`
- pattern: `<Exception>foo(new Exception())`
- match:
  - `<? extends Throwable>foo(new Exception())`
  - `<? super RuntimeException>foo(new Exception())`
  - `foo(new Exception())`

Can be combined to all other match rules, e.g. `R_CASE_SENSITIVE` | `R_EQUIVALENT_MATCH` This rule is not activated by default, so raw types or equivalent parameterized types will not be found for pattern List<String>, This mode is overridden by `R_ERASURE_MATCH` as erasure matches obviously include equivalent ones. That means that pattern with rule set to `R_EQUIVALENT_MATCH` | `R_ERASURE_MATCH` will return same results than rule only set with `R_ERASURE_MATCH`.

See Also:
  Constant Field Values

#### R_FULL_MATCH

    public static final int R_FULL_MATCH

Match rule: The search pattern matches exactly the search result, that is, the source of the search result equals the search pattern.

See Also:
  Constant Field Values

#### R_CAMELCASE_MATCH

    public static final int R_CAMELCASE_MATCH

Match rule: The search pattern contains a Camel Case expression.
Examples:

- `NPE` type string pattern will match `NullPointerException` and `NpPermissionException` types,
- `NuPoEx` type string pattern will only match `NullPointerException` type.

See Also:
  `for a detailed explanation of Camel Case matching.
  Can be combined to {@link #R_PREFIX_MATCH} match rule. For example, when prefix match rule is combined with Camel Case match rule, `"nPE"` pattern will match `nPException`.
  Match rule {@link #R_PATTERN_MATCH} may also be combined but both rules will not be used simultaneously as they are mutually exclusive. Used match rule depends on whether string pattern contains specific pattern characters (e.g. '*' or '?') or not. If it does, then only Pattern match rule will be used, otherwise only Camel Case match will be used. For example, with `"NPE"` string pattern, search will only use Camel Case match rule, but with `N*P*E*` string pattern, it will use only Pattern match rule.`, Constant Field Values

### Constructor Detail

#### SearchPattern

    public SearchPattern(int matchRule)

Creates a search pattern with the rule to apply for matching index keys. It can be exact match, prefix match, pattern match or regexp match. Rule can also be combined with a case sensitivity flag.

Parameters:
  `matchRule` - one of `R_EXACT_MATCH`, `R_PREFIX_MATCH`, `R_PATTERN_MATCH`, `R_REGEXP_MATCH`, `R_CAMELCASE_MATCH` combined with one of following values: `R_CASE_SENSITIVE`, `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH`. e.g. `R_EXACT_MATCH` | `R_CASE_SENSITIVE` if an exact and case sensitive match is requested, `R_PREFIX_MATCH` if a prefix non case sensitive match is requested or `R_EXACT_MATCH` | `R_ERASURE_MATCH` if a non case sensitive and erasure match is requested.
  Note that `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH` have no effect on non-generic types/methods search.
  Note also that default behavior for generic types/methods search is to find exact matches.

### Method Detail

#### camelCaseMatch

    public static final boolean camelCaseMatch(java.lang.String pattern,
                                               java.lang.String name)

Answers true if the pattern matches the given name using CamelCase rules, or false otherwise. CamelCase matching does NOT accept explicit wild-cards '*' and '?' and is inherently case sensitive.
CamelCase denotes the convention of writing compound names without spaces, and capitalizing every term. This function recognizes both upper and lower CamelCase, depending whether the leading character is capitalized or not. The leading part of an upper CamelCase pattern is assumed to contain a sequence of capitals which are appearing in the matching name; e.g. 'NPE' will match 'NullPointerException', but not 'NewPerfData'. A lower CamelCase pattern uses a lowercase first character. In Java, type names follow the upper CamelCase convention, whereas method or field names follow the lower CamelCase convention.
The pattern may contain lowercase characters, which will be match in a case sensitive way. These characters must appear in sequence in the name. For instance, 'NPExcep' will match 'NullPointerException', but not 'NullPointerExCEPTION' or 'NuPoEx' will match 'NullPointerException', but not 'NoPointerException'.
Examples:

1.         pattern = "NPE"
           name = NullPointerException / NoPermissionException
           result => true

2.         pattern = "NuPoEx"
           name = NullPointerException
           result => true

3.         pattern = "npe"
           name = NullPointerException
           result => false

Parameters:
  `pattern` - the given pattern
  `name` - the given name
Returns:
  true if the pattern matches the given name, false otherwise
See Also:
  `Implementation has been entirely copied from this method except for array lengthes which were obviously replaced with calls to {@link String#length()}.`

#### camelCaseMatch

    public static final boolean camelCaseMatch(java.lang.String pattern,
                                               int patternStart,
                                               int patternEnd,
                                               java.lang.String name,
                                               int nameStart,
                                               int nameEnd)

Answers true if a sub-pattern matches the subpart of the given name using CamelCase rules, or false otherwise. CamelCase matching does NOT accept explicit wild-cards '*' and '?' and is inherently case sensitive. Can match only subset of name/pattern, considering end positions as non-inclusive. The subpattern is defined by the patternStart and patternEnd positions.
CamelCase denotes the convention of writing compound names without spaces, and capitalizing every term. This function recognizes both upper and lower CamelCase, depending whether the leading character is capitalized or not. The leading part of an upper CamelCase pattern is assumed to contain a sequence of capitals which are appearing in the matching name; e.g. 'NPE' will match 'NullPointerException', but not 'NewPerfData'. A lower CamelCase pattern uses a lowercase first character. In Java, type names follow the upper CamelCase convention, whereas method or field names follow the lower CamelCase convention.
The pattern may contain lowercase characters, which will be match in a case sensitive way. These characters must appear in sequence in the name. For instance, 'NPExcep' will match 'NullPointerException', but not 'NullPointerExCEPTION' or 'NuPoEx' will match 'NullPointerException', but not 'NoPointerException'.
Examples:

1.         pattern = "NPE"
           patternStart = 0
           patternEnd = 3
           name = NullPointerException
           nameStart = 0
           nameEnd = 20
           result => true

2.         pattern = "NPE"
           patternStart = 0
           patternEnd = 3
           name = NoPermissionException
           nameStart = 0
           nameEnd = 21
           result => true

3.         pattern = "NuPoEx"
           patternStart = 0
           patternEnd = 6
           name = NullPointerException
           nameStart = 0
           nameEnd = 20
           result => true

4.         pattern = "NuPoEx"
           patternStart = 0
           patternEnd = 6
           name = NoPermissionException
           nameStart = 0
           nameEnd = 21
           result => false

5.         pattern = "npe"
           patternStart = 0
           patternEnd = 3
           name = NullPointerException
           nameStart = 0
           nameEnd = 20
           result => false

Parameters:
  `pattern` - the given pattern
  `patternStart` - the start index of the pattern, inclusive
  `patternEnd` - the end index of the pattern, exclusive
  `name` - the given name
  `nameStart` - the start index of the name, inclusive
  `nameEnd` - the end index of the name, exclusive
Returns:
  true if a sub-pattern matches the subpart of the given name, false otherwise
See Also:
  `Implementation has been entirely copied from this method except for array lengthes which were obviously replaced with calls to {@link String#length()} and for array direct access which were replaced with calls to {@link String#charAt(int)}.`

#### createAndPattern

    public static SearchPattern createAndPattern(SearchPattern leftPattern,
                                                 SearchPattern rightPattern)

Returns a search pattern that combines the given two patterns into an "and" pattern. The search result will match both the left pattern and the right pattern.

Parameters:
  `leftPattern` - the left pattern
  `rightPattern` - the right pattern
Returns:
  an "and" pattern

#### createOrPattern

    public static SearchPattern createOrPattern(SearchPattern leftPattern,
                                                SearchPattern rightPattern)

Returns a search pattern that combines the given two patterns into an "or" pattern. The search result will match either the left pattern or the right pattern.

Parameters:
  `leftPattern` - the left pattern
  `rightPattern` - the right pattern
Returns:
  an "or" pattern

#### createPattern

    public static SearchPattern createPattern(java.lang.String stringPattern,
                                              int searchFor,
                                              int limitTo,
                                              int matchRule)

Returns a search pattern based on a given string pattern. The string patterns support '*' wild-cards. The remaining parameters are used to narrow down the type of expected results.
Examples:

- search for case insensitive references to `Object`: `createSearchPattern("Object", TYPE, REFERENCES, false);`
- search for case sensitive references to exact `Object()` constructor: `createSearchPattern("java.lang.Object()", CONSTRUCTOR, REFERENCES, true);`
- search for implementers of `java.lang.Runnable`: `createSearchPattern("java.lang.Runnable", TYPE, IMPLEMENTORS, true);`

Parameters:
  `stringPattern` - the given pattern
  `searchFor` - determines the nature of the searched elements
  - `IJavaScriptSearchConstants.CLASS`: only look for classes
  - `IJavaScriptSearchConstants#INTERFACE`: only look for interfaces
  - `IJavaScriptSearchConstants.ENUM`: only look for enumeration
  - `IJavaScriptSearchConstants#ANNOTATION_TYPE`: only look for annotation type
  - `IJavaScriptSearchConstants#CLASS_AND_ENUM`: only look for classes and enumerations
  - `IJavaScriptSearchConstants#CLASS_AND_INTERFACE`: only look for classes and interfaces
  - `IJavaScriptSearchConstants.TYPE`: look for all types (ie. classes, interfaces, enum and annotation types)
  - `IJavaScriptSearchConstants.FIELD`: look for fields
  - `IJavaScriptSearchConstants.METHOD`: look for methods
  - `IJavaScriptSearchConstants.CONSTRUCTOR`: look for constructors
  - `IJavaScriptSearchConstants.PACKAGE`: look for packages
  `limitTo` - determines the nature of the expected matches
  - `IJavaScriptSearchConstants.DECLARATIONS`: will search declarations matching with the corresponding element. In case the element is a method, declarations of matching methods in subtypes will also be found, allowing to find declarations of abstract methods, etc.
    Note that additional flags `IJavaScriptSearchConstants.IGNORE_DECLARING_TYPE` and `IJavaScriptSearchConstants.IGNORE_RETURN_TYPE` are ignored for string patterns. This is due to the fact that client may omit to define them in string pattern to have same behavior.
  - `IJavaScriptSearchConstants.REFERENCES`: will search references to the given element.
  - `IJavaScriptSearchConstants.ALL_OCCURRENCES`: will search for either declarations or references as specified above.
  - `IJavaScriptSearchConstants.IMPLEMENTORS`: for types, will find all types which directly implement/extend a given interface. Note that types may be only classes or only interfaces if `IJavaScriptSearchConstants.CLASS` or `IJavaScriptSearchConstants#INTERFACE` is respectively used instead of `IJavaScriptSearchConstants.TYPE`.
  `matchRule` - one of `R_EXACT_MATCH`, `R_PREFIX_MATCH`, `R_PATTERN_MATCH`, `R_REGEXP_MATCH`, `R_CAMELCASE_MATCH` combined with one of following values: `R_CASE_SENSITIVE`, `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH`. e.g. `R_EXACT_MATCH` | `R_CASE_SENSITIVE` if an exact and case sensitive match is requested, `R_PREFIX_MATCH` if a prefix non case sensitive match is requested or `R_EXACT_MATCH` | `R_ERASURE_MATCH` if a non case sensitive and erasure match is requested.
  Note that `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH` have no effect on non-generic types/methods search.
  Note also that default behavior for generic types/methods search is to find exact matches.
Returns:
  a search pattern on the given string pattern, or `null` if the string pattern is ill-formed

#### createPattern

    public static SearchPattern createPattern(IJavaScriptElement element,
                                              int limitTo)

Returns a search pattern based on a given JavaScript element. The pattern is used to trigger the appropriate search.
Note that for generic searches, the returned pattern consider `R_ERASURE_MATCH` matches. If other kind of generic matches (ie. `R_EXACT_MATCH` or `R_EQUIVALENT_MATCH`) are expected, `createPattern(IJavaScriptElement, int, int)` method need to be used instead with the explicit match rule specified.
The pattern can be parameterized as follows:

Parameters:
  `element` - the JavaScript element the search pattern is based on
  `limitTo` - determines the nature of the expected matches
  - `IJavaScriptSearchConstants.DECLARATIONS`: will search declarations matching with the corresponding element. In case the element is a method, declarations of matching methods in subtypes will also be found, allowing to find declarations of abstract methods, etc. Some additional flags may be specified while searching declaration:
    - `IJavaScriptSearchConstants.IGNORE_DECLARING_TYPE`: declaring type will be ignored during the search.
      For example using following test case:

                            class A { A method() { return null; } }
                            class B extends A { B method() { return null; } }
                            class C { A method() { return null; } }

      search for `method` declaration with this flag will return 2 matches: in A and in C
    - `IJavaScriptSearchConstants.IGNORE_RETURN_TYPE`: return type will be ignored during the search.
      Using same example, search for `method` declaration with this flag will return 2 matches: in A and in B.
    Note that these two flags may be combined and both declaring and return types can be ignored during the search. Then, using same example, search for `method` declaration with these 2 flags will return 3 matches: in A, in B and in C
  - `IJavaScriptSearchConstants.REFERENCES`: will search references to the given element.
  - `IJavaScriptSearchConstants.ALL_OCCURRENCES`: will search for either declarations or references as specified above.
  - `IJavaScriptSearchConstants.IMPLEMENTORS`: for types, will find all types which directly implement/extend a given interface.
Returns:
  a search pattern for a JavaScript element or `null` if the given element is ill-formed

#### createPattern

    public static SearchPattern createPattern(IJavaScriptElement element,
                                              int limitTo,
                                              int matchRule)

Returns a search pattern based on a given JavaScript element. The pattern is used to trigger the appropriate search, and can be parameterized as follows:

Parameters:
  `element` - the JavaScript element the search pattern is based on
  `limitTo` - determines the nature of the expected matches
  - `IJavaScriptSearchConstants.DECLARATIONS`: will search declarations matching with the corresponding element. In case the element is a method, declarations of matching methods in subtypes will also be found, allowing to find declarations of abstract methods, etc. Some additional flags may be specified while searching declaration:
    - `IJavaScriptSearchConstants.IGNORE_DECLARING_TYPE`: declaring type will be ignored during the search.
      For example using following test case:

                            class A { A method() { return null; } }
                            class B extends A { B method() { return null; } }
                            class C { A method() { return null; } }

      search for `method` declaration with this flag will return 2 matches: in A and in C
    - `IJavaScriptSearchConstants.IGNORE_RETURN_TYPE`: return type will be ignored during the search.
      Using same example, search for `method` declaration with this flag will return 2 matches: in A and in B.
    Note that these two flags may be combined and both declaring and return types can be ignored during the search. Then, using same example, search for `method` declaration with these 2 flags will return 3 matches: in A, in B and in C
  - `IJavaScriptSearchConstants.REFERENCES`: will search references to the given element.
  - `IJavaScriptSearchConstants.ALL_OCCURRENCES`: will search for either declarations or references as specified above.
  - `IJavaScriptSearchConstants.IMPLEMENTORS`: for types, will find all types which directly implement/extend a given interface.
  `matchRule` - one of `R_EXACT_MATCH`, `R_PREFIX_MATCH`, `R_PATTERN_MATCH`, `R_REGEXP_MATCH`, `R_CAMELCASE_MATCH` combined with one of following values: `R_CASE_SENSITIVE`, `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH`. e.g. `R_EXACT_MATCH` | `R_CASE_SENSITIVE` if an exact and case sensitive match is requested, `R_PREFIX_MATCH` if a prefix non case sensitive match is requested or `R_EXACT_MATCH` |`R_ERASURE_MATCH` if a non case sensitive and erasure match is requested.
  Note that `R_ERASURE_MATCH` or `R_EQUIVALENT_MATCH` have no effect on non-generic types or methods search.
  Note also that default behavior for generic types or methods is to find exact matches.
Returns:
  a search pattern for a JavaScript element or `null` if the given element is ill-formed

#### decodeIndexKey

    public void decodeIndexKey(char[] key)

Decode the given index key in this pattern. The decoded index key is used by `matchesDecodedKey(SearchPattern)` to find out if the corresponding index entry should be considered.

This method should be re-implemented in subclasses that need to decode an index key.

Parameters:
  `key` - the given index key

#### getBlankPattern

    public abstract SearchPattern getBlankPattern()

Returns a blank pattern that can be used as a record to decode an index key.

Implementors of this method should return a new search pattern that is going to be used to decode index keys.

Returns:
  a new blank pattern
See Also:
  `decodeIndexKey(char[])`

#### getIndexKey

    public char[] getIndexKey()

Returns a key to find in relevant index categories, if null then all index entries are matched. The key will be matched according to some match rule. These potential matches will be further narrowed by the match locator, but precise match locating can be expensive, and index query should be as accurate as possible so as to eliminate obvious false hits.

This method should be re-implemented in subclasses that need to narrow down the index query.

Returns:
  an index key from this pattern, or `null` if all index entries are matched.

#### getIndexCategories

    public char[][] getIndexCategories()

Returns an array of index categories to consider for this index query. These potential matches will be further narrowed by the match locator, but precise match locating can be expensive, and index query should be as accurate as possible so as to eliminate obvious false hits.

This method should be re-implemented in subclasses that need to narrow down the index query.

Returns:
  an array of index categories

#### getMatchRule

    public final int getMatchRule()

Returns the rule to apply for matching index keys. Can be exact match, prefix match, pattern match or regexp match. Rule can also be combined with a case sensitivity flag.

Returns:
  one of R_EXACT_MATCH, R_PREFIX_MATCH, R_PATTERN_MATCH, R_REGEXP_MATCH combined with R_CASE_SENSITIVE, e.g. R_EXACT_MATCH | R_CASE_SENSITIVE if an exact and case sensitive match is requested, or R_PREFIX_MATCH if a prefix non case sensitive match is requested.

#### matchesDecodedKey

    public boolean matchesDecodedKey(SearchPattern decodedPattern)

Returns whether this pattern matches the given pattern (representing a decoded index key).

This method should be re-implemented in subclasses that need to narrow down the index query.

Parameters:
  `decodedPattern` - a pattern representing a decoded index key
Returns:
  whether this pattern matches the given pattern

#### matchesName

    public boolean matchesName(char[] pattern,
                               char[] name)

Returns whether the given name matches the given pattern.

This method should be re-implemented in subclasses that need to define how a name matches a pattern.

Parameters:
  `pattern` - the given pattern, or `null` to represent "*"
  `name` - the given name
Returns:
  whether the given name matches the given pattern

#### matchesQualificationPattern

    public static boolean matchesQualificationPattern(char[] thisQualifiedName,
                                                      char[] otherQualifiedName,
                                                      boolean isCaseSensitive)

Returns whether this pattern's prefix qualifier matches the other patterns qualified name. This pattern's qualifier must have a match rule of pattern match for a match to occur.

Parameters:
  `thisQualifiedName` - this qualifier pattern to inspect
  `otherQualifiedName` - other qualifier pattern to inspect
  `isCaseSensitive` - whether this qualifier pattern is case sensitive
Returns:
  whether this pattern's prefix qualifier matches the other patterns qualified name

#### validateMatchRule

    public static int validateMatchRule(java.lang.String stringPattern,
                                        int matchRule)

Validate compatibility between given string pattern and match rule.
Optimized (ie. returned match rule is modified) combinations are:

- `R_PATTERN_MATCH` without any '*' or '?' in string pattern: pattern match bit is unset,
- `R_PATTERN_MATCH` and `R_PREFIX_MATCH` bits simultaneously set: prefix match bit is unset,
- `R_PATTERN_MATCH` and `R_CAMELCASE_MATCH` bits simultaneously set: camel case match bit is unset,
- `R_CAMELCASE_MATCH` with invalid combination of uppercase and lowercase characters: camel case match bit is unset and replaced with prefix match pattern,
- `R_CAMELCASE_MATCH` combined with `R_PREFIX_MATCH` and `R_CASE_SENSITIVE` bits is reduced to only `R_CAMELCASE_MATCH` as Camel Case search is already prefix and case sensitive,

Rejected (ie. returned match rule -1) combinations are:

- `R_REGEXP_MATCH` with any other match mode bit set,

Parameters:
  `stringPattern` - The string pattern
  `matchRule` - The match rule
Returns:
  Optimized valid match rule or -1 if an incompatibility was detected.

#### isPatternMatch

    public static boolean isPatternMatch(java.lang.String pattern)

Returns whether the given pattern is a pattern case or not.

Parameters:
  `pattern` - the pattern to inspect
Returns:
  whether it is a pattern case or not

#### toString

    public java.lang.String toString()

Overrides:
  `toString` in class `java.lang.Object`
See Also:
  `Object.toString()`