| /******************************************************************************* |
| * Copyright (c) 2000, 2014 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 |
| * Broadcom Corporation - build configurations and references |
| *******************************************************************************/ |
| package org.eclipse.core.resources; |
| |
| import java.net.URI; |
| import org.eclipse.core.runtime.IPath; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| |
| /** |
| * A project description contains the meta-data required to define |
| * a project. In effect, a project description is a project's "content". |
| * |
| * @noimplement This interface is not intended to be implemented by clients. |
| * @noextend This interface is not intended to be extended by clients. |
| */ |
| public interface IProjectDescription { |
| /** |
| * Constant that denotes the name of the project description file (value |
| * <code>".project"</code>). |
| * The handle of a project's description file is |
| * <code>project.getFile(DESCRIPTION_FILE_NAME)</code>. |
| * The project description file is located in the root of the project's content area. |
| * |
| * @since 2.0 |
| */ |
| public static final String DESCRIPTION_FILE_NAME = ".project"; //$NON-NLS-1$ |
| |
| /** |
| * Returns the build configurations referenced by the specified configuration for the |
| * described project. |
| * <p> |
| * These references are persisted by the workspace in a private location outside the |
| * project description file, and as such will not be shared when a project is exported |
| * or persisted in a repository. As such clients are always |
| * responsible for setting these references when a project is created or recreated. |
| * </p> |
| * <p> |
| * The referenced build configurations need not exist in the workspace. |
| * The result will not contain duplicates. The order of the references is preserved |
| * from the call to {@link #setBuildConfigReferences(String, IBuildConfiguration[])}. |
| * Returns an empty array if the provided config doesn't dynamically reference |
| * any other build configurations, or the given config does not exist in this description. |
| * </p> |
| * @param configName the configuration in the described project to get the references for |
| * @return a list of dynamic build configurations |
| * @see #setBuildConfigReferences(String, IBuildConfiguration[]) |
| * @since 3.7 |
| */ |
| public IBuildConfiguration[] getBuildConfigReferences(String configName); |
| |
| /** |
| * Returns the list of build commands to run when building the described project. |
| * The commands are listed in the order in which they are to be run. |
| * |
| * @return the list of build commands for the described project |
| */ |
| public ICommand[] getBuildSpec(); |
| |
| /** |
| * Returns the descriptive comment for the described project. |
| * |
| * @return the comment for the described project |
| */ |
| public String getComment(); |
| |
| /** |
| * Returns the dynamic project references for the described project. Dynamic |
| * project references can be used instead of simple project references in cases |
| * where the reference information is computed dynamically be a third party. |
| * These references are persisted by the workspace in a private location outside |
| * the project description file, and as such will not be shared when a project is |
| * exported or persisted in a repository. A client using project references |
| * is always responsible for setting these references when a project is created |
| * or recreated. |
| * <p> |
| * The returned projects need not exist in the workspace. The result will not |
| * contain duplicates. Returns an empty array if there are no dynamic project |
| * references on this description. |
| * |
| * @see #getBuildConfigReferences(String) |
| * @see #getReferencedProjects() |
| * @see #setDynamicReferences(IProject[]) |
| * @return a list of projects |
| * @since 3.0 |
| */ |
| public IProject[] getDynamicReferences(); |
| |
| /** |
| * Returns the local file system location for the described project. The path |
| * will be either an absolute file system path, or a relative path whose first |
| * segment is the name of a workspace path variable. <code>null</code> is |
| * returned if the default location should be used. This method will return |
| * <code>null</code> if this project is not located in the local file system. |
| * |
| * @return the location for the described project or <code>null</code> |
| * @deprecated Since 3.2, project locations are not necessarily in the local file |
| * system. The more general {@link #getLocationURI()} method should be used instead. |
| */ |
| @Deprecated |
| public IPath getLocation(); |
| |
| /** |
| * Returns the location URI for the described project. <code>null</code> is |
| * returned if the default location should be used. |
| * |
| * @return the location for the described project or <code>null</code> |
| * @since 3.2 |
| * @see #setLocationURI(URI) |
| */ |
| public URI getLocationURI(); |
| |
| /** |
| * Returns the name of the described project. |
| * |
| * @return the name of the described project |
| */ |
| public String getName(); |
| |
| /** |
| * Returns the list of natures associated with the described project. |
| * Returns an empty array if there are no natures on this description. |
| * |
| * @return the list of natures for the described project |
| * @see #setNatureIds(String[]) |
| */ |
| public String[] getNatureIds(); |
| |
| /** |
| * Returns the projects referenced by the described project. These references |
| * are persisted in the project description file (".project") and as such |
| * will be shared whenever the project is exported to another workspace. For |
| * references that are likely to change from one workspace to another, dynamic |
| * references should be used instead. |
| * <p> |
| * The projects need not exist in the workspace. |
| * The result will not contain duplicates. Returns an empty |
| * array if there are no referenced projects on this description. |
| * |
| * @see #getDynamicReferences() |
| * @see #getBuildConfigReferences(String) |
| * @return a list of projects |
| */ |
| public IProject[] getReferencedProjects(); |
| |
| /** |
| * Returns whether the project nature specified by the given |
| * nature extension id has been added to the described project. |
| * |
| * @param natureId the nature extension identifier |
| * @return <code>true</code> if the described project has the given nature |
| */ |
| public boolean hasNature(String natureId); |
| |
| /** |
| * Returns a new build command. |
| * <p> |
| * Note that the new command does not become part of this project |
| * description's build spec until it is installed via the <code>setBuildSpec</code> |
| * method. |
| * </p> |
| * |
| * @return a new command |
| * @see #setBuildSpec(ICommand[]) |
| */ |
| public ICommand newCommand(); |
| |
| /** |
| * Sets the active configuration for the described project. |
| * <p> |
| * If a configuration with the specified name does not exist in the project then the |
| * first configuration in the project is treated as the active configuration. |
| * </p> |
| * |
| * @param configName the configuration to set as the active or default |
| * @since 3.7 |
| */ |
| public void setActiveBuildConfig(String configName); |
| |
| /** |
| * Sets the build configurations for the described project. |
| * <p> |
| * The passed in names must all be non-null. |
| * Before they are set, duplicates are removed. |
| * </p> |
| * <p> |
| * All projects have one default build configuration, and it is impossible to configure |
| * the project to have no build configurations. |
| * If the input is null or an empty list, the current configurations are removed, |
| * and a default build configuration is (re-)added. |
| * </p> |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @param configNames the configurations to set for the described project |
| * @see IProject#getActiveBuildConfig() |
| * @see IProject#getBuildConfigs() |
| * @see IProjectDescription#setActiveBuildConfig(String) |
| * @since 3.7 |
| */ |
| public void setBuildConfigs(String[] configNames); |
| |
| /** |
| * Sets the build configurations referenced by the specified configuration. |
| * <p> |
| * The configuration to which references are being added needs to exist in this |
| * description, but the referenced projects and build configurations need not exist. |
| * A reference with <code>null</code> configuration name is resolved to the active build configuration |
| * on use. |
| * Duplicates will be removed. The order of the referenced build configurations is preserved. |
| * If the given configuration does not exist in this description then this has no effect. |
| * </p> |
| * <p> |
| * References at the build configuration level take precedence over references at the project level. |
| * </p> |
| * <p> |
| * Like dynamic references, these build configuration references are persisted as part of workspace |
| * metadata. |
| * </p> |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @see #getBuildConfigReferences(String) |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @param configName the configuration in the described project to set the references for |
| * @param references list of build configuration references |
| * @since 3.7 |
| */ |
| public void setBuildConfigReferences(String configName, IBuildConfiguration[] references); |
| |
| /** |
| * Sets the list of build command to run when building the described project. |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @param buildSpec the array of build commands to run |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @see #getBuildSpec() |
| * @see #newCommand() |
| */ |
| public void setBuildSpec(ICommand[] buildSpec); |
| |
| /** |
| * Sets the comment for the described project. |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @param comment the comment for the described project |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @see #getComment() |
| */ |
| public void setComment(String comment); |
| |
| /** |
| * Sets the dynamic project references for the described project. |
| * The projects need not exist in the workspace. Duplicates will be |
| * removed. |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * @deprecated please use {@link IDynamicReferenceProvider} with the builders extension point to supply dynamic references |
| * @see #getDynamicReferences() |
| * @see #setBuildConfigReferences(String, IBuildConfiguration[]) |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @param projects list of projects |
| * @since 3.0 |
| */ |
| @Deprecated |
| public void setDynamicReferences(IProject[] projects); |
| |
| /** |
| * Sets the local file system location for the described project. The path must |
| * be either an absolute file system path, or a relative path whose first |
| * segment is the name of a defined workspace path variable. If |
| * <code>null</code> is specified, the default location is used. |
| * <p> |
| * Setting the location on a description for a project which already |
| * exists has no effect; the new project location is ignored when the |
| * description is set on the already existing project. This method is |
| * intended for use on descriptions for new projects or for destination |
| * projects for <code>copy</code> and <code>move</code>. |
| * </p> |
| * <p> |
| * This operation maps the root folder of the project to the exact location |
| * provided. For example, if the location for project named "P" is set |
| * to the path c:\my_plugins\Project1, the file resource at workspace path |
| * /P/index.html would be stored in the local file system at |
| * c:\my_plugins\Project1\index.html. |
| * </p> |
| * |
| * @param location the location for the described project or <code>null</code> |
| * @see #getLocation() |
| */ |
| public void setLocation(IPath location); |
| |
| /** |
| * Sets the location for the described project. |
| * If <code>null</code> is specified, the default location is used. |
| * <p> |
| * Setting the location on a description for a project which already |
| * exists has no effect; the new project location is ignored when the |
| * description is set on the already existing project. This method is |
| * intended for use on descriptions for new projects or for destination |
| * projects for <code>copy</code> and <code>move</code>. |
| * </p> |
| * <p> |
| * This operation maps the root folder of the project to the exact location |
| * provided. For example, if the location for project named "P" is set |
| * to the URI file://c:/my_plugins/Project1, the file resource at workspace path |
| * /P/index.html would be stored in the local file system at |
| * file://c:/my_plugins/Project1/index.html. |
| * </p> |
| * |
| * @param location the location for the described project or <code>null</code> |
| * @see #getLocationURI() |
| * @see IWorkspace#validateProjectLocationURI(IProject, URI) |
| * @since 3.2 |
| */ |
| public void setLocationURI(URI location); |
| |
| /** |
| * Sets the name of the described project. |
| * <p> |
| * Setting the name on a description and then setting the |
| * description on the project has no effect; the new name is ignored. |
| * </p> |
| * <p> |
| * Creating a new project with a description name which doesn't |
| * match the project handle name results in the description name |
| * being ignored; the project will be created using the name |
| * in the handle. |
| * </p> |
| * |
| * @param projectName the name of the described project |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @see #getName() |
| */ |
| public void setName(String projectName); |
| |
| /** |
| * Sets the list of natures associated with the described project. |
| * A project created with this description will have these natures |
| * added to it in the given order. |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @param natures the list of natures |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @see #getNatureIds() |
| */ |
| public void setNatureIds(String[] natures); |
| |
| /** |
| * Sets the referenced projects, ignoring any duplicates. |
| * The order of projects is preserved. |
| * The projects need not exist in the workspace. |
| * <p> |
| * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} |
| * before changes made to this description take effect. |
| * </p> |
| * |
| * @param projects a list of projects |
| * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) |
| * @see #setBuildConfigReferences(String, IBuildConfiguration[]) |
| * @see #getReferencedProjects() |
| */ |
| public void setReferencedProjects(IProject[] projects); |
| } |