IJavaElementDelta


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