Java tutorial
/******************************************************************************* * 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 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 <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 <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 <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 <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 <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 <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 <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. * <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: * <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. * * @return the name of this binding */ public String getName(); /** * 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. * * @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. * * @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 {@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 <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. * <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 {@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 {@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. * * @return a debug string */ @Override public String toString(); }