net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/IBinding.java

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