001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 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: import org.eclipse.jdt.core.IJavaElement;
013:
014: /**
015: * A binding represents a named entity in the Java language. The world of
016: * bindings provides an integrated picture of the structure of the program as
017: * seen from the compiler's point of view. This interface declare protocol
018: * common to the various different kinds of named entities in the Java language:
019: * packages, types, fields, methods, constructors, and local variables.
020: * <p>
021: * This interface is not intended to be implemented by clients.
022: * </p>
023: *
024: * @see IPackageBinding
025: * @see ITypeBinding
026: * @see IVariableBinding
027: * @see IMethodBinding
028: * @since 2.0
029: */
030: public interface IBinding {
031:
032: /**
033: * Kind constant (value 1) indicating a package binding.
034: * Bindings of this kind can be safely cast to <code>IPackageBinding</code>.
035: *
036: * @see #getKind()
037: * @see IPackageBinding
038: */
039: public static final int PACKAGE = 1;
040:
041: /**
042: * Kind constant (value 2) indicating a type binding.
043: * Bindings of this kind can be safely cast to <code>ITypeBinding</code>.
044: *
045: * @see #getKind()
046: * @see ITypeBinding
047: */
048: public static final int TYPE = 2;
049:
050: /**
051: * Kind constant (value 3) indicating a field or local variable binding.
052: * Bindings of this kind can be safely cast to <code>IVariableBinding</code>.
053: *
054: * @see #getKind()
055: * @see IVariableBinding
056: */
057: public static final int VARIABLE = 3;
058:
059: /**
060: * Kind constant (value 4) indicating a method or constructor binding.
061: * Bindings of this kind can be safely cast to <code>IMethodBinding</code>.
062: *
063: * @see #getKind()
064: * @see IMethodBinding
065: */
066: public static final int METHOD = 4;
067:
068: /**
069: * Kind constant (value 5) indicating an annotation binding.
070: * Bindings of this kind can be safely cast to <code>IAnnotationBinding</code>.
071: *
072: * @see #getKind()
073: * @see IAnnotationBinding
074: * @since 3.2
075: */
076: public static final int ANNOTATION = 5;
077:
078: /**
079: * Kind constant (value 6) indicating a member value pair binding.
080: * Bindings of this kind can be safely cast to <code>IMemberValuePairBinding</code>.
081: *
082: * @see #getKind()
083: * @see IMemberValuePairBinding
084: * @since 3.2
085: */
086: public static final int MEMBER_VALUE_PAIR = 6;
087:
088: /**
089: * Return the resolved annotations associated with this binding.
090: * <ul>
091: * <li>Package bindings - these are annotations on a package declaration.
092: * </li>
093: * <li>Type bindings - these are annotations on a class, interface, enum,
094: * or annotation type declaration. The result is the same regardless of
095: * whether the type is parameterized.</li>
096: * <li>Method bindings - these are annotations on a method or constructor
097: * declaration. The result is the same regardless of whether the method is
098: * parameterized.</li>
099: * <li>Variable bindings - these are annotations on a field, enum constant,
100: * or formal parameter declaration.</li>
101: * <li>Annotation bindings - an empty array is always returned</li>
102: * <li>Member value pair bindings - an empty array is always returned<li>
103: * </ul>
104: *
105: * @return the list of resolved annotations, or the empty list if there are no
106: * annotations associated with the object
107: * @since 3.2
108: */
109: public IAnnotationBinding[] getAnnotations();
110:
111: /**
112: * Returns the kind of bindings this is. That is one of the kind constants:
113: * <code>PACKAGE</code>,
114: * <code>TYPE</code>,
115: * <code>VARIABLE</code>,
116: * <code>METHOD</code>,
117: * <code>ANNOTATION</code>,
118: * or <code>MEMBER_VALUE_PAIR</code>.
119: * <p>
120: * Note that additional kinds might be added in the
121: * future, so clients should not assume this list is exhaustive and
122: * should program defensively, e.g. by having a reasonable default
123: * in a switch statement.
124: * </p>
125: * @return one of the kind constants
126: */
127: public int getKind();
128:
129: /**
130: * Returns the name of this binding.
131: * Details of the name are specified with each specific kind of binding.
132: *
133: * @return the name of this binding
134: */
135: public String getName();
136:
137: /**
138: * Returns the modifiers for this binding.
139: * <p>
140: * Note that deprecated is not included among the modifiers.
141: * Use <code>isDeprecated</code> to find out whether a binding is deprecated.
142: * </p>
143: *
144: * @return the bit-wise or of <code>Modifier</code> constants
145: * @see Modifier
146: */
147: public int getModifiers();
148:
149: /**
150: * Return whether this binding is for something that is deprecated.
151: * A deprecated class, interface, field, method, or constructor is one that
152: * is marked with the 'deprecated' tag in its Javadoc comment.
153: *
154: * @return <code>true</code> if this binding is deprecated, and
155: * <code>false</code> otherwise
156: */
157: public boolean isDeprecated();
158:
159: /**
160: * Return whether this binding is created because the bindings recovery is enabled. This binding is considered
161: * to be incomplete. Its internal state might be incomplete.
162: *
163: * @return <code>true</code> if this binding is a recovered binding, and
164: * <code>false</code> otherwise
165: * @since 3.3
166: */
167: public boolean isRecovered();
168:
169: /**
170: * Returns whether this binding is synthetic. A synthetic binding is one that
171: * was made up by the compiler, rather than something declared in the
172: * source code. Note that default constructors (the 0-argument constructor that
173: * the compiler generates for class declarations with no explicit constructors
174: * declarations) are not generally considered synthetic (although they
175: * may be if the class itself is synthetic).
176: * But see {@link IMethodBinding#isDefaultConstructor() IMethodBinding.isDefaultConstructor}
177: * for cases where the compiled-generated default constructor can be recognized
178: * instead.
179: *
180: * @return <code>true</code> if this binding is synthetic, and
181: * <code>false</code> otherwise
182: * @see IMethodBinding#isDefaultConstructor()
183: */
184: public boolean isSynthetic();
185:
186: /**
187: * Returns the Java element that corresponds to this binding.
188: * Returns <code>null</code> if this binding has no corresponding
189: * Java element.
190: * <p>
191: * For array types, this method returns the Java element that corresponds
192: * to the array's element type. For raw and parameterized types, this method
193: * returns the Java element of the erasure. For annotations, this methods
194: * returns the Java element of the annotation type.
195: * </p>
196: * <p>
197: * Here are the cases where a <code>null</code> should be expected:
198: * <ul>
199: * <li>primitive types, including void</li>
200: * <li>null type</li>
201: * <li>wildcard types</li>
202: * <li>capture types</li>
203: * <li>array types of any of the above</li>
204: * <li>the "length" field of an array type</li>
205: * <li>the default constructor of a source class</li>
206: * <li>the constructor of an anonymous class</li>
207: * <li>member value pairs</li>
208: * </ul>
209: * For all other kind of type, method, variable, annotation and package bindings,
210: * this method returns non-<code>null</code>.
211: * </p>
212: *
213: * @return the Java element that corresponds to this binding,
214: * or <code>null</code> if none
215: * @since 3.1
216: */
217: public IJavaElement getJavaElement();
218:
219: /**
220: * Returns the key for this binding.
221: * <p>
222: * Within a connected cluster of bindings (for example, all bindings
223: * reachable from a given AST), each binding will have a distinct keys.
224: * The keys are generated in a manner that is predictable and as
225: * stable as possible. This last property makes these keys useful for
226: * comparing bindings between disconnected clusters of bindings (for example,
227: * the bindings between the "before" and "after" ASTs of the same
228: * compilation unit).
229: * </p>
230: * <p>
231: * The exact details of how the keys are generated is unspecified.
232: * However, it is a function of the following information:
233: * <ul>
234: * <li>packages - the name of the package (for an unnamed package,
235: * some internal id)</li>
236: * <li>classes or interfaces - the VM name of the type and the key
237: * of its package</li>
238: * <li>array types - the key of the component type and number of
239: * dimensions</li>
240: * <li>primitive types - the name of the primitive type</li>
241: * <li>fields - the name of the field and the key of its declaring
242: * type</li>
243: * <li>methods - the name of the method, the key of its declaring
244: * type, and the keys of the parameter types</li>
245: * <li>constructors - the key of its declaring class, and the
246: * keys of the parameter types</li>
247: * <li>local variables - the name of the local variable, the index of the
248: * declaring block relative to its parent, the key of its method</li>
249: * <li>local types - the name of the type, the index of the declaring
250: * block relative to its parent, the key of its method</li>
251: * <li>anonymous types - the occurence count of the anonymous
252: * type relative to its declaring type, the key of its declaring type</li>
253: * <li>enum types - treated like classes</li>
254: * <li>annotation types - treated like interfaces</li>
255: * <li>type variables - the name of the type variable and
256: * the key of the generic type or generic method that declares that
257: * type variable</li>
258: * <li>wildcard types - the key of the optional wildcard type bound</li>
259: * <li>capture type bindings - the key of the wildcard captured</li>
260: * <li>generic type instances - the key of the generic type and the keys
261: * of the type arguments used to instantiate it, and whether the
262: * instance is explicit (a parameterized type reference) or
263: * implicit (a raw type reference)</li>
264: * <li>generic method instances - the key of the generic method and the keys
265: * of the type arguments used to instantiate it, and whether the
266: * instance is explicit (a parameterized method reference) or
267: * implicit (a raw method reference)</li>
268: * <li>members of generic type instances - the key of the generic type
269: * instance and the key of the corresponding member in the generic
270: * type</li>
271: * </ul>
272: * </p>
273: * <p>Note that the key for annotation bindings and member value pair bindings is
274: * not yet implemented. This returns <code>null</code> for these 2 kinds of bindings.<br>
275: * Recovered bindings have a unique key.
276: * </p>
277: *
278: * @return the key for this binding
279: */
280: public String getKey();
281:
282: /**
283: * There is no special definition of equality for bindings; equality is
284: * simply object identity. Within the context of a single cluster of
285: * bindings, each binding is represented by a distinct object. However,
286: * between different clusters of bindings, the binding objects may or may
287: * not be different; in these cases, the client should compare bindings
288: * using {@link #isEqualTo(IBinding)}, which checks their keys.
289: *
290: * @param obj {@inheritDoc}
291: * @return {@inheritDoc}
292: */
293: public boolean equals(Object obj);
294:
295: /**
296: * Returns whether this binding has the same key as that of the given
297: * binding. Within the context of a single cluster of bindings, each
298: * binding is represented by a distinct object. However, between
299: * different clusters of bindings, the binding objects may or may
300: * not be different objects; in these cases, the binding keys
301: * are used where available.
302: *
303: * @param binding the other binding, or <code>null</code>
304: * @return <code>true</code> if the given binding is the identical
305: * object as this binding, or if the keys of both bindings are the
306: * same string; <code>false</code> if the given binding is
307: * <code>null</code>, or if the bindings do not have the same key,
308: * or if one or both of the bindings have no key
309: * @see #getKey()
310: * @since 3.1
311: */
312: public boolean isEqualTo(IBinding binding);
313:
314: /**
315: * Returns a string representation of this binding suitable for debugging
316: * purposes only.
317: *
318: * @return a debug string
319: */
320: public String toString();
321: }
|