org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/dom/IBinding.java

IBinding
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
Copyright (c) 2000, 2019 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2000, 2019 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.jdt.core.dom;

import org.eclipse.jdt.core.IAnnotation;
import org.eclipse.jdt.core.IJavaElement;

A binding represents a named entity in the Java language. The world of
bindings provides an integrated picture of the structure of the program as
seen from the compiler's point of view. This interface declares protocols
common to the various different kinds of named entities in the Java language:
packages, types, fields, methods, constructors, local variables, and annotations.
See Also: IPackageBinding
ITypeBinding
IVariableBinding
IMethodBinding
IAnnotationBinding
IMemberValuePairBinding
Since: 2.0
@noimplement This interface is not intended to be implemented by clients./**
 * A binding represents a named entity in the Java language. The world of
 * bindings provides an integrated picture of the structure of the program as
 * seen from the compiler's point of view. This interface declares protocols
 * common to the various different kinds of named entities in the Java language:
 * packages, types, fields, methods, constructors, local variables, and annotations.
 *
 * @see IPackageBinding
 * @see ITypeBinding
 * @see IVariableBinding
 * @see IMethodBinding
 * @see IAnnotationBinding
 * @see IMemberValuePairBinding
 * @since 2.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IBinding {

	Kind constant (value 1) indicating a package binding.
Bindings of this kind can be safely cast to IPackageBinding.
See Also: getKind()
IPackageBinding/**
	 * Kind constant (value 1) indicating a package binding.
	 * Bindings of this kind can be safely cast to <code>IPackageBinding</code>.
	 *
	 * @see #getKind()
	 * @see IPackageBinding
	 */
	public static final int PACKAGE = 1;

	Kind constant (value 2) indicating a type binding.
Bindings of this kind can be safely cast to ITypeBinding.
See Also: getKind()
ITypeBinding/**
	 * Kind constant (value 2) indicating a type binding.
	 * Bindings of this kind can be safely cast to <code>ITypeBinding</code>.
	 *
	 * @see #getKind()
	 * @see ITypeBinding
	 */
	public static final int TYPE = 2;

	Kind constant (value 3) indicating a field or local variable binding.
Bindings of this kind can be safely cast to IVariableBinding.
See Also: getKind()
IVariableBinding/**
	 * Kind constant (value 3) indicating a field or local variable binding.
	 * Bindings of this kind can be safely cast to <code>IVariableBinding</code>.
	 *
	 * @see #getKind()
	 * @see IVariableBinding
	 */
	public static final int VARIABLE = 3;

	Kind constant (value 4) indicating a method or constructor binding.
Bindings of this kind can be safely cast to IMethodBinding.
See Also: getKind()
IMethodBinding/**
	 * Kind constant (value 4) indicating a method or constructor binding.
	 * Bindings of this kind can be safely cast to <code>IMethodBinding</code>.
	 *
	 * @see #getKind()
	 * @see IMethodBinding
	 */
	public static final int METHOD = 4;

	Kind constant (value 5) indicating an annotation binding.
Bindings of this kind can be safely cast to IAnnotationBinding.
See Also: getKind()
IAnnotationBinding
Since: 3.2/**
	 * Kind constant (value 5) indicating an annotation binding.
	 * Bindings of this kind can be safely cast to <code>IAnnotationBinding</code>.
	 *
	 * @see #getKind()
	 * @see IAnnotationBinding
	 * @since 3.2
	 */
	public static final int ANNOTATION = 5;

	Kind constant (value 6) indicating a member value pair binding.
Bindings of this kind can be safely cast to IMemberValuePairBinding.
See Also: getKind()
IMemberValuePairBinding
Since: 3.2/**
	 * Kind constant (value 6) indicating a member value pair binding.
	 * Bindings of this kind can be safely cast to <code>IMemberValuePairBinding</code>.
	 *
	 * @see #getKind()
	 * @see IMemberValuePairBinding
	 * @since 3.2
	 */
	public static final int MEMBER_VALUE_PAIR = 6;

	Kind constant (value 7) indicating a module binding (added in JLS9 API).
