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