/*******************************************************************************
* Copyright (c) 2000, 2008 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.IStatus;
/**
* Provides internal access to the workspace resource tree for the purposes of implementing the move
* and delete operations. Implementations of <code>IMoveDeleteHook</code> call these methods.
*
* @since 2.0
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IResourceTree {
/**
* Constant indicating that no file timestamp was supplied.
*
* @see #movedFile(IFile, IFile)
*/
public static final long NULL_TIMESTAMP= 0L;
/**
* Adds the current state of the given file to the local history. Does nothing if the file does
* not exist in the workspace resource tree, or if it exists in the workspace resource tree but
* not in the local file system.
* <p>
* This method is used to capture the state of a file in the workspace local history before it
* is overwritten or deleted.
* </p>
*
* @param file the file to be captured
*/
public void addToLocalHistory(IFile file);
/**
* Returns whether the given resource and its descendents to the given depth are considered to
* be in sync with the local file system. Returns <code>false</code> if the given resource does
* not exist in the workspace resource tree, but exists in the local file system; and
* conversely.
*
* @param resource the resource of interest
* @param depth the depth (one of <code>IResource.DEPTH_ZERO</code>, <code>DEPTH_ONE</code>, or
* <code>DEPTH_INFINITE</code>)
* @return <code>true</code> if the resource is synchronized, and <code>false</code> in all
* other cases
*/
public boolean isSynchronized(IResource resource, int depth);
/**
* Computes the timestamp for the given file in the local file system. Returns
* <code>NULL_TIMESTAMP</code> if the timestamp of the file in the local file system cannot be
* determined. The file need not exist in the workspace resource tree; however, if the file's
* project does not exist in the workspace resource tree, this method returns
* <code>NULL_TIMESTAMP</code> because the project's local content area is indeterminate.
* <p>
* Note that the timestamps used for workspace resource tree file synchronization are not
* necessarily interchangeable with <code>java.io.File</code> last modification time.The ones
* computed by <code>computeTimestamp</code> may have a higher resolution in some operating
* environments.
* </p>
*
* @param file the file of interest
* @return the local file system timestamp for the file, or <code>NULL_TIMESTAMP</code> if it
* could not be computed
*/
public long computeTimestamp(IFile file);
/**
* Returns the timestamp for the given file as recorded in the workspace resource tree. Returns
* <code>NULL_TIMESTAMP</code> if the given file does not exist in the workspace resource tree,
* or if the timestamp is not known.
* <p>
* Note that the timestamps used for workspace resource tree file synchronization are not
* necessarily interchangeable with <code>java.io.File</code> last modification time.The ones
* computed by <code>computeTimestamp</code> may have a higher resolution in some operating
* environments.
* </p>
*
* @param file the file of interest
* @return the workspace resource tree timestamp for the file, or <code>NULL_TIMESTAMP</code> if
* the file does not exist in the workspace resource tree, or if the timestamp is not
* known
*/
public long getTimestamp(IFile file);
/**
* Updates the timestamp for the given file in the workspace resource tree. The file is the
* local file system is not affected. Does nothing if the given file does not exist in the
* workspace resource tree.
* <p>
* The given timestamp should be that of the corresponding file in the local file system (as
* computed by <code>computeTimestamp</code>). A discrepancy between the timestamp of the file
* in the local file system and the timestamp recorded in the workspace resource tree means that
* the file is out of sync (<code>isSynchronized</code> returns <code>false</code>).
* </p>
* <p>
* This operation should be used after <code>movedFile/Folder/Project</code> to correct the
* workspace resource tree record when file timestamps change in the course of a move operation.
* </p>
* <p>
* Note that the timestamps used for workspace resource tree file synchronization are not
* necessarily interchangeable with <code>java.io.File</code> last modification time.The ones
* computed by <code>computeTimestamp</code> may have a higher resolution in some operating
* environments.
* </p>
*
* @param file the file of interest
* @param timestamp the local file system timestamp for the file, or <code>NULL_TIMESTAMP</code>
* if unknown
* @see #computeTimestamp(IFile)
*/
public void updateMovedFileTimestamp(IFile file, long timestamp);
/**
* Declares that the operation has failed for the specified reason. This method may be called
* multiple times to report multiple failures. All reasons will be accumulated and taken into
* consideration when deciding the outcome of the hooked operation as a whole.
*
* @param reason the reason the operation (or sub-operation) failed
*/
public void failed(IStatus reason);
/**
* Declares that the given file has been successfully deleted from the local file system, and
* requests that the corresponding deletion should now be made to the workspace resource tree.
* No action is taken if the given file does not exist in the workspace resource tree.
* <p>
* This method clears out any markers, session properties, and persistent properties associated
* with the given file.
* </p>
*
* @param file the file that was just deleted from the local file system
*/
public void deletedFile(IFile file);
/**
* Declares that the given folder and all its descendents have been successfully deleted from
* the local file system, and requests that the corresponding deletion should now be made to the
* workspace resource tree. No action is taken if the given folder does not exist in the
* workspace resource tree.
* <p>
* This method clears out any markers, session properties, and persistent properties associated
* with the given folder or its descendents.
* </p>
*
* @param folder the folder that was just deleted from the local file system
*/
public void deletedFolder(IFolder folder);
/**
* Declares that the given project's content area in the local file system has been successfully
* dealt with in an appropriate manner, and requests that the corresponding deletion should now
* be made to the workspace resource tree. No action is taken if the given project does not
* exist in the workspace resource tree.
* <p>
* This method clears out everything associated with this project and any of its descendent
* resources, including: markers; session properties; persistent properties; local history; and
* project-specific plug-ins working data areas. The project's content area is not affected.
* </p>
*
* @param project the project being deleted
*/
public void deletedProject(IProject project);
/**
* Declares that the given source file has been successfully moved to the given destination in
* the local file system, and requests that the corresponding changes should now be made to the
* workspace resource tree. No action is taken if the given source file does not exist in the
* workspace resource tree.
* <p>
* The destination file must not already exist in the workspace resource tree.
* </p>
* <p>
* This operation carries over the file timestamp unchanged. Use
* <code>updateMovedFileTimestamp</code> to update the timestamp of the file if its timestamp
* changed as a direct consequence of the move.
* </p>
*
* @param source the handle of the source file that was moved
* @param destination the handle of where the file moved to
* @see #computeTimestamp(IFile)
*/
public void movedFile(IFile source, IFile destination);
/**
* Declares that the given source folder and its descendents have been successfully moved to the
* given destination in the local file system, and requests that the corresponding changes
* should now be made to the workspace resource tree for the folder and all its descendents. No
* action is taken if the given source folder does not exist in the workspace resource tree.
* <p>
* This operation carries over file timestamps unchanged. Use
* <code>updateMovedFileTimestamp</code> to update the timestamp of files whose timestamps
* changed as a direct consequence of the move.
* </p>
* <p>
* The destination folder must not already exist in the workspace resource tree.
* </p>
*
* @param source the handle of the source folder that was moved
* @param destination the handle of where the folder moved to
*/
public void movedFolderSubtree(IFolder source, IFolder destination);
/**
* Declares that the given source project and its files and folders have been successfully
* relocated in the local file system if required, and requests that the rename and/or
* relocation should now be made to the workspace resource tree for the project and all its
* descendents. No action is taken if the given project does not exist in the workspace resource
* tree.
* <p>
* This operation carries over file timestamps unchanged. Use
* <code>updateMovedFileTimestamp</code> to update the timestamp of files whose timestamps
* changed as a direct consequence of the move.
* </p>
* <p>
* If the project is being renamed, the destination project must not already exist in the
* workspace resource tree.
* </p>
* <p>
* Local history is not preserved if the project is renamed. It is preserved when the project's
* content area is relocated without renaming the project.
* </p>
*
* @param source the handle of the source project that was moved
* @param description the new project description
* @return <code>true</code> if the move succeeded, and <code>false</code> otherwise
*/
public boolean movedProjectSubtree(IProject source, IProjectDescription description);
/**
* Deletes the given file in the standard manner from both the local file system and from the
* workspace resource tree.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>file.delete(updateFlags, monitor)</code> because all regular API operations that modify
* resources are off limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param file the file to delete
* @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>
*/
public void standardDeleteFile(IFile file, int updateFlags, IProgressMonitor monitor);
/**
* Deletes the given folder and its descendents in the standard manner from both the local file
* system and from the workspace resource tree.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>folder.delete(updateFlags, monitor)</code> because all regular API operations that
* modify resources are off limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param folder the folder to delete
* @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>
*/
public void standardDeleteFolder(IFolder folder, int updateFlags, IProgressMonitor monitor);
/**
* Deletes the given project and its descendents in the standard manner from both the local file
* system and from the workspace resource tree.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>project.delete(updateFlags, monitor)</code> because all regular API operations that
* modify resources are off limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param project the project to delete
* @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>
*/
public void standardDeleteProject(IProject project, int updateFlags, IProgressMonitor monitor);
/**
* Moves the given file in the standard manner from both the local file system and from the
* workspace resource tree.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>source.move(destination.getProjectRelativePath(),
* updateFlags, monitor)</code> because all regular API operations that modify resources are off
* limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param source the handle of the source file to move
* @param destination the handle of where the file will move to
* @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>
*/
public void standardMoveFile(IFile source, IFile destination, int updateFlags, IProgressMonitor monitor);
/**
* Moves the given folder and its descendents in the standard manner from both the local file
* system and from the workspace resource tree.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>source.move(destination.getProjectRelativePath(),
* updateFlags, monitor)</code> because all regular API operations that modify resources are off
* limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param source the handle of the source folder to move
* @param destination the handle of where the folder will move to
* @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>
*/
public void standardMoveFolder(IFolder source, IFolder destination, int updateFlags, IProgressMonitor monitor);
/**
* Renames and/or relocates the given project in the standard manner.
* <p>
* Implementations of <code>IMoveDeleteHook</code> must invoke this method in lieu of
* <code>source.move(description, updateFlags, monitor)</code> because all regular API
* operations that modify resources are off limits.
* </p>
* <p>
* If the operation fails, the reason for the failure is automatically collected by an internal
* call to <code>failed</code>.
* </p>
*
* @param source the handle of the source folder to move
* @param description the new project description
* @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>
*/
public void standardMoveProject(IProject source, IProjectDescription description, int updateFlags, IProgressMonitor monitor);
}