001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core.dom;
011:
012: /**
013: * A method binding represents a method or constructor of a class or interface.
014: * Method bindings usually correspond directly to method or
015: * constructor declarations found in the source code.
016: * However, in certain cases of references to a generic method,
017: * the method binding may correspond to a copy of a generic method
018: * declaration with substitutions for the method's type parameters
019: * (for these, <code>getTypeArguments</code> returns a non-empty
020: * list, and either <code>isParameterizedMethod</code> or
021: * <code>isRawMethod</code> returns <code>true</code>).
022: * And in certain cases of references to a method declared in a
023: * generic type, the method binding may correspond to a copy of a
024: * method declaration with substitutions for the type's type
025: * parameters (for these, <code>getTypeArguments</code> returns
026: * an empty list, and both <code>isParameterizedMethod</code> and
027: * <code>isRawMethod</code> return <code>false</code>).
028: * <p>
029: * This interface is not intended to be implemented by clients.
030: * </p>
031: *
032: * @see ITypeBinding#getDeclaredMethods()
033: * @since 2.0
034: */
035: public interface IMethodBinding extends IBinding {
036:
037: /**
038: * Returns whether this binding is for a constructor or a method.
039: *
040: * @return <code>true</code> if this is the binding for a constructor,
041: * and <code>false</code> if this is the binding for a method
042: */
043: public boolean isConstructor();
044:
045: /**
046: * Returns whether this binding is known to be a compiler-generated
047: * default constructor.
048: * <p>
049: * This method returns <code>false</code> for:
050: * <ul>
051: * <li>methods</li>
052: * <li>constructors with more than one parameter</li>
053: * <li>0-argument constructors where the binding information was obtained
054: * from a Java source file containing an explicit 0-argument constructor
055: * declaration</li>
056: * <li>0-argument constructors where the binding information was obtained
057: * from a Java class file (it is not possible to determine from a
058: * class file whether a 0-argument constructor was present in the source
059: * code versus generated automatically by a Java compiler)</li>
060: * </ul>
061: *
062: * @return <code>true</code> if this is known to be the binding for a
063: * compiler-generated default constructor, and <code>false</code>
064: * otherwise
065: * @since 3.0
066: */
067: public boolean isDefaultConstructor();
068:
069: /**
070: * Returns the name of the method declared in this binding. The method name
071: * is always a simple identifier. The name of a constructor is always the
072: * same as the declared name of its declaring class.
073: *
074: * @return the name of this method, or the declared name of this
075: * constructor's declaring class
076: */
077: public String getName();
078:
079: /**
080: * Returns the type binding representing the class or interface
081: * that declares this method or constructor.
082: *
083: * @return the binding of the class or interface that declares this method
084: * or constructor
085: */
086: public ITypeBinding getDeclaringClass();
087:
088: /**
089: * Returns the resolved default value of an annotation type member,
090: * or <code>null</code> if the member has no default value, or if this
091: * is not the binding for an annotation type member.
092: * <p>
093: * Resolved values are represented as follows (same as for
094: * {@link IMemberValuePairBinding#getValue()}):
095: * <ul>
096: * <li>Primitive type - the equivalent boxed object</li>
097: * <li>java.lang.Class - the <code>ITypeBinding</code> for the class object</li>
098: * <li>java.lang.String - the string value itself</li>
099: * <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 <T> 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 > 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<? extends Object></code>, but
264: * when invoked its return type becomes <code>Class<? extends
265: * </code><em>R</em><code>></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: }
|