org.eclipse.jdt.core.IJavaElementDelta Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2019 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.core;
import org.eclipse.core.resources.IResourceDelta;
import org.eclipse.jdt.core.dom.CompilationUnit;
/**
* A Java element delta describes changes in Java element between two discrete
* points in time. Given a delta, clients can access the element that has
* changed, and any children that have changed.
*
* Deltas have a different status depending on the kind of change they represent.
* The list below summarizes each status (as returned by {@link #getKind})
* and its meaning (see individual constants for a more detailed description):
*
* - {@link #ADDED} - The element described by the delta has been added.
* - {@link #REMOVED} - The element described by the delta has been removed.
* - {@link #CHANGED} - The element described by the delta has been changed in some way.
* Specification of the type of change is provided by {@link #getFlags} which returns the following values:
*
* - {@link #F_ADDED_TO_CLASSPATH} - A classpath entry corresponding to the element
* has been added to the project's classpath. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
* - {@link #F_ARCHIVE_CONTENT_CHANGED} - The contents of an archive
* has changed in some way. This flag is only valid if the element is an {@link IPackageFragmentRoot}
* which is an archive.
* - {@link #F_CHILDREN} - A child of the element has changed in some way. This flag
* is only valid if the element is an {@link IParent}.
* - {@link #F_CLASSPATH_REORDER} - A classpath entry corresponding to the element
* has changed position in the project's classpath. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
* - {@link #F_CLOSED} - The underlying {@link org.eclipse.core.resources.IProject}
* has been closed. This flag is only valid if the element is an {@link IJavaProject}.
* - {@link #F_CONTENT} - The contents of the element have been altered. This flag
* is only valid for elements which correspond to files.
*- {@link #F_FINE_GRAINED} - The delta is a fine-grained delta, that is, an analysis down
* to the members level was done to determine if there were structural changes to members of the element.
* - {@link #F_MODIFIERS} - The modifiers on the element have changed in some way.
* This flag is only valid if the element is an {@link IMember}.
* - {@link #F_OPENED} - The underlying {@link org.eclipse.core.resources.IProject}
* has been opened. This flag is only valid if the element is an {@link IJavaProject}.
* - {@link #F_REMOVED_FROM_CLASSPATH} - A classpath entry corresponding to the element
* has been removed from the project's classpath. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
* - {@link #F_SOURCEATTACHED} - The source attachment path or the source attachment root path
* of a classpath entry corresponding to the element was added. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
* - {@link #F_SOURCEDETACHED} - The source attachment path or the source attachment root path
* of a classpath entry corresponding to the element was removed. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
* - {@link #F_SUPER_TYPES} - One of the supertypes of an {@link IType} has changed.
*
*
*
*
* Move operations are indicated by other change flags, layered on top
* of the change flags described above. If element A is moved to become B,
* the delta for the change in A will have status {@link #REMOVED},
* with change flag {@link #F_MOVED_TO}. In this case,
* {@link #getMovedToElement} on delta A will return the handle for B.
* The delta for B will have status {@link #ADDED}, with change flag
* {@link #F_MOVED_FROM}, and {@link #getMovedFromElement} on delta
* B will return the handle for A. (Note, the handle to A in this case represents
* an element that no longer exists).
*
*
* Note that the move change flags only describe the changes to a single element, they
* do not imply anything about the parent or children of the element.
*
*
* The {@link #F_ADDED_TO_CLASSPATH}, {@link #F_REMOVED_FROM_CLASSPATH} and
* {@link #F_CLASSPATH_REORDER} flags are triggered by changes to a project's classpath. They do not mean that
* the underlying resource was added, removed or changed. For example, if a project P already contains a folder src, then
* adding a classpath entry with the 'P/src' path to the project's classpath will result in an {@link IJavaElementDelta}
* with the {@link #F_ADDED_TO_CLASSPATH} flag for the {@link IPackageFragmentRoot} P/src.
* On the contrary, if a resource is physically added, removed or changed and this resource corresponds to a classpath
* entry of the project, then an {@link IJavaElementDelta} with the {@link #ADDED},
* {@link #REMOVED}, or {@link #CHANGED} kind will be fired.
*
*
* Note that when a source attachment path or a source attachment root path is changed, then the flags of the delta contain
* both {@link #F_SOURCEATTACHED} and {@link #F_SOURCEDETACHED}.
*
*
* No assumptions should be made on whether the java element delta tree is rooted at the {@link IJavaModel}
* level or not.
*
*
* {@link IJavaElementDelta} object are not valid outside the dynamic scope
* of the notification.
*
*
* @see IElementChangedListener
* @see ElementChangedEvent
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IJavaElementDelta {
/**
* Status constant indicating that the element has been added.
* Note that an added java element delta has no children, as they are all implicitely added.
*/
public int ADDED = 1;
/**
* Status constant indicating that the element has been removed.
* Note that a removed java element delta has no children, as they are all implicitely removed.
*/
public int REMOVED = 2;
/**
* Status constant indicating that the element has been changed,
* as described by the change flags.
*
* @see #getFlags()
*/
public int CHANGED = 4;
/**
* Change flag indicating that the content of the element has changed.
* This flag is only valid for elements which correspond to files.
*/
public int F_CONTENT = 0x000001;
/**
* Change flag indicating that the modifiers of the element have changed.
* This flag is only valid if the element is an {@link IMember}.
*/
public int F_MODIFIERS = 0x000002;
/**
* Change flag indicating that there are changes to the children of the element.
* This flag is only valid if the element is an {@link IParent}.
*/
public int F_CHILDREN = 0x000008;
/**
* Change flag indicating that the element was moved from another location.
* The location of the old element can be retrieved using {@link #getMovedFromElement}.
*/
public int F_MOVED_FROM = 0x000010;
/**
* Change flag indicating that the element was moved to another location.
* The location of the new element can be retrieved using {@link #getMovedToElement}.
*/
public int F_MOVED_TO = 0x000020;
/**
* Change flag indicating that a classpath entry corresponding to the element has been added to the project's classpath.
* This flag is only valid if the element is an {@link IPackageFragmentRoot}.
*/
public int F_ADDED_TO_CLASSPATH = 0x000040;
/**
* Change flag indicating that a classpath entry corresponding to the element has been removed from the project's
* classpath. This flag is only valid if the element is an {@link IPackageFragmentRoot}.
*/
public int F_REMOVED_FROM_CLASSPATH = 0x000080;
/**
* Change flag indicating that a classpath entry corresponding to the element has changed position in the project's
* classpath. This flag is only valid if the element is an {@link IPackageFragmentRoot}.
* @deprecated Use {@link #F_REORDER} instead.
*/
public int F_CLASSPATH_REORDER = 0x000100;
/**
* Change flag indicating that the element has changed position relatively to its siblings.
* If the element is an {@link IPackageFragmentRoot}, a classpath entry corresponding
* to the element has changed position in the project's classpath.
*
* @since 2.1
*/
public int F_REORDER = 0x000100;
/**
* Change flag indicating that the underlying {@link org.eclipse.core.resources.IProject} has been
* opened. This flag is only valid if the element is an {@link IJavaProject}.
*/
public int F_OPENED = 0x000200;
/**
* Change flag indicating that the underlying {@link org.eclipse.core.resources.IProject} has been
* closed. This flag is only valid if the element is an {@link IJavaProject}.
*/
public int F_CLOSED = 0x000400;
/**
* Change flag indicating that one of the supertypes of an {@link IType}
* has changed.
*/
public int F_SUPER_TYPES = 0x000800;
/**
* Change flag indicating that the source attachment path or the source attachment root path of a classpath entry
* corresponding to the element was added. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
*/
public int F_SOURCEATTACHED = 0x001000;
/**
* Change flag indicating that the source attachment path or the source attachment root path of a classpath entry
* corresponding to the element was removed. This flag is only valid if the element is an
* {@link IPackageFragmentRoot}.
*/
public int F_SOURCEDETACHED = 0x002000;
/**
* Change flag indicating that this is a fine-grained delta, that is, an analysis down
* to the members level was done to determine if there were structural changes to
* members.
*
* Clients can use this flag to find out if a compilation unit
* that have a {@link #F_CONTENT} change should assume that there are
* no finer grained changes ({@link #F_FINE_GRAINED} is set) or if
* finer grained changes were not considered ({@link #F_FINE_GRAINED}
* is not set).
*
* @since 2.0
*/
public int F_FINE_GRAINED = 0x004000;
/**
* Change flag indicating that the element's archive content on the classpath has changed.
* This flag is only valid if the element is an {@link IPackageFragmentRoot}
* which is an archive.
*
* @see IPackageFragmentRoot#isArchive()
* @since 2.0
*/
public int F_ARCHIVE_CONTENT_CHANGED = 0x008000;
/**
* Change flag indicating that a compilation unit has become a primary working copy, or that a
* primary working copy has reverted to a compilation unit.
* This flag is only valid if the element is an {@link ICompilationUnit}.
*
* @since 3.0
*/
public int F_PRIMARY_WORKING_COPY = 0x010000;
/**
* Change flag indicating that the {@link IJavaProject#getRawClasspath() raw classpath}
* (or the {@link IJavaProject#getOutputLocation() output folder}) of a project has changed.
* This flag is only valid if the element is an {@link IJavaProject}.
* Also see {@link #F_RESOLVED_CLASSPATH_CHANGED}, which indicates that there is a
* change to the {@link IJavaProject#getResolvedClasspath(boolean) resolved class path}.
* The resolved classpath can change without the raw classpath changing (e.g.
* if a container resolves to a different set of classpath entries).
* And conversely, it is possible to construct a case where the raw classpath
* can change without the resolved classpath changing.
*
* @since 3.0
*/
public int F_CLASSPATH_CHANGED = 0x020000;
/**
* Change flag indicating that the resource of a primary compilation unit has changed.
* This flag is only valid if the element is a primary {@link ICompilationUnit}.
*
* @since 3.0
*/
public int F_PRIMARY_RESOURCE = 0x040000;
/**
* Change flag indicating that a reconcile operation has affected the compilation unit AST created in a
* previous reconcile operation. Use {@link #getCompilationUnitAST()} to retrieve the AST (if any is available).
* This flag is only valid if the element is an {@link ICompilationUnit} in working copy mode.
*
* @since 3.2
*/
public int F_AST_AFFECTED = 0x080000;
/**
* Change flag indicating that the categories of the element have changed.
* This flag is only valid if the element is an {@link IMember}.
*
* @since 3.2
*/
public int F_CATEGORIES = 0x100000;
/**
* Change flag indicating that the {@link IJavaProject#getResolvedClasspath(boolean)
* resolved classpath} of a project has changed.
* This flag is only valid if the element is an {@link IJavaProject}.
* Also see {@link #F_CLASSPATH_CHANGED}, which indicates that there is a
* change to the {@link IJavaProject#getRawClasspath() raw class path}.
* The resolved classpath can change without the raw classpath changing (e.g.
* if a container resolves to a different set of classpath entries).
* And conversely, it is possible to construct a case where the raw classpath
* can change without the resolved classpath changing.
*
* @since 3.4
*/
public int F_RESOLVED_CLASSPATH_CHANGED = 0x200000;
/**
* Change flag indicating that the annotations of the element have changed.
* Use {@link #getAnnotationDeltas()} to get the added/removed/changed annotations.
* This flag is only valid if the element is an {@link IAnnotatable}.
*
* @since 3.4
*/
public int F_ANNOTATIONS = 0x400000;
/**
* Change flag indicating that the attributes of the element have changed.
* Use {@link #getClasspathAttributeDeltas()} to get the added/removed/changed attributes.
*
* @since 3.33
*/
public int F_CLASSPATH_ATTRIBUTES = 0x800000;
/**
* Returns deltas for the children that have been added.
* @return deltas for the children that have been added
*/
public IJavaElementDelta[] getAddedChildren();
/**
* Returns deltas for the affected (added, removed, or changed) children.
* @return deltas for the affected (added, removed, or changed) children
*/
public IJavaElementDelta[] getAffectedChildren();
/**
* Returns deltas for affected annotations (added, removed, or changed).
* Returns an empty array if no annotations was affected, or if this delta's element is not
* an {@link IAnnotatable}.
*
* @return deltas for affected annotations (added, removed, or changed)
*
* @since 3.4
*/
public IJavaElementDelta[] getAnnotationDeltas();
/**
* Returns the compilation unit AST created by the last reconcile operation on this delta's element.
* This returns a non-null value if and only if:
*
* - the last reconcile operation on this working copy requested an AST
* - this delta's element is an {@link ICompilationUnit} in working copy mode
* - the delta comes from a {@link ElementChangedEvent#POST_RECONCILE} event
*
*
* @return the AST created during the last reconcile operation
* @see ICompilationUnit#reconcile(int, boolean, WorkingCopyOwner, org.eclipse.core.runtime.IProgressMonitor)
* @see #F_AST_AFFECTED
* @since 3.2
*/
public CompilationUnit getCompilationUnitAST();
/**
* Returns deltas for the children which have changed.
* @return deltas for the children which have changed
*/
public IJavaElementDelta[] getChangedChildren();
/**
* Returns the element that this delta describes a change to.
* @return the element that this delta describes a change to
*/
public IJavaElement getElement();
/**
* Returns flags that describe how an element has changed.
* Such flags should be tested using the &
operand. For example:
*
* if ((delta.getFlags() & IJavaElementDelta.F_CONTENT) != 0) {
* // the delta indicates a content change
* }
*
*
* @return flags that describe how an element has changed
*/
public int getFlags();
/**
* Returns the kind of this delta - one of {@link #ADDED}, {@link #REMOVED},
* or {@link #CHANGED}.
*
* @return the kind of this delta
*/
public int getKind();
/**
* Returns an element describing this element before it was moved
* to its current location, or null
if the
* {@link #F_MOVED_FROM} change flag is not set.
*
* @return an element describing this element before it was moved
* to its current location, or null
if the
* {@link #F_MOVED_FROM} change flag is not set
*/
public IJavaElement getMovedFromElement();
/**
* Returns an element describing this element in its new location,
* or null
if the {@link #F_MOVED_TO} change
* flag is not set.
*
* @return an element describing this element in its new location,
* or null
if the {@link #F_MOVED_TO} change
* flag is not set
*/
public IJavaElement getMovedToElement();
/**
* Returns deltas for the children which have been removed.
*
* @return deltas for the children which have been removed
*/
public IJavaElementDelta[] getRemovedChildren();
/**
* Returns the collection of resource deltas.
*
* Note that resource deltas, like Java element deltas, are generally only valid
* for the dynamic scope of an event notification. Clients must not hang on to
* these objects.
*
*
* @return the underlying resource deltas, or null
if none
*/
public IResourceDelta[] getResourceDeltas();
/**
* Returns deltas for affected attributes (added, removed, or changed).
* Returns an empty array if no attribute was affected, or if this delta's element is not
* for an affected {@link IClasspathEntry}.
*
* @return deltas for affected attributes (added, removed, or changed)
*
* @since 3.33
*/
default public IClasspathAttributeDelta[] getClasspathAttributeDeltas() {
return new IClasspathAttributeDelta[] {};
}
}