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