IWorkspaceRoot


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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;
12  
13  import java.net.URI  ;
14  import org.eclipse.core.runtime.*;
15  
16  /**
17   * A root resource represents the top of the resource hierarchy in a workspace.
18   * There is exactly one root in a workspace.  The root resource has the following
19   * behavior: 
20   * <ul>
21   * <li>It cannot be moved or copied </li>
22   * <li>It always exists.</li>
23   * <li>Deleting the root deletes all of the children under the root but leaves the root itself</li>
24   * <li>It is always local.</li>
25   * <li>It is never a phantom.</li>
26   * </ul>
27   * <p>
28   * This interface is not intended to be implemented by clients.
29   * </p>
30   * <p>
31   * Workspace roots implement the <code>IAdaptable</code> interface;
32   * extensions are managed by the platform's adapter manager.
33   * </p>
34   *
35   * @see Platform#getAdapterManager()
36   */
37  public interface IWorkspaceRoot extends IContainer, IAdaptable {
38  
39      /**
40       * Deletes everything in the workspace except the workspace root resource
41       * itself.
42       * <p>
43       * This is a convenience method, fully equivalent to:
44       * <pre>
45       *   delete(
46       *     (deleteContent ? IResource.ALWAYS_DELETE_PROJECT_CONTENT : IResource.NEVER_DELETE_PROJECT_CONTENT )
47       *        | (force ? FORCE : IResource.NONE),
48       *     monitor);
49       * </pre>
50       * </p>
51       * <p>
52       * This method changes resources; these changes will be reported
53       * in a subsequent resource change event.
54       * </p>
55       * <p>
56       * This method is long-running; progress and cancellation are provided
57       * by the given progress monitor.
58       * </p>
59       *
60       * @param deleteContent a flag controlling how whether content is
61       *    aggressively deleted
62       * @param force a flag controlling whether resources that are not
63       *    in sync with the local file system will be tolerated
64       * @param monitor a progress monitor, or <code>null</code> if progress
65       *    reporting is not desired
66       * @exception CoreException if this method fails. Reasons include:
67       * <ul>
68       * <li> A project could not be deleted.</li>
69       * <li> A project's contents could not be deleted.</li>
70       * <li> Resource changes are disallowed during certain types of resource change 
71       *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
72       * </ul>
73       * @exception OperationCanceledException if the operation is canceled. 
74       * Cancelation can occur even if no progress monitor is provided.
75       * @see IResource#delete(int,IProgressMonitor)
76       */
77      public void delete(boolean deleteContent, boolean force, IProgressMonitor monitor) throws CoreException;
78  
79      /**
80       * Returns the handles to all the resources (workspace root, project, folder) in
81       * the workspace which are mapped to the given path in the local file system.
82       * Returns an empty array if there are none.
83       * <p>
84       * If the path maps to the platform working location, the returned object will
85       * be a single element array consisting of an object of type <code>ROOT</code>.
86       * <p>
87       *  If the path maps to a project, the resulting array will contain a resource of 
88       *  type <code>PROJECT</code>, along with any linked folders that share the
89       *  same location.  Otherwise the resulting array will contain folders (type
90       * <code>FOLDER</code>). 
91       * <p>
92       * The path should be absolute; a relative path will be treated as
93       * absolute.  The path segments need not be valid names; a
94       * trailing separator is ignored. The resulting resources may not currently exist.
95       * <p>
96       * @param location a path in the local file system
97       * @return the corresponding containers in the workspace, or an empty array if none
98       * @since 2.1
99       */
100     public IContainer[] findContainersForLocation(IPath location);
101 
102     /**
103      * Returns the handles to all the resources (workspace root, project, folder) in
104      * the workspace which are mapped to the given URI. Returns an empty array 
105      * if there are none.
106      * <p>
107      * If the path maps to the platform working location, the returned object will
108      * be a single element array consisting of an object of type <code>ROOT</code>.
109      * <p>
110      *  If the path maps to a project, the resulting array will contain a resource of 
111      *  type <code>PROJECT</code>, along with any linked folders that share the
112      *  same location.  Otherwise the resulting array will contain folders (type
113      * <code>FOLDER</code>). 
114      * <p>
115      * The URI must be absolute; its segments need not be valid names; a
116      * trailing separator is ignored. The resulting resources may not currently exist.
117      * <p>
118      * @param location a URI path into some file system
119      * @return the corresponding containers in the workspace, or an empty array if none
120      * @since 3.2
121      */
122     public IContainer[] findContainersForLocationURI(URI   location);
123 
124     /**
125      * Returns the handles of all files that are mapped to the given path 
126      * in the local file system.  Returns an empty array if there are none.
127      * The path should be absolute; a relative path will be treated as
128      * absolute.  The path segments need not be valid names.
129      * The resulting files may not currently exist.
130      * <p>
131      * @param location a path in the local file system
132      * @return the corresponding files in the workspace, or an empty array if none
133      * @since 2.1
134      */
135     public IFile[] findFilesForLocation(IPath location);
136 
137     /**
138      * Returns the handles of all files that are mapped to the given URI.
139      * Returns an empty array if there are none.
140      * The URI must be absolute; its path segments need not be valid names.
141      * The resulting files may not currently exist.
142      * <p>
143      * @param location a URI path into some file system
144      * @return the corresponding files in the workspace, or an empty array if none
145      * @since 3.2
146      */
147     public IFile[] findFilesForLocationURI(URI   location);
148 
149     /**
150      * Returns a handle to the  workspace root, project or folder 
151      * which is mapped to the given path
152      * in the local file system, or <code>null</code> if none.
153      * If the path maps to the platform working location, the returned object
154      * will be of type <code>ROOT</code>.  If the path maps to a 
155      * project, the resulting object will be
156      * of type <code>PROJECT</code>; otherwise the resulting object 
157      * will be a folder (type <code>FOLDER</code>).
158      * The path should be absolute; a relative path will be treated as
159      * absolute.  The path segments need not be valid names; a trailing separator is ignored.
160      * The resulting resource may not currently exist.
161      * <p>
162      * This method returns null when the given file system location is not equal to 
163      * or under the location of any existing project in the workspace, or equal to the 
164      * location of the platform working location.
165      * </p>
166      * <p>
167      * Warning: This method ignores linked resources and their children.  Since
168      * linked resources may overlap other resources, a unique mapping from a
169      * file system location to a single resource is not guaranteed.  To find all 
170      * resources for a given location, including linked resources, use the method
171      * <code>findContainersForLocation</code>.
172      * </p>
173      * 
174      * @param location a path in the local file system
175      * @return the corresponding project or folder in the workspace,
176      *    or <code>null</code> if none
177      */
178     public IContainer getContainerForLocation(IPath location);
179 
180     /**
181      * Returns a handle to the file which is mapped to the given path 
182      * in the local file system, or <code>null</code> if none.
183      * The path should be absolute; a relative path will be treated as
184      * absolute.  The path segments need not be valid names.
185      * The resulting file may not currently exist.
186      * <p>
187      * This method returns null when the given file system location is not under
188      * the location of any existing project in the workspace.
189      * </p>
190      * <p>
191      * Warning: This method ignores linked resources and their children.  Since
192      * linked resources may overlap other resources, a unique mapping from a
193      * file system location to a single resource is not guaranteed.  To find all 
194      * resources for a given location, including linked resources, use the method
195      * <code>findFilesForLocation</code>.
196      * </p>
197      *
198      * @param location a path in the local file system
199      * @return the corresponding file in the workspace,
200      *    or <code>null</code> if none
201      */
202     public IFile getFileForLocation(IPath location);
203 
204     /**
205      * Returns a handle to the project resource with the given name
206      * which is a child of this root.  The given name must be a valid
207      * path segment as defined by {@link IPath#isValidSegment(String)}.
208      * <p>
209      * Note: This method deals exclusively with resource handles, 
210      * independent of whether the resources exist in the workspace.
211      * With the exception of validating that the name is a valid path segment,
212      * validation checking of the project name is not done
213      * when the project handle is constructed; rather, it is done
214      * automatically as the project is created.
215      * </p>
216      * 
217      * @param name the name of the project 
218      * @return a project resource handle
219      * @see #getProjects()
220      */
221     public IProject getProject(String   name);
222 
223     /**
224      * Returns the collection of projects which exist under this root.
225      * The projects can be open or closed.
226      * 
227      * @return an array of projects
228      * @see #getProject(String)
229      */
230     public IProject[] getProjects();
231 }
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags