001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core;
011:
012: import org.eclipse.core.resources.IResourceDelta;
013: import org.eclipse.jdt.core.dom.CompilationUnit;
014:
015: /**
016: * A Java element delta describes changes in Java element between two discrete
017: * points in time. Given a delta, clients can access the element that has
018: * changed, and any children that have changed.
019: * <p>
020: * Deltas have a different status depending on the kind of change they represent.
021: * The list below summarizes each status (as returned by {@link #getKind})
022: * and its meaning (see individual constants for a more detailled description):
023: * <ul>
024: * <li>{@link #ADDED} - The element described by the delta has been added.</li>
025: * <li>{@link #REMOVED} - The element described by the delta has been removed.</li>
026: * <li>{@link #CHANGED} - The element described by the delta has been changed in some way.
027: * Specification of the type of change is provided by {@link #getFlags} which returns the following values:
028: * <ul>
029: * <li>{@link #F_ADDED_TO_CLASSPATH} - A classpath entry corresponding to the element
030: * has been added to the project's classpath. This flag is only valid if the element is an
031: * {@link IPackageFragmentRoot}.</li>
032: * <li>{@link #F_ARCHIVE_CONTENT_CHANGED} - The contents of an archive
033: * has changed in some way. This flag is only valid if the element is an {@link IPackageFragmentRoot}
034: * which is an archive.</li>
035: * <li>{@link #F_CHILDREN} - A child of the element has changed in some way. This flag
036: * is only valid if the element is an {@link IParent}.</li>
037: * <li>{@link #F_CLASSPATH_REORDER} - A classpath entry corresponding to the element
038: * has changed position in the project's classpath. This flag is only valid if the element is an
039: * {@link IPackageFragmentRoot}.</li>
040: * <li>{@link #F_CLOSED} - The underlying {@link org.eclipse.core.resources.IProject}
041: * has been closed. This flag is only valid if the element is an {@link IJavaProject}.</li>
042: * <li>{@link #F_CONTENT} - The contents of the element have been altered. This flag
043: * is only valid for elements which correspond to files.</li>
044: *<li>{@link #F_FINE_GRAINED} - The delta is a fine-grained delta, that is, an analysis down
045: * to the members level was done to determine if there were structural changes to members of the element.</li>
046: * <li>{@link #F_MODIFIERS} - The modifiers on the element have changed in some way.
047: * This flag is only valid if the element is an {@link IMember}.</li>
048: * <li>{@link #F_OPENED} - The underlying {@link org.eclipse.core.resources.IProject}
049: * has been opened. This flag is only valid if the element is an {@link IJavaProject}.</li>
050: * <li>{@link #F_REMOVED_FROM_CLASSPATH} - A classpath entry corresponding to the element
051: * has been removed from the project's classpath. This flag is only valid if the element is an
052: * {@link IPackageFragmentRoot}.</li>
053: * <li>{@link #F_SOURCEATTACHED} - The source attachment path or the source attachment root path
054: * of a classpath entry corresponding to the element was added. This flag is only valid if the element is an
055: * {@link IPackageFragmentRoot}.</li>
056: * <li>{@link #F_SOURCEDETACHED} - The source attachment path or the source attachment root path
057: * of a classpath entry corresponding to the element was removed. This flag is only valid if the element is an
058: * {@link IPackageFragmentRoot}.</li>
059: * <li>{@link #F_SUPER_TYPES} - One of the supertypes of an {@link IType} has changed</li>.
060: * </ul>
061: * </li>
062: * </ul>
063: * </p>
064: * <p>
065: * Move operations are indicated by other change flags, layered on top
066: * of the change flags described above. If element A is moved to become B,
067: * the delta for the change in A will have status {@link #REMOVED},
068: * with change flag {@link #F_MOVED_TO}. In this case,
069: * {@link #getMovedToElement} on delta A will return the handle for B.
070: * The delta for B will have status {@link #ADDED}, with change flag
071: * {@link #F_MOVED_FROM}, and {@link #getMovedFromElement} on delta
072: * B will return the handle for A. (Note, the handle to A in this case represents
073: * an element that no longer exists).
074: * </p>
075: * <p>
076: * Note that the move change flags only describe the changes to a single element, they
077: * do not imply anything about the parent or children of the element.
078: * </p>
079: * <p>
080: * The {@link #F_ADDED_TO_CLASSPATH}, {@link #F_REMOVED_FROM_CLASSPATH} and
081: * {@link #F_CLASSPATH_REORDER} flags are triggered by changes to a project's classpath. They do not mean that
082: * the underlying resource was added, removed or changed. For example, if a project P already contains a folder src, then
083: * adding a classpath entry with the 'P/src' path to the project's classpath will result in an {@link IJavaElementDelta}
084: * with the {@link #F_ADDED_TO_CLASSPATH} flag for the {@link IPackageFragmentRoot} P/src.
085: * On the contrary, if a resource is physically added, removed or changed and this resource corresponds to a classpath
086: * entry of the project, then an {@link IJavaElementDelta} with the {@link #ADDED},
087: * {@link #REMOVED}, or {@link #CHANGED} kind will be fired.
088: * </p>
089: * <p>
090: * Note that when a source attachment path or a source attachment root path is changed, then the flags of the delta contain
091: * both {@link #F_SOURCEATTACHED} and {@link #F_SOURCEDETACHED}.
092: * </p>
093: * <p>
094: * No assumptions should be made on whether the java element delta tree is rooted at the {@link IJavaModel}
095: * level or not.
096: * </p>
097: * <p>
098: * {@link IJavaElementDelta} object are not valid outside the dynamic scope
099: * 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 = 0x000001;
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 {@link IMember}.
136: */
137: public int F_MODIFIERS = 0x000002;
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 {@link IParent}.
142: */
143: public int F_CHILDREN = 0x000008;
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 {@link #getMovedFromElement}.
148: */
149: public int F_MOVED_FROM = 0x000010;
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 {@link #getMovedToElement}.
154: */
155: public int F_MOVED_TO = 0x000020;
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 {@link IPackageFragmentRoot}.
160: */
161: public int F_ADDED_TO_CLASSPATH = 0x000040;
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 {@link IPackageFragmentRoot}.
166: */
167: public int F_REMOVED_FROM_CLASSPATH = 0x000080;
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 {@link IPackageFragmentRoot}.
172: * @deprecated Use {@link #F_REORDER} instead.
173: */
174: public int F_CLASSPATH_REORDER = 0x000100;
175: /**
176: * Change flag indicating that the element has changed position relatively to its siblings.
177: * If the element is an {@link IPackageFragmentRoot}, 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 = 0x000100;
183:
184: /**
185: * Change flag indicating that the underlying {@link org.eclipse.core.resources.IProject} has been
186: * opened. This flag is only valid if the element is an {@link IJavaProject}.
187: */
188: public int F_OPENED = 0x000200;
189:
190: /**
191: * Change flag indicating that the underlying {@link org.eclipse.core.resources.IProject} has been
192: * closed. This flag is only valid if the element is an {@link IJavaProject}.
193: */
194: public int F_CLOSED = 0x000400;
195:
196: /**
197: * Change flag indicating that one of the supertypes of an {@link IType}
198: * has changed.
199: */
200: public int F_SUPER_TYPES = 0x000800;
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: * {@link IPackageFragmentRoot}.
206: */
207: public int F_SOURCEATTACHED = 0x001000;
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: * {@link IPackageFragmentRoot}.
213: */
214: public int F_SOURCEDETACHED = 0x002000;
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 {@link #F_CONTENT} change should assume that there are
223: * no finer grained changes ({@link #F_FINE_GRAINED} is set) or if
224: * finer grained changes were not considered ({@link #F_FINE_GRAINED}
225: * is not set).
226: *
227: * @since 2.0
228: */
229: public int F_FINE_GRAINED = 0x004000;
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 {@link IPackageFragmentRoot}
234: * which is an archive.
235: *
236: * @see IPackageFragmentRoot#isArchive()
237: * @since 2.0
238: */
239: public int F_ARCHIVE_CONTENT_CHANGED = 0x008000;
240:
241: /**
242: * Change flag indicating that a compilation unit has become a primary working copy, or that a
243: * primary working copy has reverted to a compilation unit.
244: * This flag is only valid if the element is an {@link ICompilationUnit}.
245: *
246: * @since 3.0
247: */
248: public int F_PRIMARY_WORKING_COPY = 0x010000;
249:
250: /**
251: * Change flag indicating that the raw classpath (or the output folder) of a project has changed.
252: * This flag is only valid if the element is an {@link IJavaProject}.
253: *
254: * @since 3.0
255: */
256: public int F_CLASSPATH_CHANGED = 0x020000;
257:
258: /**
259: * Change flag indicating that the resource of a primary compilation unit has changed.
260: * This flag is only valid if the element is a primary {@link ICompilationUnit}.
261: *
262: * @since 3.0
263: */
264: public int F_PRIMARY_RESOURCE = 0x040000;
265:
266: /**
267: * Change flag indicating that a reconcile operation has affected the compilation unit AST created in a
268: * previous reconcile operation. Use {@link #getCompilationUnitAST()} to retrieve the AST (if any is available).
269: * This flag is only valid if the element is an {@link ICompilationUnit} in working copy mode.
270: *
271: * @since 3.2
272: */
273: public int F_AST_AFFECTED = 0x080000;
274:
275: /**
276: * Change flag indicating that the categories of the element have changed.
277: * This flag is only valid if the element is an {@link IMember}.
278: *
279: * @since 3.2
280: */
281: public int F_CATEGORIES = 0x100000;
282:
283: /**
284: * Returns deltas for the children that have been added.
285: * @return deltas for the children that have been added
286: */
287: public IJavaElementDelta[] getAddedChildren();
288:
289: /**
290: * Returns deltas for the affected (added, removed, or changed) children.
291: * @return deltas for the affected (added, removed, or changed) children
292: */
293: public IJavaElementDelta[] getAffectedChildren();
294:
295: /**
296: * Returns the compilation unit AST created by the last reconcile operation on this delta's element.
297: * This returns a non-null value if and only if:
298: * <ul>
299: * <li>the last reconcile operation on this working copy requested an AST</li>
300: * <li>this delta's element is an {@link ICompilationUnit} in working copy mode</li>
301: * <li>the delta comes from a {@link ElementChangedEvent#POST_RECONCILE} event
302: * </ul>
303: *
304: * @return the AST created during the last reconcile operation
305: * @see ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, org.eclipse.core.runtime.IProgressMonitor)
306: * @see #F_AST_AFFECTED
307: * @since 3.2
308: */
309: public CompilationUnit getCompilationUnitAST();
310:
311: /**
312: * Returns deltas for the children which have changed.
313: * @return deltas for the children which have changed
314: */
315: public IJavaElementDelta[] getChangedChildren();
316:
317: /**
318: * Returns the element that this delta describes a change to.
319: * @return the element that this delta describes a change to
320: */
321: public IJavaElement getElement();
322:
323: /**
324: * Returns flags that describe how an element has changed.
325: * Such flags should be tested using the <code>&</code> operand. For example:
326: * <pre>
327: * if ((delta.getFlags() & IJavaElementDelta.F_CONTENT) != 0) {
328: * // the delta indicates a content change
329: * }
330: * </pre>
331: *
332: * @return flags that describe how an element has changed
333: */
334: public int getFlags();
335:
336: /**
337: * Returns the kind of this delta - one of {@link #ADDED}, {@link #REMOVED},
338: * or {@link #CHANGED}.
339: *
340: * @return the kind of this delta
341: */
342: public int getKind();
343:
344: /**
345: * Returns an element describing this element before it was moved
346: * to its current location, or <code>null</code> if the
347: * {@link #F_MOVED_FROM} change flag is not set.
348: *
349: * @return an element describing this element before it was moved
350: * to its current location, or <code>null</code> if the
351: * {@link #F_MOVED_FROM} change flag is not set
352: */
353: public IJavaElement getMovedFromElement();
354:
355: /**
356: * Returns an element describing this element in its new location,
357: * or <code>null</code> if the {@link #F_MOVED_TO} change
358: * flag is not set.
359: *
360: * @return an element describing this element in its new location,
361: * or <code>null</code> if the {@link #F_MOVED_TO} change
362: * flag is not set
363: */
364: public IJavaElement getMovedToElement();
365:
366: /**
367: * Returns deltas for the children which have been removed.
368: *
369: * @return deltas for the children which have been removed
370: */
371: public IJavaElementDelta[] getRemovedChildren();
372:
373: /**
374: * Returns the collection of resource deltas.
375: * <p>
376: * Note that resource deltas, like Java element deltas, are generally only valid
377: * for the dynamic scope of an event notification. Clients must not hang on to
378: * these objects.
379: * </p>
380: *
381: * @return the underlying resource deltas, or <code>null</code> if none
382: */
383: public IResourceDelta[] getResourceDeltas();
384: }
|