IProjectDescription


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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 java.net.URI  ;
14  import org.eclipse.core.runtime.IPath;
15  import org.eclipse.core.runtime.IProgressMonitor;
16  
17  /**
18   * A project description contains the meta-data required to define
19   * a project.  In effect, a project description is a project's "content".
20   * <p>
21   * This interface is not intended to be implemented by clients.
22   * </p>
23   */
24  public interface IProjectDescription {
25      /**
26       * Constant that denotes the name of the project description file (value 
27       * <code>".project"</code>). 
28       * The handle of a project's description file is 
29       * <code>project.getFile(DESCRIPTION_FILE_NAME)</code>.
30       * The project description file is located in the root of the project's content area.
31       * 
32       * @since 2.0
33       */
34      public static final String   DESCRIPTION_FILE_NAME = ".project"; //$NON-NLS-1$
35  
36      /**
37       * Returns the list of build commands to run when building the described project.
38       * The commands are listed in the order in which they are to be run.
39       *
40       * @return the list of build commands for the described project 
41       */
42      public ICommand[] getBuildSpec();
43  
44      /**
45       * Returns the descriptive comment for the described project.
46       *
47       * @return the comment for the described project
48       */
49      public String   getComment();
50  
51      /**
52       * Returns the dynamic project references for the described project. Dynamic
53       * project references can be used instead of simple project references in cases
54       * where the reference information is computed dynamically be a third party.
55       * These references are persisted by the workspace in a private location outside
56       * the project description file, and as such will not be shared when a project is
57       * exported or persisted in a repository.  A client using project references
58       * is always responsible for setting these references when a project is created
59       * or recreated.
60       * <p>
61       * The returned projects need not exist in the workspace. The result will not 
62       * contain duplicates. Returns an empty array if there are no dynamic project 
63       * references on this description.
64       *
65       * @see #getReferencedProjects()
66       * @see #setDynamicReferences(IProject[])
67       * @return a list of projects
68       * @since 3.0
69       */
70      public IProject[] getDynamicReferences();
71  
72      /**
73       * Returns the  local file system location for the described project.  The path
74       * will be either an absolute file system path, or a relative path whose first
75       * segment is the name of a workspace path variable. <code>null</code> is
76       * returned if the default location should be used.  This method will return 
77       * <code>null</code> if this project is not located in the local file system.
78       *
79       * @return the location for the described project or <code>null</code>
80       * @deprecated Since 3.2, project locations are not necessarily in the local file
81       * system.  The more general {@link #getLocationURI()} method should be used instead.
82       */
83      public IPath getLocation();
84  
85      /**
86       * Returns the location URI for the described project.  <code>null</code> is
87       * returned if the default location should be used.
88       *
89       * @return the location for the described project or <code>null</code>
90       * @since 3.2
91       * @see #setLocationURI(URI)
92       */
93      public URI   getLocationURI();
94  
95      /**
96       * Returns the name of the described project.
97       *
98       * @return the name of the described project
99       */
100     public String   getName();
101 
102     /** 
103      * Returns the list of natures associated with the described project.
104      * Returns an empty array if there are no natures on this description.
105      *
106      * @return the list of natures for the described project
107      * @see #setNatureIds(String[])
108      */
109     public String  [] getNatureIds();
110 
111     /**
112      * Returns the projects referenced by the described project. These references
113      * are persisted in the project description file (&quot;.project&quot;) and as such
114      * will be shared whenever the project is exported to another workspace. For
115      * references that are likely to change from one workspace to another, dynamic
116      * references should be used instead.
117      * <p>
118      * The projects need not exist in the workspace.
119      * The result will not contain duplicates. Returns an empty
120      * array if there are no referenced projects on this description.
121      *
122      *@see #getDynamicReferences()
123      * @return a list of projects
124      */
125     public IProject[] getReferencedProjects();
126 
127     /** 
128      * Returns whether the project nature specified by the given
129      * nature extension id has been added to the described project. 
130      *
131      * @param natureId the nature extension identifier
132      * @return <code>true</code> if the described project has the given nature 
133      */
134     public boolean hasNature(String   natureId);
135 
136     /**
137      * Returns a new build command.
138      * <p>
139      * Note that the new command does not become part of this project
140      * description's build spec until it is installed via the <code>setBuildSpec</code>
141      * method.
142      * </p>
143      *
144      * @return a new command
145      * @see #setBuildSpec(ICommand[])
146      */
147     public ICommand newCommand();
148 
149     /**
150      * Sets the list of build command to run when building the described project.
151      * <p>
152      * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} 
153      * before changes made to this description take effect.
154      * </p>
155      *
156      * @param buildSpec the array of build commands to run
157      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
158      * @see #getBuildSpec()
159      * @see #newCommand()
160      */
161     public void setBuildSpec(ICommand[] buildSpec);
162 
163     /**
164      * Sets the comment for the described project.
165      * <p>
166      * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} 
167      * before changes made to this description take effect.
168      * </p>
169      *
170      * @param comment the comment for the described project
171      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
172      * @see #getComment()
173      */
174     public void setComment(String   comment);
175 
176     /**
177      * Sets the dynamic project references for the described project. 
178      * The projects need not exist in the workspace. Duplicates will be
179      * removed.  
180      * <p>
181      * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} 
182      * before changes made to this description take effect.
183      * </p>
184      * @see #getDynamicReferences()
185      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
186      * @param projects list of projects
187      * @since 3.0
188      */
189     public void setDynamicReferences(IProject[] projects);
190 
191     /**
192      * Sets the local file system location for the described project.  The path must
193      * be either an absolute file system path, or a relative path whose first
194      * segment is the name of a defined workspace path variable.  If
195      * <code>null</code> is specified, the default location is used.
196      * <p>
197      * Setting the location on a description for a project which already
198      * exists has no effect; the new project location is ignored when the
199      * description is set on the already existing project. This method is 
200      * intended for use on descriptions for new projects or for destination 
201      * projects for <code>copy</code> and <code>move</code>.
202      * </p>
203      * <p>
204      * This operation maps the root folder of the project to the exact location
205      * provided.  For example, if the location for project named "P" is set
206      * to the path c:\my_plugins\Project1, the file resource at workspace path
207      * /P/index.html  would be stored in the local file system at 
208      * c:\my_plugins\Project1\index.html.
209      * </p>
210      *
211      * @param location the location for the described project or <code>null</code>
212      * @see #getLocation()
213      */
214     public void setLocation(IPath location);
215 
216     /**
217      * Sets the location for the described project.  
218      * If <code>null</code> is specified, the default location is used.
219      * <p>
220      * Setting the location on a description for a project which already
221      * exists has no effect; the new project location is ignored when the
222      * description is set on the already existing project. This method is 
223      * intended for use on descriptions for new projects or for destination 
224      * projects for <code>copy</code> and <code>move</code>.
225      * </p>
226      * <p>
227      * This operation maps the root folder of the project to the exact location
228      * provided.  For example, if the location for project named "P" is set
229      * to the URI file://c:/my_plugins/Project1, the file resource at workspace path
230      * /P/index.html  would be stored in the local file system at 
231      * file://c:/my_plugins/Project1/index.html.
232      * </p>
233      *
234      * @param location the location for the described project or <code>null</code>
235      * @see #getLocationURI()
236      * @see IWorkspace#validateProjectLocationURI(IProject, URI)
237      * @since 3.2
238      */
239     public void setLocationURI(URI   location);
240 
241     /**
242      * Sets the name of the described project.
243      * <p>
244      * Setting the name on a description and then setting the 
245      * description on the project has no effect; the new name is ignored.
246      * </p>
247      * <p>
248      * Creating a new project with a description name which doesn't
249      * match the project handle name results in the description name
250      * being ignored; the project will be created using the name
251      * in the handle.
252      * </p>
253      *
254      * @param projectName the name of the described project
255      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
256      * @see #getName()
257      */
258     public void setName(String   projectName);
259 
260     /** 
261      * Sets the list of natures associated with the described project.
262      * A project created with this description will have these natures
263      * added to it in the given order.
264      * <p>
265      * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} 
266      * before changes made to this description take effect.
267      * </p>
268      *
269      * @param natures the list of natures
270      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
271      * @see #getNatureIds()
272      */
273     public void setNatureIds(String  [] natures);
274 
275     /**
276      * Sets the referenced projects, ignoring any duplicates.
277      * The order of projects is preserved.
278      * The projects need not exist in the workspace.
279      * <p>
280      * Users must call {@link IProject#setDescription(IProjectDescription, int, IProgressMonitor)} 
281      * before changes made to this description take effect.
282      * </p>
283      *
284      * @param projects a list of projects
285      * @see IProject#setDescription(IProjectDescription, int, IProgressMonitor)
286      * @see #getReferencedProjects()
287      */
288     public void setReferencedProjects(IProject[] projects);
289 }
290
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags