KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > dom > IBinding


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 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 org.eclipse.jdt.core.dom;
13
14 import org.eclipse.jdt.core.IJavaElement;
15
16 /**
17  * A binding represents a named entity in the Java language. The world of
18  * bindings provides an integrated picture of the structure of the program as
19  * seen from the compiler's point of view. This interface declare protocol
20  * common to the various different kinds of named entities in the Java language:
21  * packages, types, fields, methods, constructors, and local variables.
22  * <p>
23  * This interface is not intended to be implemented by clients.
24  * </p>
25  *
26  * @see IPackageBinding
27  * @see ITypeBinding
28  * @see IVariableBinding
29  * @see IMethodBinding
30  * @since 2.0
31  */
32 public interface IBinding {
33
34     /**
35      * Kind constant (value 1) indicating a package binding.
36      * Bindings of this kind can be safely cast to <code>IPackageBinding</code>.
37      *
38      * @see #getKind()
39      * @see IPackageBinding
40      */
41     public static final int PACKAGE = 1;
42
43     /**
44      * Kind constant (value 2) indicating a type binding.
45      * Bindings of this kind can be safely cast to <code>ITypeBinding</code>.
46      *
47      * @see #getKind()
48      * @see ITypeBinding
49      */
50     public static final int TYPE = 2;
51
52     /**
53      * Kind constant (value 3) indicating a field or local variable binding.
54      * Bindings of this kind can be safely cast to <code>IVariableBinding</code>.
55      *
56      * @see #getKind()
57      * @see IVariableBinding
58      */
59     public static final int VARIABLE = 3;
60
61     /**
62      * Kind constant (value 4) indicating a method or constructor binding.
63      * Bindings of this kind can be safely cast to <code>IMethodBinding</code>.
64      *
65      * @see #getKind()
66      * @see IMethodBinding
67      */
68     public static final int METHOD = 4;
69
70     /**
71      * Kind constant (value 5) indicating an annotation binding.
72      * Bindings of this kind can be safely cast to <code>IAnnotationBinding</code>.
73      *
74      * @see #getKind()
75      * @see IAnnotationBinding
76      * @since 3.2
77      */
78     public static final int ANNOTATION = 5;
79
80     /**
81      * Kind constant (value 6) indicating a member value pair binding.
82      * Bindings of this kind can be safely cast to <code>IMemberValuePairBinding</code>.
83      *
84      * @see #getKind()
85      * @see IMemberValuePairBinding
86      * @since 3.2
87      */
88     public static final int MEMBER_VALUE_PAIR = 6;
89
90     /**
91      * Return the resolved annotations associated with this binding.
92      * <ul>
93      * <li>Package bindings - these are annotations on a package declaration.
94      * </li>
95      * <li>Type bindings - these are annotations on a class, interface, enum,
96      * or annotation type declaration. The result is the same regardless of
97      * whether the type is parameterized.</li>
98      * <li>Method bindings - these are annotations on a method or constructor
99      * declaration. The result is the same regardless of whether the method is
100      * parameterized.</li>
101      * <li>Variable bindings - these are annotations on a field, enum constant,
102      * or formal parameter declaration.</li>
103      * <li>Annotation bindings - an empty array is always returned</li>
104      * <li>Member value pair bindings - an empty array is always returned<li>
105      * </ul>
106      *
107      * @return the list of resolved annotations, or the empty list if there are no
108      * annotations associated with the object
109      * @since 3.2
110      */
111     public IAnnotationBinding[] getAnnotations();
112
113     /**
114      * Returns the kind of bindings this is. That is one of the kind constants:
115      * <code>PACKAGE</code>,
116      * <code>TYPE</code>,
117      * <code>VARIABLE</code>,
118      * <code>METHOD</code>,
119      * <code>ANNOTATION</code>,
120      * or <code>MEMBER_VALUE_PAIR</code>.
121      * <p>
122      * Note that additional kinds might be added in the
123      * future, so clients should not assume this list is exhaustive and
124      * should program defensively, e.g. by having a reasonable default
125      * in a switch statement.
126      * </p>
127      * @return one of the kind constants
128      */
129     public int getKind();
130
131     /**
132      * Returns the name of this binding.
133      * Details of the name are specified with each specific kind of binding.
134      *
135      * @return the name of this binding
136      */
137     public String JavaDoc getName();
138
139     /**
140      * Returns the modifiers for this binding.
141      * <p>
142      * Note that deprecated is not included among the modifiers.
143      * Use <code>isDeprecated</code> to find out whether a binding is deprecated.
144      * </p>
145      *
146      * @return the bit-wise or of <code>Modifier</code> constants
147      * @see Modifier
148      */
149     public int getModifiers();
150
151     /**
152      * Return whether this binding is for something that is deprecated.
153      * A deprecated class, interface, field, method, or constructor is one that
154      * is marked with the 'deprecated' tag in its Javadoc comment.
155      *
156      * @return <code>true</code> if this binding is deprecated, and
157      * <code>false</code> otherwise
158      */
159     public boolean isDeprecated();
160
161     /**
162      * Return whether this binding is created because the bindings recovery is enabled. This binding is considered
163      * to be incomplete. Its internal state might be incomplete.
164      *
165      * @return <code>true</code> if this binding is a recovered binding, and
166      * <code>false</code> otherwise
167      * @since 3.3
168      */
169     public boolean isRecovered();
170
171     /**
172      * Returns whether this binding is synthetic. A synthetic binding is one that
173      * was made up by the compiler, rather than something declared in the
174      * source code. Note that default constructors (the 0-argument constructor that
175      * the compiler generates for class declarations with no explicit constructors
176      * declarations) are not generally considered synthetic (although they
177      * may be if the class itself is synthetic).
178      * But see {@link IMethodBinding#isDefaultConstructor() IMethodBinding.isDefaultConstructor}
179      * for cases where the compiled-generated default constructor can be recognized
180      * instead.
181      *
182      * @return <code>true</code> if this binding is synthetic, and
183      * <code>false</code> otherwise
184      * @see IMethodBinding#isDefaultConstructor()
185      */
186     public boolean isSynthetic();
187
188     /**
189      * Returns the Java element that corresponds to this binding.
190      * Returns <code>null</code> if this binding has no corresponding
191      * Java element.
192      * <p>
193      * For array types, this method returns the Java element that corresponds
194      * to the array's element type. For raw and parameterized types, this method
195      * returns the Java element of the erasure. For annotations, this methods
196      * returns the Java element of the annotation type.
197      * </p>
198      * <p>
199      * Here are the cases where a <code>null</code> should be expected:
200      * <ul>
201      * <li>primitive types, including void</li>
202      * <li>null type</li>
203      * <li>wildcard types</li>
204      * <li>capture types</li>
205      * <li>array types of any of the above</li>
206      * <li>the "length" field of an array type</li>
207      * <li>the default constructor of a source class</li>
208      * <li>the constructor of an anonymous class</li>
209      * <li>member value pairs</li>
210      * </ul>
211      * For all other kind of type, method, variable, annotation and package bindings,
212      * this method returns non-<code>null</code>.
213      * </p>
214      *
215      * @return the Java element that corresponds to this binding,
216      * or <code>null</code> if none
217      * @since 3.1
218      */
219     public IJavaElement getJavaElement();
220
221     /**
222      * Returns the key for this binding.
223      * <p>
224      * Within a connected cluster of bindings (for example, all bindings
225      * reachable from a given AST), each binding will have a distinct keys.
226      * The keys are generated in a manner that is predictable and as
227      * stable as possible. This last property makes these keys useful for
228      * comparing bindings between disconnected clusters of bindings (for example,
229      * the bindings between the "before" and "after" ASTs of the same
230      * compilation unit).
231      * </p>
232      * <p>
233      * The exact details of how the keys are generated is unspecified.
234      * However, it is a function of the following information:
235      * <ul>
236      * <li>packages - the name of the package (for an unnamed package,
237      * some internal id)</li>
238      * <li>classes or interfaces - the VM name of the type and the key
239      * of its package</li>
240      * <li>array types - the key of the component type and number of
241      * dimensions</li>
242      * <li>primitive types - the name of the primitive type</li>
243      * <li>fields - the name of the field and the key of its declaring
244      * type</li>
245      * <li>methods - the name of the method, the key of its declaring
246      * type, and the keys of the parameter types</li>
247      * <li>constructors - the key of its declaring class, and the
248      * keys of the parameter types</li>
249      * <li>local variables - the name of the local variable, the index of the
250      * declaring block relative to its parent, the key of its method</li>
251      * <li>local types - the name of the type, the index of the declaring
252      * block relative to its parent, the key of its method</li>
253      * <li>anonymous types - the occurence count of the anonymous
254      * type relative to its declaring type, the key of its declaring type</li>
255      * <li>enum types - treated like classes</li>
256      * <li>annotation types - treated like interfaces</li>
257      * <li>type variables - the name of the type variable and
258      * the key of the generic type or generic method that declares that
259      * type variable</li>
260      * <li>wildcard types - the key of the optional wildcard type bound</li>
261      * <li>capture type bindings - the key of the wildcard captured</li>
262      * <li>generic type instances - the key of the generic type and the keys
263      * of the type arguments used to instantiate it, and whether the
264      * instance is explicit (a parameterized type reference) or
265      * implicit (a raw type reference)</li>
266      * <li>generic method instances - the key of the generic method and the keys
267      * of the type arguments used to instantiate it, and whether the
268      * instance is explicit (a parameterized method reference) or
269      * implicit (a raw method reference)</li>
270      * <li>members of generic type instances - the key of the generic type
271      * instance and the key of the corresponding member in the generic
272      * type</li>
273      * </ul>
274      * </p>
275      * <p>Note that the key for annotation bindings and member value pair bindings is
276      * not yet implemented. This returns <code>null</code> for these 2 kinds of bindings.<br>
277      * Recovered bindings have a unique key.
278      * </p>
279      *
280      * @return the key for this binding
281      */
282     public String JavaDoc getKey();
283
284     /**
285      * There is no special definition of equality for bindings; equality is
286      * simply object identity. Within the context of a single cluster of
287      * bindings, each binding is represented by a distinct object. However,
288      * between different clusters of bindings, the binding objects may or may
289      * not be different; in these cases, the client should compare bindings
290      * using {@link #isEqualTo(IBinding)}, which checks their keys.
291      *
292      * @param obj {@inheritDoc}
293      * @return {@inheritDoc}
294      */
295     public boolean equals(Object JavaDoc obj);
296
297     /**
298      * Returns whether this binding has the same key as that of the given
299      * binding. Within the context of a single cluster of bindings, each
300      * binding is represented by a distinct object. However, between
301      * different clusters of bindings, the binding objects may or may
302      * not be different objects; in these cases, the binding keys
303      * are used where available.
304      *
305      * @param binding the other binding, or <code>null</code>
306      * @return <code>true</code> if the given binding is the identical
307      * object as this binding, or if the keys of both bindings are the
308      * same string; <code>false</code> if the given binding is
309      * <code>null</code>, or if the bindings do not have the same key,
310      * or if one or both of the bindings have no key
311      * @see #getKey()
312      * @since 3.1
313      */
314     public boolean isEqualTo(IBinding binding);
315
316     /**
317      * Returns a string representation of this binding suitable for debugging
318      * purposes only.
319      *
320      * @return a debug string
321      */
322     public String JavaDoc toString();
323 }
324
Popular Tags