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 26package com.sun.jdi; 27 28import 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 */ 42public 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} 441