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