KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > IContainer


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 org.eclipse.core.runtime.*;
14
15 /**
16  * Interface for resources which may contain
17  * other resources (termed its <em>members</em>). While the
18  * workspace itself is not considered a container in this sense, the
19  * workspace root resource is a container.
20  * <p>
21  * This interface is not intended to be implemented by clients.
22  * </p>
23  * <p>
24  * Containers implement the <code>IAdaptable</code> interface;
25  * extensions are managed by the platform's adapter manager.
26  * </p>
27  *
28  * @see Platform#getAdapterManager()
29  * @see IProject
30  * @see IFolder
31  * @see IWorkspaceRoot
32  */

33 public interface IContainer extends IResource, IAdaptable {
34
35     /*====================================================================
36      * Constants defining which members are wanted:
37      *====================================================================*/

38
39     /**
40      * Member constant (bit mask value 1) indicating that phantom member resources are
41      * to be included.
42      *
43      * @see IResource#isPhantom()
44      * @since 2.0
45      */

46     public static final int INCLUDE_PHANTOMS = 1;
47
48     /**
49      * Member constant (bit mask value 2) indicating that team private members are
50      * to be included.
51      *
52      * @see IResource#isTeamPrivateMember()
53      * @since 2.0
54      */

55     public static final int INCLUDE_TEAM_PRIVATE_MEMBERS = 2;
56
57     /**
58      * Member constant (bit mask value 4) indicating that derived resources
59      * are to be excluded.
60      *
61      * @see IResource#isDerived()
62      * @since 3.1
63      */

64     public static final int EXCLUDE_DERIVED = 4;
65
66     /**
67      * Returns whether a resource of some type with the given path
68      * exists relative to this resource.
69      * The supplied path may be absolute or relative; in either case, it is
70      * interpreted as relative to this resource. Trailing separators are ignored.
71      * If the path is empty this container is checked for existence.
72      *
73      * @param path the path of the resource
74      * @return <code>true</code> if a resource of some type with the given path
75      * exists relative to this resource, and <code>false</code> otherwise
76      * @see IResource#exists()
77      */

78     public boolean exists(IPath path);
79
80     /**
81      * Finds and returns the member resource (project, folder, or file)
82      * with the given name in this container, or <code>null</code> if no such
83      * resource exists.
84      *
85      * <p> N.B. Unlike the methods which traffic strictly in resource
86      * handles, this method infers the resulting resource's type from the
87      * resource existing at the calculated path in the workspace.
88      * </p>
89      *
90      * @param name the string name of the member resource
91      * @return the member resource, or <code>null</code> if no such
92      * resource exists
93      */

94     public IResource findMember(String JavaDoc name);
95
96     /**
97      * Finds and returns the member resource (project, folder, or file)
98      * with the given name in this container, or <code>null</code> if
99      * there is no such resource.
100      * <p>
101      * If the <code>includePhantoms</code> argument is <code>false</code>,
102      * only a member resource with the given name that exists will be returned.
103      * If the <code>includePhantoms</code> argument is <code>true</code>,
104      * the method also returns a resource if the workspace is keeping track of a
105      * phantom with that name.
106      * </p><p>
107      * Note that no attempt is made to exclude team-private member resources
108      * as with <code>members</code>.
109      * </p><p>
110      * N.B. Unlike the methods which traffic strictly in resource
111      * handles, this method infers the resulting resource's type from the
112      * existing resource (or phantom) in the workspace.
113      * </p>
114      *
115      * @param name the string name of the member resource
116      * @param includePhantoms <code>true</code> if phantom resources are
117      * of interest; <code>false</code> if phantom resources are not of
118      * interest
119      * @return the member resource, or <code>null</code> if no such
120      * resource exists
121      * @see #members()
122      * @see IResource#isPhantom()
123      */

124     public IResource findMember(String JavaDoc name, boolean includePhantoms);
125
126     /**
127      * Finds and returns the member resource identified by the given path in
128      * this container, or <code>null</code> if no such resource exists.
129      * The supplied path may be absolute or relative; in either case, it is
130      * interpreted as relative to this resource. Trailing separators and the path's
131      * device are ignored. If the path is empty this container is returned. Parent
132      * references in the supplied path are discarded if they go above the workspace
133      * root.
134      * <p>
135      * Note that no attempt is made to exclude team-private member resources
136      * as with <code>members</code>.
137      * </p><p>
138      * N.B. Unlike the methods which traffic strictly in resource
139      * handles, this method infers the resulting resource's type from the
140      * resource existing at the calculated path in the workspace.
141      * </p>
142      *
143      * @param path the path of the desired resource
144      * @return the member resource, or <code>null</code> if no such
145      * resource exists
146      */

147     public IResource findMember(IPath path);
148
149     /**
150      * Finds and returns the member resource identified by the given path in
151      * this container, or <code>null</code> if there is no such resource.
152      * The supplied path may be absolute or relative; in either case, it is
153      * interpreted as relative to this resource. Trailing separators and the path's
154      * device are ignored. If the path is empty this container is returned.
155      * Parent references in the supplied path are discarded if they go above the
156      * workspace root.
157      * <p>
158      * If the <code>includePhantoms</code> argument is <code>false</code>,
159      * only a resource that exists at the given path will be returned.
160      * If the <code>includePhantoms</code> argument is <code>true</code>,
161      * the method also returns a resource if the workspace is keeping track of
162      * a phantom member resource at the given path.
163      * </p><p>
164      * Note that no attempt is made to exclude team-private member resources
165      * as with <code>members</code>.
166      * </p><p>
167      * N.B. Unlike the methods which traffic strictly in resource
168      * handles, this method infers the resulting resource's type from the
169      * existing resource (or phantom) at the calculated path in the workspace.
170      * </p>
171      *
172      * @param path the path of the desired resource
173      * @param includePhantoms <code>true</code> if phantom resources are
174      * of interest; <code>false</code> if phantom resources are not of
175      * interest
176      * @return the member resource, or <code>null</code> if no such
177      * resource exists
178      * @see #members(boolean)
179      * @see IResource#isPhantom()
180      */

181     public IResource findMember(IPath path, boolean includePhantoms);
182
183     /**
184      * Returns the default charset for resources in this container.
185      * <p>
186      * This is a convenience method, fully equivalent to:
187      * <pre>
188      * getDefaultCharset(true);
189      * </pre>
190      * </p><p>
191      * Note that this method does not check whether the result is a supported
192      * charset name. Callers should be prepared to handle
193      * <code>UnsupportedEncodingException</code> where this charset is used.
194      * </p>
195      *
196      * @return the name of the default charset encoding for this container
197      * @exception CoreException if this method fails
198      * @see IContainer#getDefaultCharset(boolean)
199      * @see IFile#getCharset()
200      * @since 3.0
201      */

202     public String JavaDoc getDefaultCharset() throws CoreException;
203
204     /**
205      * Returns the default charset for resources in this container.
206      * <p>
207      * If checkImplicit is <code>false</code>, this method
208      * will return the charset defined by calling #setDefaultCharset, provided this
209      * container exists, or <code>null</code> otherwise.
210      * </p><p>
211      * If checkImplicit is <code>true</code>, this method uses the following
212      * algorithm to determine the charset to be returned:
213      * <ol>
214      * <li>the one explicitly set by calling #setDefaultCharset
215      * (with a non-null argument) on this container, if any, and this container
216      * exists, or</li>
217      * <li>the parent's default charset, if this container has a parent (is not the
218      * workspace root), or</li>
219      * <li>the charset returned by ResourcesPlugin#getEncoding.</li>
220      * </ol>
221      * </p><p>
222      * Note that this method does not check whether the result is a supported
223      * charset name. Callers should be prepared to handle
224      * <code>UnsupportedEncodingException</code> where this charset is used.
225      * </p>
226      * @return the name of the default charset encoding for this container,
227      * or <code>null</code>
228      * @exception CoreException if this method fails
229      * @see IFile#getCharset()
230      * @since 3.0
231      */

232     public String JavaDoc getDefaultCharset(boolean checkImplicit) throws CoreException;
233
234     /**
235      * Returns a handle to the file identified by the given path in this
236      * container.
237      * <p>
238      * This is a resource handle operation; neither the resource nor
239      * the result need exist in the workspace.
240      * The validation check on the resource name/path is not done
241      * when the resource handle is constructed; rather, it is done
242      * automatically as the resource is created.
243      * <p>
244      * The supplied path may be absolute or relative; in either case, it is
245      * interpreted as relative to this resource and is appended
246      * to this container's full path to form the full path of the resultant resource.
247      * A trailing separator is ignored. The path of the resulting resource must
248      * have at least two segments.
249      * </p>
250      *
251      * @param path the path of the member file
252      * @return the (handle of the) member file
253      * @see #getFolder(IPath)
254      */

255     public IFile getFile(IPath path);
256
257     /**
258      * Returns a handle to the folder identified by the given path in this
259      * container.
260      * <p>
261      * This is a resource handle operation; neither the resource nor
262      * the result need exist in the workspace.
263      * The validation check on the resource name/path is not done
264      * when the resource handle is constructed; rather, it is done
265      * automatically as the resource is created.
266      * <p>
267      * The supplied path may be absolute or relative; in either case, it is
268      * interpreted as relative to this resource and is appended
269      * to this container's full path to form the full path of the resultant resource.
270      * A trailing separator is ignored. The path of the resulting resource must
271      * have at least two segments.
272      * </p>
273      *
274      * @param path the path of the member folder
275      * @return the (handle of the) member folder
276      * @see #getFile(IPath)
277      */

278     public IFolder getFolder(IPath path);
279
280     /**
281      * Returns a list of existing member resources (projects, folders and files)
282      * in this resource, in no particular order.
283      * <p>
284      * This is a convenience method, fully equivalent to <code>members(IResource.NONE)</code>.
285      * Team-private member resources are <b>not</b> included in the result.
286      * </p><p>
287      * Note that the members of a project or folder are the files and folders
288      * immediately contained within it. The members of the workspace root
289      * are the projects in the workspace.
290      * </p>
291      *
292      * @return an array of members of this resource
293      * @exception CoreException if this request fails. Reasons include:
294      * <ul>
295      * <li> This resource does not exist.</li>
296      * <li> This resource is a project that is not open.</li>
297      * </ul>
298      * @see #findMember(IPath)
299      * @see IResource#isAccessible()
300      */

301     public IResource[] members() throws CoreException;
302
303     /**
304      * Returns a list of all member resources (projects, folders and files)
305      * in this resource, in no particular order.
306      * <p>
307      * This is a convenience method, fully equivalent to:
308      * <pre>
309      * members(includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
310      * </pre>
311      * Team-private member resources are <b>not</b> included in the result.
312      * </p>
313      *
314      * @param includePhantoms <code>true</code> if phantom resources are
315      * of interest; <code>false</code> if phantom resources are not of
316      * interest
317      * @return an array of members of this resource
318      * @exception CoreException if this request fails. Reasons include:
319      * <ul>
320      * <li> This resource does not exist.</li>
321      * <li> <code>includePhantoms</code> is <code>false</code> and
322      * this resource does not exist.</li>
323      * <li> <code>includePhantoms</code> is <code>false</code> and
324      * this resource is a project that is not open.</li>
325      * </ul>
326      * @see #members(int)
327      * @see IResource#exists()
328      * @see IResource#isPhantom()
329      */

330     public IResource[] members(boolean includePhantoms) throws CoreException;
331
332     /**
333      * Returns a list of all member resources (projects, folders and files)
334      * in this resource, in no particular order.
335      * <p>
336      * If the <code>INCLUDE_PHANTOMS</code> flag is not specified in the member
337      * flags (recommended), only member resources that exist will be returned.
338      * If the <code>INCLUDE_PHANTOMS</code> flag is specified,
339      * the result will also include any phantom member resources the
340      * workspace is keeping track of.
341      * </p><p>
342      * If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> flag is specified
343      * in the member flags, team private members will be included along with
344      * the others. If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> flag
345      * is not specified (recommended), the result will omit any team private
346      * member resources.
347      * </p>
348      * <p>
349      * If the <code>EXCLUDE_DERIVED</code> flag is not specified, derived
350      * resources are included. If the <code>EXCLUDE_DERIVED</code> flag is
351      * specified in the member flags, derived resources are not included.
352      * </p>
353      *
354      * @param memberFlags bit-wise or of member flag constants
355      * (<code>INCLUDE_PHANTOMS</code>, <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code>
356      * and <code>EXCLUDE_DERIVED</code>) indicating which members are of interest
357      * @return an array of members of this resource
358      * @exception CoreException if this request fails. Reasons include:
359      * <ul>
360      * <li> This resource does not exist.</li>
361      * <li> the <code>INCLUDE_PHANTOMS</code> flag is not specified and
362      * this resource does not exist.</li>
363      * <li> the <code>INCLUDE_PHANTOMS</code> flag is not specified and
364      * this resource is a project that is not open.</li>
365      * </ul>
366      * @see IResource#exists()
367      * @since 2.0
368      */

369     public IResource[] members(int memberFlags) throws CoreException;
370
371     /**
372      * Returns a list of recently deleted files inside this container that
373      * have one or more saved states in the local history. The depth parameter
374      * determines how deep inside the container to look. This resource may or
375      * may not exist in the workspace.
376      * <p>
377      * When applied to an existing project resource, this method returns recently
378      * deleted files with saved states in that project. Note that local history is
379      * maintained with each individual project, and gets discarded when a project
380      * is deleted from the workspace. If applied to a deleted project, this method
381      * returns the empty list.
382      * </p><p>
383      * When applied to the workspace root resource (depth infinity), this method
384      * returns all recently deleted files with saved states in all existing projects.
385      * </p><p>
386      * When applied to a folder (or project) resource (depth one),
387      * this method returns all recently deleted member files with saved states.
388      * </p><p>
389      * When applied to a folder resource (depth zero),
390      * this method returns an empty list unless there was a recently deleted file
391      * with saved states at the same path as the folder.
392      * </p><p>
393      * This method is long-running; progress and cancellation are provided
394      * by the given progress monitor.
395      * </p>
396      *
397      * @param depth depth limit: one of <code>DEPTH_ZERO</code>, <code>DEPTH_ONE</code>
398      * or <code>DEPTH_INFINITE</code>
399      * @param monitor a progress monitor, or <code>null</code> if progress
400      * reporting and cancellation are not desired
401      * @return an array of recently deleted files
402      * @exception CoreException if this method fails
403      * @see IFile#getHistory(IProgressMonitor)
404      * @since 2.0
405      */

406     public IFile[] findDeletedMembersWithHistory(int depth, IProgressMonitor monitor) throws CoreException;
407
408     /**
409      * Sets the default charset for this container. Passing a value of <code>null</code>
410      * will remove the default charset setting for this resource.
411      *
412      * @param charset a charset string, or <code>null</code>
413      * @exception CoreException if this method fails Reasons include:
414      * <ul>
415      * <li> This resource does not exist.</li>
416      * <li> An error happened while persisting this setting.</li>
417      * </ul>
418      * @see IContainer#getDefaultCharset()
419      * @since 3.0
420      * @deprecated Replaced by {@link #setDefaultCharset(String, IProgressMonitor)} which
421      * is a workspace operation and reports changes in resource deltas.
422      */

423     public void setDefaultCharset(String JavaDoc charset) throws CoreException;
424
425     /**
426      * Sets the default charset for this container. Passing a value of <code>null</code>
427      * will remove the default charset setting for this resource.
428      * <p>
429      * This method changes resources; these changes will be reported
430      * in a subsequent resource change event, including an indication
431      * that the encoding of affected resources has been changed.
432      * </p>
433      * <p>
434      * This method is long-running; progress and cancellation are provided
435      * by the given progress monitor.
436      * </p>
437      *
438      * @param charset a charset string, or <code>null</code>
439      * @param monitor a progress monitor, or <code>null</code> if progress
440      * reporting is not desired
441      * @exception OperationCanceledException if the operation is canceled.
442      * Cancelation can occur even if no progress monitor is provided.
443      * @exception CoreException if this method fails Reasons include:
444      * <ul>
445      * <li> This resource is not accessible.</li>
446      * <li> An error happened while persisting this setting.</li>
447      * <li> Resource changes are disallowed during certain types of resource change
448      * event notification. See {@link IResourceChangeEvent} for more details.</li>
449      * </ul>
450      * @see IContainer#getDefaultCharset()
451      * @see IResourceRuleFactory#charsetRule(IResource)
452      * @since 3.0
453      */

454     public void setDefaultCharset(String JavaDoc charset, IProgressMonitor monitor) throws CoreException;
455 }
456
Popular Tags