[jvm] API draft 3 updates
[idea/community.git] / java / java-psi-api / src / com / intellij / psi / PsiMethod.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.JvmConstructor;
19 import com.intellij.lang.jvm.JvmMethod;
20 import com.intellij.lang.jvm.JvmParameter;
21 import com.intellij.lang.jvm.types.JvmReferenceType;
22 import com.intellij.lang.jvm.types.JvmType;
23 import com.intellij.pom.PomRenameableTarget;
24 import com.intellij.psi.util.MethodSignature;
25 import com.intellij.psi.util.MethodSignatureBackedByPsiMethod;
26 import com.intellij.util.ArrayFactory;
27 import com.intellij.util.IncorrectOperationException;
28 import org.jetbrains.annotations.NonNls;
29 import org.jetbrains.annotations.NotNull;
30 import org.jetbrains.annotations.Nullable;
31
32 import java.util.List;
33
34 /**
35  * Represents a Java method or constructor.
36  *
37  * @see PsiClass#getMethods()
38  */
39 public interface PsiMethod extends PsiMember, PsiNameIdentifierOwner, PsiModifierListOwner, PsiDocCommentOwner, PsiTypeParameterListOwner,
40                                    PomRenameableTarget<PsiElement>, PsiTarget, PsiParameterListOwner, JvmMethod, JvmConstructor {
41   /**
42    * The empty array of PSI methods which can be reused to avoid unnecessary allocations.
43    */
44   PsiMethod[] EMPTY_ARRAY = new PsiMethod[0];
45
46   ArrayFactory<PsiMethod> ARRAY_FACTORY = count -> count == 0 ? EMPTY_ARRAY : new PsiMethod[count];
47
48   /**
49    * Returns the return type of the method.
50    *
51    * @return the method return type, or null if the method is a constructor.
52    */
53   @Nullable
54   PsiType getReturnType();
55
56   /**
57    * Returns the type element for the return type of the method.
58    *
59    * @return the type element for the return type, or null if the method is a constructor.
60    */
61   @Nullable
62   PsiTypeElement getReturnTypeElement();
63
64   /**
65    * Returns the parameter list for the method.
66    *
67    * @return the parameter list instance.
68    */
69   @Override
70   @NotNull
71   PsiParameterList getParameterList();
72
73   /**
74    * Returns the list of thrown exceptions for the method.
75    *
76    * @return the list of thrown exceptions instance.
77    */
78   @NotNull
79   PsiReferenceList getThrowsList();
80
81   /**
82    * Returns the body of the method.
83    *
84    * @return the method body, or null if the method belongs to a compiled class.
85    */
86   @Override
87   @Nullable
88   PsiCodeBlock getBody();
89
90   /**
91    * Checks if the method is a constructor.
92    *
93    * @return true if the method is a constructor, false otherwise
94    */
95   boolean isConstructor();
96
97   /**
98    * Checks if the method accepts a variable number of arguments.
99    *
100    * @return true if the method is varargs, false otherwise.
101    */
102   boolean isVarArgs();
103
104   /**
105    * Returns the signature of this method, using the specified substitutor to specify
106    * values of generic type parameters.
107    *
108    * @param substitutor the substitutor.
109    * @return the method signature instance.
110    */
111   @NotNull
112   MethodSignature getSignature(@NotNull PsiSubstitutor substitutor);
113
114   /**
115    * Returns the name identifier for the method.
116    *
117    * @return the name identifier instance.
118    */
119   @Override
120   @Nullable
121   PsiIdentifier getNameIdentifier();
122
123   /**
124    * Searches the superclasses and base interfaces of the containing class to find
125    * the methods which this method overrides or implements. Can return multiple results
126    * if the base class and/or one or more of the implemented interfaces have a method
127    * with the same signature. If the overridden method in turn overrides another method,
128    * only the directly overridden method is returned.
129    *
130    * @return the array of super methods, or an empty array if no methods are found.
131    */
132   @NotNull
133   PsiMethod[] findSuperMethods();
134
135   /**
136    * Searches the superclasses and base interfaces of the containing class to find
137    * the methods which this method overrides or implements, optionally omitting
138    * the accessibility check. Can return multiple results if the base class and/or
139    * one or more of the implemented interfaces have a method with the same signature.
140    * If the overridden method in turn overrides another method, only the directly
141    * overridden method is returned.
142    *
143    * @param checkAccess if false, the super methods are searched even if this method
144    *                    is private. If true, an empty result list is returned for private methods.
145    * @return the array of super methods, or an empty array if no methods are found.
146    */
147   @NotNull
148   PsiMethod[] findSuperMethods(boolean checkAccess);
149
150   /**
151    * Searches the superclasses and base interfaces of the specified class to find
152    * the methods which this method can override or implement. Can return multiple results
153    * if the base class and/or one or more of the implemented interfaces have a method
154    * with the same signature.
155    *
156    * @param parentClass the class to search for super methods.
157    * @return the array of super methods, or an empty array if no methods are found.
158    */
159   @NotNull
160   PsiMethod[] findSuperMethods(PsiClass parentClass);
161
162   /**
163    * Searches the superclasses and base interfaces of the containing class to find
164    * static and instance methods with the signature matching the signature of this method.
165    * Can return multiple results if the base class and/or one or more of the implemented
166    * interfaces have a method with the same signature. If the overridden method in turn
167    * overrides another method, only the directly overridden method is returned.
168    *
169    * @param checkAccess if false, the super methods are searched even if this method
170    *                    is private. If true, an empty result list is returned for private methods.
171    * @return the array of matching method signatures, or an empty array if no methods are found.
172    */
173   @NotNull
174   List<MethodSignatureBackedByPsiMethod> findSuperMethodSignaturesIncludingStatic(boolean checkAccess);
175
176   /**
177    * Returns the method in the deepest base superclass or interface of the containing class which
178    * this method overrides or implements.
179    *
180    * @return the overridden or implemented method, or null if this method does not override
181    *         or implement any other method.
182    * @deprecated use {@link #findDeepestSuperMethods()} instead
183    */
184   @Nullable
185   PsiMethod findDeepestSuperMethod();
186
187   @NotNull
188   PsiMethod[] findDeepestSuperMethods();
189
190   @Override
191   @NotNull
192   PsiModifierList getModifierList();
193
194   @Override
195   @NotNull
196   @NonNls
197   String getName();
198
199   @Override
200   PsiElement setName(@NonNls @NotNull String name) throws IncorrectOperationException;
201
202   @NotNull
203   HierarchicalMethodSignature getHierarchicalMethodSignature();
204
205   @NotNull
206   @Override
207   default JvmType returnType() {
208     return PsiJvmConversionHelper.getMethodReturnType(this);
209   }
210
211   @NotNull
212   @Override
213   default Iterable<JvmParameter> parameters() {
214     return PsiJvmConversionHelper.getMethodParameters(this);
215   }
216
217   @NotNull
218   @Override
219   default Iterable<JvmReferenceType> throwsTypes() {
220     return PsiJvmConversionHelper.getMethodThrowsTypes(this);
221   }
222 }