Java tutorial
/******************************************************************************* * 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 org.eclipse.core.runtime.IPath; import org.eclipse.core.runtime.IProgressMonitor; import java.net.URI; /** * 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> * @see #getDynamicReferences() * @see #setBuildConfigReferences(String, IBuildConfiguration[]) * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor) * @param projects list of projects * @since 3.0 */ 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); }