eclipse_jdt/src/org/eclipse/jdt/core/dom/IBinding.java

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