Bindings of this kind can be safely cast to IModuleBinding.
See Also: getKind()
IModuleBinding
Since: 3.14/**
	 * Kind constant (value 7) indicating a module binding (added in JLS9 API).
	 * Bindings of this kind can be safely cast to <code>IModuleBinding</code>.
	 *
	 * @see #getKind()
	 * @see IModuleBinding
	 * @since 3.14
	 */
	public static final int MODULE = 7;

	Returns the resolved declaration annotations associated with this binding.

Package bindings - these are annotations on a package declaration.

Type bindings - these are annotations on a class, interface, enum,
or annotation type declaration. The result is the same regardless of
whether the type is parameterized.
Method bindings - these are annotations on a method or constructor
declaration. The result is the same regardless of whether the method is
parameterized.
Variable bindings - these are annotations on a field, enum constant,
or formal parameter declaration.
Annotation bindings - an empty array is always returned
Member value pair bindings - an empty array is always returned


Note: This method only returns declaration annotations.
Type annotations in the sense of JLS8 9.7.4 are not returned. Type annotations can be retrieved via ITypeBinding.getTypeAnnotations(). 
Returns: the list of resolved declaration annotations, or the empty list if there are no
   declaration annotations associated with the entity represented by this binding
Since: 3.2/**
	 * Returns the resolved declaration annotations associated with this binding.
	 * <ul>
	 * <li>Package bindings - these are annotations on a package declaration.
	 * </li>
	 * <li>Type bindings - these are annotations on a class, interface, enum,
	 * or annotation type declaration. The result is the same regardless of
	 * whether the type is parameterized.</li>
	 * <li>Method bindings - these are annotations on a method or constructor
	 * declaration. The result is the same regardless of whether the method is
	 * parameterized.</li>
	 * <li>Variable bindings - these are annotations on a field, enum constant,
	 * or formal parameter declaration.</li>
	 * <li>Annotation bindings - an empty array is always returned</li>
	 * <li>Member value pair bindings - an empty array is always returned</li>
	 * </ul>
	 * <p>
	 * <b>Note:</b> This method only returns declaration annotations.
	 * <em>Type annotations</em> in the sense of JLS8 9.7.4 are <em>not</em> returned.
	 * Type annotations can be retrieved via {@link ITypeBinding#getTypeAnnotations()}. 
	 * </p>
	 *
	 * @return the list of resolved declaration annotations, or the empty list if there are no
	 *    declaration annotations associated with the entity represented by this binding
	 * @since 3.2
	 */
	public IAnnotationBinding[] getAnnotations();

	Returns the kind of bindings this is. That is one of the kind constants:
PACKAGE,
	TYPE,
	VARIABLE,
	METHOD,
	ANNOTATION,
 MEMBER_VALUE_PAIR, or
MODULE.

Note that additional kinds might be added in the
future, so clients should not assume this list is exhaustive and
should program defensively, e.g. by having a reasonable default
in a switch statement.

Returns: one of the kind constants/**
	 * Returns the kind of bindings this is. That is one of the kind constants:
	 * <code>PACKAGE</code>,
	 * 	<code>TYPE</code>,
	 * 	<code>VARIABLE</code>,
	 * 	<code>METHOD</code>,
	 * 	<code>ANNOTATION</code>,
	 *  <code>MEMBER_VALUE_PAIR</code>, or
	 * <code>MODULE</code>.
	 * <p>
	 * Note that additional kinds might be added in the
	 * future, so clients should not assume this list is exhaustive and
	 * should program defensively, e.g. by having a reasonable default
	 * in a switch statement.
	 * </p>
	 * @return one of the kind constants
	 */
	public int getKind();

	Returns the name of this binding.
