/******************************************************************************* * Copyright (c) 2000, 2008 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/epl-v10.html * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package net.sourceforge.phpdt.core.dom; /** * A type binding represents fully-resolved type. There are a number of * different kinds of type bindings: * * * @see ITypeBinding#getDeclaredTypes() * @since 2.0 * @noimplement This interface is not intended to be implemented by clients. */ public interface ITypeBinding extends IBinding { /** * Answer an array type binding using the receiver and the given dimension. * *

If the receiver is an array binding, then the resulting dimension is the given dimension * plus the dimension of the receiver. Otherwise the resulting dimension is the given * dimension.

* * @param dimension the given dimension * @return an array type binding * @throws IllegalArgumentException: * @since 3.3 */ public ITypeBinding createArrayType(int dimension); /** * Returns the binary name of this type binding. * The binary name of a class is defined in the Java Language * Specification 3rd edition, section 13.1. *

* Note that in some cases, the binary name may be unavailable. * This may happen, for example, for a local type declared in * unreachable code. *

* * @return the binary name of this type, or null * if the binary name is unknown * @since 3.0 */ public String getBinaryName(); /** * Returns the bound of this wildcard type if it has one. * Returns null if this is not a wildcard type. * * @return the bound of this wildcard type, or null if none * @see #isWildcardType() * @see #isUpperbound() * @since 3.1 */ public ITypeBinding getBound(); /** * Returns the binding representing the component type of this array type, * or null if this is not an array type binding. The component * type of an array might be an array type. *

This is subject to change before 3.2 release.

* * @return the component type binding, or null if this is * not an array type * @since 3.2 */ public ITypeBinding getComponentType(); /** * Returns a list of bindings representing all the fields declared * as members of this class, interface, or enum type. * *

These include public, protected, default (package-private) access, * and private fields declared by the class, but excludes inherited fields. * Synthetic fields may or may not be included. Fields from binary types that * reference unresolvable types may not be included.

* *

Returns an empty list if the class, interface, or enum declares no fields, * and for other kinds of type bindings that do not directly have members.

* *

The resulting bindings are in no particular order.

* * @return the list of bindings for the field members of this type, * or the empty list if this type does not have field members */ public IVariableBinding[] getDeclaredFields(); /** * Returns a list of method bindings representing all the methods and * constructors declared for this class, interface, enum, or annotation * type. *

These include public, protected, default (package-private) access, * and private methods Synthetic methods and constructors may or may not be * included. Returns an empty list if the class, interface, or enum, * type declares no methods or constructors, if the annotation type declares * no members, or if this type binding represents some other kind of type * binding. Methods from binary types that reference unresolvable types may * not be included.

*

The resulting bindings are in no particular order.

* * @return the list of method bindings for the methods and constructors * declared by this class, interface, enum type, or annotation type, * or the empty list if this type does not declare any methods or constructors */ public IMethodBinding[] getDeclaredMethods(); /** * Returns the declared modifiers for this class or interface binding * as specified in the original source declaration of the class or * interface. The result may not correspond to the modifiers in the compiled * binary, since the compiler may change them (in particular, for inner * class emulation). The getModifiers method should be used if * the compiled modifiers are needed. Returns -1 if this type does not * represent a class or interface. * * @return the bit-wise or of Modifier constants * @see #getModifiers() * @see Modifier */ public int getDeclaredModifiers(); /** * Returns a list of type bindings representing all the types declared as * members of this class, interface, or enum type. * These include public, protected, default (package-private) access, * and private classes, interfaces, enum types, and annotation types * declared by the type, but excludes inherited types. Returns an empty * list if the type declares no type members, or if this type * binding represents an array type, a primitive type, a type variable, * a wildcard type, a capture, or the null type. * The resulting bindings are in no particular order. * * @return the list of type bindings for the member types of this type, * or the empty list if this type does not have member types */ public ITypeBinding[] getDeclaredTypes(); /** * Returns the type binding representing the class, interface, or enum * that declares this binding. *

* The declaring class of a member class, interface, enum, annotation * type is the class, interface, or enum type of which it is a member. * The declaring class of a local class or interface (including anonymous * classes) is the innermost class or interface containing the expression * or statement in which this type is declared. *

*

The declaring class of a type variable is the class in which the type * variable is declared if it is declared on a type. It returns * null otherwise. *

*

The declaring class of a capture binding is the innermost class or * interface containing the expression or statement in which this capture is * declared. *

*

Array types, primitive types, the null type, top-level types, * wildcard types, recovered binding have no declaring class. *

* * @return the binding of the type that declares this type, or * null if none */ public ITypeBinding getDeclaringClass(); /** * Returns the method binding representing the method that declares this binding * of a local type or type variable. *

* The declaring method of a local class or interface (including anonymous * classes) is the innermost method containing the expression or statement in * which this type is declared. Returns null if the type * is declared in an initializer. *

*

* The declaring method of a type variable is the method in which the type * variable is declared if it is declared on a method. It * returns null otherwise. *

*

Array types, primitive types, the null type, top-level types, * wildcard types, capture bindings, and recovered binding have no * declaring method. *

* * @return the binding of the method that declares this type, or * null if none * @since 3.1 */ public IMethodBinding getDeclaringMethod(); /** * Returns the dimensionality of this array type, or 0 if this * is not an array type binding. * * @return the number of dimension of this array type binding, or * 0 if this is not an array type */ public int getDimensions(); /** * Returns the binding representing the element type of this array type, * or null if this is not an array type binding. The element * type of an array is never itself an array type. * * @return the element type binding, or null if this is * not an array type */ public ITypeBinding getElementType(); /** * Returns the erasure of this type binding. * * * @return the erasure type binding * @since 3.1 */ public ITypeBinding getErasure(); /** * Returns a list of type bindings representing the direct superinterfaces * of the class, interface, or enum type represented by this type binding. *

* If this type binding represents a class or enum type, the return value * is an array containing type bindings representing all interfaces * directly implemented by this class. The number and order of the interface * objects in the array corresponds to the number and order of the interface * names in the implements clause of the original declaration * of this type. *

*

* If this type binding represents an interface, the array contains * type bindings representing all interfaces directly extended by this * interface. The number and order of the interface objects in the array * corresponds to the number and order of the interface names in the * extends clause of the original declaration of this interface. *

*

* If the class or enum implements no interfaces, or the interface extends * no interfaces, or if this type binding represents an array type, a * primitive type, the null type, a type variable, an annotation type, * a wildcard type, or a capture binding, this method returns an array of * length 0. *

* * @return the list of type bindings for the interfaces extended by this * class or enum, or interfaces extended by this interface, or otherwise * the empty list */ public ITypeBinding[] getInterfaces(); /** * Returns the compiled modifiers for this class, interface, enum, * or annotation type binding. * The result may not correspond to the modifiers as declared in the * original source, since the compiler may change them (in particular, * for inner class emulation). The getDeclaredModifiers method * should be used if the original modifiers are needed. * Returns 0 if this type does not represent a class, an interface, an enum, an annotation * type or a recovered type. * * @return the compiled modifiers for this type binding or 0 * if this type does not represent a class, an interface, an enum, an annotation * type or a recovered type. * @see #getDeclaredModifiers() */ public int getModifiers(); /** * Returns the unqualified name of the type represented by this binding * if it has one. * * * @return the unqualified name of the type represented by this binding, * or the empty string if it has none * @see #getQualifiedName() */ public String getName(); /** * Returns the binding for the package in which this type is declared. * *

The package of a recovered type reference binding is either * the package of the enclosing type, or, if the type name is the name of a * {@linkplain AST#resolveWellKnownType(String) well-known type}, * the package of the matching well-known type.

* * @return the binding for the package in which this class, interface, * enum, or annotation type is declared, or null if this type * binding represents a primitive type, an array type, the null type, * a type variable, a wildcard type, a capture binding. */ public IPackageBinding getPackage(); /** * Returns the fully qualified name of the type represented by this * binding if it has one. * * * @return the fully qualified name of the type represented by this * binding, or the empty string if it has none * @see #getName() * @since 2.1 */ public String getQualifiedName(); /** * Returns the type binding for the superclass of the type represented * by this class binding. *

* If this type binding represents any class other than the class * java.lang.Object, then the type binding for the direct * superclass of this class is returned. If this type binding represents * the class java.lang.Object, then null is * returned. *

* Loops that ascend the class hierarchy need a suitable termination test. * Rather than test the superclass for null, it is more * transparent to check whether the class is Object, by * comparing whether the class binding is identical to * ast.resolveWellKnownType("java.lang.Object"). *

*

* If this type binding represents an interface, an array type, a * primitive type, the null type, a type variable, an enum type, * an annotation type, a wildcard type, or a capture binding then * null is returned. *

* * @return the superclass of the class represented by this type binding, * or null if none * @see AST#resolveWellKnownType(String) */ public ITypeBinding getSuperclass(); /** * Returns the type arguments of this generic type instance, or the * empty list for other type bindings. *

* Note that type arguments only occur on a type binding that represents * an instance of a generic type corresponding to a parameterized type * reference (e.g., Collection<String>). * Do not confuse these with type parameters which only occur on the * type binding corresponding directly to the declaration of the * generic class or interface (e.g., Collection<T>). *

* * @return the list of type bindings for the type arguments used to * instantiate the corresponding generic type, or otherwise the empty list * @see #getTypeDeclaration() * @see #isGenericType() * @see #isParameterizedType() * @see #isRawType() * @since 3.1 */ public ITypeBinding[] getTypeArguments(); /** * Returns the declared type bounds of this type variable or capture. If the * variable or the capture had no explicit bound, then it returns an empty list. *

* Note that per construction, it can only contain one class or array type, * at most, and then it is located in first position. *

*

* Also note that array type bound may only occur in the case of a capture * binding, e.g. capture-of ? extends Object[] *

* * @return the list of type bindings for this type variable or capture, * or otherwise the empty list * @see #isCapture() * @see #isTypeVariable() * @since 3.1 */ public ITypeBinding[] getTypeBounds(); /** * Returns the binding for the type declaration corresponding to this type * binding. *

For parameterized types ({@link #isParameterizedType()}) * and most raw types ({@link #isRawType()}), this method returns the binding * for the corresponding generic type.

*

For raw member types ({@link #isRawType()}, {@link #isMember()}) * of a raw declaring class, the type declaration is a generic or a non-generic * type.

*

A different non-generic binding will be returned when one of the declaring * types/methods was parameterized.

*

For other type bindings, this returns the same binding.

* * @return the type binding * @since 3.1 */ public ITypeBinding getTypeDeclaration(); /** * Returns the type parameters of this class or interface type binding. *

* Note that type parameters only occur on the binding of the * declaring generic class or interface; e.g., Collection<T>. * Type bindings corresponding to a raw or parameterized reference to a generic * type do not carry type parameters (they instead have non-empty type arguments * and non-trivial erasure). *

* * @return the list of binding for the type variables for the type * parameters of this type, or otherwise the empty list * @see #isTypeVariable() * @since 3.1 */ // TODO (jeem) - clarify whether binding for a generic type instance carries a copy of the generic type's type parameters as well as type arguments public ITypeBinding[] getTypeParameters(); /** * Returns the corresponding wildcard binding of this capture binding. * Returns null if this type bindings does not represent * a capture binding. * * @return the corresponding wildcard binding for a capture * binding, null otherwise * @since 3.1 */ public ITypeBinding getWildcard(); /** * Returns whether this type binding represents an annotation type. *

* Note that an annotation type is always an interface. *

* * @return true if this object represents an annotation type, * and false otherwise * @since 3.1 */ public boolean isAnnotation(); /** * Returns whether this type binding represents an anonymous class. *

* An anonymous class is a subspecies of local class, and therefore mutually * exclusive with member types. Note that anonymous classes have no name * (getName returns the empty string). *

* * @return true if this type binding is for an anonymous class, * and false otherwise */ public boolean isAnonymous(); /** * Returns whether this type binding represents an array type. * * @return true if this type binding is for an array type, * and false otherwise * @see #getElementType() * @see #getDimensions() */ public boolean isArray(); /** * Returns whether an expression of this type can be assigned to a variable * of the given type, as specified in section 5.2 of The Java Language * Specification, Third Edition (JLS3). * *

If the receiver or the argument is a recovered type, the answer is always false, * unless the two types are identical or the argument is java.lang.Object.

* * @param variableType the type of a variable to check compatibility against * @return true if an expression of this type can be assigned to a * variable of the given type, and false otherwise * @since 3.1 */ public boolean isAssignmentCompatible(ITypeBinding variableType); /** * Returns whether this type binding represents a capture binding. *

* Capture bindings result from capture conversion as specified * in section 5.1.10 of The Java Language Specification, * Third Edition (JLS3). *

*

* A capture binding may have upper bounds and a lower bound. * Upper bounds may be accessed using {@link #getTypeBounds()}, * the lower bound must be accessed indirectly through the associated * wildcard {@link #getWildcard()} when it is a lower bound wildcard. *

*

* Note that capture bindings are distinct from type variables * (even though they are often depicted as synthetic type * variables); as such, {@link #isTypeVariable()} answers * false for capture bindings, and * {@link #isCapture()} answers false for type variables. *

* * @return true if this type binding is a capture, * and false otherwise * @see #getTypeBounds() * @see #getWildcard() * @since 3.1 */ public boolean isCapture(); /** * Returns whether this type is cast compatible with the given type, * as specified in section 5.5 of The Java Language * Specification, Third Edition (JLS3). *

* NOTE: The cast compatibility check performs backwards. * When testing whether type B can be cast to type A, one would use: * A.isCastCompatible(B) *

* *

If the receiver or the argument is a recovered type, the answer is always false, * unless the two types are identical or the argument is java.lang.Object.

* * @param type the type to check compatibility against * @return true if this type is cast compatible with the * given type, and false otherwise * @since 3.1 */ public boolean isCastCompatible(ITypeBinding type); /** * Returns whether this type binding represents a class type or a recovered binding. * * @return true if this object represents a class or a recovered binding, * and false otherwise */ public boolean isClass(); /** * Returns whether this type binding represents an enum type. * * @return true if this object represents an enum type, * and false otherwise * @since 3.1 */ public boolean isEnum(); /** * Returns whether this type binding originated in source code. * Returns false for all primitive types, the null type, * array types, and for all classes, interfaces, enums, annotation * types, type variables, parameterized type references, * raw type references, wildcard types, and capture bindings * whose information came from a pre-compiled binary class file. * * @return true if the type is in source code, * and false otherwise */ public boolean isFromSource(); /** * Returns whether this type binding represents a declaration of * a generic class or interface. *

* Note that type parameters only occur on the binding of the * declaring generic class or interface; e.g., Collection<T>. * Type bindings corresponding to a raw or parameterized reference to a generic * type do not carry type parameters (they instead have non-empty type arguments * and non-trivial erasure). * This method is fully equivalent to getTypeParameters().length > 0). *

*

* Note that {@link #isGenericType()}, * {@link #isParameterizedType()}, * and {@link #isRawType()} are mutually exclusive. *

* * @return true if this type binding represents a * declaration of a generic class or interface, and false otherwise * @see #getTypeParameters() * @since 3.1 */ public boolean isGenericType(); /** * Returns whether this type binding represents an interface type. *

* Note that an interface can also be an annotation type. *

* * @return true if this object represents an interface, * and false otherwise */ public boolean isInterface(); /** * Returns whether this type binding represents a local class. *

* A local class is any nested class or enum type not declared as a member * of another class or interface. A local class is a subspecies of nested * type, and mutually exclusive with member types. Note that anonymous * classes are a subspecies of local classes. *

*

* Also note that interfaces and annotation types cannot be local. *

* * @return true if this type binding is for a local class or * enum type, and false otherwise */ public boolean isLocal(); /** * Returns whether this type binding represents a member class or * interface. *

* A member type is any type declared as a member of * another type. A member type is a subspecies of nested * type, and mutually exclusive with local types. *

* * @return true if this type binding is for a member class, * interface, enum, or annotation type, and false otherwise */ public boolean isMember(); /** * Returns whether this type binding represents a nested class, interface, * enum, or annotation type. *

* A nested type is any type whose declaration occurs within * the body of another. The set of nested types is disjoint from the set of * top-level types. Nested types further subdivide into member types, local * types, and anonymous types. *

* * @return true if this type binding is for a nested class, * interface, enum, or annotation type, and false otherwise */ public boolean isNested(); /** * Returns whether this type binding represents the null type. *

* The null type is the type of a NullLiteral node. *

* * @return true if this type binding is for the null type, * and false otherwise */ public boolean isNullType(); /** * Returns whether this type binding represents an instance of * a generic type corresponding to a parameterized type reference. *

* For example, an AST type like * Collection<String> typically resolves to a * type binding whose type argument is the type binding for the * class java.lang.String and whose erasure is the type * binding for the generic type java.util.Collection. *

*

* Note that {@link #isGenericType()}, * {@link #isParameterizedType()}, * and {@link #isRawType()} are mutually exclusive. *

* * @return true if this type binding represents a * an instance of a generic type corresponding to a parameterized * type reference, and false otherwise * @see #getTypeArguments() * @see #getTypeDeclaration() * @since 3.1 */ public boolean isParameterizedType(); /** * Returns whether this type binding represents a primitive type. *

* There are nine predefined type bindings to represent the eight primitive * types and void. These have the same names as the primitive * types that they represent, namely boolean, byte, char, short, int, * long, float, and double, and void. *

* * @return true if this type binding is for a primitive type, * and false otherwise */ public boolean isPrimitive(); /** * Returns whether this type binding represents an instance of * a generic type corresponding to a raw type reference. *

* For example, an AST type like * Collection typically resolves to a * type binding whose type argument is the type binding for * the class java.lang.Object (the * default bound for the single type parameter of * java.util.Collection) and whose erasure is the * type binding for the generic type * java.util.Collection. *

*

* Note that {@link #isGenericType()}, * {@link #isParameterizedType()}, * and {@link #isRawType()} are mutually exclusive. *

* * @return true if this type binding represents a * an instance of a generic type corresponding to a raw * type reference, and false otherwise * @see #getTypeDeclaration() * @see #getTypeArguments() * @since 3.1 */ public boolean isRawType(); /** * Returns whether this type is subtype compatible with the given type, * as specified in section 4.10 of The Java Language * Specification, Third Edition (JLS3). * *

If the receiver or the argument is a recovered type, the answer is always false, * unless the two types are identical or the argument is java.lang.Object.

* * @param type the type to check compatibility against * @return true if this type is subtype compatible with the * given type, and false otherwise * @since 3.1 */ public boolean isSubTypeCompatible(ITypeBinding type); /** * Returns whether this type binding represents a top-level class, * interface, enum, or annotation type. *

* A top-level type is any type whose declaration does not occur within the * body of another type declaration. The set of top level types is disjoint * from the set of nested types. *

* * @return true if this type binding is for a top-level class, * interface, enum, or annotation type, and false otherwise */ public boolean isTopLevel(); /** * Returns whether this type binding represents a type variable. * Type variables bindings carry the type variable's bounds. *

* Note that type variables are distinct from capture bindings * (even though capture bindings are often depicted as synthetic * type variables); as such, {@link #isTypeVariable()} answers * false for capture bindings, and * {@link #isCapture()} answers false for type variables. *

* * @return true if this type binding is for a type variable, * and false otherwise * @see #getName() * @see #getTypeBounds() * @since 3.1 */ public boolean isTypeVariable(); /** * Returns whether this wildcard type is an upper bound * ("extends") as opposed to a lower bound ("super"). * Note that this property is only relevant for wildcards * that have a bound. * * @return true if this wildcard type has a bound that is * an upper bound, and false in all other cases * @see #isWildcardType() * @see #getBound() * @since 3.1 */ public boolean isUpperbound(); /** * Returns whether this type binding represents a wildcard type. A wildcard * type occus only as an argument to a parameterized type reference. *

* For example, a AST type like * Collection<? extends Object> typically resolves to a * parameterized type binding whose type argument is a wildcard type * with upper type bound java.util.Object. *

* * @return true if this object represents a wildcard type, * and false otherwise * @since 3.1 * @see #getBound() * @see #isUpperbound() */ public boolean isWildcardType(); }