1 /*
2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.jdi;
27
28 import java.util.List;
29
30 /**
31 * A static or instance method in the target VM. See {@link TypeComponent}
32 * for general information about Field and Method mirrors.
33 *
34 * @see ObjectReference
35 * @see ReferenceType
36 *
37 * @author Robert Field
38 * @author Gordon Hirsch
39 * @author James McIlree
40 * @since 1.3
41 */
42 public interface Method extends TypeComponent, Locatable, Comparable<Method> {
43
44 /**
45 * Returns a text representation of the return type,
46 * as specified in the declaration of this method.
47 * <P>
48 * This type name is always available even if
49 * the type has not yet been created or loaded.
50 *
51 * @return a {@code String} containing the return type name.
52 */
53 String returnTypeName();
54
55 /**
56 * Returns the return type,
57 * as specified in the declaration of this method.
58 * <P>
59 * Note: if the return type of this method is a reference type (class,
60 * interface, or array) and it has not been created or loaded
61 * by the declaring type's class loader - that is,
62 * {@link TypeComponent#declaringType declaringType()}
63 * {@code .classLoader()},
64 * then ClassNotLoadedException will be thrown.
65 * Also, a reference type may have been loaded but not yet prepared,
66 * in which case the type will be returned
67 * but attempts to perform some operations on the returned type
68 * (e.g. {@link ReferenceType#fields() fields()}) will throw
69 * a {@link ClassNotPreparedException}.
70 * Use {@link ReferenceType#isPrepared()} to determine if
71 * a reference type is prepared.
72 *
73 * @see Type
74 * @see Field#type() Field.type() - for usage examples
75 * @return the return {@link Type} of this method.
76 * @throws ClassNotLoadedException if the type has not yet been
77 * created or loaded
78 * through the appropriate class loader.
79 */
80 Type returnType() throws ClassNotLoadedException;
81
82 /**
83 * Returns a list containing a text representation of the type
84 * of each formal parameter of this method.
85 * <P>
86 * This list is always available even if
87 * the types have not yet been created or loaded.
88 *
89 * @return a {@link java.util.List List} of {@link String},
90 * one List element for each parameter of this method.
91 * Each element represents the type of a formal parameter
92 * as specified at compile-time.
93 * If the formal parameter was declared with an ellipsis, then
94 * it is represented as an array of the type before the ellipsis.
95 */
96 List<String> argumentTypeNames();
97
98 /**
99 * Returns a list containing the type
100 * of each formal parameter of this method.
101 * <P>
102 * Note: if there is any parameter whose type
103 * is a reference type (class, interface, or array)
104 * and it has not been created or loaded
105 * by the declaring type's class loader - that is,
106 * {@link TypeComponent#declaringType declaringType()}
107 * {@code .classLoader()},
108 * then ClassNotLoadedException will be thrown.
109 * Also, a reference type may have been loaded but not yet prepared,
110 * in which case the list will be returned
111 * but attempts to perform some operations on the type
112 * (e.g. {@link ReferenceType#fields() fields()}) will throw
113 * a {@link ClassNotPreparedException}.
114 * Use {@link ReferenceType#isPrepared()} to determine if
115 * a reference type is prepared.
116 *
117 * @see Type
118 * @return return a {@link java.util.List List} of {@link Type},
119 * one List element for each parameter of this method.
120 * Each element represents the type of a formal parameter
121 * as specified at compile-time.
122 * If the formal parameter was declared with an ellipsis, then
123 * it is represented as an array of the type before the ellipsis.
124 *
125 * @throws ClassNotLoadedException if the type has not yet been loaded
126 * through the appropriate class loader.
127 */
128 List<Type> argumentTypes() throws ClassNotLoadedException;
129
130 /**
131 * Determine if this method is abstract.
132 *
133 * @return {@code true} if the method is declared abstract;
134 * {@code false} otherwise.
135 */
136 boolean isAbstract();
137
138 /**
139 * Determine if this method is a default method
140 *
141 * @return {@code true} if the method is declared default;
142 * {@code false} otherwise.
143 *
144 * @since 1.8
145 */
146 default boolean isDefault() {
147 throw new UnsupportedOperationException();
148 }
149
150 /**
151 * Determine if this method is synchronized.
152 *
153 * @return {@code true} if the method is declared synchronized;
154 * {@code false} otherwise.
155 */
156 boolean isSynchronized();
157
158 /**
159 * Determine if this method is native.
160 *
161 * @return {@code true} if the method is declared native;
162 * {@code false} otherwise.
163 */
164 boolean isNative();
165
166 /**
167 * Determine if this method accepts a variable number of arguments.
168 *
169 * @return {@code true} if the method accepts a variable number
170 * of arguments, {@code false} otherwise.
171 *
172 * @since 1.5
173 */
174 boolean isVarArgs();
175
176 /**
177 * Determine if this method is a bridge method. Bridge
178 * methods are defined in
179 * <cite>The Java™ Language Specification</cite>.
180 *
181 * @return {@code true} if the method is a bridge method,
182 * {@code false} otherwise.
183 *
184 * @since 1.5
185 */
186 boolean isBridge();
187
188 /**
189 * Determine if this method is a constructor.
190 *
191 * @return {@code true} if the method is a constructor;
192 * {@code false} otherwise.
193 */
194 boolean isConstructor();
195
196 /**
197 * Determine if this method is a static initializer.
198 *
199 * @return {@code true} if the method is a static initializer;
200 * {@code false} otherwise.
201 */
202 boolean isStaticInitializer();
203
204 /**
205 * Determine if this method is obsolete.
206 *
207 * @return {@code true} if this method has been made obsolete by a
208 * {@link VirtualMachine#redefineClasses} operation.
209 *
210 * @since 1.4
211 */
212 boolean isObsolete();
213
214 /**
215 * Returns a list containing a {@link Location} object for
216 * each executable source line in this method.
217 * <P>
218 * This method is equivalent to
219 * {@code allLineLocations(vm.getDefaultStratum(),null)} -
220 * see {@link #allLineLocations(String,String)}
221 * for more information.
222 *
223 * @return a List of all source line {@link Location} objects.
224 *
225 * @throws AbsentInformationException if there is no line
226 * number information for this (non-native, non-abstract)
227 * method.
228 */
229 List<Location> allLineLocations() throws AbsentInformationException;
230
231 /**
232 * Returns a list containing a {@link Location} object for
233 * each executable source line in this method.
234 * <P>
235 * Each location maps a source line to a range of code
236 * indices.
237 * The beginning of the range can be determined through
238 * {@link Location#codeIndex}.
239 * The returned list is ordered by code index
240 * (from low to high).
241 * <P>
242 * The returned list may contain multiple locations for a
243 * particular line number, if the compiler and/or VM has
244 * mapped that line to two or more disjoint code index ranges.
245 * <P>
246 * If the method is native or abstract, an empty list is
247 * returned.
248 * <P>
249 * Returned list is for the specified <i>stratum</i>
250 * (see {@link Location} for a description of strata).
251 *
252 * @param stratum The stratum to retrieve information from
253 * or {@code null} for the {@link ReferenceType#defaultStratum()}
254 *
255 * @param sourceName Return locations only within this
256 * source file or {@code null} to return locations.
257 *
258 * @return a List of all source line {@link Location} objects.
259 *
260 * @throws AbsentInformationException if there is no line
261 * number information for this (non-native, non-abstract)
262 * method. Or if <i>sourceName</i> is non-{@code null}
263 * and source name information is not present.
264 *
265 * @since 1.4
266 */
267 List<Location> allLineLocations(String stratum, String sourceName)
268 throws AbsentInformationException;
269
270 /**
271 * Returns a List containing all {@link Location} objects
272 * that map to the given line number.
273 * <P>
274 * This method is equivalent to
275 * {@code locationsOfLine(vm.getDefaultStratum(), null,
276 * lineNumber)} -
277 * see {@link
278 * #locationsOfLine(java.lang.String,java.lang.String,int)}
279 * for more information.
280 *
281 * @param lineNumber the line number
282 *
283 * @return a List of {@link Location} objects that map to
284 * the given line number.
285 *
286 * @throws AbsentInformationException if there is no line
287 * number information for this method.
288 */
289 List<Location> locationsOfLine(int lineNumber) throws AbsentInformationException;
290
291 /**
292 * Returns a List containing all {@link Location} objects
293 * that map to the given line number and source name.
294 * <P>
295 * Returns a list containing each {@link Location} that maps
296 * to the given line. The returned list will contain a
297 * location for each disjoint range of code indices that have
298 * been assigned to the given line by the compiler and/or
299 * VM. Each returned location corresponds to the beginning of
300 * this range. An empty list will be returned if there is no
301 * executable code at the specified line number; specifically,
302 * native and abstract methods will always return an empty
303 * list.
304 * <p>
305 * Returned list is for the specified <i>stratum</i>
306 * (see {@link Location} for a description of strata).
307 *
308 * @param stratum the stratum to use for comparing line number
309 * and source name, or null to use the default
310 * stratum
311 * @param sourceName the source name containing the
312 * line number, or null to match all
313 * source names
314 * @param lineNumber the line number
315 *
316 * @return a List of {@link Location} objects that map to
317 * the given line number.
318 *
319 * @throws AbsentInformationException if there is no line
320 * number information for this method.
321 * Or if <i>sourceName</i> is non-{@code null}
322 * and source name information is not present.
323 *
324 * @since 1.4
325 */
326 List<Location> locationsOfLine(String stratum, String sourceName,
327 int lineNumber)
328 throws AbsentInformationException;
329
330 /**
331 * Returns a {@link Location} for the given code index.
332 *
333 * @return the {@link Location} corresponding to the
334 * given code index or null if the specified code index is not a
335 * valid code index for this method (native and abstract methods
336 * will always return null).
337 */
338 Location locationOfCodeIndex(long codeIndex);
339
340 /**
341 * Returns a list containing each {@link LocalVariable} declared
342 * in this method. The list includes any variable declared in any
343 * scope within the method. It may contain multiple variables of the
344 * same name declared within disjoint scopes. Arguments are considered
345 * local variables and will be present in the returned list.
346 *
347 * If local variable information is not available, values of
348 * actual arguments to method invocations can be obtained
349 * by using the method {@link StackFrame#getArgumentValues()}
350 *
351 * @return the list of {@link LocalVariable} objects which mirror
352 * local variables declared in this method in the target VM.
353 * If there are no local variables, a zero-length list is returned.
354 * @throws AbsentInformationException if there is no variable
355 * information for this method.
356 * Generally, local variable information is not available for
357 * native or abstract methods (that is, their argument name
358 * information is not available), thus they will throw this exception.
359 */
360 List<LocalVariable> variables() throws AbsentInformationException;
361
362 /**
363 * Returns a list containing each {@link LocalVariable} of a
364 * given name in this method.
365 * Multiple variables can be returned
366 * if the same variable name is used in disjoint
367 * scopes within the method.
368 *
369 * @return the list of {@link LocalVariable} objects of the given
370 * name.
371 * If there are no matching local variables, a zero-length list
372 * is returned.
373 * @throws AbsentInformationException if there is no variable
374 * information for this method.
375 * Generally, local variable information is not available for
376 * native or abstract methods (that is, their argument name
377 * information is not available), thus they will throw this exception.
378 */
379 List<LocalVariable> variablesByName(String name)
380 throws AbsentInformationException;
381
382 /**
383 * Returns a list containing each {@link LocalVariable} that is
384 * declared as an argument of this method.
385 *
386 * If local variable information is not available, values of
387 * actual arguments to method invocations can be obtained
388 * by using the method {@link StackFrame#getArgumentValues()}
389 *
390 * @return the list of {@link LocalVariable} arguments.
391 * If there are no arguments, a zero-length list is returned.
392 * @throws AbsentInformationException if there is no variable
393 * information for this method.
394 * Generally, local variable information is not available for
395 * native or abstract methods (that is, their argument name
396 * information is not available), thus they will throw this exception.
397 */
398 List<LocalVariable> arguments() throws AbsentInformationException;
399
400 /**
401 * Returns an array containing the bytecodes for this method.
402 * <P>
403 * Not all target virtual machines support this operation.
404 * Use {@link VirtualMachine#canGetBytecodes()}
405 * to determine if the operation is supported.
406 *
407 * @return the array of bytecodes; abstract and native methods
408 * will return a zero-length array.
409 * @throws java.lang.UnsupportedOperationException if
410 * the target virtual machine does not support
411 * the retrieval of bytecodes.
412 */
413 byte[] bytecodes();
414
415 /**
416 * Returns the {@link Location} of this method, if there
417 * is executable code associated with it.
418 *
419 * @return the {@link Location} of this mirror, or null if
420 * this is an abstract method; native methods will return a
421 * Location object whose codeIndex is -1.
422 */
423 Location location();
424
425 /**
426 * Compares the specified Object with this method for equality.
427 *
428 * @return true if the Object is a method and if both
429 * mirror the same method (declared in the same class or interface, in
430 * the same VM).
431 */
432 boolean equals(Object obj);
433
434 /**
435 * Returns the hash code value for this Method.
436 *
437 * @return the integer hash code.
438 */
439 int hashCode();
440 }