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   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   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   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   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   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   charset, IProgressMonitor monitor) throws CoreException;
455 }
456
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags