KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags