Java Doc for SearchPattern.java in  » IDE-Eclipse » jdt » org » eclipse » jdt » core » search » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 SearchPattern.getIndexCategories() and SearchPattern.getIndexKey() , as well as the match rule (see SearchPattern.getMatchRule() ). A blank pattern is then created (see SearchPattern.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 SearchPattern.decodeIndexKey(char[]) . The original pattern is then asked if it matches the decoded key using SearchPattern.matchesDecodedKey(SearchPattern) . If it matches, a search document is created for this index entry using SearchParticipant.getDocument(String) .

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

Examples:

• 'NPE' type string pattern will match 'NullPointerException' and 'NoPermissionException' types,
• 'NuPoEx' type string pattern will only match 'NullPointerException' type.

• 'HM' type string pattern will match 'HashMap' and 'HtmlMapper' types, but not 'HashMapEntry'
• 'HMap' type string pattern will match 'HashMap' type but not 'HtmlMapper'.

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

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

• pattern: List<Exception>
• match: List<Object>

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

• SearchPattern.R_PATTERN_MATCH without any '*' or '?' in string pattern:
  => pattern match flag is reset,
• SearchPattern.R_PATTERN_MATCH and SearchPattern.R_PREFIX_MATCH flags simultaneously set:
   => prefix match flag is reset,
• SearchPattern.R_PATTERN_MATCH and SearchPattern.R_CAMEL_CASE_MATCH (or deprecated SearchPattern.R_CAMELCASE_MATCH ) flags simultaneously set:
   => camel case match flag is reset,
• SearchPattern.R_CAMEL_CASE_MATCH (or deprecated SearchPattern.R_CAMELCASE_MATCH ) with invalid combination of uppercase and lowercase characters:
   => camel case match flag is reset and replaced with prefix match pattern,
  
• The deprecated SearchPattern.R_CAMELCASE_MATCH flag combined with SearchPattern.R_PREFIX_MATCH and SearchPattern.R_CASE_SENSITIVE flags is reduced to deprecated SearchPattern.R_CAMELCASE_MATCH flag only,

Examples:

• 'NPE' type string pattern will match 'NullPointerException' and 'NoPermissionException' types,
• 'NuPoEx' type string pattern will only match 'NullPointerException' type.

Match rule SearchPattern.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.

See Also:   SearchPattern.camelCaseMatch(String,String)
See Also:    for a detailed explanation of Camel
See Also:   Case matching.
since:
   3.2SearchPattern.R_CAMEL_CASE_MATCHSearchPattern.R_PREFIX_MATCH

• 'HM' type string pattern will match 'HashMap' and 'HtmlMapper' types, but not 'HashMapEntry'
• 'HMap' type string pattern will match 'HashMap' type but not 'HtmlMapper'.

This rule still can be combined to prefix match to accept prefix matches ('HashMap' pattern matching 'HashMapEntry' name). It can also be combined to case sensitive match to reject case insensitive matches ('HAMA' pattern will not match 'HashMap' name).

If SearchPattern.R_PATTERN_MATCH rule is also combined, then the real used match rule will depend 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.

See Also:   CharOperation.camelCaseMatch(char[]char[]boolean)
See Also:    for a detailed
See Also:   explanation of Camel Case matching.
See Also:   

since:
   3.4

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

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

• pattern: List<Exception>
• match: List<Object>

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

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

Digit characters are treated in a special way. They can be used in the pattern but are not always considered as leading character. For instance, both 'UTF16DSS' and 'UTFDSS' patterns will match 'UTF16DocumentScannerSupport'.

This method allows prefix match in Camel Case (see SearchPattern.camelCaseMatch(String,String,boolean) ).

 Examples:
 
  pattern = "NPE"
 name = NullPointerException / NoPermissionException
 result => true
 
  pattern = "NuPoEx"
 name = NullPointerException
 result => true
 
  pattern = "npe"
 name = NullPointerException
 result => false
 
  pattern = "IPL3"
 name = "IPerspectiveListener3"
 result => true
 
  pattern = "HM"
 name = "HashMapEntry"
 result => true
 
  pattern = "HMap"
 name = "HatMapper"
 result => true
 

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

Digit characters are treated in a special way. They can be used in the pattern but are not always considered as leading character. For instance, both 'UTF16DSS' and 'UTFDSS' patterns will match 'UTF16DocumentScannerSupport'.

CamelCase may or may not match prefixes depending on the given parameter. When the prefix match parameter is true, the given pattern can match only a prefix of the given name. For instance, 'HM' , 'HaMa' and 'HMap' patterns will all match 'HashMap', 'HatMapper' and 'HashMapEntry'.
Reversely, if the prefix match parameter is false, then pattern and name must have exactly the same number of parts, and their last parts must be identical if they contain lowercase characters. For instance, 'HMap' and 'HaMap' patterns will match 'HashMap' but neither 'HashMapEntry' nor 'HatMapper'. Note that when the last part does not contain lowercase characters, then the name may end with lowercase characters. So, 'HM' pattern will match both 'HashMap' and 'HatMapper' but will not match 'HashMapEntry'.

 Examples:
 
  pattern = "NPE"
 name = NullPointerException / NoPermissionException
 result => true
 
  pattern = "NuPoEx"
 name = NullPointerException
 result => true
 
  pattern = "npe"
 name = NullPointerException
 result => false
 
  pattern = "IPL3"
 name = "IPerspectiveListener3"
 result => true
 
  pattern = "HM"
 name = "HashMapEntry"
 result => (prefixMatch == true)
 
  pattern = "HMap"
 name = "HatMapper"
 result => (prefixMatch == true)
 

• For example, when it's true:
  - HM type string pattern will matchHashMap and HtmlMapper types,but not HashMapEntry
  - HMap type string pattern will matchHashMap type but not HtmlMapper.
• and, when it's false:
  - HM type string pattern will match both HashMap and HtmlMapperand HashMapEntry
  - HMap type string pattern will match bothHashMap and HtmlMapper types.

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

Digit characters are treated in a special way. They can be used in the pattern but are not always considered as leading character. For instance, both 'UTF16DSS' and 'UTFDSS' patterns will match 'UTF16DocumentScannerSupport'.

Digit characters are treated in a special way. They can be used in the pattern but are not always considered as leading character. For instance, both 'UTF16DSS' and 'UTFDSS' patterns will match 'UTF16DocumentScannerSupport'.

This method allows prefix match in Camel Case (see SearchPattern.camelCaseMatch(String,int,int,String,int,int,boolean) ).

Examples:

 
  pattern = "NPE"
 patternStart = 0
 patternEnd = 3
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => true
 
  pattern = "NPE"
 patternStart = 0
 patternEnd = 3
 name = NoPermissionException
 nameStart = 0
 nameEnd = 21
 result => true
 
  pattern = "NuPoEx"
 patternStart = 0
 patternEnd = 6
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => true
 
  pattern = "NuPoEx"
 patternStart = 0
 patternEnd = 6
 name = NoPermissionException
 nameStart = 0
 nameEnd = 21
 result => false
 
  pattern = "npe"
 patternStart = 0
 patternEnd = 3
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => false
 
  pattern = "IPL3"
 patternStart = 0
 patternEnd = 3
 name = "IPerspectiveListener3"
 nameStart = 0
 nameEnd = 21
 result => true
 
  pattern = "HM"
 patternStart = 0
 patternEnd = 2
 name = "HashMapEntry"
 nameStart = 0
 nameEnd = 12
 result => true
 
  pattern = "HMap"
 patternStart = 0
 patternEnd = 4
 name = "HatMapper"
 nameStart = 0
 nameEnd = 9
 result => true
 

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

Digit characters are treated in a special way. They can be used in the pattern but are not always considered as leading character. For instance, both 'UTF16DSS' and 'UTFDSS' patterns will match 'UTF16DocumentScannerSupport'.

CamelCase may or may not match prefixes depending on the given parameter. When the prefix match parameter is true, the given pattern can match only a prefix of the given name. For instance, 'HM' , 'HaMa' and 'HMap' patterns will all match 'HashMap', 'HatMapper' and 'HashMapEntry'.
Reversely, if the prefix match parameter is false, then pattern and name must have exactly the same number of parts, and their last parts must be identical if they contain lowercase characters. For instance, 'HMap' and 'HaMap' patterns will match 'HashMap' but neither 'HashMapEntry' nor 'HatMapper'. Note that when the last part does not contain lowercase characters, then the name may end with lowercase characters. So, 'HM' pattern will match both 'HashMap' and 'HatMapper' but will not match 'HashMapEntry'.

Examples:

 
  pattern = "NPE"
 patternStart = 0
 patternEnd = 3
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => true
 
  pattern = "NPE"
 patternStart = 0
 patternEnd = 3
 name = NoPermissionException
 nameStart = 0
 nameEnd = 21
 result => true
 
  pattern = "NuPoEx"
 patternStart = 0
 patternEnd = 6
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => true
 
  pattern = "NuPoEx"
 patternStart = 0
 patternEnd = 6
 name = NoPermissionException
 nameStart = 0
 nameEnd = 21
 result => false
 
  pattern = "npe"
 patternStart = 0
 patternEnd = 3
 name = NullPointerException
 nameStart = 0
 nameEnd = 20
 result => false
 
  pattern = "IPL3"
 patternStart = 0
 patternEnd = 3
 name = "IPerspectiveListener3"
 nameStart = 0
 nameEnd = 21
 result => true
 
  pattern = "HM"
 patternStart = 0
 patternEnd = 2
 name = "HashMapEntry"
 nameStart = 0
 nameEnd = 12
 result => (prefixMatch == true)
 
  pattern = "HMap"
 patternStart = 0
 patternEnd = 4
 name = "HatMapper"
 nameStart = 0
 nameEnd = 9
 result => (prefixMatch == true)
 

• For example, when it's true:
  - HM type string pattern will matchHashMap and HtmlMapper types,but not HashMapEntry
  - HMap type string pattern will matchHashMap type but not HtmlMapper.
• and, when it's false:
  - HM type string pattern will match both HashMap and HtmlMapperand HashMapEntry
  - HMap type string pattern will match bothHashMap and HtmlMapper types.

• 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);

