IResourceTree


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.resources.team;
12  
13  import org.eclipse.core.resources.*;
14  import org.eclipse.core.runtime.IProgressMonitor;
15  import org.eclipse.core.runtime.IStatus;
16  
17  /**
18   * Provides internal access to the workspace resource tree for the purposes of
19   * implementing the move and delete operations. Implementations of 
20   * <code>IMoveDeleteHook</code> call these methods.
21   * <p>
22   * This interface is not intended to be implemented by clients.
23   * </p>
24   * 
25   * @since 2.0
26   */
27  public interface IResourceTree {
28  
29      /**
30       * Constant indicating that no file timestamp was supplied.
31       * 
32       * @see #movedFile(IFile, IFile)
33       */
34      public static final long NULL_TIMESTAMP = 0L;
35  
36      /**
37       * Adds the current state of the given file to the local history.
38       * Does nothing if the file does not exist in the workspace resource tree,
39       * or if it exists in the workspace resource tree but not in the local file
40       * system.
41       * <p>
42       * This method is used to capture the state of a file in the workspace
43       * local history before it is overwritten or deleted.
44       * </p>
45       * 
46       * @param file the file to be captured
47       */
48      public void addToLocalHistory(IFile file);
49  
50      /**
51       * Returns whether the given resource and its descendents to the given depth 
52       * are considered to be in sync with the local file system. Returns 
53       * <code>false</code> if the given resource does not exist in the workspace
54       * resource tree, but exists in the local file system; and conversely.
55       * 
56       * @param resource the resource of interest
57       * @param depth the depth (one of <code>IResource.DEPTH_ZERO</code>,
58       *   <code>DEPTH_ONE</code>, or <code>DEPTH_INFINITE</code>)
59       * @return <code>true</code> if the resource is synchronized, and
60       *    <code>false</code> in all other cases
61       */
62      public boolean isSynchronized(IResource resource, int depth);
63  
64      /**
65       * Computes the timestamp for the given file in the local file system.
66       * Returns <code>NULL_TIMESTAMP</code> if the timestamp of the file in
67       * the local file system cannot be determined. The file need not exist in
68       * the workspace resource tree; however, if the file's project does not
69       * exist in the workspace resource tree, this method returns
70       * <code>NULL_TIMESTAMP</code> because the project's local content area
71       * is indeterminate.
72       * <p>
73       * Note that the timestamps used for workspace resource tree file 
74       * synchronization are not necessarily interchangeable with 
75       * <code>java.io.File</code> last modification time.The ones computed by
76       * <code>computeTimestamp</code> may have a higher resolution in some
77       * operating environments.
78       * </p>
79       * 
80       * @param file the file of interest
81       * @return the local file system timestamp for the file, or 
82       *    <code>NULL_TIMESTAMP</code> if it could not be computed
83       */
84      public long computeTimestamp(IFile file);
85  
86      /**
87       * Returns the timestamp for the given file as recorded in the workspace
88       * resource tree. Returns <code>NULL_TIMESTAMP</code> if the given file
89       * does not exist in the workspace resource tree, or if the timestamp is
90       * not known.
91       * <p>
92       * Note that the timestamps used for workspace resource tree file 
93       * synchronization are not necessarily interchangeable with 
94       * <code>java.io.File</code> last modification time.The ones computed by
95       * <code>computeTimestamp</code> may have a higher resolution in some
96       * operating environments.
97       * </p>
98       * 
99       * @param file the file of interest
100      * @return the workspace resource tree timestamp for the file, or 
101      *    <code>NULL_TIMESTAMP</code> if the file does not exist in the 
102      *    workspace resource tree, or if the timestamp is not known
103      */
104     public long getTimestamp(IFile file);
105 
106     /**
107      * Updates the timestamp for the given file in the workspace resource tree.
108      * The file is the local file system is not affected. Does nothing if the
109      * given file does not exist in the workspace resource tree.
110      * <p>
111      * The given timestamp should be that of the corresponding file in the local
112      * file system (as computed by <code>computeTimestamp</code>). A discrepancy
113      * between the timestamp of the file in the local file system and the
114      * timestamp recorded in the workspace resource tree means that the file is
115      * out of sync (<code>isSynchronized</code> returns <code>false</code>).
116      * </p>
117      * <p>
118      * This operation should be used after <code>movedFile/Folder/Project</code>
119      * to correct the workspace resource tree record when file timestamps change
120      * in the course of a move operation.
121      * </p>
122      * <p>
123      * Note that the timestamps used for workspace resource tree file 
124      * synchronization are not necessarily interchangeable with 
125      * <code>java.io.File</code> last modification time.The ones computed by
126      * <code>computeTimestamp</code> may have a higher resolution in some
127      * operating environments.
128      * </p>
129      * 
130      * @param file the file of interest
131      * @param timestamp the local file system timestamp for the file, or 
132      *    <code>NULL_TIMESTAMP</code> if unknown
133      * @see #computeTimestamp(IFile)
134      */
135     public void updateMovedFileTimestamp(IFile file, long timestamp);
136 
137     /**
138      * Declares that the operation has failed for the specified reason.
139      * This method may be called multiple times to report multiple
140      * failures. All reasons will be accumulated and taken into consideration
141      * when deciding the outcome of the hooked operation as a whole.
142      * 
143      * @param reason the reason the operation (or sub-operation) failed
144      */
145     public void failed(IStatus reason);
146 
147     /**
148      * Declares that the given file has been successfully deleted from the
149      * local file system, and requests that the corresponding deletion should
150      * now be made to the workspace resource tree. No action is taken if the
151      * given file does not exist in the workspace resource tree.
152      * <p>
153      * This method clears out any markers, session properties, and persistent
154      * properties associated with the given file.
155      * </p>
156      * 
157      * @param file the file that was just deleted from the local file system
158      */
159     public void deletedFile(IFile file);
160 
161     /**
162      * Declares that the given folder and all its descendents have been 
163      * successfully deleted from the local file system, and requests that the
164      * corresponding deletion should now be made to the workspace resource tree.
165      * No action is taken if the given folder does not exist in the workspace
166      * resource tree.
167      * <p>
168      * This method clears out any markers, session properties, and persistent
169      * properties associated with the given folder or its descendents.
170      * </p>
171      * 
172      * @param folder the folder that was just deleted from the local file system
173      */
174     public void deletedFolder(IFolder folder);
175 
176     /**
177      * Declares that the given project's content area in the local file system
178      * has been successfully dealt with in an appropriate manner, and requests 
179      * that the corresponding deletion should now be made to the workspace 
180      * resource tree. No action is taken if the given project does not exist in
181      * the workspace resource tree.
182      * <p>
183      * This method clears out everything associated with this project and any of 
184      * its descendent resources, including: markers; session properties; 
185      * persistent properties; local history; and project-specific plug-ins 
186      * working data areas. The project's content area is not affected.
187      * </p>
188      * 
189      * @param project the project being deleted
190      */
191     public void deletedProject(IProject project);
192 
193     /**
194      * Declares that the given source file has been successfully moved to the
195      * given destination in the local file system, and requests that the
196      * corresponding changes should now be made to the workspace resource tree.
197      * No action is taken if the given source file does not exist in the 
198      * workspace resource tree.
199      * <p>
200      * The destination file must not already exist in the workspace resource
201      * tree.
202      * </p><p>
203      * This operation carries over the file timestamp unchanged. Use 
204      * <code>updateMovedFileTimestamp</code> to update the timestamp 
205      * of the file if its timestamp changed as a direct consequence of the move.
206      * </p>
207      * 
208      * @param source the handle of the source file that was moved
209      * @param destination the handle of where the file moved to
210      * @see #computeTimestamp(IFile)
211      */
212     public void movedFile(IFile source, IFile destination);
213 
214     /**
215      * Declares that the given source folder and its descendents have been
216      * successfully moved to the given destination in the local file system,
217      * and requests that the corresponding changes should now be made to the
218      * workspace resource tree for the folder and all its descendents. No action
219      * is taken if the given source folder does not exist in the workspace
220      * resource tree.
221      * <p>
222      * This operation carries over file timestamps unchanged. Use 
223      * <code>updateMovedFileTimestamp</code> to update the timestamp of files
224      * whose timestamps changed as a direct consequence of the move.
225      * </p><p>
226      * The destination folder must not already exist in the workspace resource
227      * tree.
228      * </p>
229      * 
230      * @param source the handle of the source folder that was moved
231      * @param destination the handle of where the folder moved to
232      */
233     public void movedFolderSubtree(IFolder source, IFolder destination);
234 
235     /**
236      * Declares that the given source project and its files and folders have 
237      * been successfully relocated in the local file system if required, and
238      * requests that the rename and/or relocation should now be made to the
239      * workspace resource tree for the project and all its descendents. No
240      * action is taken if the given project does not exist in the workspace
241      * resource tree.
242      * <p>
243      * This operation carries over file timestamps unchanged. Use 
244      * <code>updateMovedFileTimestamp</code> to update the timestamp of files whose 
245      * timestamps changed as a direct consequence of the move.
246      * </p><p>
247      * If the project is being renamed, the destination project must not
248      * already exist in the workspace resource tree.
249      * </p><p>
250      * Local history is not preserved if the project is renamed. It is preserved
251      * when the project's content area is relocated without renaming the
252      * project.
253      * </p>
254      * 
255      * @param source the handle of the source project that was moved
256      * @param description the new project description
257      * @return <code>true</code> if the move succeeded, and <code>false</code>
258      *    otherwise
259      */
260     public boolean movedProjectSubtree(IProject source, IProjectDescription description);
261 
262     /**
263      * Deletes the given file in the standard manner from both the local file 
264      * system and from the workspace resource tree.
265      * <p>
266      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
267      * in lieu of  <code>file.delete(updateFlags, monitor)</code> because all
268      * regular API operations that modify resources are off limits.
269      * </p><p>
270      * If the operation fails, the reason for the failure is automatically
271      * collected by an internal call to <code>failed</code>.
272      * </p>
273      * 
274      * @param file the file to delete
275      * @param updateFlags bit-wise or of update flag constants as per 
276      *    <code>IResource.delete(int,IProgressMonitor)</code>
277      * @param monitor the progress monitor, or <code>null</code> as per 
278      *    <code>IResource.delete(int,IProgressMonitor)</code>
279      */
280     public void standardDeleteFile(IFile file, int updateFlags, IProgressMonitor monitor);
281 
282     /**
283      * Deletes the given folder and its descendents in the standard manner from
284      * both the local file system and from  the workspace resource tree.
285      * <p>
286      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
287      * in lieu of  <code>folder.delete(updateFlags, monitor)</code> because all
288      * regular API operations that modify resources are off limits.
289      * </p><p>
290      * If the operation fails, the reason for the failure is automatically
291      * collected by an internal call to <code>failed</code>.
292      * </p>
293      * 
294      * @param folder the folder to delete
295      * @param updateFlags bit-wise or of update flag constants as per 
296      *    <code>IResource.delete(int,IProgressMonitor)</code>
297      * @param monitor the progress monitor, or <code>null</code> as per 
298      *    <code>IResource.delete(int,IProgressMonitor)</code>
299      */
300     public void standardDeleteFolder(IFolder folder, int updateFlags, IProgressMonitor monitor);
301 
302     /**
303      * Deletes the given project and its descendents in the standard manner from
304      * both the local file system and from the workspace resource tree.
305      * <p>
306      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
307      * in lieu of  <code>project.delete(updateFlags, monitor)</code> because all
308      * regular API operations that modify resources are off limits.
309      * </p><p>
310      * If the operation fails, the reason for the failure is automatically 
311      * collected by an internal call to <code>failed</code>.
312      * </p>
313      * 
314      * @param project the project to delete
315      * @param updateFlags bit-wise or of update flag constants as per 
316      *    <code>IResource.delete(int,IProgressMonitor)</code>
317      * @param monitor the progress monitor, or <code>null</code> as per 
318      *    <code>IResource.delete(int,IProgressMonitor)</code>
319      */
320     public void standardDeleteProject(IProject project, int updateFlags, IProgressMonitor monitor);
321 
322     /**
323      * Moves the given file in the standard manner from both the local file 
324      * system and from the workspace resource tree.
325      * <p>
326      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
327      * in lieu of <code>source.move(destination.getProjectRelativePath(),
328      * updateFlags, monitor)</code> because all regular API  operations that
329      * modify resources are off limits.
330      * </p><p>
331      * If the operation fails, the reason for the failure is automatically 
332      * collected by an internal call to <code>failed</code>.
333      * </p>
334      * 
335      * @param source the handle of the source file to move
336      * @param destination the handle of where the file will move to
337      * @param updateFlags bit-wise or of update flag constants as per 
338      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
339      * @param monitor the progress monitor, or <code>null</code> as per 
340      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
341      */
342     public void standardMoveFile(IFile source, IFile destination, int updateFlags, IProgressMonitor monitor);
343 
344     /**
345      * Moves the given folder and its descendents in the standard manner from
346      * both the local file system and from the workspace resource tree.
347      * <p>
348      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
349      * in lieu of <code>source.move(destination.getProjectRelativePath(),
350      * updateFlags, monitor)</code> because all regular API  operations that
351      * modify resources are off limits.
352      * </p><p>
353      * If the operation fails, the reason for the failure is automatically
354      * collected by an internal call to <code>failed</code>.
355      * </p>
356      * 
357      * @param source the handle of the source folder to move
358      * @param destination the handle of where the folder will move to
359      * @param updateFlags bit-wise or of update flag constants as per 
360      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
361      * @param monitor the progress monitor, or <code>null</code> as per 
362      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
363      */
364     public void standardMoveFolder(IFolder source, IFolder destination, int updateFlags, IProgressMonitor monitor);
365 
366     /**
367      * Renames and/or relocates the given project in the standard manner.
368      * <p>
369      * Implementations of <code>IMoveDeleteHook</code> must invoke this method
370      * in lieu of <code>source.move(description, updateFlags, monitor)</code>
371      * because all regular API  operations that modify resources are off limits.
372      * </p><p>
373      * If the operation fails, the reason for the failure is automatically
374      * collected by an internal call to <code>failed</code>.
375      * </p>
376      * 
377      * @param source the handle of the source folder to move
378      * @param description the new project description
379      * @param updateFlags bit-wise or of update flag constants as per 
380      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
381      * @param monitor the progress monitor, or <code>null</code> as per 
382      *    <code>IResource.move(IPath,int,IProgressMonitor)</code>
383      */
384     public void standardMoveProject(IProject source, IProjectDescription description, int updateFlags, IProgressMonitor monitor);
385 }
386
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags