net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/IMethodBinding.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2008 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Eclipse Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/epl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11
  12 package net.sourceforge.phpdt.core.dom;
  13
  14 /**
  15  * A method binding represents a method or constructor of a class or interface.
  16  * Method bindings usually correspond directly to method or
  17  * constructor declarations found in the source code.
  18  * However, in certain cases of references to a generic method,
  19  * the method binding may correspond to a copy of a generic method
  20  * declaration with substitutions for the method's type parameters
  21  * (for these, <code>getTypeArguments</code> returns a non-empty
  22  * list, and either <code>isParameterizedMethod</code> or
  23  * <code>isRawMethod</code> returns <code>true</code>).
  24  * And in certain cases of references to a method declared in a
  25  * generic type, the method binding may correspond to a copy of a
  26  * method declaration with substitutions for the type's type
  27  * parameters (for these, <code>getTypeArguments</code> returns
  28  * an empty list, and both <code>isParameterizedMethod</code> and
  29  * <code>isRawMethod</code> return <code>false</code>).
  30  *
  31  * @see ITypeBinding#getDeclaredMethods()
  32  * @since 2.0
  33  * @noimplement This interface is not intended to be implemented by clients.
  34  */
  35 public interface IMethodBinding extends IBinding {
  36
  37         /**
  38          * Returns whether this binding is for a constructor or a method.
  39          *
  40          * @return <code>true</code> if this is the binding for a constructor,
  41          *    and <code>false</code> if this is the binding for a method
  42          */
  43         public boolean isConstructor();
  44
  45         /**
  46          * Returns whether this binding is known to be a compiler-generated
  47          * default constructor.
  48          * <p>
  49          * This method returns <code>false</code> for:
  50          * <ul>
  51          * <li>methods</li>
  52          * <li>constructors with more than one parameter</li>
  53          * <li>0-argument constructors where the binding information was obtained
  54          * from a Java source file containing an explicit 0-argument constructor
  55          * declaration</li>
  56          * <li>0-argument constructors where the binding information was obtained
  57          * from a Java class file (it is not possible to determine from a
  58          * class file whether a 0-argument constructor was present in the source
  59          * code versus generated automatically by a Java compiler)</li>
  60          * </ul>
  61          *
  62          * @return <code>true</code> if this is known to be the binding for a
  63          * compiler-generated default constructor, and <code>false</code>
  64          * otherwise
  65          * @since 3.0
  66          */
  67         public boolean isDefaultConstructor();
  68
  69         /**
  70          * Returns the name of the method declared in this binding. The method name
  71          * is always a simple identifier. The name of a constructor is always the
  72          * same as the declared name of its declaring class.
  73          *
  74          * @return the name of this method, or the declared name of this
  75          *   constructor's declaring class
  76          */
  77         public String getName();
  78
  79         /**
  80          * Returns the type binding representing the class or interface
  81          * that declares this method or constructor.
  82          *
  83          * @return the binding of the class or interface that declares this method
  84          *    or constructor
  85          */
  86         public ITypeBinding getDeclaringClass();
  87
  88         /**
  89          * Returns the resolved default value of an annotation type member,
  90          * or <code>null</code> if the member has no default value, or if this
  91          * is not the binding for an annotation type member.
  92          * <p>
  93          * Resolved values are represented as follows (same as for
  94          * {@link IMemberValuePairBinding#getValue()}):
  95          * <ul>
  96          * <li>Primitive type - the equivalent boxed object</li>
  97          * <li>java.lang.Class - the <code>ITypeBinding</code> for the class object</li>
  98          * <li>java.lang.String - the string value itself</li>
  99          * <li>enum type - the <code>IVariableBinding</code> for the enum constant</li>
 100          * <li>annotation type - an <code>IAnnotationBinding</code></li>
 101          * <li>array type - an <code>Object[]</code> whose elements are as per above
 102          * (the language only allows single dimensional arrays in annotations)</li>
 103          * </ul>
 104          *
 105          * @return the default value of this annotation type member, or <code>null</code>
 106          * if none or not applicable
 107          * @since 3.2
 108          */
 109         public Object getDefaultValue();
 110
 111         /**
 112          * Returns the resolved annotations of a parameter of this method.
 113          * The result returned is the same regardless of whether
 114          * this is a parameterized method.
 115          *
 116          * @param paramIndex the index of the parameter of interest
 117          * @return the resolved annotations of the <code>paramIndex</code>th parameter,
 118          * or an empty list if there are none
 119          * @throws ArrayIndexOutOfBoundsException if <code>paramIndex</code> is
 120          * not a valid index
 121          * @since 3.2
 122          */
 123         public IAnnotationBinding[] getParameterAnnotations(int paramIndex);
 124
 125         /**
 126          * Returns a list of type bindings representing the formal parameter types,
 127          * in declaration order, of this method or constructor. Returns an array of
 128          * length 0 if this method or constructor does not takes any parameters.
 129          * <p>
 130          * Note that the binding for the last parameter type of a vararg method
 131          * declaration like <code>void fun(Foo... args)</code> is always for
 132          * an array type (i.e., <code>Foo[]</code>) reflecting the the way varargs
 133          * get compiled. However, the type binding obtained directly from
 134          * the <code>SingleVariableDeclaration</code> for the vararg parameter
 135          * is always for the type as written; i.e., the type binding for
 136          * <code>Foo</code>.
 137          * </p>
 138          * <p>
 139          * Note: The result does not include synthetic parameters introduced by
 140          * inner class emulation.
 141          * </p>
 142          *
 143          * @return a (possibly empty) list of type bindings for the formal
 144          *   parameters of this method or constructor
 145          */
 146         public ITypeBinding[] getParameterTypes();
 147
 148         /**
 149          * Returns the binding for the return type of this method. Returns the
 150          * special primitive <code>void</code> return type for constructors.
 151          *
 152          * @return the binding for the return type of this method, or the
 153          *    <code>void</code> return type for constructors
 154          */
 155         public ITypeBinding getReturnType();
 156
 157         /**
 158          * Returns a list of type bindings representing the types of the exceptions thrown
 159          * by this method or constructor. Returns an array of length 0 if this method
 160          * throws no exceptions. The resulting types are in no particular order.
 161          *
 162          * @return a list of type bindings for exceptions
 163          *   thrown by this method or constructor
 164          */
 165         public ITypeBinding[] getExceptionTypes();
 166
 167         /**
 168          * Returns the type parameters of this method or constructor binding.
 169          * <p>
 170          * Note that type parameters only occur on the binding of the
 171          * declaring generic method. Type bindings corresponding to a raw or
 172          * parameterized reference to a generic method do not carry type
 173          * parameters (they instead have non-empty type arguments
 174          * and non-trivial erasure).
 175          * </p>
 176          *
 177          * @return the list of binding for the type variables for the type
 178          * parameters of this method, or otherwise the empty list
 179          * @see ITypeBinding#isTypeVariable()
 180          * @since 3.1
 181          */
 182         public ITypeBinding[] getTypeParameters();
 183
 184         /**
 185          * Returns whether this is the binding for an annotation type member.
 186          *
 187          * @return <code>true</code> iff this is the binding for an annotation type member
 188          *         and <code>false</code> otherwise
 189          * @since 3.2
 190          */
 191         public boolean isAnnotationMember();
 192
 193         /**
 194          * Returns whether this method binding represents a declaration of
 195          * a generic method.
 196          * <p>
 197          * Note that type parameters only occur on the binding of the
 198          * declaring generic method; e.g., <code>public &lt;T&gt; T identity(T t);</code>.
 199          * Method bindings corresponding to a raw or parameterized reference to a generic
 200          * method do not carry type parameters (they instead have non-empty type arguments
 201          * and non-trivial erasure).
 202          * This method is fully equivalent to <code>getTypeParameters().length &gt; 0)</code>.
 203          * </p>
 204          * <p>
 205          * Note that {@link #isGenericMethod()},
 206          * {@link #isParameterizedMethod()},
 207          * and {@link #isRawMethod()} are mutually exclusive.
 208          * </p>
 209          *
 210          * @return <code>true</code> if this method binding represents a
 211          * declaration of a generic method, and <code>false</code> otherwise
 212          * @see #getTypeParameters()
 213          * @since 3.1
 214          */
 215         public boolean isGenericMethod();
 216
 217         /**
 218          * Returns whether this method binding represents an instance of
 219          * a generic method corresponding to a parameterized method reference.
 220          * <p>
 221          * Note that {@link #isGenericMethod()},
 222          * {@link #isParameterizedMethod()},
 223          * and {@link #isRawMethod()} are mutually exclusive.
 224          * </p>
 225          *
 226          * @return <code>true</code> if this method binding represents a
 227          * an instance of a generic method corresponding to a parameterized
 228          * method reference, and <code>false</code> otherwise
 229          * @see #getMethodDeclaration()
 230          * @see #getTypeArguments()
 231          * @since 3.1
 232          */
 233         public boolean isParameterizedMethod();
 234
 235         /**
 236          * Returns the type arguments of this generic method instance, or the
 237          * empty list for other method bindings.
 238          * <p>
 239          * Note that type arguments only occur on a method binding that represents
 240          * an instance of a generic method corresponding to a raw or parameterized
 241          * reference to a generic method. Do not confuse these with type parameters
 242          * which only occur on the method binding corresponding directly to the
 243          * declaration of a generic method.
 244          * </p>
 245          *
 246          * @return the list of type bindings for the type arguments used to
 247          * instantiate the corrresponding generic method, or otherwise the empty list
 248          * @see #getMethodDeclaration()
 249          * @see #isParameterizedMethod()
 250          * @see #isRawMethod()
 251          * @since 3.1
 252          */
 253         public ITypeBinding[] getTypeArguments();
 254
 255         /**
 256          * Returns the binding for the method declaration corresponding to this
 257          * method binding. For parameterized methods ({@link #isParameterizedMethod()})
 258          * and raw methods ({@link #isRawMethod()}), this method returns the binding
 259          * for the corresponding generic method. For other method bindings, this
 260          * returns the same binding.
 261          *
 262          * <p>Note: The one notable exception is the method <code>Object.getClass()</code>,
 263          * which is declared to return <code>Class&lt;? extends Object&gt;</code>, but
 264          * when invoked its return type becomes <code>Class&lt;? extends
 265          * </code><em>R</em><code>&gt;</code>, where <em>R</em> is the compile type of
 266          * the receiver of the method invocation.</p>
 267          *
 268          * @return the method binding
 269          * @since 3.1
 270          */
 271         public IMethodBinding getMethodDeclaration();
 272
 273         /**
 274          * Returns whether this method binding represents an instance of
 275          * a generic method corresponding to a raw method reference.
 276          * <p>
 277          * Note that {@link #isGenericMethod()},
 278          * {@link #isParameterizedMethod()},
 279          * and {@link #isRawMethod()} are mutually exclusive.
 280          * </p>
 281          *
 282          * @return <code>true</code> if this method binding represents a
 283          * an instance of a generic method corresponding to a raw
 284          * method reference, and <code>false</code> otherwise
 285          * @see #getMethodDeclaration()
 286          * @see #getTypeArguments()
 287          * @since 3.1
 288          */
 289         public boolean isRawMethod();
 290
 291         /**
 292          * Returns whether this method's signature is a subsignature of the given method as
 293          * specified in section 8.4.2 of <em>The Java Language Specification, Third Edition</em> (JLS3).
 294          *
 295          * @return <code>true</code> if this method's signature is a subsignature of the given method
 296          * @since 3.1
 297          */
 298         public boolean isSubsignature(IMethodBinding otherMethod);
 299
 300         /**
 301          * Returns whether this is a variable arity method.
 302          * <p>
 303          * Note: Variable arity ("varargs") methods were added in JLS3.
 304          * </p>
 305          *
 306          * @return <code>true</code> if this is a variable arity method,
 307          *    and <code>false</code> otherwise
 308          * @since 3.1
 309          */
 310         public boolean isVarargs();
 311
 312         /**
 313          * Returns whether this method overrides the given method,
 314          * as specified in section 8.4.8.1 of <em>The Java Language
 315          * Specification, Third Edition</em> (JLS3).
 316          *
 317          * @param method the method that is possibly overriden
 318          * @return <code>true</code> if this method overrides the given method,
 319          * and <code>false</code> otherwise
 320          * @since 3.1
 321          */
 322         public boolean overrides(IMethodBinding method);
 323 }