• IJavaSearchConstants.CLASS: only look for classes
• IJavaSearchConstants.INTERFACE: only look for interfaces
• IJavaSearchConstants.ENUM: only look for enumeration
• IJavaSearchConstants.ANNOTATION_TYPE: only look for annotation type
• IJavaSearchConstants.CLASS_AND_ENUM: only look for classes and enumerations
• IJavaSearchConstants.CLASS_AND_INTERFACE: only look for classes and interfaces
• IJavaSearchConstants.TYPE: look for all types (i.e. classes, interfaces, enum and annotation types)
• IJavaSearchConstants.FIELD: look for fields
• IJavaSearchConstants.METHOD: look for methods
• IJavaSearchConstants.CONSTRUCTOR: look for constructors
• IJavaSearchConstants.PACKAGE: look for packages

• IJavaSearchConstants.DECLARATIONS: will search declarations matchingwith the corresponding element. In case the element is a method, declarations of matchingmethods in sub-types will also be found, allowing to find declarations of abstract methods, etc.
  Note that additional flags IJavaSearchConstants.IGNORE_DECLARING_TYPE andIJavaSearchConstants.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.
• IJavaSearchConstants.REFERENCES: will search references to the given element.
• IJavaSearchConstants.ALL_OCCURRENCES: will search for either declarations orreferences as specified above.
• IJavaSearchConstants.IMPLEMENTORS: for types, will find all typeswhich directly implement/extend a given interface.Note that types may be only classes or only interfaces if IJavaSearchConstants.CLASS orIJavaSearchConstants.INTERFACE is respectively used instead of IJavaSearchConstants.TYPE.

