Community
Participate
Working Groups
20060824 A first step toward more advanced searching would be to offer more finegrained search criterias. Currently it is only possible to find all type references of 'X'. It would be nice to distinguish the references by the AST-location where they were used. For example inside as a cast type ((X) a).foo()) or as a variable type. (X var;) type reference locations: - reference in field type - reference in variable type - reference in method return type - reference in method parameters - reference in throws declaration - reference in super class - reference in super interface declaration - reference in catch block - reference in cast - reference in static member access (X.foo()) - reference in class instance creation (new X()) - reference in class literal access (foo(X.class)) - reference in type variable bounds (class A<E extends X>) - reference in import declaration (import p.X;) - reference in annotation (@X void foo()) - reference in annotation argument (@A(arg=@X)) void foo()) - reference as parameterized type argument (List<X>) - reference as wild card bound (? extends X) The last 2 options could probably be combined with the other bits ('A<X> foo;' X matches if 'parameterized type argument' and 'variable type' are set) method reference locations: - as super invocation (super.x()) - with qualifier (a.x()) - with this (this.x() or x()) - as annotation argument (@A(x="Hello")) field reference locations: - with qualifier (a.x()) - with this (this.x() or x()) - read access - write access This information would best be returned when a match is found. Or/and a mask is passed on search so only those references are reported.
Unfortunately, I had not enough time to implement this requirement for 3.3 M3. Need to make decision for M4 if this bug will still stay in plan or not...
Definitely not for 3.3 M5 and not sure this will be done for 3.3, only if time permit...
I'm afraid we won't be able to address this requirement for 3.3 => defer
The ability to search for types in reference annotation declarations is definitely something that we would like to build upon in to provide rich tooling around Java and EE 5 annotations. Can this be contained for 3.4?
Reopening. Either a general story or a story for specific scenarii could be considered (do we know them?)
The most general solution would of course be a SearchRequestor that can return the ASTNode of a match, such that clients can extract what they need.
We need an efficient story if possible too. If the pattern is not super specific, then we may end up in a situation where performance is really bad, as it would force us to create a DOM AST for each individual match (and I suspect with bindings). The current match locator is optimized to avoid resolving when unnecessary (which as soon as you ask for DOM AST+bindings is simply doing much more work).
Our particular interest area is for annotations. The scenario is for annotations that the user will take advantage of and not that the annotation implementation class will be changed. Here are some searches I can think of: 1. Searching class files for use of the annotation e.g. @Deprecated at the various Java Element scopes. 2. Search for a particular combination of an annotation with attribute e.g. @StandardAnnotation(name = "foo") 3. Search for the use of either 1 and 2 above, but also allow us to specify the context around it. a. Java Element the annotation is specified on b. Whether it is a class, interface, etc of a particular type
(In reply to comment #8) > Our particular interest area is for annotations. The scenario is for > annotations that the user will take advantage of and not that the annotation > implementation class will be changed. > > Here are some searches I can think of: > 1. Searching class files for use of the annotation > e.g. @Deprecated at the various Java Element scopes. This point looks like the comment 0 "reference in annotation (@X void foo())" > 2. Search for a particular combination of an annotation with attribute > e.g. @StandardAnnotation(name = "foo") This point seems to be different from comment 0 "reference in annotation argument (@A(arg=@X)) void foo())"... Can you confirm that you are you looking for StandardAnnotation references using "name" member? Which means that @StandardAnnotation, @StandardAnnotation(text = "blabla") or @StandardAnnotation(name = "foo", text = "blabla") would not be returned by SearchEngine... > 3. Search for the use of either 1 and 2 above, but also allow us to > specify the context around it. > a. Java Element the annotation is specified on > b. Whether it is a class, interface, etc of a particular type > IMO, Search context looks more like bug 110157 and would require too much work (not on 3.4 plan...).
(In reply to comment #8) > 3. Search for the use of either 1 and 2 above, but also allow us to > specify the context around it. > a. Java Element the annotation is specified on So you have an IJavaElement in hands, and you want to search for references to an annotation on this IJavaElement ? In this case, I would suggest to use a search scope that would contain only your IJavaElement. If by "Java Element" you meant something else than an IJavaElement, could you please elaborate ? > b. Whether it is a class, interface, etc of a particular type As Frederic said, this would be much harder to get. Could you please give the use case for this ?
Here is the way we intend to implement this functionality... Fine grain would be specified in SearchPattern using an additional parameter on createPattern(*) method. This parameter - which could be named something like 'fineGrain' - would be a bit pattern combining several flags defined in IJavaSearchConstants. The list of supported flags will be finalized later... The specified fine grain flags would be stored in the created pattern and accessible through pattern locator method (e.g. PatternLocator#fineGrain() method) overridden on specific pattern locator. Note that if user would not specify any fine grain flags, then they would have to be all enabled to allow all matches to be reported as before... Search Engine would then filter possible matches during the parse of the source. The MatchLocatorParser would set fine grain flags while consuming specific nodes and then, pattern locator would verify during match verification if the pattern fine grain flags match the current parsed ones. Theoretically, it should possible to filer *all* fine grain flags during the "parse phase" and avoid other specific fine grain tests during the "locating phase" of the search. Some (or all?) fine grain filters might also be done during indexing. Typically, annotation used as modifier could be stored in a specific index category (e.g. 'annotRef') instead of common one 'ref' and speed-up search request by parsing only files with this kind of references. I do not know what could be the interface to give user access to this kind of Java Search request. I just prototyped small changes to current Java Search page by adding a new group where flags can be set onto this new parameter. I'm quite sure this would not be the final interface as I know JDT/UI already thinks this dialog is too complex...
(In reply to comment #9) > (In reply to comment #8) > > 1. Searching class files for use of the annotation > > e.g. @Deprecated at the various Java Element scopes. > This point looks like the comment 0 "reference in annotation (@X void foo())" > Correct > > 2. Search for a particular combination of an annotation with attribute > > e.g. @StandardAnnotation(name = "foo") > This point seems to be different from comment 0 "reference in annotation > argument (@A(arg=@X)) void foo())"... > Can you confirm that you are you looking for StandardAnnotation references > using "name" member? Which means that @StandardAnnotation, > @StandardAnnotation(text = "blabla") or @StandardAnnotation(name = "foo", text > = "blabla") would not be returned by SearchEngine... > Close. The search should return results where a. a name member exists From your examples @StandardAnnotation(name = "foo", text = "blabla") would be returned. b. optionally the name member contains a certain value > > 3. Search for the use of either 1 and 2 above, but also allow us to > > specify the context around it. > > a. Java Element the annotation is specified on > > b. Whether it is a class, interface, etc of a particular type > > > IMO, Search context looks more like bug 110157 and would require too much work > (not on 3.4 plan...). > For "a." above, it really relies on Java element properties to say search for uses of an annotation as applied to a method, or class, but not to a specific method or class. This wouldn't be template based search as 110157 implies. For "b.", bug 110157 would serve the purpose but is less crucial.
comment 11 sounds very good.
Some more thoughts. If finegrain flags are passed to a search pattern to better discriminate; it should be possible to ask a search match for the same information. Like if you search for all refs to a given type, you could be interested to know that certain matches were located inside annotations, without doing a separate query. Taking some distance a little, scopes are usually used for narrowing the location of a match (i.e. look for type refs inside type X). Shouldn't thus scope be enhanced to express more sophisticated locations ? Like inside annotations ? I could imagine an approach where a scope could be even given some search patterns (declaration patterns), so you could search for reference to type IOException inside #main(*) methods. So it would only take the addition of a pattern for representing an annotation, so as to be able to combine it in the scope: search for type ref X inside annotations
As the first needed fine grain flavor would be about annotations (see comment 8), it seems necessary to set a dependency on bug 79112... Indeed, we need to wait for new Java Model annotation element (likely IAnnotationReference) as it will be returned in the SearchMatch while searching for annotation references...
Re: comment 14. Thinking more of richer scope, I don't them scaling with some possible future finegrain search, e.g. caught exception types, thrown exception types, cast types, etc... Hence it feels the flag approach would evolve better along these lines.
(In reply to comment #16) > Re: comment 14. > Thinking more of richer scope, I don't them scaling with some possible future > finegrain search, e.g. caught exception types, thrown exception types, cast > types, etc... > > Hence it feels the flag approach would evolve better along these lines. > Agreed. I think this kind of fine grain search should be addressed on another bug (bug 110157 or a new one if necessary)... The JavaSearchScope approach will then be used in this bug for all refining information expressed through a search pattern based on a java element. Comment 8 point 3.a) would be a typical example of this. Let's say that the client wants to perform a search request on references of @SandardAnnotation annotation which are applied on all "foo" methods... Then, the SearchEngine request search pattern would be a new pattern AnnotationReferencePattern ("Deprecated", limitTo: REFERENCES) and the fine grain search pattern a MethodPattern ("foo", limitTo: DECLARATIONS). The latter would be set onto the IJavaSearchScope using a new SearchEngine API method: #createJavaSearchScope(IJavaElement[], int, SearchPattern)
Once bug 79112 is fixed, should we also change the behavior of SearchMatch#getElement() to return an IAnnotation ? Pros: It would follow the spec: "In case of a reference match, this is the inner-most enclosing element of the reference." Cons: It would break clients that assume that the element can be navigated to from the Java mnodel root using getChildren() (like the Search view ?)
> Once bug 79112 is fixed, should we also change the behavior of > SearchMatch#getElement() to return an IAnnotation ? I'd say no. You could argue that an enclosing element must have the child listed in getChildren(), which is not the case for bastard IJavaElements (IAnnotation, ITypeParameter, ILocalVariable). See also ITypeRoot.getElementAt(int). Matches in type parameters and local variables are currently also attributed to their parent.
After talking about the possible implementation for this with Jerome, we agreed on the fact that both approaches may be implemented. So, I have opened new bug 209625 to track work on scope as suggested by Philippe in comment 14 and I will keep this bug to track work on additional parameter of SearchPattern#createPattern(...) methods as described in comment 11.
> Once bug 79112 is fixed, should we also change the behavior of > SearchMatch#getElement() to return an IAnnotation ? In case we later find that somebody needs more specific local elements, this could be added later, similar to how we've already done with TypeReferenceMatch#getLocalElement(), etc. .
(In reply to comment #21) > In case we later find that somebody needs more specific local elements, this > could be added later, similar to how we've already done with > TypeReferenceMatch#getLocalElement(), etc. . > Can't getLocalElement() return the IAnnotation in this case and modify the javadoc accordingly?
> Can't getLocalElement() return the IAnnotation in this case [..] That would be OK for me once bug 209661 is fixed. (And I just fixed a bug in RenameTypeProcessor that would have been revealed by this change ;-). However, up to now, only TypeReferenceMatch declares getLocalElement(). If you return IAnnotations as local elements, then you also have to add this query to other search matches for consistency (e.g. to MethodReferenceMatch for member value pair names).
(In reply to comment #23) > That would be OK for me once bug 209661 is fixed. (And I just fixed a bug in > RenameTypeProcessor that would have been revealed by this change ;-). > > However, up to now, only TypeReferenceMatch declares getLocalElement(). If you > return IAnnotations as local elements, then you also have to add this query to > other search matches for consistency (e.g. to MethodReferenceMatch for member > value pair names). > Annotations can be used on local variable (bug 209778 is an example). In this case we could not used the local element to report both the local variable and the annotation. So, I think that my suggestion in comment 22 was not a good idea and I finally agree to add this later if it would become necessary...
Finally the API change to implement is simpler than described in comment 11. If we agree that fine grained functionality is just a stronger limitation specified while creating the pattern, no additional parameter is necessary. We just need to add flags on limitTo parameter. Here's a first list of possible flags covering several of the required type references contexts described in comment 0: /** * Return only references to type used in field type declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int FIELD_TYPE_DECLARATION_TYPE_REFERENCE = 0x00000040; /** * Return only references to type used in local variable declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int LOCAL_VARIABLE_DECLARATION_TYPE_REFERENCE = 0x00000080; /** * Return only references to type used in method parameter declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int PARAMETER_TYPE_DECLARATION_TYPE_REFERENCE = 0x00000100; /** * Return only references to type used as superclass type. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int SUPERCLASS_TYPE_REFERENCE = 0x00000200; /** * Return only references to types used in throws clause. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int THROWS_CLAUSE_TYPE_REFERENCE = 0x00000400; /** * Return only reference to types used in a cast expression. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int CAST_TYPE_REFERENCE = 0x00000800; /** * Return only reference to types used in an allocation expression. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int ALLOCATION_EXPRESSION_TYPE_REFERENCE = 0x00001000; /** * Return only reference to types used as method return type. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int RETURN_TYPE_REFERENCE = 0x00002000; /** * Return only reference to types used in import declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch type reference * matches} will be returned. *</p> * @since 3.4 * @category limitTo */ int IMPORT_DECLARATION_TYPE_REFERENCE = 0x00004000; I will work on methods and fields references contexts. Martin, please let me know if there are some other type references you think it could be interesting/necessary to add in the list above...
I've spawned bug 209996 to continue the discussion on returning IAnnotations from getLocalElement() (see comment 18 to comment 24). (In reply to comment #25) Here are my comments to the missing cases from the list in comment 0: - reference in super interface declaration I would change SUPERCLASS_TYPE_REFERENCE to SUPERTYPE_TYPE_REFERENCE and support interfaces there as well. - reference in catch block This would be really helpful (see also blocked bug 73205) - reference in type variable bounds (class A<E extends X>) - reference as parameterized type argument (List<X>) - reference as wild card bound (? extends X) These can probably already be expressed with pattern searches (see bug 208260). - reference in annotation (@X void foo()) Can be done on the client side if bug 209996 is implemented. Otherwise, bug 204682 would require an ANNOTATION_TYPE_REFERENCE. - reference in static member access (X.foo()) - reference in class literal access (foo(X.class)) - reference in annotation argument (@A(arg=@X)) void foo()) Less interesting, OK to drop for now.
Here's the new API proposal addressing all flags requested in comment 26: /** * Return only references to type used in field type declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int FIELD_TYPE_DECLARATION_TYPE_REFERENCE = 0x40; /** * Return only references to type used in local variable declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int LOCAL_VARIABLE_DECLARATION_TYPE_REFERENCE = 0x80; /** * Return only references to type used in method parameter declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int PARAMETER_TYPE_DECLARATION_TYPE_REFERENCE = 0x100; /** * Return only references to type used as super type. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int SUPERTYPE_TYPE_REFERENCE = 0x200; /** * Return only references to type used as super interface. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int SUPERINTERFACE_TYPE_REFERENCE = 0x400; /** * Return only references to types used in throws clause. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int THROWS_CLAUSE_TYPE_REFERENCE = 0x800; /** * Return only reference to types used in a cast expression. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int CAST_TYPE_REFERENCE = 0x1000; /** * Return only reference to types used in a catch header. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int CATCH_TYPE_REFERENCE = 0x2000; /** * Return only reference to types used in an allocation expression. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int ALLOCATION_EXPRESSION_TYPE_REFERENCE = 0x4000; /** * Return only reference to types used as method return type. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int RETURN_TYPE_REFERENCE = 0x8000; /** * Return only reference to types used in import declaration. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int IMPORT_DECLARATION_TYPE_REFERENCE = 0x10000; /** * Return only reference to types used as annotation. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int ANNOTATION_TYPE_REFERENCE = 0x20000; /** * Return only reference to types used as type variable bound. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int TYPE_VARIABLE_BOUND_TYPE_REFERENCE = 0x40000; /** * Return only reference to types used as parameterized type. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int PARAMETERIZED_TYPE_REFERENCE = 0x80000; /** * Return only reference to types used as wildcard bound. * <p> * When this flag is used, only {@link TypeReferenceMatch} matches will be * returned. *</p> * @since 3.4 * @category limitTo */ int WILDCARD_BOUND_TYPE_REFERENCE = 0x100000; /** * Return only super field accesses or method invocations (e.g. using * <code>super</code> qualifier). * <p> * When this flag is used, the kind of returned matches will depend on the * specified nature of searched element: * <ul> * <li>for {@link #FIELD} nature, only {@link FieldReferenceMatch} matches * will be accepted,</li> * <li>for {@link #METHOD} nature, only {@link MethodReferenceMatch} * matches will be returned</li> * </ul> *</p> * @since 3.4 * @category limitTo */ int SUPER_REFERENCE = 0x1000000; /** * Return only qualified field accesses or method invocations. * <p> * When this flag is used, the kind of returned matches will depend on the * specified nature of searched element: * <ul> * <li>for {@link #FIELD} nature, only {@link FieldReferenceMatch} matches * will be accepted,</li> * <li>for {@link #METHOD} nature, only {@link MethodReferenceMatch} * matches will be returned</li> * </ul> *</p> * @since 3.4 * @category limitTo */ int QUALIFIED_REFERENCE = 0x2000000; /** * Return only primary field accesses or method invocations (e.g. using * <code>this</code> qualifier). * <p> * When this flag is used, the kind of returned matches will depend on the * specified nature of searched element: * <ul> * <li>for {@link #FIELD} nature, only {@link FieldReferenceMatch} matches * will be accepted,</li> * <li>for {@link #METHOD} nature, only {@link MethodReferenceMatch} * matches will be returned</li> * </ul> *</p> * @since 3.4 * @category limitTo */ int THIS_REFERENCE = 0x4000000; /** * Return only field accesses or method invocations without any qualification. * <p> * When this flag is used, the kind of returned matches will depend on the * specified nature of searched element: * <ul> * <li>for {@link #FIELD} nature, only {@link FieldReferenceMatch} matches * will be accepted,</li> * <li>for {@link #METHOD} nature, only {@link MethodReferenceMatch} * matches will be returned</li> * </ul> *</p> * @since 3.4 * @category limitTo */ int IMPLICIT_THIS_REFERENCE = 0x8000000;
Some remarks on comment 26 requests: >> - reference in super interface declaration > I would change SUPERCLASS_TYPE_REFERENCE to SUPERTYPE_TYPE_REFERENCE and > support interfaces there as well. > done >> - reference in catch block > This would be really helpful (see also blocked bug 73205) > done >> - reference in type variable bounds (class A<E extends X>) >> - reference as parameterized type argument (List<X>) >> - reference as wild card bound (? extends X) > These can probably already be expressed with pattern searches > (see bug 208260). > This is not true. User can only specify type parameters of generic type(s) or type arguments of a parameterized type(s) using the string pattern. So, this kind of search will only be possible with the following fine grain search flags: - TYPE_VARIABLE_BOUND_TYPE_REFERENCE - PARAMETERIZED_TYPE_REFERENCE - WILDCARD_BOUND_TYPE_REFERENCE > - reference in annotation (@X void foo()) > Can be done on the client side if bug 209996 is implemented. Otherwise, bug > 204682 would require an ANNOTATION_TYPE_REFERENCE. > Finally implemented with the ANNOTATION_TYPE_REFERENCE fine grain search flag. > - reference in static member access (X.foo()) > - reference in class literal access (foo(X.class)) > - reference in annotation argument (@A(arg=@X)) void foo()) > Less interesting, OK to drop for now. > Not implemented
Created attachment 83867 [details] Proposed patch
Created attachment 83868 [details] JavaSearchPage to activate the fine grain flags Here's a JDT/UI patch I wrote to test these additional flags in a runtime workbench.
Created attachment 83882 [details] New proposed patch Sorry, a little glitch was present in previous posted patch which made several JDT/UI tests failing... This should be fixed with this new patch
Released for 3.4M4 in HEAD stream. Note that I've released the code as early as possible to allow JDT/UI playing with this new functionality. However, I'm still running complementary tests and may tune the code in near future (especially the documentation)...
*** Bug 73205 has been marked as a duplicate of this bug. ***
Verified for 3.4 M4 using build I20071211-0010
