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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.resources.IResourceDelta;
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.
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):
25 * <li><code>ADDED</code> - The element described by the delta has been
27 * <li><code>REMOVED</code> - The element described by the delta has been
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:
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>.
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
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
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.
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>.
112 * No assumptions should be made on whether the java element delta tree is
113 * rooted at the <code>IJavaModel</code> level or not.
116 * <code>IJavaElementDelta</code> object are not valid outside the dynamic
117 * scope of the notification.
120 * This interface is not intended to be implemented by clients.
123 public interface IJavaElementDelta {
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
130 public int ADDED = 1;
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
137 public int REMOVED = 2;
140 * Status constant indicating that the element has been changed, as
141 * described by the change flags.
145 public int CHANGED = 4;
148 * Change flag indicating that the content of the element has changed. This
149 * flag is only valid for elements which correspond to files.
151 public int F_CONTENT = 0x0001;
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>.
157 public int F_MODIFIERS = 0x0002;
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>.
164 public int F_CHILDREN = 0x0008;
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>.
171 public int F_MOVED_FROM = 0x0010;
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>.
178 public int F_MOVED_TO = 0x0020;
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>.
185 public int F_ADDED_TO_CLASSPATH = 0x0040;
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>.
192 public int F_REMOVED_FROM_CLASSPATH = 0x0080;
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>.
199 * @deprecated Use F_REORDER instead.
201 public int F_CLASSPATH_REORDER = 0x0100;
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.
211 public int F_REORDER = 0x0100;
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>.
218 public int F_OPENED = 0x0200;
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>.
225 public int F_CLOSED = 0x0400;
228 * Change flag indicating that one of the supertypes of an
229 * <code>IType</code> has changed.
231 public int F_SUPER_TYPES = 0x0800;
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>.
239 public int F_SOURCEATTACHED = 0x1000;
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>.
247 public int F_SOURCEDETACHED = 0x2000;
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.
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
262 public int F_FINE_GRAINED = 0x4000;
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.
269 * @see IPackageFragmentRoot#isArchive
272 public int F_ARCHIVE_CONTENT_CHANGED = 0x8000;
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>.
282 public int F_PRIMARY_WORKING_COPY = 0x10000;
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>.
291 public int F_CLASSPATH_CHANGED = 0x20000;
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>.
300 public int F_PRIMARY_RESOURCE = 0x40000;
303 * Returns deltas for the children that have been added.
305 * @return deltas for the children that have been added
307 public IJavaElementDelta[] getAddedChildren();
310 * Returns deltas for the affected (added, removed, or changed) children.
312 * @return deltas for the affected (added, removed, or changed) children
314 public IJavaElementDelta[] getAffectedChildren();
317 * Returns deltas for the children which have changed.
319 * @return deltas for the children which have changed
321 public IJavaElementDelta[] getChangedChildren();
324 * Returns the element that this delta describes a change to.
326 * @return the element that this delta describes a change to
328 public IJavaElement getElement();
331 * Returns flags that describe how an element has changed. Such flags should
332 * be tested using the <code>&</code> operand. For example:
335 * if ((delta.getFlags() & IJavaElementDelta.F_CONTENT) != 0) {
336 * // the delta indicates a content change
340 * @return flags that describe how an element has changed
342 public int getFlags();
345 * Returns the kind of this delta - one of <code>ADDED</code>,
346 * <code>REMOVED</code>, or <code>CHANGED</code>.
348 * @return the kind of this delta
350 public int getKind();
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.
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
361 public IJavaElement getMovedFromElement();
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
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
372 public IJavaElement getMovedToElement();
375 * Returns deltas for the children which have been removed.
377 * @return deltas for the children which have been removed
379 public IJavaElementDelta[] getRemovedChildren();
382 * Returns the collection of resource deltas.
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.
389 * @return the underlying resource deltas, or <code>null</code> if none
391 public IResourceDelta[] getResourceDeltas();