Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse JDT Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jdt.core.search
Class SearchPattern

    java.lang.Object
      org.eclipse.jdt.internal.core.search.matching.InternalSearchPattern
          org.eclipse.jdt.core.search.SearchPattern

public abstract class SearchPattern
extends org.eclipse.jdt.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.

Since:
  3.0
See Also:
  `createPattern(org.eclipse.jdt.core.IJavaElement, int)`, `createPattern(String, int, int, int)`

Field Summary
`static int` | `R_CASE_SENSITIVE` Match rule: The search pattern matches the search result only if cases are the same.
`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_PATTERN_MATCH` Match rule: The search pattern contains one or more wild cards ('*') where a wild-card can replace 0 or more characters in the search result.
`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
`SearchPattern(int matchRule)` Creates a search pattern with the rule to apply for matching index keys.

Method Summary
`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(IJavaElement element, int limitTo)` Returns a search pattern based on a given Java element.
`static SearchPattern` | `createPattern(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.
`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.
`String` | `toString()`

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 ('*') where a wild-card can replace 0 or more characters 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

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 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.

Method Detail

### 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(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
    - `IJavaSearchConstants.CLASS`: only look for classes
    - `IJavaSearchConstants.INTERFACE`: only look for interfaces
    - `IJavaSearchConstants.TYPE`: look for both classes and interfaces
    - `IJavaSearchConstants.FIELD`: look for fields
    - `IJavaSearchConstants.METHOD`: look for methods
    - `IJavaSearchConstants.CONSTRUCTOR`: look for constructors
    - `IJavaSearchConstants.PACKAGE`: look for packages
    `limitTo` - determines the nature of the expected matches
    - `IJavaSearchConstants.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.
    - `IJavaSearchConstants.REFERENCES`: will search references to the given element.
    - `IJavaSearchConstants.ALL_OCCURRENCES`: will search for either declarations or references as specified above.
    - `IJavaSearchConstants.IMPLEMENTORS`: for interface, will find all types which implements a given interface.
    `matchRule` - 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.
  Returns:
    a search pattern on the given string pattern, or `null` if the string pattern is ill-formed

### createPattern

    public static SearchPattern createPattern(IJavaElement element,
                                              int limitTo)

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

  Parameters:
    `element` - the Java element the search pattern is based on
    `limitTo` - determines the nature of the expected matches
    - `IJavaSearchConstants.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.
    - `IJavaSearchConstants.REFERENCES`: will search references to the given element.
    - `IJavaSearchConstants.ALL_OCCURRENCES`: will search for either declarations or references as specified above.
    - `IJavaSearchConstants.IMPLEMENTORS`: for interface, will find all types which implements a given interface.
  Returns:
    a search pattern for a Java 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

### toString

    public String toString()

  See Also:
    `Object.toString()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse JDT Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) IBM Corp. and others 2000, 2004. All Rights Reserved.