Details of the name are specified with each specific kind of binding.
Returns: the name of this binding/**
	 * Returns the name of this binding.
	 * Details of the name are specified with each specific kind of binding.
	 *
	 * @return the name of this binding
	 */
	public String getName();

	Returns the modifiers for this binding.

Note that 'deprecated' is not included among the modifiers.
Use isDeprecated to find out whether a binding is deprecated.

See Also: Modifier
Returns: the bit-wise or of Modifier constants/**
	 * Returns the modifiers for this binding.
	 * <p>
	 * Note that 'deprecated' is not included among the modifiers.
	 * Use <code>isDeprecated</code> to find out whether a binding is deprecated.
	 * </p>
	 *
	 * @return the bit-wise or of <code>Modifier</code> constants
	 * @see Modifier
	 */
	public int getModifiers();

	Return whether this binding is for something that is deprecated.
A deprecated class, interface, field, method, or constructor is one that
is marked with the 'deprecated' tag in its Javadoc comment.
Returns: true if this binding is deprecated, and
   false otherwise/**
	 * Return whether this binding is for something that is deprecated.
	 * A deprecated class, interface, field, method, or constructor is one that
	 * is marked with the 'deprecated' tag in its Javadoc comment.
	 *
	 * @return <code>true</code> if this binding is deprecated, and
	 *    <code>false</code> otherwise
	 */
	public boolean isDeprecated();

	Return whether this binding is created because the bindings recovery is enabled. This binding is considered
to be incomplete. Its internal state might be incomplete.
Returns: true if this binding is a recovered binding, and
   false otherwise
Since: 3.3/**
	 * Return whether this binding is created because the bindings recovery is enabled. This binding is considered
	 * to be incomplete. Its internal state might be incomplete.
	 *
	 * @return <code>true</code> if this binding is a recovered binding, and
	 *    <code>false</code> otherwise
	 * @since 3.3
	 */
	public boolean isRecovered();

	Returns whether this binding is synthetic. A synthetic binding is one that was made up by the compiler, rather than something declared in the source code. Note that default constructors (the 0-argument constructor that the compiler generates for class declarations with no explicit constructors declarations) are not generally considered synthetic (although they may be if the class itself is synthetic). But see IMethodBinding.isDefaultConstructor for cases where the compiled-generated default constructor can be recognized instead. 
See Also: IMethodBinding.isDefaultConstructor()
Returns: true if this binding is synthetic, and
   false otherwise/**
	 * Returns whether this binding is synthetic. A synthetic binding is one that
	 * was made up by the compiler, rather than something declared in the
	 * source code. Note that default constructors (the 0-argument constructor that
	 * the compiler generates for class declarations with no explicit constructors
	 * declarations) are not generally considered synthetic (although they
	 * may be if the class itself is synthetic).
	 * But see {@link IMethodBinding#isDefaultConstructor() IMethodBinding.isDefaultConstructor}
	 * for cases where the compiled-generated default constructor can be recognized
	 * instead.
	 *
	 * @return <code>true</code> if this binding is synthetic, and
	 *    <code>false</code> otherwise
	 * @see IMethodBinding#isDefaultConstructor()
	 */
	public boolean isSynthetic();

	Returns the Java element that corresponds to this binding.
Returns null if this binding has no corresponding
Java element.
 For array types, this method returns the Java element that corresponds to the array's element type. For raw and parameterized types, this method returns the Java element of the erasure. For annotations, this method returns the Java element of the annotation (i.e. an IAnnotation). 

Here are the cases where a null should be expected:

primitive types, including void
null type
wildcard types
capture types
array types of any of the above
the "length" field of an array type
the default constructor of a source class
the constructor of an anonymous class
member value pairs
synthetic bindings
problem package bindings (since Java 9)


For all other kind of type, method, variable, annotation and package bindings,
this method returns non-null.

Returns: the Java element that corresponds to this binding,
		or null if none
