net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/ITypeHierarchy.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2004 IBM Corporation and others.
   3  * All rights reserved. This program and the accompanying materials
   4  * are made available under the terms of the Common Public License v1.0
   5  * which accompanies this distribution, and is available at
   6  * http://www.eclipse.org/legal/cpl-v10.html
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import java.io.OutputStream;
  14
  15 import org.eclipse.core.runtime.IProgressMonitor;
  16
  17 /**
  18  * A type hierarchy provides navigations between a type and its resolved
  19  * supertypes and subtypes for a specific type or for all types within a region.
  20  * Supertypes may extend outside of the type hierarchy's region in which it was
  21  * created such that the root of the hierarchy is always included. For example,
  22  * if a type hierarchy is created for a <code>java.io.File</code>, and the
  23  * region the hierarchy was created in is the package fragment
  24  * <code>java.io</code>, the supertype <code>java.lang.Object</code> will
  25  * still be included.
  26  * <p>
  27  * A type hierarchy is static and can become stale. Although consistent when
  28  * created, it does not automatically track changes in the model. As changes in
  29  * the model potentially invalidate the hierarchy, change notifications are sent
  30  * to registered <code>ITypeHierarchyChangedListener</code>s. Listeners
  31  * should use the <code>exists</code> method to determine if the hierarchy has
  32  * become completely invalid (for example, when the type or project the
  33  * hierarchy was created on has been removed). To refresh a hierarchy, use the
  34  * <code>refresh</code> method.
  35  * </p>
  36  * <p>
  37  * The type hierarchy may contain cycles due to malformed supertype
  38  * declarations. Most type hierarchy queries are oblivious to cycles; the
  39  * <code>getAll* </code> methods are implemented such that they are unaffected
  40  * by cycles.
  41  * </p>
  42  * <p>
  43  * This interface is not intended to be implemented by clients.
  44  * </p>
  45  */
  46 public interface ITypeHierarchy {
  47         /**
  48          * Adds the given listener for changes to this type hierarchy. Listeners are
  49          * notified when this type hierarchy changes and needs to be refreshed. Has
  50          * no effect if an identical listener is already registered.
  51          *
  52          * @param listener
  53          *            the listener
  54          */
  55         void addTypeHierarchyChangedListener(ITypeHierarchyChangedListener listener);
  56
  57         /**
  58          * Returns whether the given type is part of this hierarchy.
  59          *
  60          * @param type
  61          *            the given type
  62          * @return true if the given type is part of this hierarchy, false otherwise
  63          */
  64         boolean contains(IType type);
  65
  66         /**
  67          * Returns whether the type and project this hierarchy was created on exist.
  68          *
  69          * @return true if the type and project this hierarchy was created on exist,
  70          *         false otherwise
  71          */
  72         boolean exists();
  73
  74         /**
  75          * Returns all classes in this type hierarchy's graph, in no particular
  76          * order. Any classes in the creation region which were not resolved to have
  77          * any subtypes or supertypes are not included in the result.
  78          *
  79          * @return all classes in this type hierarchy's graph
  80          */
  81         IType[] getAllClasses();
  82
  83         /**
  84          * Returns all interfaces in this type hierarchy's graph, in no particular
  85          * order. Any interfaces in the creation region which were not resolved to
  86          * have any subtypes or supertypes are not included in the result.
  87          *
  88          * @return all interfaces in this type hierarchy's graph
  89          */
  90         IType[] getAllInterfaces();
  91
  92         /**
  93          * Returns all resolved subtypes (direct and indirect) of the given type, in
  94          * no particular order, limited to the types in this type hierarchy's graph.
  95          * An empty array is returned if there are no resolved subtypes for the
  96          * given type.
  97          *
  98          * @param type
  99          *            the given type
 100          * @return all resolved subtypes (direct and indirect) of the given type
 101          */
 102         IType[] getAllSubtypes(IType type);
 103
 104         /**
 105          * Returns all resolved superclasses of the given class, in bottom-up order.
 106          * An empty array is returned if there are no resolved superclasses for the
 107          * given class.
 108          *
 109          * <p>
 110          * NOTE: once a type hierarchy has been created, it is more efficient to
 111          * query the hierarchy for superclasses than to query a class recursively up
 112          * the superclass chain. Querying an element performs a dynamic resolution,
 113          * whereas the hierarchy returns a pre-computed result.
 114          *
 115          * @param type
 116          *            the given type
 117          * @return all resolved superclasses of the given class, in bottom-up order,
 118          *         an empty array if none.
 119          */
 120         IType[] getAllSuperclasses(IType type);
 121
 122         /**
 123          * Returns all resolved superinterfaces (direct and indirect) of the given
 124          * type. If the given type is a class, this includes all superinterfaces of
 125          * all superclasses. An empty array is returned if there are no resolved
 126          * superinterfaces for the given type.
 127          *
 128          * <p>
 129          * NOTE: once a type hierarchy has been created, it is more efficient to
 130          * query the hierarchy for superinterfaces than to query a type recursively.
 131          * Querying an element performs a dynamic resolution, whereas the hierarchy
 132          * returns a pre-computed result.
 133          *
 134          * @param type
 135          *            the given type
 136          * @return all resolved superinterfaces (direct and indirect) of the given
 137          *         type, an empty array if none
 138          */
 139         IType[] getAllSuperInterfaces(IType type);
 140
 141         /**
 142          * Returns all resolved supertypes of the given type, in bottom-up order. An
 143          * empty array is returned if there are no resolved supertypes for the given
 144          * type.
 145          * <p>
 146          * Note that <code>java.lang.Object</code> is NOT considered to be a
 147          * supertype of any interface type.
 148          * </p>
 149          * <p>
 150          * NOTE: once a type hierarchy has been created, it is more efficient to
 151          * query the hierarchy for supertypes than to query a type recursively up
 152          * the supertype chain. Querying an element performs a dynamic resolution,
 153          * whereas the hierarchy returns a pre-computed result.
 154          *
 155          * @param type
 156          *            the given type
 157          * @return all resolved supertypes of the given class, in bottom-up order,
 158          *         an empty array if none
 159          */
 160         IType[] getAllSupertypes(IType type);
 161
 162         /**
 163          * Returns all types in this type hierarchy's graph, in no particular order.
 164          * Any types in the creation region which were not resolved to have any
 165          * subtypes or supertypes are not included in the result.
 166          *
 167          * @return all types in this type hierarchy's grap
 168          */
 169         IType[] getAllTypes();
 170
 171         /**
 172          * Return the flags associated with the given type (would be equivalent to
 173          * <code>IMember.getFlags()</code>), or <code>-1</code> if this
 174          * information wasn't cached on the hierarchy during its computation.
 175          *
 176          * @param type
 177          *            the given type
 178          * @return the modifier flags for this member
 179          * @see Flags
 180          * @since 2.0
 181          */
 182         int getCachedFlags(IType type);
 183
 184         /**
 185          * Returns all interfaces resolved to extend the given interface, in no
 186          * particular order, limited to the interfaces in this hierarchy's graph.
 187          * Returns an empty collection if the given type is a class, or if no
 188          * interfaces were resolved to extend the given interface.
 189          *
 190          * @param type
 191          *            the given type
 192          * @return all interfaces resolved to extend the given interface limited to
 193          *         the interfaces in this hierarchy's graph, an empty array if none.
 194          */
 195         IType[] getExtendingInterfaces(IType type);
 196
 197         /**
 198          * Returns all classes resolved to implement the given interface, in no
 199          * particular order, limited to the classes in this type hierarchy's graph.
 200          * Returns an empty collection if the given type is a class, or if no
 201          * classes were resolved to implement the given interface.
 202          *
 203          * @param type
 204          *            the given type
 205          * @return all classes resolved to implement the given interface limited to
 206          *         the classes in this type hierarchy's graph, an empty array if
 207          *         none
 208          */
 209         IType[] getImplementingClasses(IType type);
 210
 211         /**
 212          * Returns all classes in the graph which have no resolved superclass, in no
 213          * particular order.
 214          *
 215          * @return all classes in the graph which have no resolved superclass
 216          */
 217         IType[] getRootClasses();
 218
 219         /**
 220          * Returns all interfaces in the graph which have no resolved
 221          * superinterfaces, in no particular order.
 222          *
 223          * @return all interfaces in the graph which have no resolved
 224          *         superinterfaces
 225          */
 226         IType[] getRootInterfaces();
 227
 228         /**
 229          * Returns the direct resolved subclasses of the given class, in no
 230          * particular order, limited to the classes in this type hierarchy's graph.
 231          * Returns an empty collection if the given type is an interface, or if no
 232          * classes were resolved to be subclasses of the given class.
 233          *
 234          * @param type
 235          *            the given type
 236          * @return the direct resolved subclasses of the given class limited to the
 237          *         classes in this type hierarchy's graph, an empty collection if
 238          *         none.
 239          */
 240         IType[] getSubclasses(IType type);
 241
 242         /**
 243          * Returns the direct resolved subtypes of the given type, in no particular
 244          * order, limited to the types in this type hierarchy's graph. If the type
 245          * is a class, this returns the resolved subclasses. If the type is an
 246          * interface, this returns both the classes which implement the interface
 247          * and the interfaces which extend it.
 248          *
 249          * @param type
 250          *            the given type
 251          * @return the direct resolved subtypes of the given type limited to the
 252          *         types in this type hierarchy's graph
 253          */
 254         IType[] getSubtypes(IType type);
 255
 256         /**
 257          * Returns the resolved superclass of the given class, or <code>null</code>
 258          * if the given class has no superclass, the superclass could not be
 259          * resolved, or if the given type is an interface.
 260          *
 261          * @param type
 262          *            the given type
 263          * @return the resolved superclass of the given class, or <code>null</code>
 264          *         if the given class has no superclass, the superclass could not be
 265          *         resolved, or if the given type is an interface
 266          */
 267         IType getSuperclass(IType type);
 268
 269         /**
 270          * Returns the direct resolved interfaces that the given type implements or
 271          * extends, in no particular order, limited to the interfaces in this type
 272          * hierarchy's graph. For classes, this gives the interfaces that the class
 273          * implements. For interfaces, this gives the interfaces that the interface
 274          * extends.
 275          *
 276          * @param type
 277          *            the given type
 278          * @return the direct resolved interfaces that the given type implements or
 279          *         extends limited to the interfaces in this type hierarchy's graph
 280          */
 281         IType[] getSuperInterfaces(IType type);
 282
 283         /**
 284          * Returns the resolved supertypes of the given type, in no particular
 285          * order, limited to the types in this type hierarchy's graph. For classes,
 286          * this returns its superclass and the interfaces that the class implements.
 287          * For interfaces, this returns the interfaces that the interface extends.
 288          * As a consequence <code>java.lang.Object</code> is NOT considered to be
 289          * a supertype of any interface type.
 290          *
 291          * @param type
 292          *            the given type
 293          * @return the resolved supertypes of the given type limited to the types in
 294          *         this type hierarchy's graph
 295          */
 296         IType[] getSupertypes(IType type);
 297
 298         /**
 299          * Returns the type this hierarchy was computed for. Returns
 300          * <code>null</code> if this hierarchy was computed for a region.
 301          *
 302          * @return the type this hierarchy was computed for
 303          */
 304         IType getType();
 305
 306         /**
 307          * Re-computes the type hierarchy reporting progress.
 308          *
 309          * @param monitor
 310          *            the given progress monitor
 311          * @exception JavaModelException
 312          *                if unable to refresh the hierarchy
 313          */
 314         void refresh(IProgressMonitor monitor) throws JavaModelException;
 315
 316         /**
 317          * Removes the given listener from this type hierarchy. Has no affect if an
 318          * identical listener is not registered.
 319          *
 320          * @param listener
 321          *            the listener
 322          */
 323         void removeTypeHierarchyChangedListener(
 324                         ITypeHierarchyChangedListener listener);
 325
 326         /**
 327          * Stores the type hierarchy in an output stream. This stored hierarchy can
 328          * be load by IType#loadTypeHierachy(IJavaProject, InputStream,
 329          * IProgressMonitor). Listeners of this hierarchy are not stored.
 330          *
 331          * Only hierarchies created by the following methods can be store:
 332          * <ul>
 333          * <li>IType#newSupertypeHierarchy(IProgressMonitor)</li>
 334          * <li>IType#newTypeHierarchy(IJavaProject, IProgressMonitor)</li>
 335          * <li>IType#newTypeHierarchy(IProgressMonitor)</li>
 336          * </u>
 337          *
 338          * @param outputStream
 339          *            output stream where the hierarchy will be stored
 340          * @param monitor
 341          *            the given progress monitor
 342          * @exception JavaModelException
 343          *                if unable to store the hierarchy in the ouput stream
 344          * @see IType#loadTypeHierachy(java.io.InputStream, IProgressMonitor)
 345          * @since 2.1
 346          */
 347         void store(OutputStream outputStream, IProgressMonitor monitor)
 348                         throws JavaModelException;
 349 }