/*******************************************************************************
 *  Copyright (c) 2000, 2009 IBM Corporation and others.
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  which accompanies this distribution, and is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 * 
 *  Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.resources;

import org.eclipse.core.runtime.*;

/**
 * Interface for resources which may contain
 * other resources (termed its <em>members</em>). While the 
 * workspace itself is not considered a container in this sense, the
 * workspace root resource is a container.
 * <p>
 * Containers implement the <code>IAdaptable</code> interface;
 * extensions are managed by the platform's adapter manager.
 * </p>
 *
 * @see Platform#getAdapterManager()
 * @see IProject
 * @see IFolder
 * @see IWorkspaceRoot
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IContainer extends IResource, IAdaptable {

	/*====================================================================
	 * Constants defining which members are wanted:
	 *====================================================================*/

	/**
	 * Member constant (bit mask value 1) indicating that phantom member resources are
	 * to be included.
	 * 
	 * @see IResource#isPhantom()
	 * @since 2.0
	 */
	public static final int INCLUDE_PHANTOMS = 1;

	/**
	 * Member constant (bit mask value 2) indicating that team private members are
	 * to be included.
	 * 
	 * @see IResource#isTeamPrivateMember()
	 * @since 2.0
	 */
	public static final int INCLUDE_TEAM_PRIVATE_MEMBERS = 2;

	/**
	 * Member constant (bit mask value 4) indicating that derived resources
	 * are to be excluded.
	 * 
	 * @see IResource#isDerived()
	 * @since 3.1
	 */
	public static final int EXCLUDE_DERIVED = 4;
	
	/**
	 * Member constant (bit mask value 8) indicating that hidden resources
	 * are to be included.
	 * 
	 * @see IResource#isHidden()
	 * @since 3.4
	 */
	public static final int INCLUDE_HIDDEN = 8;

	/**
	 * Returns whether a resource of some type with the given path 
	 * exists relative to this resource.
	 * The supplied path may be absolute or relative; in either case, it is
	 * interpreted as relative to this resource.  Trailing separators are ignored.
	 * If the path is empty this container is checked for existence.
	 *
	 * @param path the path of the resource
	 * @return <code>true</code> if a resource of some type with the given path 
	 *     exists relative to this resource, and <code>false</code> otherwise
	 * @see IResource#exists()
	 */
	public boolean exists(IPath path);

	/**
	 * Finds and returns the member resource (project, folder, or file)
	 * with the given name in this container, or <code>null</code> if no such
	 * resource exists.
	 * 
	 * <p> N.B. Unlike the methods which traffic strictly in resource
	 * handles, this method infers the resulting resource's type from the
	 * resource existing at the calculated path in the workspace.
	 * </p>
	 *
	 * @param name the string name of the member resource
	 * @return the member resource, or <code>null</code> if no such
	 * 		resource exists
	 */
	public IResource findMember(String name);

	/**
	 * Finds and returns the member resource (project, folder, or file)
	 * with the given name in this container, or <code>null</code> if 
	 * there is no such resource.
	 * <p>
	 * If the <code>includePhantoms</code> argument is <code>false</code>, 
	 * only a member resource with the given name that exists will be returned.
	 * If the <code>includePhantoms</code> argument is <code>true</code>,
	 * the method also returns a resource if the workspace is keeping track of a
	 * phantom with that name.
	 * </p><p>
	 * Note that no attempt is made to exclude team-private member resources
	 * as with <code>members</code>.
	 * </p><p>
	 * N.B. Unlike the methods which traffic strictly in resource
	 * handles, this method infers the resulting resource's type from the
	 * existing resource (or phantom) in the workspace.
	 * </p>
	 *
	 * @param name the string name of the member resource
	 * @param includePhantoms <code>true</code> if phantom resources are
	 *   of interest; <code>false</code> if phantom resources are not of
	 *   interest
	 * @return the member resource, or <code>null</code> if no such
	 * 		resource exists
	 * @see #members()
	 * @see IResource#isPhantom()
	 */
	public IResource findMember(String name, boolean includePhantoms);

	/**
	 * Finds and returns the member resource identified by the given path in
	 * this container, or <code>null</code> if no such resource exists.
	 * The supplied path may be absolute or relative; in either case, it is
	 * interpreted as relative to this resource.   Trailing separators and the path's
	 * device are ignored. If the path is empty this container is returned.  Parent
	 * references in the supplied path are discarded if they go above the workspace
	 * root.
	 * <p>
	 * Note that no attempt is made to exclude team-private member resources
	 * as with <code>members</code>.
	 * </p><p> 
	 * N.B. Unlike the methods which traffic strictly in resource
	 * handles, this method infers the resulting resource's type from the
	 * resource existing at the calculated path in the workspace.
	 * </p>
	 *
	 * @param path the path of the desired resource
	 * @return the member resource, or <code>null</code> if no such
	 * 		resource exists
	 */
	public IResource findMember(IPath path);

	/**
	 * Finds and returns the member resource identified by the given path in
	 * this container, or <code>null</code> if there is no such resource.
	 * The supplied path may be absolute or relative; in either case, it is
	 * interpreted as relative to this resource.  Trailing separators and the path's
	 * device are ignored.  If the path is empty this container is returned.
	 * Parent references in the supplied path are discarded if they go above the 
	 * workspace root.
	 * <p>
	 * If the <code>includePhantoms</code> argument is <code>false</code>, 
	 * only a resource that exists at the given path will be returned.
	 * If the <code>includePhantoms</code> argument is <code>true</code>,
	 * the method also returns a resource if the workspace is keeping track of
	 * a phantom member resource at the given path.
	 * </p><p>
	 * Note that no attempt is made to exclude team-private member resources
	 * as with <code>members</code>.
	 * </p><p>
	 * N.B. Unlike the methods which traffic strictly in resource
	 * handles, this method infers the resulting resource's type from the
	 * existing resource (or phantom) at the calculated path in the workspace.
	 * </p>
	 *
	 * @param path the path of the desired resource
	 * @param includePhantoms <code>true</code> if phantom resources are
	 *   of interest; <code>false</code> if phantom resources are not of
	 *   interest
	 * @return the member resource, or <code>null</code> if no such
	 * 		resource exists
	 * @see #members(boolean)
	 * @see IResource#isPhantom()
	 */
	public IResource findMember(IPath path, boolean includePhantoms);

	/**
	 * Returns the default charset for resources in this container.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * <pre>
	 *   getDefaultCharset(true);
	 * </pre>
	 * </p><p>
	 * Note that  this method does not check whether the result is a supported
	 * charset name. Callers should be prepared to handle 
	 * <code>UnsupportedEncodingException</code> where this charset is used. 
	 * </p>
	 *
	 * @return the name of the default charset encoding for this container 
	 * @exception CoreException if this method fails
	 * @see IContainer#getDefaultCharset(boolean) 
	 * @see IFile#getCharset()
	 * @since 3.0
	 */
	public String getDefaultCharset() throws CoreException;

	/**
	 * Returns the default charset for resources in this container.
	 * <p>
	 * If checkImplicit is <code>false</code>, this method 
	 * will return the charset defined by calling #setDefaultCharset, provided this 
	 * container exists, or <code>null</code> otherwise.
	 * </p><p>
	 * If checkImplicit is <code>true</code>, this method uses the following 
	 * algorithm to determine the charset to be returned:
	 * <ol>
	 * <li>the one explicitly set by calling #setDefaultCharset 
	 * (with a non-null argument) on this container, if any, and this container 
	 * exists, or</li>  
	 * <li>the parent's default charset, if this container has a parent (is not the 
	 * workspace root), or</li>
	 * <li>the charset returned by ResourcesPlugin#getEncoding.</li> 
	 * </ol>
	 *  </p><p>
	 * Note that  this method does not check whether the result is a supported
	 * charset name. Callers should be prepared to handle 
	 * <code>UnsupportedEncodingException</code> where this charset is used. 
	 * </p>
	 * @return the name of the default charset encoding for this container,
	 * or <code>null</code> 
	 * @exception CoreException if this method fails
	 * @see IFile#getCharset()
	 * @since 3.0
	 */
	public String getDefaultCharset(boolean checkImplicit) throws CoreException;

	/**
	 * Returns a handle to the file identified by the given path in this
	 * container.
	 * <p> 
	 * This is a resource handle operation; neither the resource nor
	 * the result need exist in the workspace.
	 * The validation check on the resource name/path is not done
	 * when the resource handle is constructed; rather, it is done
	 * automatically as the resource is created.
	 * <p>
	 * The supplied path may be absolute or relative; in either case, it is
	 * interpreted as relative to this resource and is appended
	 * to this container's full path to form the full path of the resultant resource.
	 * A trailing separator is ignored. The path of the resulting resource must 
	 * have at least two segments.
	 * </p>
	 *
	 * @param path the path of the member file
	 * @return the (handle of the) member file
	 * @see #getFolder(IPath)
	 */
	public IFile getFile(IPath path);

	/**
	 * Returns a handle to the folder identified by the given path in this
	 * container.
	 * <p> 
	 * This is a resource handle operation; neither the resource nor
	 * the result need exist in the workspace.
	 * The validation check on the resource name/path is not done
	 * when the resource handle is constructed; rather, it is done
	 * automatically as the resource is created. 
	 * <p>
	 * The supplied path may be absolute or relative; in either case, it is
	 * interpreted as relative to this resource and is appended
	 * to this container's full path to form the full path of the resultant resource.
	 * A trailing separator is ignored. The path of the resulting resource must
	 * have at least two segments.
	 * </p>
	 *
	 * @param path the path of the member folder
	 * @return the (handle of the) member folder
	 * @see #getFile(IPath)
	 */
	public IFolder getFolder(IPath path);

	/**
	 * Returns a list of existing member resources (projects, folders and files)
	 * in this resource, in no particular order.
	 * <p>
	 * This is a convenience method, fully equivalent to <code>members(IResource.NONE)</code>.
	 * Team-private member resources are <b>not</b> included in the result.
	 * </p><p>
	 * Note that the members of a project or folder are the files and folders
	 * immediately contained within it.  The members of the workspace root
	 * are the projects in the workspace.
	 * </p>
	 *
	 * @return an array of members of this resource
	 * @exception CoreException if this request fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> This resource is a project that is not open.</li>
	 * </ul>
	 * @see #findMember(IPath)
	 * @see IResource#isAccessible()
	 */
	public IResource[] members() throws CoreException;

	/**
	 * Returns a list of all member resources (projects, folders and files)
	 * in this resource, in no particular order.
	 * <p>
	 * This is a convenience method, fully equivalent to:
	 * <pre>
	 *   members(includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
	 * </pre>
	 * Team-private member resources are <b>not</b> included in the result.
	 * </p>
	 *
	 * @param includePhantoms <code>true</code> if phantom resources are
	 *   of interest; <code>false</code> if phantom resources are not of
	 *   interest
	 * @return an array of members of this resource
	 * @exception CoreException if this request fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> <code>includePhantoms</code> is <code>false</code> and
	 *     this resource does not exist.</li>
	 * <li> <code>includePhantoms</code> is <code>false</code> and
	 *     this resource is a project that is not open.</li>
	 * </ul>
	 * @see #members(int)
	 * @see IResource#exists()
	 * @see IResource#isPhantom()
	 */
	public IResource[] members(boolean includePhantoms) throws CoreException;

	/**
	 * Returns a list of all member resources (projects, folders and files)
	 * in this resource, in no particular order.
	 * <p>
	 * If the <code>INCLUDE_PHANTOMS</code> flag is not specified in the member 
	 * flags (recommended), only member resources that exist will be returned.
	 * If the <code>INCLUDE_PHANTOMS</code> flag is specified,
	 * the result will also include any phantom member resources the
	 * workspace is keeping track of.
	 * </p><p>
	 * If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> flag is specified 
	 * in the member flags, team private members will be included along with
	 * the others. If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> flag
	 * is not specified (recommended), the result will omit any team private
	 * member resources.
	 * </p><p>
	 * If the {@link #INCLUDE_HIDDEN} flag is specified in the member flags, hidden 
	 * members will be included along with the others. If the {@link #INCLUDE_HIDDEN} flag
	 * is not specified (recommended), the result will omit any hidden
	 * member resources.
	 * </p>
	 * <p>
	 * If the <code>EXCLUDE_DERIVED</code> flag is not specified, derived 
	 * resources are included. If the <code>EXCLUDE_DERIVED</code> flag is 
	 * specified in the member flags, derived resources are not included.
	 * </p>
	 *
	 * @param memberFlags bit-wise or of member flag constants
	 *   ({@link #INCLUDE_PHANTOMS}, {@link #INCLUDE_TEAM_PRIVATE_MEMBERS},
	 *   {@link #INCLUDE_HIDDEN} and {@link #EXCLUDE_DERIVED}) indicating which members are of interest
	 * @return an array of members of this resource
	 * @exception CoreException if this request fails. Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> the <code>INCLUDE_PHANTOMS</code> flag is not specified and
	 *     this resource does not exist.</li>
	 * <li> the <code>INCLUDE_PHANTOMS</code> flag is not specified and
	 *     this resource is a project that is not open.</li>
	 * </ul>
	 * @see IResource#exists()
	 * @since 2.0
	 */
	public IResource[] members(int memberFlags) throws CoreException;

	/**
	 * Returns a list of recently deleted files inside this container that
	 * have one or more saved states in the local history. The depth parameter
	 * determines how deep inside the container to look. This resource may or
	 * may not exist in the workspace.
	 * <p>
	 * When applied to an existing project resource, this method returns recently 
	 * deleted files with saved states in that project. Note that local history is
	 * maintained with each individual project, and gets discarded when a project
	 * is deleted from the workspace. If applied to a deleted project, this method
	 * returns the empty list.
	 * </p><p>
	 * When applied to the workspace root resource (depth infinity), this method
	 * returns all recently deleted files with saved states in all existing projects.
	 * </p><p>
	 * When applied to a folder (or project) resource (depth one),
	 * this method returns all recently deleted member files with saved states.
	 * </p><p>
	 * When applied to a folder resource (depth zero),
	 * this method returns an empty list unless there was a recently deleted file
	 * with saved states at the same path as the folder.
	 * </p><p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor. 
	 * </p>
	 * 
	 * @param depth depth limit: one of <code>DEPTH_ZERO</code>, <code>DEPTH_ONE</code>
	 *    or <code>DEPTH_INFINITE</code>
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting and cancellation are not desired
	 * @return an array of recently deleted files
	 * @exception CoreException if this method fails
	 * @see IFile#getHistory(IProgressMonitor)
	 * @since 2.0
	 */
	public IFile[] findDeletedMembersWithHistory(int depth, IProgressMonitor monitor) throws CoreException;

	/**
	 * Sets the default charset for this container. Passing a value of <code>null</code>
	 * will remove the default charset setting for this resource.
	 *
	 * @param charset a charset string, or <code>null</code>
	 * @exception CoreException if this method fails Reasons include:
	 * <ul>
	 * <li> This resource does not exist.</li>
	 * <li> An error happened while persisting this setting.</li>
	 * </ul>
	 * @see IContainer#getDefaultCharset()
	 * @since 3.0
	 * @deprecated Replaced by {@link #setDefaultCharset(String, IProgressMonitor)} which 
	 * 	is a workspace operation and reports changes in resource deltas. 
	 */
	public void setDefaultCharset(String charset) throws CoreException;

	/**
	 * Sets the default charset for this container. Passing a value of <code>null</code>
	 * will remove the default charset setting for this resource.
	 * <p>
	 * This method changes resources; these changes will be reported
	 * in a subsequent resource change event, including an indication 
	 * that the encoding of affected resources has been changed.
	 * </p>
	 * <p>
	 * This method is long-running; progress and cancellation are provided
	 * by the given progress monitor. 
	 * </p>
	 *
	 * @param charset a charset string, or <code>null</code>
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @exception OperationCanceledException if the operation is canceled. 
	 * Cancelation can occur even if no progress monitor is provided.
	 * @exception CoreException if this method fails Reasons include:
	 * <ul>
	 * <li> This resource is not accessible.</li>
	 * <li> An error happened while persisting this setting.</li>
	 * <li> Resource changes are disallowed during certain types of resource change 
	 *       event notification. See {@link IResourceChangeEvent} for more details.</li>
	 * </ul>
	 * @see IContainer#getDefaultCharset()
	 * @see IResourceRuleFactory#charsetRule(IResource)
	 * @since 3.0
	 */
	public void setDefaultCharset(String charset, IProgressMonitor monitor) throws CoreException;
}