diff -r fd16c54261b3 -r 90ce3da70b43 jdk/src/share/classes/com/sun/jdi/Method.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/jdk/src/share/classes/com/sun/jdi/Method.java Sat Dec 01 00:00:00 2007 +0000 @@ -0,0 +1,431 @@ +/* + * Copyright 1998-2005 Sun Microsystems, Inc. All Rights Reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Sun designates this + * particular file as subject to the "Classpath" exception as provided + * by Sun in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, + * CA 95054 USA or visit www.sun.com if you need additional information or + * have any questions. + */ + +package com.sun.jdi; + +import java.util.List; + +/** + * A static or instance method in the target VM. See {@link TypeComponent} + * for general information about Field and Method mirrors. + * + * @see ObjectReference + * @see ReferenceType + * + * @author Robert Field + * @author Gordon Hirsch + * @author James McIlree + * @since 1.3 + */ +public interface Method extends TypeComponent, Locatable, Comparable { + + /** + * Returns a text representation of the return type, + * as specified in the declaration of this method. + *

+ * This type name is always available even if + * the type has not yet been created or loaded. + * + * @return a String containing the return type name. + */ + String returnTypeName(); + + /** + * Returns the return type, + * as specified in the declaration of this method. + *

+ * Note: if the return type of this method is a reference type (class, + * interface, or array) and it has not been created or loaded + * by the declaring type's class loader - that is, + * {@link TypeComponent#declaringType declaringType()} + * .classLoader(), + * then ClassNotLoadedException will be thrown. + * Also, a reference type may have been loaded but not yet prepared, + * in which case the type will be returned + * but attempts to perform some operations on the returned type + * (e.g. {@link ReferenceType#fields() fields()}) will throw + * a {@link ClassNotPreparedException}. + * Use {@link ReferenceType#isPrepared()} to determine if + * a reference type is prepared. + * + * @see Type + * @see Field#type() Field.type() - for usage examples + * @return the return {@link Type} of this method. + * @throws ClassNotLoadedException if the type has not yet been + * created or loaded + * through the appropriate class loader. + */ + Type returnType() throws ClassNotLoadedException; + + /** + * Returns a list containing a text representation of the type + * of each formal parameter of this method. + *

+ * This list is always available even if + * the types have not yet been created or loaded. + * + * @return a {@link java.util.List List} of {@link String}, + * one List element for each parameter of this method. + * Each element represents the type of a formal parameter + * as specified at compile-time. + * If the formal parameter was declared with an ellipsis, then + * it is represented as an array of the type before the ellipsis. + * + */ + List argumentTypeNames(); + + /** + * Returns a list containing the type + * of each formal parameter of this method. + *

+ * Note: if there is any parameter whose type + * is a reference type (class, interface, or array) + * and it has not been created or loaded + * by the declaring type's class loader - that is, + * {@link TypeComponent#declaringType declaringType()} + * .classLoader(), + * then ClassNotLoadedException will be thrown. + * Also, a reference type may have been loaded but not yet prepared, + * in which case the list will be returned + * but attempts to perform some operations on the type + * (e.g. {@link ReferenceType#fields() fields()}) will throw + * a {@link ClassNotPreparedException}. + * Use {@link ReferenceType#isPrepared()} to determine if + * a reference type is prepared. + * + * @see Type + * @return return a {@link java.util.List List} of {@link Type}, + * one List element for each parameter of this method. + * Each element represents the type of a formal parameter + * as specified at compile-time. + * If the formal parameter was declared with an ellipsis, then + * it is represented as an array of the type before the ellipsis. + * + * @throws ClassNotLoadedException if the type has not yet been loaded + * through the appropriate class loader. + */ + List argumentTypes() throws ClassNotLoadedException; + + /** + * Determine if this method is abstract. + * + * @return true if the method is declared abstract; + * false otherwise. + */ + boolean isAbstract(); + + /** + * Determine if this method is synchronized. + * + * @return true if the method is declared synchronized; + * false otherwise. + */ + boolean isSynchronized(); + + /** + * Determine if this method is native. + * + * @return true if the method is declared native; + * false otherwise. + */ + boolean isNative(); + + /** + * Determine if this method accepts a variable number of arguments. + * + * @return true if the method accepts a variable number + * of arguments, false otherwise. + * + * @since 1.5 + */ + boolean isVarArgs(); + + /** + * Determine if this method is a bridge method. Bridge + * methods are defined in the + * + * "JavaTM + * Language Specification, 3rd Edition. + * + * @return true if the method is a bridge method, + * false otherwise. + * + * @since 1.5 + */ + boolean isBridge(); + + /** + * Determine if this method is a constructor. + * + * @return true if the method is a constructor; + * false otherwise. + */ + boolean isConstructor(); + + /** + * Determine if this method is a static initializer. + * + * @return true if the method is a static initializer; + * false otherwise. + */ + boolean isStaticInitializer(); + + /** + * Determine if this method is obsolete. + * + * @return true if this method has been made obsolete by a + * {@link VirtualMachine#redefineClasses} operation. + * + * @since 1.4 + */ + boolean isObsolete(); + + /** + * Returns a list containing a {@link Location} object for + * each executable source line in this method. + *

+ * This method is equivalent to + * allLineLocations(vm.getDefaultStratum(),null) - + * see {@link #allLineLocations(String,String)} + * for more information. + * + * @return a List of all source line {@link Location} objects. + * + * @throws AbsentInformationException if there is no line + * number information for this (non-native, non-abstract) + * method. + */ + List allLineLocations() throws AbsentInformationException; + + /** + * Returns a list containing a {@link Location} object for + * each executable source line in this method. + *

+ * Each location maps a source line to a range of code + * indices. + * The beginning of the range can be determined through + * {@link Location#codeIndex}. + * The returned list is ordered by code index + * (from low to high). + *

+ * The returned list may contain multiple locations for a + * particular line number, if the compiler and/or VM has + * mapped that line to two or more disjoint code index ranges. + *

+ * If the method is native or abstract, an empty list is + * returned. + *

+ * Returned list is for the specified stratum + * (see {@link Location} for a description of strata). + * + * @param stratum The stratum to retrieve information from + * or null for the {@link ReferenceType#defaultStratum()} + * + * @param sourceName Return locations only within this + * source file or null to return locations. + * + * @return a List of all source line {@link Location} objects. + * + * @throws AbsentInformationException if there is no line + * number information for this (non-native, non-abstract) + * method. Or if sourceName is non-null + * and source name information is not present. + * + * @since 1.4 + */ + List allLineLocations(String stratum, String sourceName) + throws AbsentInformationException; + + /** + * Returns a List containing all {@link Location} objects + * that map to the given line number. + *

+ * This method is equivalent to + * locationsOfLine(vm.getDefaultStratum(), null, + * lineNumber) - + * see {@link + * #locationsOfLine(java.lang.String,java.lang.String,int)} + * for more information. + * + * @param lineNumber the line number + * + * @return a List of {@link Location} objects that map to + * the given line number. + * + * @throws AbsentInformationException if there is no line + * number information for this method. + */ + List locationsOfLine(int lineNumber) throws AbsentInformationException; + + /** + * Returns a List containing all {@link Location} objects + * that map to the given line number and source name. + *

+ * Returns a list containing each {@link Location} that maps + * to the given line. The returned list will contain a + * location for each disjoint range of code indices that have + * been assigned to the given line by the compiler and/or + * VM. Each returned location corresponds to the beginning of + * this range. An empty list will be returned if there is no + * executable code at the specified line number; specifically, + * native and abstract methods will always return an empty + * list. + *

+ * Returned list is for the specified stratum + * (see {@link Location} for a description of strata). + * + * @param stratum the stratum to use for comparing line number + * and source name, or null to use the default + * stratum + * @param sourceName the source name containing the + * line number, or null to match all + * source names + * @param lineNumber the line number + * + * @return a List of {@link Location} objects that map to + * the given line number. + * + * @throws AbsentInformationException if there is no line + * number information for this method. + * Or if sourceName is non-null + * and source name information is not present. + * + * @since 1.4 + */ + List locationsOfLine(String stratum, String sourceName, + int lineNumber) + throws AbsentInformationException; + + /** + * Returns a {@link Location} for the given code index. + * + * @return the {@link Location} corresponding to the + * given code index or null if the specified code index is not a + * valid code index for this method (native and abstract methods + * will always return null). + */ + Location locationOfCodeIndex(long codeIndex); + + /** + * Returns a list containing each {@link LocalVariable} declared + * in this method. The list includes any variable declared in any + * scope within the method. It may contain multiple variables of the + * same name declared within disjoint scopes. Arguments are considered + * local variables and will be present in the returned list. + * + * If local variable information is not available, values of + * actual arguments to method invocations can be obtained + * by using the method {@link StackFrame#getArgumentValues()} + * + * @return the list of {@link LocalVariable} objects which mirror + * local variables declared in this method in the target VM. + * If there are no local variables, a zero-length list is returned. + * @throws AbsentInformationException if there is no variable + * information for this method. + * Generally, local variable information is not available for + * native or abstract methods (that is, their argument name + * information is not available), thus they will throw this exception. + */ + List variables() throws AbsentInformationException; + + /** + * Returns a list containing each {@link LocalVariable} of a + * given name in this method. + * Multiple variables can be returned + * if the same variable name is used in disjoint + * scopes within the method. + * + * @return the list of {@link LocalVariable} objects of the given + * name. + * If there are no matching local variables, a zero-length list + * is returned. + * @throws AbsentInformationException if there is no variable + * information for this method. + * Generally, local variable information is not available for + * native or abstract methods (that is, their argument name + * information is not available), thus they will throw this exception. + */ + List variablesByName(String name) + throws AbsentInformationException; + + /** + * Returns a list containing each {@link LocalVariable} that is + * declared as an argument of this method. + * + * If local variable information is not available, values of + * actual arguments to method invocations can be obtained + * by using the method {@link StackFrame#getArgumentValues()} + * + * @return the list of {@link LocalVariable} arguments. + * If there are no arguments, a zero-length list is returned. + * @throws AbsentInformationException if there is no variable + * information for this method. + * Generally, local variable information is not available for + * native or abstract methods (that is, their argument name + * information is not available), thus they will throw this exception. + */ + List arguments() throws AbsentInformationException; + + /** + * Returns an array containing the bytecodes for this method. + *

+ * Not all target virtual machines support this operation. + * Use {@link VirtualMachine#canGetBytecodes()} + * to determine if the operation is supported. + * + * @return the array of bytecodes; abstract and native methods + * will return a zero-length array. + * @throws java.lang.UnsupportedOperationException if + * the target virtual machine does not support + * the retrieval of bytecodes. + */ + byte[] bytecodes(); + + /** + * Returns the {@link Location} of this method, if there + * is executable code associated with it. + * + * @return the {@link Location} of this mirror, or null if + * this is an abstract method; native methods will return a + * Location object whose codeIndex is -1. + */ + Location location(); + + /** + * Compares the specified Object with this method for equality. + * + * @return true if the Object is a method and if both + * mirror the same method (declared in the same class or interface, in + * the same VM). + */ + boolean equals(Object obj); + + /** + * Returns the hash code value for this Method. + * + * @return the integer hash code + */ + int hashCode(); +}