/*******************************************************************************
* 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.team;
import org.eclipse.core.resources.*;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.OperationCanceledException;
/**
* Primary interface for hooking the implementation of <code>IResource.move</code> and
* <code>IResource.delete</code>.
* <p>
* This interface is intended to be implemented by the team component in conjunction with the
* <code>org.eclipse.core.resources.moveDeleteHook</code> standard extension point. Individual team
* providers may also implement this interface. It is not intended to be implemented by other
* clients. The methods defined on this interface are called from within the implementations of
* <code>IResource.move</code> and <code>IResource.delete</code>. They are not intended to be called
* from anywhere else.
* </p>
*
* @since 2.0
*/
public interface IMoveDeleteHook {
/**
* Implements <code>IResource.delete(int,IProgressMonitor)</code> where the receiver is a file.
* Returns <code>true</code> to accept responsibility for implementing this operation as per the
* API contract.
* <p>
* In broad terms, a full re-implementation should delete the file in the local file system and
* then call <code>tree.deletedFile</code> to complete the updating of the workspace resource
* tree to reflect this fact. If unsuccessful in deleting the file from the local file system,
* it should instead call <code>tree.failed</code> to report the reason for the failure. In
* either case, it should return <code>true</code> to indicate that the operation was attempted.
* The <code>FORCE</code> update flag needs to be honored: unless <code>FORCE</code> is
* specified, the implementation must use <code>tree.isSynchronized</code> to determine whether
* the file is in sync before attempting to delete it. The <code>KEEP_HISTORY</code> update flag
* needs to be honored as well; use <code>tree.addToLocalHistory</code> to capture the contents
* of the file before deleting it from the local file system.
* </p>
* <p>
* An extending implementation should perform whatever pre-processing it needs to do and then
* call <code>tree.standardDeleteFile</code> to explicitly invoke the standard file deletion
* behavior, which deletes both the file from the local file system and updates the workspace
* resource tree. It should return <code>true</code> to indicate that the operation was
* attempted.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardDeleteFile</code> and returning <code>true</code>.
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param file the handle of the file to delete; the receiver of
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#delete(int,IProgressMonitor)
*/
public boolean deleteFile(IResourceTree tree, IFile file, int updateFlags, IProgressMonitor monitor);
/**
* Implements <code>IResource.delete(int,IProgressMonitor)</code> where the receiver is a
* folder. Returns <code>true</code> to accept responsibility for implementing this operation as
* per the API contract.
* <p>
* In broad terms, a full re-implementation should delete the directory tree in the local file
* system and then call <code>tree.deletedFolder</code> to complete the updating of the
* workspace resource tree to reflect this fact. If unsuccessful in deleting the directory or
* any of its descendents from the local file system, it should instead call
* <code>tree.failed</code> to report each reason for failure. In either case it should return
* <code>true</code> to indicate that the operation was attempted. The <code>FORCE</code> update
* flag needs to be honored: unless <code>FORCE</code> is specified, the implementation must use
* <code>tree.isSynchronized</code> to determine whether the folder subtree is in sync before
* attempting to delete it. The <code>KEEP_HISTORY</code> update flag needs to be honored as
* well; use <code>tree.addToLocalHistory</code> to capture the contents of any files being
* deleted.
* </p>
* <p>
* A partial re-implementation should perform whatever pre-processing it needs to do and then
* call <code>tree.standardDeleteFolder</code> to explicitly invoke the standard folder deletion
* behavior, which deletes both the folder and its descendents from the local file system and
* updates the workspace resource tree. It should return <code>true</code> to indicate that the
* operation was attempted.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardDeleteFolder</code> and returning <code>true</code>.
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param folder the handle of the folder to delete; the receiver of
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#delete(int,IProgressMonitor)
*/
public boolean deleteFolder(IResourceTree tree, IFolder folder, int updateFlags, IProgressMonitor monitor);
/**
* Implements <code>IResource.delete(int,IProgressMonitor)</code> where the receiver is a
* project. Returns <code>true</code> to accept responsibility for implementing this operation
* as per the API contract.
* <p>
* In broad terms, a full re-implementation should delete the project content area in the local
* file system if required (the files of a closed project should be deleted only if the
* <code>IResource.ALWAYS_DELETE_PROJECT_CONTENTS</code> update flag is specified; the files of
* an open project should be deleted unless the the
* <code>IResource.NEVER_DELETE_PROJECT_CONTENTS</code> update flag is specified). It should
* then call <code>tree.deletedProject</code> to complete the updating of the workspace resource
* tree to reflect this fact. If unsuccessful in deleting the project's files from the local
* file system, it should instead call <code>tree.failed</code> to report the reason for the
* failure. In either case, it should return <code>true</code> to indicate that the operation
* was attempted. The <code>FORCE</code> update flag may need to be honored if the project is
* open: unless <code>FORCE</code> is specified, the implementation must use
* <code>tree.isSynchronized</code> to determine whether the project subtree is in sync before
* attempting to delete it. Note that local history is not maintained when a project is deleted,
* regardless of the setting of the <code>KEEP_HISTORY</code> update flag.
* </p>
* <p>
* A partial re-implementation should perform whatever pre-processing it needs to do and then
* call <code>tree.standardDeleteProject</code> to explicitly invoke the standard project
* deletion behavior. It should return <code>true</code> to indicate that the operation was
* attempted.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardDeleteProject</code> and returning <code>true</code>
* .
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param project the handle of the project to delete; the receiver of
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.delete(int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#delete(int,IProgressMonitor)
*/
public boolean deleteProject(IResourceTree tree, IProject project, int updateFlags, IProgressMonitor monitor);
/**
* Implements <code>IResource.move(IPath,int,IProgressMonitor)</code> where the receiver is a
* file. Returns <code>true</code> to accept responsibility for implementing this operation as
* per the API contract.
* <p>
* On entry to this hook method, the following is guaranteed about the workspace resource tree:
* the source file exists; the destination file does not exist; the container of the destination
* file exists and is accessible. In broad terms, a full re-implementation should move the file
* in the local file system and then call <code>tree.moveFile</code> to complete the updating of
* the workspace resource tree to reflect this fact. If unsuccessful in moving the file in the
* local file system, it should instead call <code>tree.failed</code> to report the reason for
* the failure. In either case, it should return <code>true</code> to indicate that the
* operation was attempted. The <code>FORCE</code> update flag needs to be honored: unless
* <code>FORCE</code> is specified, the implementation must use <code>tree.isSynchronized</code>
* to determine whether the file is in sync before attempting to move it. The
* <code>KEEP_HISTORY</code> update flag needs to be honored as well; use
* <code>tree.addToLocalHistory</code> to capture the contents of the file (naturally, this must
* be before moving the file from the local file system).
* </p>
* <p>
* An extending implementation should perform whatever pre-processing it needs to do and then
* call <code>tree.standardMoveFile</code> to explicitly invoke the standard file moving
* behavior, which moves both the file in the local file system and updates the workspace
* resource tree. It should return <code>true</code> to indicate that the operation was
* attempted.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardMoveFile</code> and returning <code>true</code>.
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param source the handle of the file to move; the receiver of
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param destination the handle of where the file will move to; the handle equivalent of the
* first parameter to <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#move(org.eclipse.core.runtime.IPath,int,IProgressMonitor)
*/
public boolean moveFile(IResourceTree tree, IFile source, IFile destination, int updateFlags, IProgressMonitor monitor);
/**
* Implements <code>IResource.move(IPath,int,IProgressMonitor)</code> where the receiver is a
* project. Returns <code>true</code> to accept responsibility for implementing this operation
* as per the API contract.
* <p>
* On entry to this hook method, the following is guaranteed about the workspace resource tree:
* the source folder exists; the destination folder does not exist; the container of the
* destination folder exists and is accessible. In broad terms, a full re-implementation should
* move the directory tree in the local file system and then call <code>tree.movedFolder</code>
* to complete the updating of the workspace resource tree to reflect this fact. If unsuccessful
* in moving the directory or any of its descendents in the local file system, call
* <code>tree.failed</code> to report each reason for failure. In either case, return
* <code>true</code> to indicate that the operation was attempted. The <code>FORCE</code> update
* flag needs to be honored: unless <code>FORCE</code> is specified, the implementation must use
* <code>tree.isSynchronized</code> to determine whether the folder subtree is in sync before
* attempting to move it. The <code>KEEP_HISTORY</code> update flag needs to be honored as well;
* use <code>tree.addToLocalHistory</code> to capture the contents of any files being moved.
* </p>
* <p>
* A partial re-implementation should perform whatever pre-processing it needs to do and then
* call <code>tree.standardMoveFolder</code> to explicitly invoke the standard folder move
* behavior, which move both the folder and its descendents in the local file system and updates
* the workspace resource tree. Return <code>true</code> to indicate that the operation was
* attempted.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardDeleteFolder</code> and returning <code>true</code>.
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param source the handle of the folder to move; the receiver of
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param destination the handle of where the folder will move to; the handle equivalent of the
* first parameter to <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#move(org.eclipse.core.runtime.IPath,int,IProgressMonitor)
*/
public boolean moveFolder(IResourceTree tree, IFolder source, IFolder destination, int updateFlags, IProgressMonitor monitor);
/**
* Implements <code>IResource.move(IPath,int,IProgressMonitor)</code> and
* <code>IResource.move(IProjectDescription,int,IProgressMonitor)</code> where the receiver is a
* project. Returns <code>true</code> to accept responsibility for implementing this operation
* as per the API contracts.
* <p>
* On entry to this hook method, the source project is guaranteed to exist and be open in the
* workspace resource tree. If the given description contains a different name from that of the
* given project, then the project is being renamed (and its content possibly relocated). If the
* given description contains the same name as the given project, then the project is being
* relocated but not renamed. When the project is being renamed, the destination project is
* guaranteed not to exist in the workspace resource tree.
* </p>
* <p>
* Returning <code>false</code> is the easy way for the implementation to say "pass". It is
* equivalent to calling <code>tree.standardMoveProject</code> and returning <code>true</code>.
* </p>
* <p>
* The implementation of this method runs "below" the resources API and is therefore very
* restricted in what resource API method it can call. The list of useable methods includes most
* resource operations that read but do not update the resource tree; resource operations that
* modify resources and trigger deltas must not be called from within the dynamic scope of the
* invocation of this method.
* </p>
*
* @param tree the workspace resource tree; this object is only valid for the duration of the
* invocation of this method, and must not be used after this method has completed
* @param source the handle of the open project to move; the receiver of
* <code>IResource.move(IProjectDescription,int,IProgressMonitor)</code> or
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param description the new description of the project; the first parameter to
* <code>IResource.move(IProjectDescription,int,IProgressMonitor)</code>, or a copy
* of the project's description with the location changed to the path given in the
* first parameter to <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param updateFlags bit-wise or of update flag constants as per
* <code>IResource.move(IProjectDescription,int,IProgressMonitor)</code> or
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @param monitor the progress monitor, or <code>null</code> as per
* <code>IResource.move(IProjectDescription,int,IProgressMonitor)</code> or
* <code>IResource.move(IPath,int,IProgressMonitor)</code>
* @return <code>false</code> if this method declined to assume responsibility for this
* operation, and <code>true</code> if this method attempted to carry out the operation
* @exception OperationCanceledException if the operation is canceled. Cancelation can occur
* even if no progress monitor is provided.
* @see IResource#move(org.eclipse.core.runtime.IPath,int,IProgressMonitor)
* @see IResource#move(IProjectDescription,int,IProgressMonitor)
*/
public boolean moveProject(IResourceTree tree, IProject source, IProjectDescription description, int updateFlags, IProgressMonitor monitor);
}