/*

 * Copyright (c) 1998, 2011, Oracle and/or its affiliates. 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.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.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<Method> {

    /**

     * Returns a text representation of the return type,

     * as specified in the declaration of this method.

     * <P>

     * 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.

     * <P>

     * 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 <CODE>declaringType()</CODE>}

     * <CODE>.classLoader()</CODE>,

     * 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.

     * <P>

     * 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<String> argumentTypeNames();

    /**

     * Returns a list containing the type

     * of each formal parameter of this method.

     * <P>

     * 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 <CODE>declaringType()</CODE>}

     * <CODE>.classLoader()</CODE>,

     * 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<Type> argumentTypes() throws ClassNotLoadedException;

    /**

     * Determine if this method is abstract.

     *

     * @return <code>true</code> if the method is declared abstract;

     * false otherwise.

     */

    boolean isAbstract();

    /**

     * Determine if this method is synchronized.

     *

     * @return <code>true</code> if the method is declared synchronized;

     * false otherwise.

     */

    boolean isSynchronized();

    /**

     * Determine if this method is native.

     *

     * @return <code>true</code> if the method is declared native;

     * false otherwise.

     */

    boolean isNative();

    /**

     * Determine if this method accepts a variable number of arguments.

     *

     * @return <code>true</code> 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

     * <cite>The Java&trade; Language Specification</cite>.

     *

     * @return <code>true</code> if the method is a bridge method,

     * false otherwise.

     *

     * @since 1.5

     */

    boolean isBridge();

    /**

     * Determine if this method is a constructor.

     *

     * @return <code>true</code> if the method is a constructor;

     * false otherwise.

     */

    boolean isConstructor();

    /**

     * Determine if this method is a static initializer.

     *

     * @return <code>true</code> if the method is a static initializer;

     * false otherwise.

     */

    boolean isStaticInitializer();

    /**

     * Determine if this method is obsolete.

     *

     * @return <code>true</code> 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.

     * <P>

     * This method is equivalent to

     * <code>allLineLocations(vm.getDefaultStratum(),null)</code> -

     * 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<Location> allLineLocations() throws AbsentInformationException;

    /**

     * Returns a list containing a {@link Location} object for

     * each executable source line in this method.

     * <P>

     * 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).

     * <P>

     * 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.

     * <P>

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

     * returned.

     * <P>

     * Returned list is for the specified <i>stratum</i>

     * (see {@link Location} for a description of strata).

     *

     * @param stratum The stratum to retrieve information from

     * or <code>null</code> for the {@link ReferenceType#defaultStratum()}

     *

     * @param sourceName Return locations only within this

     * source file or <code>null</code> 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 <i>sourceName</i> is non-<code>null</code>

     * and source name information is not present.

     *

     * @since 1.4

     */

    List<Location> allLineLocations(String stratum, String sourceName)

        throws AbsentInformationException;

    /**

     * Returns a List containing all {@link Location} objects

     * that map to the given line number.

     * <P>

     * This method is equivalent to

     * <code>locationsOfLine(vm.getDefaultStratum(), null,

     * lineNumber)</code> -

     * 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<Location> locationsOfLine(int lineNumber) throws AbsentInformationException;

    /**

     * Returns a List containing all {@link Location} objects

     * that map to the given line number and source name.

     * <P>

     * 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.

     * <p>

     * Returned list is for the specified <i>stratum</i>

     * (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 <i>sourceName</i> is non-<code>null</code>

     * and source name information is not present.

     *

     * @since 1.4

     */

    List<Location> 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<LocalVariable> 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<LocalVariable> 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<LocalVariable> arguments() throws AbsentInformationException;

    /**

     * Returns an array containing the bytecodes for this method.

     * <P>

     * 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();

}