org.eclipse.core.resources.IResourceDelta Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2009 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import org.eclipse.core.internal.watson.IElementComparator;
import org.eclipse.core.resources.mapping.IResourceChangeDescriptionFactory;
import org.eclipse.core.runtime.*;
/**
* A resource delta represents changes in the state of a resource tree
* between two discrete points in time.
*
* Resource deltas implement the IAdaptable interface;
* extensions are managed by the platform's adapter manager.
*
*
* @see IResource
* @see Platform#getAdapterManager()
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IResourceDelta extends IAdaptable {
/*====================================================================
* Constants defining resource delta kinds:
*====================================================================*/
/**
* Delta kind constant indicating that the resource has not been changed in any way.
*
* @see IResourceDelta#getKind()
*/
public static final int NO_CHANGE = IElementComparator.K_NO_CHANGE;
/**
* Delta kind constant (bit mask) indicating that the resource has been added
* to its parent. That is, one that appears in the "after" state,
* not in the "before" one.
*
* @see IResourceDelta#getKind()
*/
public static final int ADDED = 0x1;
/**
* Delta kind constant (bit mask) indicating that the resource has been removed
* from its parent. That is, one that appears in the "before" state,
* not in the "after" one.
*
* @see IResourceDelta#getKind()
*/
public static final int REMOVED = 0x2;
/**
* Delta kind constant (bit mask) indicating that the resource has been changed.
* That is, one that appears in both the "before" and "after" states.
*
* @see IResourceDelta#getKind()
*/
public static final int CHANGED = 0x4;
/**
* Delta kind constant (bit mask) indicating that a phantom resource has been added at
* the location of the delta node.
*
* @see IResourceDelta#getKind()
*/
public static final int ADDED_PHANTOM = 0x8;
/**
* Delta kind constant (bit mask) indicating that a phantom resource has been removed from
* the location of the delta node.
*
* @see IResourceDelta#getKind()
*/
public static final int REMOVED_PHANTOM = 0x10;
/**
* The bit mask which describes all possible delta kinds,
* including ones involving phantoms.
*
* @see IResourceDelta#getKind()
*/
public static final int ALL_WITH_PHANTOMS = CHANGED | ADDED | REMOVED | ADDED_PHANTOM | REMOVED_PHANTOM;
/*====================================================================
* Constants which describe resource changes:
*====================================================================*/
/**
* Change constant (bit mask) indicating that the content of the resource has changed.
*
* @see IResourceDelta#getFlags()
*/
public static final int CONTENT = 0x100;
/**
* Change constant (bit mask) indicating that the resource was moved from another location.
* The location in the "before" state can be retrieved using getMovedFromPath().
*
* @see IResourceDelta#getFlags()
*/
public static final int MOVED_FROM = 0x1000;
/**
* Change constant (bit mask) indicating that the resource was moved to another location.
* The location in the new state can be retrieved using getMovedToPath().
*
* @see IResourceDelta#getFlags()
*/
public static final int MOVED_TO = 0x2000;
/**
* Change constant (bit mask) indicating that the resource was copied from another location.
* The location in the "before" state can be retrieved using getMovedFromPath().
* This flag is only used when describing potential changes using an {@link IResourceChangeDescriptionFactory}.
*
* @see IResourceDelta#getFlags()
* @since 3.2
*/
public static final int COPIED_FROM = 0x800;
/**
* Change constant (bit mask) indicating that the resource was opened or closed.
* This flag is also set when the project did not exist in the "before" state.
* For example, if the current state of the resource is open then it was previously closed
* or did not exist.
*
* @see IResourceDelta#getFlags()
*/
public static final int OPEN = 0x4000;
/**
* Change constant (bit mask) indicating that the type of the resource has changed.
*
* @see IResourceDelta#getFlags()
*/
public static final int TYPE = 0x8000;
/**
* Change constant (bit mask) indicating that the resource's sync status has changed.
* This type of change is not included in build deltas, only in those for resource notification.
*
* @see IResourceDelta#getFlags()
*/
public static final int SYNC = 0x10000;
/**
* Change constant (bit mask) indicating that the resource's markers have changed.
* This type of change is not included in build deltas, only in those for resource notification.
*
* @see IResourceDelta#getFlags()
*/
public static final int MARKERS = 0x20000;
/**
* Change constant (bit mask) indicating that the resource has been
* replaced by another at the same location (i.e., the resource has
* been deleted and then added).
*
* @see IResourceDelta#getFlags()
*/
public static final int REPLACED = 0x40000;
/**
* Change constant (bit mask) indicating that a project's description has changed.
*
* @see IResourceDelta#getFlags()
*/
public static final int DESCRIPTION = 0x80000;
/**
* Change constant (bit mask) indicating that the encoding of the resource has changed.
*
* @see IResourceDelta#getFlags()
* @since 3.0
*/
public static final int ENCODING = 0x100000;
/**
* Change constant (bit mask) indicating that the underlying file or folder of the linked resource has been added or removed.
*
* @see IResourceDelta#getFlags()
* @since 3.4
*/
public static final int LOCAL_CHANGED = 0x200000;
/**
* Change constant (bit mask) indicating that the derived flag of the resource has changed.
*
* @see IResourceDelta#getFlags()
* @since 3.6
*/
public static final int DERIVED_CHANGED = 0x400000;
/**
* Accepts the given visitor.
* The only kinds of resource deltas visited
* are ADDED, REMOVED,
* and CHANGED.
* The visitor's visit method is called with this
* resource delta if applicable. If the visitor returns true,
* the resource delta's children are also visited.
*
* This is a convenience method, fully equivalent to
* accept(visitor, IResource.NONE).
* Although the visitor will be invoked for this resource delta, it will not be
* invoked for any team-private member resources.
*
*
* @param visitor the visitor
* @exception CoreException if the visitor failed with this exception.
* @see IResourceDeltaVisitor#visit(IResourceDelta)
*/
public void accept(IResourceDeltaVisitor visitor) throws CoreException;
/**
* Accepts the given visitor.
* The visitor's visit method is called with this
* resource delta. If the visitor returns true,
* the resource delta's children are also visited.
*
* This is a convenience method, fully equivalent to:
*
* accept(visitor, includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
*
* Although the visitor will be invoked for this resource delta, it will not be
* invoked for any team-private member resources.
*
*
* @param visitor the visitor
* @param includePhantoms true if phantom resources are
* of interest; false if phantom resources are not of
* interest
* @exception CoreException if the visitor failed with this exception.
* @see #accept(IResourceDeltaVisitor)
* @see IResource#isPhantom()
* @see IResourceDeltaVisitor#visit(IResourceDelta)
*/
public void accept(IResourceDeltaVisitor visitor, boolean includePhantoms) throws CoreException;
/**
* Accepts the given visitor.
* The visitor's visit method is called with this
* resource delta. If the visitor returns true,
* the resource delta's children are also visited.
*
* The member flags determine which child deltas of this resource delta will be visited.
* The visitor will always be invoked for this resource delta.
*
* If the INCLUDE_PHANTOMS member flag is not specified
* (recommended), only child resource deltas involving existing resources will be visited
* (kinds ADDED, REMOVED, and CHANGED).
* If the INCLUDE_PHANTOMS member flag is specified,
* the result will also include additions and removes of phantom resources
* (kinds ADDED_PHANTOM and REMOVED_PHANTOM).
*
*
* If the INCLUDE_TEAM_PRIVATE_MEMBERS member flag is not specified
* (recommended), resource deltas involving team private member resources will be
* excluded from the visit. If the INCLUDE_TEAM_PRIVATE_MEMBERS member
* flag is specified, the visit will also include additions and removes of
* team private member resources.
*
*
* @param visitor the visitor
* @param memberFlags bit-wise or of member flag constants
* (IContainer.INCLUDE_PHANTOMS, INCLUDE_HIDDEN
* and INCLUDE_TEAM_PRIVATE_MEMBERS) indicating which members are of interest
* @exception CoreException if the visitor failed with this exception.
* @see IResource#isPhantom()
* @see IResource#isTeamPrivateMember()
* @see IResource#isHidden()
* @see IContainer#INCLUDE_PHANTOMS
* @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
* @see IContainer#INCLUDE_HIDDEN
* @see IResourceDeltaVisitor#visit(IResourceDelta)
* @since 2.0
*/
public void accept(IResourceDeltaVisitor visitor, int memberFlags) throws CoreException;
/**
* Finds and returns the descendent delta identified by the given path in
* this delta, or null if no such descendent exists.
* The supplied path may be absolute or relative; in either case, it is
* interpreted as relative to this delta. Trailing separators are ignored.
* If the path is empty this delta is returned.
*
* This is a convenience method to avoid manual traversal of the delta
* tree in cases where the listener is only interested in changes to
* particular resources. Calling this method will generally be
* faster than manually traversing the delta to a particular descendent.
*
* @param path the path of the desired descendent delta
* @return the descendent delta, or null if no such
* descendent exists in the delta
* @since 2.0
*/
public IResourceDelta findMember(IPath path);
/**
* Returns resource deltas for all children of this resource
* which were added, removed, or changed. Returns an empty
* array if there are no affected children.
*
* This is a convenience method, fully equivalent to:
*
* getAffectedChildren(ADDED | REMOVED | CHANGED, IResource.NONE);
*
* Team-private member resources are not included in the result; neither are
* phantom resources.
*
*
* @return the resource deltas for all affected children
* @see IResourceDelta#ADDED
* @see IResourceDelta#REMOVED
* @see IResourceDelta#CHANGED
* @see #getAffectedChildren(int,int)
*/
public IResourceDelta[] getAffectedChildren();
/**
* Returns resource deltas for all children of this resource
* whose kind is included in the given mask. Kind masks are formed
* by the bitwise or of IResourceDelta kind constants.
* Returns an empty array if there are no affected children.
*
* This is a convenience method, fully equivalent to:
*
* getAffectedChildren(kindMask, IResource.NONE);
*
* Team-private member resources are not included in the result.
*
*
* @param kindMask a mask formed by the bitwise or of IResourceDelta
* delta kind constants
* @return the resource deltas for all affected children
* @see IResourceDelta#ADDED
* @see IResourceDelta#REMOVED
* @see IResourceDelta#CHANGED
* @see IResourceDelta#ADDED_PHANTOM
* @see IResourceDelta#REMOVED_PHANTOM
* @see IResourceDelta#ALL_WITH_PHANTOMS
* @see #getAffectedChildren(int,int)
*/
public IResourceDelta[] getAffectedChildren(int kindMask);
/**
* Returns resource deltas for all children of this resource
* whose kind is included in the given mask. Masks are formed
* by the bitwise or of IResourceDelta kind constants.
* Returns an empty array if there are no affected children.
*
* If the INCLUDE_TEAM_PRIVATE_MEMBERS member flag is not specified,
* (recommended), resource deltas involving team private member resources will be
* excluded. If the INCLUDE_TEAM_PRIVATE_MEMBERS member
* flag is specified, the result will also include resource deltas of the
* specified kinds to team private member resources.
*
*
* If the {@link IContainer#INCLUDE_HIDDEN} member flag is not specified,
* (recommended), resource deltas involving hidden resources will be
* excluded. If the {@link IContainer#INCLUDE_HIDDEN} member
* flag is specified, the result will also include resource deltas of the
* specified kinds to hidden resources.
*
*
* Specifying the IContainer.INCLUDE_PHANTOMS member flag is equivalent
* to including IContainer.ADDED_PHANTOM and IContainer.REMOVED_PHANTOM
* in the kind mask.
*
*
* @param kindMask a mask formed by the bitwise or of IResourceDelta
* delta kind constants
* @param memberFlags bit-wise or of member flag constants
* (IContainer.INCLUDE_PHANTOMS, IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS
* and IContainer.INCLUDE_HIDDEN)
* indicating which members are of interest
* @return the resource deltas for all affected children
* @see IResourceDelta#ADDED
* @see IResourceDelta#REMOVED
* @see IResourceDelta#CHANGED
* @see IResourceDelta#ADDED_PHANTOM
* @see IResourceDelta#REMOVED_PHANTOM
* @see IResourceDelta#ALL_WITH_PHANTOMS
* @see IContainer#INCLUDE_PHANTOMS
* @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
* @see IContainer#INCLUDE_HIDDEN
* @since 2.0
*/
public IResourceDelta[] getAffectedChildren(int kindMask, int memberFlags);
/**
* Returns flags which describe in more detail how a resource has been affected.
*
* The following codes (bit masks) are used when kind is CHANGED, and
* also when the resource is involved in a move:
*
* CONTENT - The bytes contained by the resource have
* been altered, or IResource.touch has been called on
* the resource.DERIVED_CHANGED - The derived flag of the resource has
* been altered.ENCODING - The encoding of the resource may have been altered.
* This flag is not set when the encoding changes due to the file being modified,
* or being moved.DESCRIPTION - The description of the project has been altered,
* or IResource.touch has been called on the project.
* This flag is only valid for project resources.OPEN - The project's open/closed state has changed.
* If it is not open, it was closed, and vice versa. This flag is only valid for project resources.TYPE - The resource (a folder or file) has changed its type.SYNC - The resource's sync status has changed.MARKERS - The resource's markers have changed.REPLACED - The resource (and all its properties)
* was deleted (either by a delete or move), and was subsequently re-created
* (either by a create, move, or copy).LOCAL_CHANGED - The resource is a linked resource,
* and the underlying file system object has been added or removed.
* The following code is only used if kind is REMOVED
* (or CHANGED in conjunction with REPLACED):
*
* MOVED_TO - The resource has moved.
* getMovedToPath will return the path of where it was moved to.
* The following code is only used if kind is ADDED
* (or CHANGED in conjunction with REPLACED):
*
* MOVED_FROM - The resource has moved.
* getMovedFromPath will return the path of where it was moved from.
* The following code is only used when describing potential changes using an {@link IResourceChangeDescriptionFactory}:
*
* COPIED_FROM - Change constant (bit mask) indicating that the resource was copied from another location.
* The location in the "before" state can be retrieved using getMovedFromPath().
*
* A simple move operation would result in the following delta information.
* If a resource is moved from A to B (with no other changes to A or B),
* then A will have kind REMOVED, with flag MOVED_TO,
* and getMovedToPath on A will return the path for B.
* B will have kind ADDED, with flag MOVED_FROM,
* and getMovedFromPath on B will return the path for A.
* B's other flags will describe any other changes to the resource, as compared
* to its previous location at A.
*
*
* Note that the move flags only describe the changes to a single resource; they
* don't necessarily imply anything about the parent or children of the resource.
* If the children were moved as a consequence of a subtree move operation,
* they will have corresponding move flags as well.
*
*
* Note that it is possible for a file resource to be replaced in the workspace
* by a folder resource (or the other way around).
* The resource delta, which is actually expressed in terms of
* paths instead or resources, shows this as a change to either the
* content or children.
*
*
* @return the flags
* @see IResourceDelta#CONTENT
* @see IResourceDelta#DERIVED_CHANGED
* @see IResourceDelta#DESCRIPTION
* @see IResourceDelta#ENCODING
* @see IResourceDelta#LOCAL_CHANGED
* @see IResourceDelta#OPEN
* @see IResourceDelta#MOVED_TO
* @see IResourceDelta#MOVED_FROM
* @see IResourceDelta#COPIED_FROM
* @see IResourceDelta#TYPE
* @see IResourceDelta#SYNC
* @see IResourceDelta#MARKERS
* @see IResourceDelta#REPLACED
* @see #getKind()
* @see #getMovedFromPath()
* @see #getMovedToPath()
* @see IResource#move(IPath, int, IProgressMonitor)
*/
public int getFlags();
/**
* Returns the full, absolute path of this resource delta.
*
* Note: the returned path never has a trailing separator.
*
* @return the full, absolute path of this resource delta
* @see IResource#getFullPath()
* @see #getProjectRelativePath()
*/
public IPath getFullPath();
/**
* Returns the kind of this resource delta.
* Normally, one of ADDED,
* REMOVED, CHANGED.
* When phantom resources have been explicitly requested,
* there are two additional kinds: ADDED_PHANTOM
* and REMOVED_PHANTOM.
*
* @return the kind of this resource delta
* @see IResourceDelta#ADDED
* @see IResourceDelta#REMOVED
* @see IResourceDelta#CHANGED
* @see IResourceDelta#ADDED_PHANTOM
* @see IResourceDelta#REMOVED_PHANTOM
*/
public int getKind();
/**
* Returns the changes to markers on the corresponding resource.
* Returns an empty array if no markers changed.
*
* @return the marker deltas
*/
public IMarkerDelta[] getMarkerDeltas();
/**
* Returns the full path (in the "before" state) from which this resource
* (in the "after" state) was moved. This value is only valid
* if the MOVED_FROM change flag is set; otherwise,
* null is returned.
*
* Note: the returned path never has a trailing separator.
*
* @return a path, or null
* @see #getMovedToPath()
* @see #getFullPath()
* @see #getFlags()
*/
public IPath getMovedFromPath();
/**
* Returns the full path (in the "after" state) to which this resource
* (in the "before" state) was moved. This value is only valid if the
* MOVED_TO change flag is set; otherwise,
* null is returned.
*
* Note: the returned path never has a trailing separator.
*
* @return a path, or null
* @see #getMovedFromPath()
* @see #getFullPath()
* @see #getFlags()
*/
public IPath getMovedToPath();
/**
* Returns the project-relative path of this resource delta.
* Returns the empty path for projects and the workspace root.
*
* A resource's project-relative path indicates the route from the project
* to the resource. Within a workspace, there is exactly one such path
* for any given resource. The returned path never has a trailing separator.
*
* @return the project-relative path of this resource delta
* @see IResource#getProjectRelativePath()
* @see #getFullPath()
* @see Path#EMPTY
*/
public IPath getProjectRelativePath();
/**
* Returns a handle for the affected resource.
*
* For additions (ADDED), this handle describes the newly-added resource; i.e.,
* the one in the "after" state.
*
* For changes (CHANGED), this handle also describes the resource in the "after"
* state. When a file or folder resource has changed type, the
* former type of the handle can be inferred.
*
* For removals (REMOVED), this handle describes the resource in the "before"
* state. Even though this resource would not normally exist in the
* current workspace, the type of resource that was removed can be
* determined from the handle.
*
* For phantom additions and removals (ADDED_PHANTOM
* and REMOVED_PHANTOM), this is the handle of the phantom resource.
*
* @return the affected resource (handle)
*/
public IResource getResource();
}