org.aspectj.org.eclipse.jdt.core.dom.IBinding Maven / Gradle / Ivy
Show all versions of aspectjtools Show documentation
/*******************************************************************************
* 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.aspectj.org.eclipse.jdt.core.dom;
import org.aspectj.org.eclipse.jdt.core.IAnnotation;
import org.aspectj.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 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 #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 #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 #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 #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 #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 #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 #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 {@link ITypeBinding#getTypeAnnotations()}.
*
*
* @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.
*
* @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.
*
* @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.
*
*
* @return the bit-wise or of Modifier 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.
*
* @return true if this binding is deprecated, and
* false 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.
*
* @return true if this binding is a recovered binding, and
* false 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 {@link IMethodBinding#isDefaultConstructor() IMethodBinding.isDefaultConstructor}
* for cases where the compiled-generated default constructor can be recognized
* instead.
*
* @return true if this binding is synthetic, and
* false 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 {@link 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.
*
*
* @return the Java element that corresponds to this binding,
* or null 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
* {@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).
*
*
* 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 {@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.
*
* 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.
*
*
* @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 {@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.
*
* 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.
*
*
* @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 {@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.
*
*
* 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
* true for such type bindings. By construction of the key, this also applies
* to method bindings if their declaring types contain type annotations.
*
*
* @param binding the other binding, or null
* @return 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
* @see #getKey()
* @since 3.1
*/
public boolean isEqualTo(IBinding binding);
/**
* Returns a string representation of this binding suitable for debugging
* purposes only.
*
* @return a debug string
*/
@Override
public String toString();
}