Community
Participate
Working Groups
The Java search constants define the following constants: TYPE CLASS INTERFACE ENUM ANNOTATION_TYPE In 3.0 where we only had classes I could use the constants to express all kinds of type search combinations. Both class and interface or class or interface. Now with Java 5.0, I can only search for all types or separately for classes, interface, enums and annotations. For example I can't specify enum | class.
Unfortunately, current values does not allow to mix them (ENUM+INTERFACE = ANNOTATION_TYPE+CLASS). So, I see 2 solutions: A) Modify existing 3.1 values: - ENUM from 7 to 0x10 - ANNOTATION_TYPE from 8 to 0x20 This would allow user to mix them and specify nature of searched element by adding all foolowing values: CLASS, INTERFACE, ENUM and ANNOTATION_TYPE. Of course SearchEngine should then verify that no other values were added and typically would reject such addition as ENUM+PACKAGE for example. B) Another possibility would be to keep existing values for ENUM and ANNOTATION_TYPE and add other values: 1) all possible ones (ie. 11 additional!) 2) only specific ones: ENUM_AND_CLASSES, INTERFACE_AND_ANNOTATION_TYPE, CLASS_AND_INTERFACE, others...?
Philippe, what's your mind about this?
Modifying API would be done for M6 and implementation done for M7 using already existing bug 88219
Since the constants for ENUM and ANNOTATION_TYPE got added for 3.1 I am in favor to give them a different value so that we are able to combine them. For me it is OK if the implementation happens in M7.
I would also favor solution (A). 3.0 APIs wrt to 1.5 support were best guesses. We clearly got some wrong, and we should fix them. Note that this needs to be recorded somewhere for latter fixing the API migration document.
Jim - is the current direction fine by you in term of API ?
The original Java search constants were an enumeration-style listing of different possible values: UNKNOWN = -1, TYPE= 0, METHOD= 1, PACKAGE= 2, CONSTRUCTOR= 3, FIELD= 4, CLASS= 5, INTERFACE= 6, which did not support any combinations except for the build-in one: TYPE means same as CLASS or INTERFACE. So ENUM = 7 and ANNOTATION_TYPE = 8 follow the original pattern. Suggestion A in comment #1 of turning ENUM and ANNOTATION_TYPE into bit masks that can be ORed with another value is asking for trouble because only some of the constants would be meaningfully OR-able. I favor solution B2, with additional constants that would be genuinely useful. TYPE=0 should probably be construed in the spec to mean INTERFACE or CLASS or ENUM or ANNOTATION_TYPE. If that was done, there would be a way to search for types in general as well as for the 4 specific subkinds. Dirk: Would there be any other combinations that would be useful?
The most useful constants I can think of are (assuming that interface includes annotations since in the Java model/DOM AST annotations.isInterface() == true): ALL_TYPES= CLASS, ENUM, INTEFACE, ANNOTATION CLASS_AND_INTERFACE CLASS_AND_ENUM ENUM_AND_ANNOTATION However, this is a limitation I think we should avoid. What's about doing the following: - we deprecate TYPE, CLASS, and INTERFACE in IJavaSearchConstants - create a IJavaTypeSearchConstants interface with the following values: int CLASS= 5; int INTERFACE= 6; int ENUM= 0x10; int ANNOTATION= 0x20; Although this aren't true bit constants they allow bitwise combination and are compatible with the old style.
I agree that limitation should be avoided as there will be someone to ask for missing ones in the future... So, if it is really annoying to mix OR-able values with not OR-able, I think Dirk proposal in comment 8 is OK. However, in IJavaTypeSearchConstants, I do not understand why it's necessary to keep old values for CLASS and INTERFACE? Why not make this interface a "pure" bit mask template and use: CLASS = 0x10 INTERFACE = 0x20 ENUM = 0x40 ANNOTATION_TYPE = 0x80 ALL_TYPES = CLASS | INTERFACE | ENUM | ANNOTATION_TYPE SearchEngine would map deprecated values to these new ones and user could use this new interface to mix whatever type values he wants...
Correct, search engine could do the mapping.
Mixing bit OR-able masks and enumeration is a bad idea because other clients are likely to think that all values can be used as masks. It will be error prone. Here's a counter proposal: TYPE=0 means classes, interfaces, enumerations, annotation types CLASS=5 means classes and enums only INTERFACE=6 means means interface and annotation types only ENUM=7 means enums only ANNOTATION_TYPE=8 means annotation types only CLASS_AND_INTERFACE=9 means classes and interfaces only
If these OR-able values are in a new interface which explicitely tells user that they are only applyable on types nature and not usable with values of the "old" interface, then I do not understand why we cannot use this solution. What do you think if class and interface values in IJavaTypesSearchConstants have different name: /** * This interface defines nature of searched types. * Note that these values can be combined together but not with nature of * searched elements defined in IJavaSearchConstants. *... */ interface IJavaTypesSearchConstants { CLASS_TYPE = 0x10 INTERFACE_TYPE = 0x20 ENUM_TYPE = 0x40 ANNOTATION_TYPE = 0x80 ALL_TYPES = CLASS | INTERFACE | ENUM | ANNOTATION_TYPE } SearchEngine would verify that user did not try to mix nature of these 2 interfaces by testing that intersection is empty between 0x0F and 0xF0 bits...
Actually, since the search engine provides all information whether a type is a enum, class, interface or annotation in the type name requestor API clients could filter the result set. So only having a predefined set of constants would work. The minimum number is: ALL_TYPES INTEFACES CLASS ENUM ANNOTATION_TYPE ENUM_AND_CLASS (do get all non intefaces)
A limited set of predefined constants retrofitted into the existing ones is simpler than introducing a new class. Here's a list that meets Dirk's requirements: TYPE=0 means classes, interfaces, enumerations, annotation types CLASS=5 means classes only INTERFACE=6 means means interfaces only ENUM=7 means enums only ANNOTATION_TYPE=8 means annotation types only CLASS_AND_ENUM=9 means classes and enums only So the API changes are: - "widen" TYPE to include enumerations, annotation types - add CLASS_AND_ENUM=9 Here's patch (includes missing @since 3.1 tags): Index: IJavaSearchConstants.java =================================================================== RCS file: /home/eclipse/org.eclipse.jdt.core/search/org/eclipse/jdt/core/search/IJa vaSearchConstants.java,v retrieving revision 1.22 diff -u -r1.22 IJavaSearchConstants.java --- IJavaSearchConstants.java 14 Mar 2005 14:40:20 -0000 1.22 +++ IJavaSearchConstants.java 21 Mar 2005 23:30:24 -0000 @@ -32,7 +32,8 @@ /* Nature of searched element */ /** - * The searched element is a type. + * The searched element is a type, which may include classes, interfaces, + * enums, and annotation types. */ int TYPE= 0; @@ -70,15 +71,24 @@ /** * The searched element is an enum. - * More selective than using TYPE + * More selective than using TYPE. + * @since 3.1 */ int ENUM= 7; /** * The searched element is an annotation type. * More selective than using TYPE + * @since 3.1 */ int ANNOTATION_TYPE= 8; + + /** + * The searched element is an enum or an annotation type. + * More selective than using {@link #TYPE}. + * @since 3.1 + */ + int CLASS_AND_ENUM= 9; /* Nature of match */
Oops. There was a bug in the comment for CLASS_AND_ENUM: Index: IJavaSearchConstants.java =================================================================== RCS file: /home/eclipse/org.eclipse.jdt.core/search/org/eclipse/jdt/core/search/IJa vaSearchConstants.java,v retrieving revision 1.22 diff -u -r1.22 IJavaSearchConstants.java --- IJavaSearchConstants.java 14 Mar 2005 14:40:20 -0000 1.22 +++ IJavaSearchConstants.java 21 Mar 2005 23:33:05 -0000 @@ -32,7 +32,8 @@ /* Nature of searched element */ /** - * The searched element is a type. + * The searched element is a type, which may include classes, interfaces, + * enums, and annotation types. */ int TYPE= 0; @@ -70,15 +71,24 @@ /** * The searched element is an enum. - * More selective than using TYPE + * More selective than using TYPE. + * @since 3.1 */ int ENUM= 7; /** * The searched element is an annotation type. * More selective than using TYPE + * @since 3.1 */ int ANNOTATION_TYPE= 8; + + /** + * The searched element is an class or enum type. + * More selective than using {@link #TYPE}. + * @since 3.1 + */ + int CLASS_AND_ENUM= 9; /* Nature of match */
Isn't there a change of behavior with this proposal? Searching for TYPE nature with 3.1 M5 will return only classes and interfaces but would return classes, interfaces, enums and annotations with 3.1 M6. But perhaps we don't care about this kind of change between two 3.1 milestones? If so, I think we should at least also propose a CLASS_AND_INTERFACE value (which wouldn't include annotations) to retrieve previous TYPE behavior...
I don't believe the widening of TYPE should be significant (even if it is a change from M5). And adding CLASS_AND_INTERFACE = 10 rounds things out nicely. Release API change to HEAD.
Thanks Jeem
Verified in I20050330-0500
