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

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2003 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 org.eclipse.core.resources.IResourceDelta;
  14
  15 /**
  16  * A Java element delta describes changes in Java element between two discrete
  17  * points in time. Given a delta, clients can access the element that has
  18  * changed, and any children that have changed.
  19  * <p>
  20  * Deltas have a different status depending on the kind of change they
  21  * represent. The list below summarizes each status (as returned by
  22  * <code>getKind</code>) and its meaning (see individual constants for a more
  23  * detailled description):
  24  * <ul>
  25  * <li><code>ADDED</code> - The element described by the delta has been
  26  * added.</li>
  27  * <li><code>REMOVED</code> - The element described by the delta has been
  28  * removed.</li>
  29  * <li><code>CHANGED</code> - The element described by the delta has been
  30  * changed in some way. Specification of the type of change is provided by
  31  * <code>getFlags</code> which returns the following values:
  32  * <ul>
  33  * <li><code>F_ADDED_TO_CLASSPATH</code> - A classpath entry corresponding to
  34  * the element has been added to the project's classpath. This flag is only
  35  * valid if the element is an <code>IPackageFragmentRoot</code>.</li>
  36  * <li><code>F_ARCHIVE_CONTENT_CHANGED</code> - The contents of an archive
  37  * has changed in some way. This flag is only valid if the element is an
  38  * <code>IPackageFragmentRoot</code> which is an archive.</li>
  39  * <li><code>F_CHILDREN</code> - A child of the element has changed in some
  40  * way. This flag is only valid if the element is an <code>IParent</code>.</li>
  41  * <li><code>F_CLASSPATH_REORDER</code> - A classpath entry corresponding to
  42  * the element has changed position in the project's classpath. This flag is
  43  * only valid if the element is an <code>IPackageFragmentRoot</code>.</li>
  44  * <li><code>F_CLOSED</code> - The underlying <code>IProject</code> has
  45  * been closed. This flag is only valid if the element is an
  46  * <code>IJavaProject</code>.</li>
  47  * <li><code>F_CONTENT</code> - The contents of the element have been
  48  * altered. This flag is only valid for elements which correspond to files.</li>
  49  * <li><code>F_FINE_GRAINED</code> - The delta is a fine-grained delta, that
  50  * is, an analysis down to the members level was done to determine if there were
  51  * structural changes to members of the element.</li>
  52  * <li><code>F_MODIFIERS</code> - The modifiers on the element have changed
  53  * in some way. This flag is only valid if the element is an
  54  * <code>IMember</code>.</li>
  55  * <li><code>F_OPENED</code> - The underlying <code>IProject</code> has
  56  * been opened. This flag is only valid if the element is an
  57  * <code>IJavaProject</code>.</li>
  58  * <li><code>F_REMOVED_FROM_CLASSPATH</code> - A classpath entry
  59  * corresponding to the element has been removed from the project's classpath.
  60  * This flag is only valid if the element is an
  61  * <code>IPackageFragmentRoot</code>.</li>
  62  * <li><code>F_SOURCEATTACHED</code> - The source attachment path or the
  63  * source attachment root path of a classpath entry corresponding to the element
  64  * was added. This flag is only valid if the element is an
  65  * <code>IPackageFragmentRoot</code>.</li>
  66  * <li><code>F_SOURCEDETACHED</code> - The source attachment path or the
  67  * source attachment root path of a classpath entry corresponding to the element
  68  * was removed. This flag is only valid if the element is an
  69  * <code>IPackageFragmentRoot</code>.</li>
  70  * <li><code>F_SUPER_TYPES</code> - One of the supertypes of an
  71  * <code>IType</code> has changed</li>.
  72  * </ul>
  73  * </li>
  74  * </ul>
  75  * </p>
  76  * <p>
  77  * Move operations are indicated by other change flags, layered on top of the
  78  * change flags described above. If element A is moved to become B, the delta
  79  * for the change in A will have status <code>REMOVED</code>, with change
  80  * flag <code>F_MOVED_TO</code>. In this case, <code>getMovedToElement</code>
  81  * on delta A will return the handle for B. The delta for B will have status
  82  * <code>ADDED</code>, with change flag <code>F_MOVED_FROM</code>, and
  83  * <code>getMovedFromElement</code> on delta B will return the handle for A.
  84  * (Note, the handle to A in this case represents an element that no longer
  85  * exists).
  86  * </p>
  87  * <p>
  88  * Note that the move change flags only describe the changes to a single
  89  * element, they do not imply anything about the parent or children of the
  90  * element.
  91  * </p>
  92  * <p>
  93  * The <code>F_ADDED_TO_CLASSPATH</code>,
  94  * <code>F_REMOVED_FROM_CLASSPATH</code> and <code>F_CLASSPATH_REORDER</code>
  95  * flags are triggered by changes to a project's classpath. They do not mean
  96  * that the underlying resource was added, removed or changed. For example, if a
  97  * project P already contains a folder src, then adding a classpath entry with
  98  * the 'P/src' path to the project's classpath will result in an
  99  * <code>IJavaElementDelta</code> with the <code>F_ADDED_TO_CLASSPATH</code>
 100  * flag for the <code>IPackageFragmentRoot</code> P/src. On the contrary, if a
 101  * resource is physically added, removed or changed and this resource
 102  * corresponds to a classpath entry of the project, then an
 103  * <code>IJavaElementDelta</code> with the <code>ADDED</code>,
 104  * <code>REMOVED</code>, or <code>CHANGED</code> kind will be fired.
 105  * </p>
 106  * <p>
 107  * Note that when a source attachment path or a source attachment root path is
 108  * changed, then the flags of the delta contain both
 109  * <code>F_SOURCEATTACHED</code> and <code>F_SOURCEDETTACHED</code>.
 110  * </p>
 111  * <p>
 112  * No assumptions should be made on whether the java element delta tree is
 113  * rooted at the <code>IJavaModel</code> level or not.
 114  * </p>
 115  * <p>
 116  * <code>IJavaElementDelta</code> object are not valid outside the dynamic
 117  * scope of the notification.
 118  * </p>
 119  * <p>
 120  * This interface is not intended to be implemented by clients.
 121  * </p>
 122  */
 123 public interface IJavaElementDelta {
 124
 125         /**
 126          * Status constant indicating that the element has been added. Note that an
 127          * added java element delta has no children, as they are all implicitely
 128          * added.
 129          */
 130         public int ADDED = 1;
 131
 132         /**
 133          * Status constant indicating that the element has been removed. Note that a
 134          * removed java element delta has no children, as they are all implicitely
 135          * removed.
 136          */
 137         public int REMOVED = 2;
 138
 139         /**
 140          * Status constant indicating that the element has been changed, as
 141          * described by the change flags.
 142          *
 143          * @see #getFlags
 144          */
 145         public int CHANGED = 4;
 146
 147         /**
 148          * Change flag indicating that the content of the element has changed. This
 149          * flag is only valid for elements which correspond to files.
 150          */
 151         public int F_CONTENT = 0x0001;
 152
 153         /**
 154          * Change flag indicating that the modifiers of the element have changed.
 155          * This flag is only valid if the element is an <code>IMember</code>.
 156          */
 157         public int F_MODIFIERS = 0x0002;
 158
 159         /**
 160          * Change flag indicating that there are changes to the children of the
 161          * element. This flag is only valid if the element is an
 162          * <code>IParent</code>.
 163          */
 164         public int F_CHILDREN = 0x0008;
 165
 166         /**
 167          * Change flag indicating that the element was moved from another location.
 168          * The location of the old element can be retrieved using
 169          * <code>getMovedFromElement</code>.
 170          */
 171         public int F_MOVED_FROM = 0x0010;
 172
 173         /**
 174          * Change flag indicating that the element was moved to another location.
 175          * The location of the new element can be retrieved using
 176          * <code>getMovedToElement</code>.
 177          */
 178         public int F_MOVED_TO = 0x0020;
 179
 180         /**
 181          * Change flag indicating that a classpath entry corresponding to the
 182          * element has been added to the project's classpath. This flag is only
 183          * valid if the element is an <code>IPackageFragmentRoot</code>.
 184          */
 185         public int F_ADDED_TO_CLASSPATH = 0x0040;
 186
 187         /**
 188          * Change flag indicating that a classpath entry corresponding to the
 189          * element has been removed from the project's classpath. This flag is only
 190          * valid if the element is an <code>IPackageFragmentRoot</code>.
 191          */
 192         public int F_REMOVED_FROM_CLASSPATH = 0x0080;
 193
 194         /**
 195          * Change flag indicating that a classpath entry corresponding to the
 196          * element has changed position in the project's classpath. This flag is
 197          * only valid if the element is an <code>IPackageFragmentRoot</code>.
 198          *
 199          * @deprecated Use F_REORDER instead.
 200          */
 201         public int F_CLASSPATH_REORDER = 0x0100;
 202
 203         /**
 204          * Change flag indicating that the element has changed position relatively
 205          * to its siblings. If the element is an <code>IPackageFragmentRoot</code>,
 206          * a classpath entry corresponding to the element has changed position in
 207          * the project's classpath.
 208          *
 209          * @since 2.1
 210          */
 211         public int F_REORDER = 0x0100;
 212
 213         /**
 214          * Change flag indicating that the underlying <code>IProject</code> has
 215          * been opened. This flag is only valid if the element is an
 216          * <code>IJavaProject</code>.
 217          */
 218         public int F_OPENED = 0x0200;
 219
 220         /**
 221          * Change flag indicating that the underlying <code>IProject</code> has
 222          * been closed. This flag is only valid if the element is an
 223          * <code>IJavaProject</code>.
 224          */
 225         public int F_CLOSED = 0x0400;
 226
 227         /**
 228          * Change flag indicating that one of the supertypes of an
 229          * <code>IType</code> has changed.
 230          */
 231         public int F_SUPER_TYPES = 0x0800;
 232
 233         /**
 234          * Change flag indicating that the source attachment path or the source
 235          * attachment root path of a classpath entry corresponding to the element
 236          * was added. This flag is only valid if the element is an
 237          * <code>IPackageFragmentRoot</code>.
 238          */
 239         public int F_SOURCEATTACHED = 0x1000;
 240
 241         /**
 242          * Change flag indicating that the source attachment path or the source
 243          * attachment root path of a classpath entry corresponding to the element
 244          * was removed. This flag is only valid if the element is an
 245          * <code>IPackageFragmentRoot</code>.
 246          */
 247         public int F_SOURCEDETACHED = 0x2000;
 248
 249         /**
 250          * Change flag indicating that this is a fine-grained delta, that is, an
 251          * analysis down to the members level was done to determine if there were
 252          * structural changes to members.
 253          * <p>
 254          * Clients can use this flag to find out if a compilation unit that have a
 255          * <code>F_CONTENT</code> change should assume that there are no finer
 256          * grained changes (<code>F_FINE_GRAINED</code> is set) or if finer
 257          * grained changes were not considered (<code>F_FINE_GRAINED</code> is
 258          * not set).
 259          *
 260          * @since 2.0
 261          */
 262         public int F_FINE_GRAINED = 0x4000;
 263
 264         /**
 265          * Change flag indicating that the element's archive content on the
 266          * classpath has changed. This flag is only valid if the element is an
 267          * <code>IPackageFragmentRoot</code> which is an archive.
 268          *
 269          * @see IPackageFragmentRoot#isArchive
 270          * @since 2.0
 271          */
 272         public int F_ARCHIVE_CONTENT_CHANGED = 0x8000;
 273
 274         /**
 275          * Change flag indicating that a compilation unit has become a primary
 276          * working copy, or that a primary working copy has reverted to a
 277          * compilation unit. This flag is only valid if the element is an
 278          * <code>ICompilationUnit</code>.
 279          *
 280          * @since 3.0
 281          */
 282         public int F_PRIMARY_WORKING_COPY = 0x10000;
 283
 284         /**
 285          * Change flag indicating that the raw classpath (or the output folder) of a
 286          * project has changed. This flag is only valid if the element is an
 287          * <code>IJavaProject</code>.
 288          *
 289          * @since 3.0
 290          */
 291         public int F_CLASSPATH_CHANGED = 0x20000;
 292
 293         /**
 294          * Change flag indicating that the resource of a primary compilation unit
 295          * has changed. This flag is only valid if the element is a primary
 296          * <code>ICompilationUnit</code>.
 297          *
 298          * @since 3.0
 299          */
 300         public int F_PRIMARY_RESOURCE = 0x40000;
 301
 302         /**
 303          * Returns deltas for the children that have been added.
 304          *
 305          * @return deltas for the children that have been added
 306          */
 307         public IJavaElementDelta[] getAddedChildren();
 308
 309         /**
 310          * Returns deltas for the affected (added, removed, or changed) children.
 311          *
 312          * @return deltas for the affected (added, removed, or changed) children
 313          */
 314         public IJavaElementDelta[] getAffectedChildren();
 315
 316         /**
 317          * Returns deltas for the children which have changed.
 318          *
 319          * @return deltas for the children which have changed
 320          */
 321         public IJavaElementDelta[] getChangedChildren();
 322
 323         /**
 324          * Returns the element that this delta describes a change to.
 325          *
 326          * @return the element that this delta describes a change to
 327          */
 328         public IJavaElement getElement();
 329
 330         /**
 331          * Returns flags that describe how an element has changed. Such flags should
 332          * be tested using the <code>&</code> operand. For example:
 333          *
 334          * <pre>
 335          * if ((delta.getFlags() &amp; IJavaElementDelta.F_CONTENT) != 0) {
 336          *      // the delta indicates a content change
 337          * }
 338          * </pre>
 339          *
 340          * @return flags that describe how an element has changed
 341          */
 342         public int getFlags();
 343
 344         /**
 345          * Returns the kind of this delta - one of <code>ADDED</code>,
 346          * <code>REMOVED</code>, or <code>CHANGED</code>.
 347          *
 348          * @return the kind of this delta
 349          */
 350         public int getKind();
 351
 352         /**
 353          * Returns an element describing this element before it was moved to its
 354          * current location, or <code>null</code> if the <code>F_MOVED_FROM</code>
 355          * change flag is not set.
 356          *
 357          * @return an element describing this element before it was moved to its
 358          *         current location, or <code>null</code> if the
 359          *         <code>F_MOVED_FROM</code> change flag is not set
 360          */
 361         public IJavaElement getMovedFromElement();
 362
 363         /**
 364          * Returns an element describing this element in its new location, or
 365          * <code>null</code> if the <code>F_MOVED_TO</code> change flag is not
 366          * set.
 367          *
 368          * @return an element describing this element in its new location, or
 369          *         <code>null</code> if the <code>F_MOVED_TO</code> change flag
 370          *         is not set
 371          */
 372         public IJavaElement getMovedToElement();
 373
 374         /**
 375          * Returns deltas for the children which have been removed.
 376          *
 377          * @return deltas for the children which have been removed
 378          */
 379         public IJavaElementDelta[] getRemovedChildren();
 380
 381         /**
 382          * Returns the collection of resource deltas.
 383          * <p>
 384          * Note that resource deltas, like Java element deltas, are generally only
 385          * valid for the dynamic scope of an event notification. Clients must not
 386          * hang on to these objects.
 387          * </p>
 388          *
 389          * @return the underlying resource deltas, or <code>null</code> if none
 390          */
 391         public IResourceDelta[] getResourceDeltas();
 392 }