f13308fcdfb4163a3e0ac6362fef7b3c3c054fa2
[phpeclipse.git] / 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 }