[jvm] API draft 3 updates
[idea/community.git] / java / java-psi-api / src / com / intellij / psi / PsiClass.java
1 /*
2  * Copyright 2000-2017 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.psi;
17
18 import com.intellij.lang.jvm.JvmClass;
19 import com.intellij.lang.jvm.JvmClassKind;
20 import com.intellij.lang.jvm.types.JvmClassType;
21 import com.intellij.openapi.util.Pair;
22 import com.intellij.pom.PomRenameableTarget;
23 import com.intellij.util.ArrayFactory;
24 import com.intellij.util.IncorrectOperationException;
25 import org.jetbrains.annotations.NonNls;
26 import org.jetbrains.annotations.NotNull;
27 import org.jetbrains.annotations.Nullable;
28
29 import java.util.Collection;
30 import java.util.List;
31
32 import static com.intellij.psi.PsiJvmConversionHelper.*;
33
34 /**
35  * Represents a Java class or interface.
36  *
37  * @see PsiJavaFile#getClasses()
38  */
39 public interface PsiClass
40   extends PsiNameIdentifierOwner, PsiModifierListOwner, PsiDocCommentOwner, PsiTypeParameterListOwner,
41           PsiQualifiedNamedElement, PsiTarget, PomRenameableTarget<PsiElement>, JvmClass {
42   /**
43    * The empty array of PSI classes which can be reused to avoid unnecessary allocations.
44    */
45   @NotNull PsiClass[] EMPTY_ARRAY = new PsiClass[0];
46
47   ArrayFactory<PsiClass> ARRAY_FACTORY = count -> count == 0 ? EMPTY_ARRAY : new PsiClass[count];
48
49   /**
50    * Returns the fully qualified name of the class.
51    *
52    * @return the qualified name of the class, or null for anonymous and local classes, and for type parameters
53    */
54   @Nullable
55   String getQualifiedName();
56
57   /**
58    * Checks if the class is an interface.
59    *
60    * @return true if the class is an interface, false otherwise.
61    */
62   boolean isInterface();
63
64   /**
65    * Checks if the class is an annotation type.
66    *
67    * @return true if the class is an annotation type, false otherwise
68    */
69   boolean isAnnotationType();
70
71   /**
72    * Checks if the class is an enumeration.
73    *
74    * @return true if the class is an enumeration, false otherwise.
75    */
76   boolean isEnum();
77
78   /**
79    * Returns the list of classes that this class or interface extends.
80    *
81    * @return the extends list, or null for anonymous classes.
82    */
83   @Nullable
84   PsiReferenceList getExtendsList();
85
86   /**
87    * Returns the list of interfaces that this class implements.
88    *
89    * @return the implements list, or null for anonymous classes
90    */
91   @Nullable
92   PsiReferenceList getImplementsList();
93
94   /**
95    * Returns the list of class types for the classes that this class or interface extends.
96    *
97    * @return the list of extended class types, or an empty list for anonymous classes.
98    */
99   @NotNull
100   PsiClassType[] getExtendsListTypes();
101
102   /**
103    * Returns the list of class types for the interfaces that this class implements.
104    *
105    * @return the list of extended class types, or an empty list for anonymous classes,
106    *         enums and annotation types
107    */
108   @NotNull
109   PsiClassType[] getImplementsListTypes();
110
111   /**
112    * Returns the base class of this class.
113    *
114    * @return the base class. May return null when jdk is not configured, so no java.lang.Object is found,
115    *         or for java.lang.Object itself
116    */
117   @Nullable
118   PsiClass getSuperClass();
119
120   /**
121    * Returns the list of interfaces implemented by the class, or extended by the interface.
122    *
123    * @return the list of interfaces.
124    */
125   @NotNull
126   PsiClass[] getInterfaces();
127
128   /**
129    * Returns the list of classes and interfaces extended or implemented by the class.
130    *
131    * @return the list of classes or interfaces. May return zero elements when jdk is
132    *         not configured, so no java.lang.Object is found
133    */
134   @NotNull
135   PsiClass[] getSupers();
136
137   /**
138    * Returns the list of class types for the classes and interfaces extended or
139    * implemented by the class.
140    *
141    * @return the list of class types for the classes or interfaces.
142    *         For the class with no explicit extends list, the returned list always contains at least one element for the java.lang.Object type.
143    *         If psiClass is java.lang.Object, returned list is empty.
144    */
145   @NotNull PsiClassType[] getSuperTypes();
146
147   /**
148    * Returns the list of fields in the class.
149    *
150    * @return the list of fields.
151    */
152   @NotNull
153   PsiField[] getFields();
154
155   /**
156    * Returns the list of methods in the class.
157    *
158    * @return the list of methods.
159    */
160   @NotNull
161   PsiMethod[] getMethods();
162
163   /**
164    * Returns the list of constructors for the class.
165    *
166    * @return the list of constructors,
167    */
168   @NotNull
169   PsiMethod[] getConstructors();
170
171   /**
172    * Returns the list of inner classes for the class.
173    *
174    * @return the list of inner classes.
175    */
176   @NotNull PsiClass[] getInnerClasses();
177
178   /**
179    * Returns the list of class initializers for the class.
180    *
181    * @return the list of class initializers.
182    */
183   @NotNull PsiClassInitializer[] getInitializers();
184
185   /**
186    * Returns the list of fields in the class and all its superclasses.
187    *
188    * @return the list of fields.
189    */
190   @NotNull PsiField[] getAllFields();
191
192   /**
193    * Returns the list of methods in the class and all its superclasses.
194    *
195    * @return the list of methods.
196    */
197   @NotNull PsiMethod[] getAllMethods();
198
199   /**
200    * Returns the list of inner classes for the class and all its superclasses.
201    *
202    * @return the list of inner classes.
203    */
204   @NotNull PsiClass[] getAllInnerClasses();
205
206   /**
207    * Searches the class (and optionally its superclasses) for the field with the specified name.
208    *
209    * @param name       the name of the field to find.
210    * @param checkBases if true, the field is also searched in the base classes of the class.
211    * @return the field instance, or null if the field cannot be found.
212    */
213   @Nullable
214   PsiField findFieldByName(@NonNls String name, boolean checkBases);
215
216   /**
217    * Searches the class (and optionally its superclasses) for the method with
218    * the signature matching the signature of the specified method.
219    *
220    * @param patternMethod the method used as a pattern for the search.
221    * @param checkBases    if true, the method is also searched in the base classes of the class.
222    * @return the method instance, or null if the method cannot be found.
223    */
224   @Nullable
225   PsiMethod findMethodBySignature(PsiMethod patternMethod, boolean checkBases);
226
227   /**
228    * Searches the class (and optionally its superclasses) for the methods with the signature
229    * matching the signature of the specified method. If the superclasses are not searched,
230    * the method returns multiple results only in case of a syntax error (duplicate method).
231    *
232    * @param patternMethod the method used as a pattern for the search.
233    * @param checkBases    if true, the method is also searched in the base classes of the class.
234    * @return the found methods, or an empty array if no methods are found.
235    */
236   @NotNull
237   PsiMethod[] findMethodsBySignature(PsiMethod patternMethod, boolean checkBases);
238
239   /**
240    * Searches the class (and optionally its superclasses) for the methods with the specified name.
241    *
242    * @param name       the name of the methods to find.
243    * @param checkBases if true, the methods are also searched in the base classes of the class.
244    * @return the found methods, or an empty array if no methods are found.
245    */
246   @NotNull
247   PsiMethod[] findMethodsByName(@NonNls String name, boolean checkBases);
248
249   /**
250    * Searches the class (and optionally its superclasses) for the methods with the specified name
251    * and returns the methods along with their substitutors.
252    *
253    * @param name       the name of the methods to find.
254    * @param checkBases if true, the methods are also searched in the base classes of the class.
255    * @return the found methods and their substitutors, or an empty list if no methods are found.
256    */
257   @NotNull
258   List<Pair<PsiMethod, PsiSubstitutor>> findMethodsAndTheirSubstitutorsByName(@NonNls String name, boolean checkBases);
259
260   /**
261    * Returns the list of methods in the class and all its superclasses, along with their
262    * substitutors.
263    *
264    * @return the list of methods and their substitutors
265    */
266   @NotNull
267   List<Pair<PsiMethod, PsiSubstitutor>> getAllMethodsAndTheirSubstitutors();
268
269   /**
270    * Searches the class (and optionally its superclasses) for the inner class with the specified name.
271    *
272    * @param name       the name of the inner class to find.
273    * @param checkBases if true, the inner class is also searched in the base classes of the class.
274    * @return the inner class instance, or null if the inner class cannot be found.
275    */
276   @Nullable
277   PsiClass findInnerClassByName(@NonNls String name, boolean checkBases);
278
279   /**
280    * Returns the token representing the opening curly brace of the class.
281    *
282    * @return the token instance, or null if the token is missing in the source code file.
283    */
284   @Nullable
285   PsiElement getLBrace();
286
287   /**
288    * Returns the token representing the closing curly brace of the class.
289    *
290    * @return the token instance, or null if the token is missing in the source code file.
291    */
292   @Nullable
293   PsiElement getRBrace();
294
295   /**
296    * Returns the name identifier of the class.
297    *
298    * @return the name identifier, or null if the class is anonymous or synthetic jsp class
299    */
300   @Override
301   @Nullable
302   PsiIdentifier getNameIdentifier();
303
304   /**
305    * Returns the PSI member in which the class has been declared (for example,
306    * the method containing the anonymous inner class, or the file containing a regular
307    * class, or the class owning a type parameter).
308    *
309    * @return the member in which the class has been declared.
310    */
311   PsiElement getScope();
312
313   /**
314    * Checks if this class is an inheritor of the specified base class.
315    * Only java inheritance rules are considered.
316    * Note that {@link com.intellij.psi.search.searches.ClassInheritorsSearch}
317    *  may return classes that are inheritors in broader, e.g. in ejb sense, but not in java sense.
318    *
319    * @param baseClass the base class to check the inheritance.
320    * @param checkDeep if false, only direct inheritance is checked; if true, the base class is
321    *                  searched in the entire inheritance chain
322    * @return true if the class is an inheritor, false otherwise
323    */
324   boolean isInheritor(@NotNull PsiClass baseClass, boolean checkDeep);
325
326   /**
327    * Checks if this class is a deep inheritor of the specified base class possibly bypassing a class
328    * when checking inheritance chain.
329    * Only java inheritance rules are considered.
330    * Note that {@link com.intellij.psi.search.searches.ClassInheritorsSearch}
331    *  may return classes that are inheritors in broader, e.g. in ejb sense, but not in java sense.
332    *
333    * @param baseClass the base class to check the inheritance.
334    *                  searched in the entire inheritance chain
335    * @param classToByPass class to bypass the inheratance check for
336    * @return true if the class is an inheritor, false otherwise
337    */
338   boolean isInheritorDeep(PsiClass baseClass, @Nullable PsiClass classToByPass);
339
340   /**
341    * For an inner class, returns its containing class.
342    *
343    * @return the containing class, or null if the class is not an inner class.
344    */
345   @Override
346   @Nullable
347   PsiClass getContainingClass();
348
349   /**
350    * Returns the hierarchical signatures for all methods in the specified class and
351    * its superclasses and superinterfaces.
352    *
353    * @return the collection of signatures.
354    * @since 5.1
355    */
356   @NotNull
357   Collection<HierarchicalMethodSignature> getVisibleSignatures();
358
359   @Override
360   PsiElement setName(@NonNls @NotNull String name) throws IncorrectOperationException;
361
362   @NotNull
363   @Override
364   default JvmClassKind classKind() {
365     return getJvmClassKind(this);
366   }
367
368   @Nullable
369   @Override
370   default JvmClassType superClassType() {
371     return getClassSuperType(this);
372   }
373
374   @NotNull
375   @Override
376   default Iterable<JvmClassType> interfaceTypes() {
377     return getClassInterfaces(this);
378   }
379 }