/*******************************************************************************
 * Copyright (c) 2000, 2009 QNX Software Systems 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:
 *     QNX Software Systems - Initial API and implementation
 *******************************************************************************/
package org.eclipse.cdt.core.model;

import java.util.Map;

import org.eclipse.cdt.core.CCorePlugin;
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;

/**
 * A C project represents a view of a project resource in terms of C 
 * elements such as , ICContainer, ITranslationUnit ....
 * <code>CoreModel.create(project)</code>.
 * </p>
 *
 * @see CoreModel#create(org.eclipse.core.resources.IProject)
 * 
 * @noextend This interface is not intended to be extended by clients.
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface ICProject extends IParent, IOpenable, ICElement {

	/**
	 * Returns the <code>ICElement</code> corresponding to the given
	 * path, or <code>null</code> if no such 
	 * <code>ICElement</code> is found.
	 *
	 * @exception CModelException if the given path is <code>null</code>
	 *  or absolute
	 */
	ICElement findElement(IPath path) throws CModelException;

	/**
	 * Return the ArchiveContainer of this Project.
	 * @throws CModelException
	 */
	IArchiveContainer getArchiveContainer() throws CModelException;

	/**
	 * Return the BinaryContainer of this Project.
	 * @throws CModelException
	 */
	IBinaryContainer getBinaryContainer() throws CModelException;

	/**
	 * Returns the source root folders of the project.
	 * 
	 * <p>NOTE: This is equivalent to <code>getChildren()</code>.
	 * 
	 * @return ISourceRoot - root folders
	 * @exception CModelException
	 */
	ISourceRoot[] getSourceRoots() throws CModelException;

	/**
	 * Returns all of the existing source roots that exist
	 * on the project, in the order they are defined by the ".cdtproject".
	 *
	 * @return all of the existing package fragment roots that exist
	 * on the classpath
	 * @exception CModelException if this element does not exist or if an
	 *		exception occurs while accessing its corresponding resource
	 */
	ISourceRoot[] getAllSourceRoots() throws CModelException;

	/**
	 * 
	 * @param entry
	 * @return ISourceRoot
	 * @throws CModelException
	 */
	ISourceRoot getSourceRoot(ISourceEntry entry) throws CModelException;

	ISourceRoot findSourceRoot(IResource resource);
	
	ISourceRoot findSourceRoot(IPath path);

	/**
	 * Return the output entries.
	 * 
	 * @throws CModelException
	 */
	public IOutputEntry[] getOutputEntries() throws CModelException;

	/**
	 * @param resource
	 */
	boolean isOnOutputEntry(IResource resource);

	/**
	 * @param resource
	 */
	boolean isOnSourceRoot(IResource resource);

	/**
	 * @param element
	 */
	boolean isOnSourceRoot(ICElement element);

	/**
	 * Return the library references for this project.
	 * 
	 * @return [] ILibraryReference
	 */
	ILibraryReference[] getLibraryReferences() throws CModelException;

	/**
	 * Return the include paths set on the project.
	 * 
	 * @throws CModelException
	 */
	IIncludeReference[] getIncludeReferences() throws CModelException;

	/**
	 * Returns the names of the projects that are directly required by this
	 * project. A project is required if it is in its cpath entries.
	 * <p>
	 * The project names are returned in the order they appear on the cpathentries.
	 *
	 * @return the names of the projects that are directly required by this project
	 * @exception CModelException if this element does not exist or if an
	 *              exception occurs while accessing its corresponding resource
	 */
	String[] getRequiredProjectNames() throws CModelException;

	/**
	 * 
	 * @return IProject
	 */
	IProject getProject();

	/**
	 * Helper method for returning one option value only. Equivalent to <code>(String)this.getOptions(inheritCCoreOptions).get(optionName)</code>
	 * Note that it may answer <code>null</code> if this option does not exist, or if there is no custom value for it.
	 * <p>
	 * For a complete description of the configurable options, see <code>CCorePlugin#getDefaultOptions</code>.
	 * </p>
	 * 
	 * @param optionName the name of an option
	 * @param inheritCCoreOptions - boolean indicating whether CCorePlugin options should be inherited as well
	 * @return the String value of a given option
	 * @see CCorePlugin#getDefaultOptions
	 */
	String getOption(String optionName, boolean inheritCCoreOptions);

	/**
	 * Returns the table of the current custom options for this project. Projects remember their custom options,
	 * in other words, only the options different from the the CCorePlugin global options for the workspace.
	 * A boolean argument allows to directly merge the project options with global ones from <code>CCorePlugin</code>.
	 * <p>
	 * For a complete description of the configurable options, see <code>CCorePlugin#getDefaultOptions</code>.
	 * </p>
	 * 
	 * @param inheritCCoreOptions - boolean indicating whether CCorePlugin options should be inherited as well
	 * @return table of current settings of all options 
	 *   (key type: <code>String</code>; value type: <code>String</code>)
	 * @see CCorePlugin#getDefaultOptions
	 */
	Map<String, String> getOptions(boolean inheritCCoreOptions);

	/**
	 * Helper method for setting one option value only. Equivalent to <code>Map options = this.getOptions(false); map.put(optionName, optionValue); this.setOptions(map)</code>
	 * <p>
	 * For a complete description of the configurable options, see <code>CCorePlugin#getDefaultOptions</code>.
	 * </p>
	 * 
	 * @param optionName the name of an option
	 * @param optionValue the value of the option to set
	 * @see CCorePlugin#getDefaultOptions
	 */
	void setOption(String optionName, String optionValue);

	/**
	 * Sets the project custom options. All and only the options explicitly included in the given table 
	 * are remembered; all previous option settings are forgotten, including ones not explicitly
	 * mentioned.
	 * <p>
	 * For a complete description of the configurable options, see <code>CCorePlugin#getDefaultOptions</code>.
	 * </p>
	 * 
	 * @param newOptions the new options (key type: <code>String</code>; value type: <code>String</code>),
	 *   or <code>null</code> to flush all custom options (clients will automatically get the global CCorePlugin options).
	 * @see CCorePlugin#getDefaultOptions
	 */
	void setOptions(Map<String, String> newOptions);

	/**
	 * Returns the list of entries for the project. This corresponds to the exact set
	 * of entries which were assigned using <code>setCPathEntries</code>.
	 * <p>
	 *
	 * @return the list of entries for the project.
	 * @exception CModelException if this element does not exist or if an
	 *              exception occurs while accessing its corresponding resource
	 */
	IPathEntry[] getResolvedPathEntries() throws CModelException;

	/**
	 * Returns the list of entries for the project. This corresponds to the exact set
	 * of entries which were assigned using <code>setCPathEntries</code>.
	 * <p>
	 *
	 * @return the list of entries for the project.
	 * @exception CModelException if this element does not exist or if an
	 *              exception occurs while accessing its corresponding resource
	 */
	IPathEntry[] getRawPathEntries() throws CModelException;

	/**
	 * Sets the entries for this project.
	 *
	 * @param entries a list of IPathEntry[] entries
	 * @param monitor the given progress monitor
	 * @exception CModelException if the entries could not be set. Reasons include:
	 * <ul>
	 * <li> This C/C++ element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
	 * <li> The entries are being modified during resource change event notification (CORE_EXCEPTION)
	 * </ul>
	 */
	void setRawPathEntries(IPathEntry[] entries, IProgressMonitor monitor) throws CModelException;

	/**
	 * Returns an array of non-C resources directly contained in this project.
	 * It does not transitively answer non-C resources contained in folders;
	 * these would have to be explicitly iterated over.
	 * <p>
	 * Non-C resources includes files, folders, projects  not accounted for.
	 * </p>
	 * 
	 * @return an array of non-C resources directly contained in this project
	 * @exception CModelException if this element does not exist or if an
	 *              exception occurs while accessing its corresponding resource
	 */
	Object[] getNonCResources() throws CModelException;

}