Since: 3.1/**
	 * Returns the Java element that corresponds to this binding.
	 * Returns <code>null</code> if this binding has no corresponding
	 * Java element.
	 * <p>
	 * For array types, this method returns the Java element that corresponds
	 * to the array's element type. For raw and parameterized types, this method
	 * returns the Java element of the erasure. For annotations, this method
	 * returns the Java element of the annotation (i.e. an {@link IAnnotation}).
	 * </p>
	 * <p>
	 * Here are the cases where a <code>null</code> should be expected:
	 * <ul>
	 * <li>primitive types, including void</li>
	 * <li>null type</li>
	 * <li>wildcard types</li>
	 * <li>capture types</li>
	 * <li>array types of any of the above</li>
	 * <li>the "length" field of an array type</li>
	 * <li>the default constructor of a source class</li>
	 * <li>the constructor of an anonymous class</li>
	 * <li>member value pairs</li>
	 * <li>synthetic bindings</li>
	 * <li>problem package bindings (since Java 9)</li>
	 * </ul>
	 * <p>
	 * For all other kind of type, method, variable, annotation and package bindings,
	 * this method returns non-<code>null</code>.
	 * </p>
	 *
	 * @return the Java element that corresponds to this binding,
	 * 		or <code>null</code> if none
	 * @since 3.1
	 */
	public IJavaElement getJavaElement();

	Returns the key for this binding.
 Within a single cluster of bindings (produced by the same call to an ASTParser#create*(*) method)), each binding has a distinct key. The keys are generated in a manner that is predictable and as stable as possible. This last property makes these keys useful for comparing bindings between different clusters of bindings (for example, the bindings between the "before" and "after" ASTs of the same compilation unit). 

The exact details of how the keys are generated is unspecified.
However, it is a function of the following information:

packages - the name of the package (for an unnamed package,
  some internal id)
classes or interfaces - the VM name of the type and the key
  of its package
array types - the key of the component type and number of
  dimensions
primitive types - the name of the primitive type
fields - the name of the field and the key of its declaring
  type
methods - the name of the method, the key of its declaring
  type, and the keys of the parameter types
constructors - the key of its declaring class, and the
  keys of the parameter types
local variables - the name of the local variable, the index of the
  declaring block relative to its parent, the key of its method
local types - the name of the type, the index of the declaring
  block relative to its parent, the key of its method
anonymous types - the occurrence count of the anonymous
  type relative to its declaring type, the key of its declaring type
enum types - treated like classes
annotation types - treated like interfaces
type variables - the name of the type variable and
the key of the generic type or generic method that declares that
type variable
wildcard types - the key of the optional wildcard type bound
capture type bindings - the key of the wildcard captured
generic type instances - the key of the generic type and the keys
of the type arguments used to instantiate it, and whether the
instance is explicit (a parameterized type reference) or
implicit (a raw type reference)
generic method instances - the key of the generic method and the keys
of the type arguments used to instantiate it, and whether the
instance is explicit (a parameterized method reference) or
implicit (a raw method reference)
members of generic type instances - the key of the generic type
instance and the key of the corresponding member in the generic
type
annotations - the key of the annotated element and the key of
the annotation type


The key for a type binding does not contain type annotations, so type bindings with different type annotations may have the same key (iff they denote the same un-annotated type). By construction, this also applies to method bindings if their declaring types contain type annotations. 
Note that the key for member value pair bindings is
not yet implemented. This method returns null for that kind of bindings.

Recovered bindings have a unique key.

Returns: the key for this binding/**
	 * Returns the key for this binding.
	 * <p>
	 * Within a single cluster of bindings (produced by the same call to an
	 * {@code ASTParser#create*(*)} method)), each binding has a distinct key.
	 * The keys are generated in a manner that is predictable and as
	 * stable as possible. This last property makes these keys useful for
	 * comparing bindings between different clusters of bindings (for example,
	 * the bindings between the "before" and "after" ASTs of the same
	 * compilation unit).
	 * </p>
	 * <p>
	 * The exact details of how the keys are generated is unspecified.
	 * However, it is a function of the following information:
	 * <ul>
	 * <li>packages - the name of the package (for an unnamed package,
	 *   some internal id)</li>
	 * <li>classes or interfaces - the VM name of the type and the key
	 *   of its package</li>
	 * <li>array types - the key of the component type and number of
	 *   dimensions</li>
	 * <li>primitive types - the name of the primitive type</li>
	 * <li>fields - the name of the field and the key of its declaring
	 *   type</li>
	 * <li>methods - the name of the method, the key of its declaring
	 *   type, and the keys of the parameter types</li>
	 * <li>constructors - the key of its declaring class, and the
	 *   keys of the parameter types</li>
	 * <li>local variables - the name of the local variable, the index of the
	 *   declaring block relative to its parent, the key of its method</li>
	 * <li>local types - the name of the type, the index of the declaring
	 *   block relative to its parent, the key of its method</li>
	 * <li>anonymous types - the occurrence count of the anonymous
	 *   type relative to its declaring type, the key of its declaring type</li>
	 * <li>enum types - treated like classes</li>
	 * <li>annotation types - treated like interfaces</li>
	 * <li>type variables - the name of the type variable and
	 * the key of the generic type or generic method that declares that
	 * type variable</li>
	 * <li>wildcard types - the key of the optional wildcard type bound</li>
     * <li>capture type bindings - the key of the wildcard captured</li>
	 * <li>generic type instances - the key of the generic type and the keys
	 * of the type arguments used to instantiate it, and whether the
	 * instance is explicit (a parameterized type reference) or
	 * implicit (a raw type reference)</li>
	 * <li>generic method instances - the key of the generic method and the keys
	 * of the type arguments used to instantiate it, and whether the
	 * instance is explicit (a parameterized method reference) or
	 * implicit (a raw method reference)</li>
	 * <li>members of generic type instances - the key of the generic type
	 * instance and the key of the corresponding member in the generic
	 * type</li>
	 * <li>annotations - the key of the annotated element and the key of
	 * the annotation type</li>
	 * </ul>
	 * <p>
	 * The key for a type binding does <em>not</em> contain {@link ITypeBinding#getTypeAnnotations() type annotations},
	 * so type bindings with different type annotations may have the same key (iff they denote the same un-annotated type).
	 * By construction, this also applies to method bindings if their declaring types contain type annotations.
	 * </p>
	 * <p>Note that the key for member value pair bindings is
	 * not yet implemented. This method returns <code>null</code> for that kind of bindings.<br>
	 * Recovered bindings have a unique key.
	 * </p>
	 *
	 * @return the key for this binding
	 */
	public String getKey();

	There is no special definition of equality for bindings; equality is simply object identity. Within the context of a single cluster of bindings (produced by the same call to an ASTParser#create*(*) method), each binding is represented by a separate object. However, between different clusters of bindings, the binding objects may or may not be different; in these cases, the client should compare bindings using isEqualTo(IBinding), which is functionally equivalent to checking their keys for equality.  Since JLS8, type bindings can contain type annotations. Note that type bindings that denote the same un-annotated type have the same key, but they are not identical if they contain different type annotations. Type bindings that contain the same type annotations may or may not be identical. 
Params: obj – {@inheritDoc}
See Also: ITypeBinding.getTypeDeclaration()
Returns: {@inheritDoc}/**
	 * There is no special definition of equality for bindings; equality is
	 * simply object identity.  Within the context of a single cluster of
	 * bindings (produced by the same call to an {@code ASTParser#create*(*)} method),
	 * each binding is represented by a separate object. However,
	 * between different clusters of bindings, the binding objects may or may
	 * not be different; in these cases, the client should compare bindings
	 * using {@link #isEqualTo(IBinding)}, which is functionally equivalent to
	 * checking their keys for equality.
	 * <p>
	 * Since JLS8, type bindings can contain {@link ITypeBinding#getTypeAnnotations() type annotations}.
	 * Note that type bindings that denote the same un-annotated type have the same {@link #getKey() key},
	 * but they are not identical if they contain different type annotations.
	 * Type bindings that contain the same type annotations may or may not be identical.
	 * </p>
	 *
	 * @param obj {@inheritDoc}
	 * @return {@inheritDoc}
	 * @see ITypeBinding#getTypeDeclaration()
	 */
	@Override
	public boolean equals(Object obj);

	Returns whether this binding has the same key as that of the given binding. Within the context of a single cluster of bindings (produced by the same call to an ASTParser#create*(*) method), each binding is represented by a distinct object. However, between different clusters of bindings, the binding objects may or may not be different objects; in these cases, the binding keys are used where available.  Note that type bindings that only differ in their type annotations have the same key, and hence this method returns true for such type bindings. By construction of the key, this also applies
to method bindings if their declaring types contain type annotations.

Params: binding – the other binding, or null
See Also: getKey()
Returns: true if the given binding is the identical
object as this binding, or if the keys of both bindings are the
same string; false if the given binding is
null, or if the bindings do not have the same key,
or if one or both of the bindings have no key
Since: 3.1/**
	 * Returns whether this binding has the same key as that of the given
	 * binding. Within the context of a single cluster of bindings
	 * (produced by the same call to an {@code ASTParser#create*(*)} method), each
	 * binding is represented by a distinct object. However, between
	 * different clusters of bindings, the binding objects may or may
	 * not be different objects; in these cases, the binding keys
	 * are used where available.
	 * 
	 * <p>
	 * Note that type bindings that only differ in their {@link ITypeBinding#getTypeAnnotations() type annotations}
	 * have the same {@link IBinding#getKey() key}, and hence this method returns
	 * <code>true</code> for such type bindings. By construction of the key, this also applies
	 * to method bindings if their declaring types contain type annotations.
	 * </p>
	 *
	 * @param binding the other binding, or <code>null</code>
	 * @return <code>true</code> if the given binding is the identical
	 * object as this binding, or if the keys of both bindings are the
	 * same string; <code>false</code> if the given binding is
	 * <code>null</code>, or if the bindings do not have the same key,
	 * or if one or both of the bindings have no key
	 * @see #getKey()
	 * @since 3.1
	 */
	public boolean isEqualTo(IBinding binding);

	Returns a string representation of this binding suitable for debugging
purposes only.
Returns: a debug string/**
	 * Returns a string representation of this binding suitable for debugging
	 * purposes only.
	 *
	 * @return a debug string
	 */
	@Override
	public String toString();
}
See Also:	IPackageBinding ITypeBinding IVariableBinding IMethodBinding IAnnotationBinding IMemberValuePairBinding
Since:	2.0
@noimplement	This interface is not intended to be implemented by clients.
Returns:	the list of resolved declaration annotations, or the empty list if there are no declaration annotations associated with the entity represented by this binding
Since:	3.2
See Also:	Modifier
Returns:	the bit-wise or of `Modifier` constants
Returns:	`true` if this binding is a recovered binding, and `false` otherwise
Since:	3.3
See Also:	IMethodBinding.isDefaultConstructor()
Returns:	`true` if this binding is synthetic, and `false` otherwise
Returns:	the Java element that corresponds to this binding, or `null` if none
Since:	3.1
Params:	obj – {@inheritDoc}
See Also:	ITypeBinding.getTypeDeclaration()
Returns:	{@inheritDoc}
Params:	binding – the other binding, or `null`
See Also:	getKey()
Returns:	`true` if the given binding is the identical object as this binding, or if the keys of both bindings are the same string; `false` if the given binding is `null`, or if the bindings do not have the same key, or if one or both of the bindings have no key
Since:	3.1
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/dom/IBinding.java