• IJavaSearchConstants.DECLARATIONS: will search declarations matchingwith the corresponding element. In case the element is a method, declarations of matchingmethods in sub-types will also be found, allowing to find declarations of abstract methods, etc.Some additional flags may be specified while searching declaration:
  • IJavaSearchConstants.IGNORE_DECLARING_TYPE: declaring type will be ignoredduring 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 flagwill return 2 matches: in A and in C
  • IJavaSearchConstants.IGNORE_RETURN_TYPE: return type will be ignoredduring the search.
    Using same example, search for method declaration with this flagwill return 2 matches: in A and in B.
  Note that these two flags may be combined and both declaring and return types can be ignoredduring the search. Then, using same example, search for method declarationwith these 2 flags will return 3 matches: in A, in B and in C
• IJavaSearchConstants.REFERENCES: will search references to the given element.
• IJavaSearchConstants.ALL_OCCURRENCES: will search for either declarations orreferences as specified above.
• IJavaSearchConstants.IMPLEMENTORS: for types, will find all typeswhich directly implement/extend a given interface.

• IJavaSearchConstants.DECLARATIONS: will search declarations matchingwith the corresponding element. In case the element is a method, declarations of matchingmethods in sub-types will also be found, allowing to find declarations of abstract methods, etc.Some additional flags may be specified while searching declaration:
  • IJavaSearchConstants.IGNORE_DECLARING_TYPE: declaring type will be ignoredduring 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 flagwill return 2 matches: in A and in C
  • IJavaSearchConstants.IGNORE_RETURN_TYPE: return type will be ignoredduring the search.
    Using same example, search for method declaration with this flagwill return 2 matches: in A and in B.
  Note that these two flags may be combined and both declaring and return types can be ignoredduring the search. Then, using same example, search for method declarationwith these 2 flags will return 3 matches: in A, in B and in C
• IJavaSearchConstants.REFERENCES: will search references to the given element.
• IJavaSearchConstants.ALL_OCCURRENCES: will search for either declarations orreferences as specified above.
• IJavaSearchConstants.IMPLEMENTORS: for types, will find all typeswhich directly implement/extend a given interface.

This method should be re-implemented in subclasses that need 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.

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

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

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

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

• SearchPattern.R_PATTERN_MATCH without any '*' or '?' in string pattern:
  => pattern match flag is reset,
• SearchPattern.R_PATTERN_MATCH and SearchPattern.R_PREFIX_MATCH flags simultaneously set:
   => prefix match flag is reset,
• SearchPattern.R_PATTERN_MATCH and SearchPattern.R_CAMEL_CASE_MATCH (or deprecated SearchPattern.R_CAMELCASE_MATCH ) flags simultaneously set:
   => camel case match flag is reset,
• SearchPattern.R_CAMEL_CASE_MATCH (or deprecated SearchPattern.R_CAMELCASE_MATCH ) with invalid combination of uppercase and lowercase characters:
   => camel case match flag is reset and replaced with prefix match pattern,
  
• The deprecated SearchPattern.R_CAMELCASE_MATCH flag combined with SearchPattern.R_PREFIX_MATCH and SearchPattern.R_CASE_SENSITIVE flags is reduced to deprecated SearchPattern.R_CAMELCASE_MATCH flag only,

• SearchPattern.R_REGEXP_MATCH with any other match mode flag set,