All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.core.resources.IResourceDelta Maven / Gradle / Ivy

Go to download 

/*******************************************************************************
 * Copyright (c) 2000, 2009 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.core.resources;

import org.eclipse.core.internal.watson.IElementComparator;
import org.eclipse.core.resources.mapping.IResourceChangeDescriptionFactory;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.Platform;

/**
 * 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()
	 */
	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()
	 */
	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()
	 */
	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()
	 */
	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()
	 */
	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()
	 */
	int REMOVED_PHANTOM = 0x10;

	/**
	 * The bit mask which describes all possible delta kinds,
	 * including ones involving phantoms.
	 *
	 * @see IResourceDelta#getKind()
	 */
	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()
	 */
	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()
	 */
	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()
	 */
	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
	 */
	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()
	 */
	int OPEN = 0x4000;

	/**
	 * Change constant (bit mask) indicating that the type of the resource has changed.
	 *
	 * @see IResourceDelta#getFlags()
	 */
	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()
	 */
	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()
	 */
	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()
	 */
	int REPLACED = 0x40000;

	/**
	 * Change constant (bit mask) indicating that a project's description has changed.
	 *
	 * @see IResourceDelta#getFlags()
	 */
	int DESCRIPTION = 0x80000;

	/**
	 * Change constant (bit mask) indicating that the encoding of the resource has changed.
	 *
	 * @see IResourceDelta#getFlags()
	 * @since 3.0
	 */
	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
	 */
	int LOCAL_CHANGED = 0x200000;

	/**
	 * Change constant (bit mask) indicating that the derived flag of the resource has changed.
	 *
	 * @see IResourceDelta#getFlags()
	 * @since 3.6
	 */
	int DERIVED_CHANGED = 0x400000;

	/**
	 * Change constant (bit mask) indicating that the content of the resource is
	 * proposed to be deleted. This flag can only be found in deltas created by
	 * {@link IResourceChangeDescriptionFactory} and indicates that the underlined
	 * file object is proposed to be deleted from the file system (as opposite to
	 * the change where only workspace model is deleted).
	 *
	 * @see IResourceChangeDescriptionFactory
	 * @see IResourceDelta#getFlags()
	 * @since 3.16
	 */
	int DELETE_CONTENT_PROPOSED = 0x800000;

	/**
	 * 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)
	 */
	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)
	 */
	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
	 */
	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
	 */
	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)
	 */
	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)
	 */
	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
	 */
	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)
	 */
	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()
	 */
	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
	 */
	int getKind();

	/**
	 * Returns the changes to markers on the corresponding resource.
	 * Returns an empty array if no markers changed.
	 *
	 * @return the marker deltas
	 */
	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()
	 */
	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()
	 */
	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 IPath#EMPTY
	 */
	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)
	 */
	IResource getResource();
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy