1 /******************************************************************************* 2 * Copyright (c) 2000, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 * Red Hat Incorporated - loadProjectDescription(InputStream) 14 * Broadcom Corporation - build configurations and references 15 *******************************************************************************/ 16 package org.eclipse.core.resources; 17 18 import java.io.InputStream; 19 import java.net.URI; 20 import java.util.Map; 21 import org.eclipse.core.resources.team.FileModificationValidationContext; 22 import org.eclipse.core.runtime.*; 23 import org.eclipse.core.runtime.jobs.ISchedulingRule; 24 25 /** 26 * Workspaces are the basis for Eclipse Platform resource management. There is 27 * only one workspace per running platform. All resources exist in the context 28 * of this workspace. 29 * <p> 30 * A workspace corresponds closely to discreet areas in the local file system. 31 * Each project in a workspace maps onto a specific area of the file system. The 32 * folders and files within a project map directly onto the corresponding 33 * directories and files in the file system. One sub-directory, the workspace 34 * metadata area, contains internal information about the workspace and its 35 * resources. This metadata area should be accessed only by the Platform or via 36 * Platform API calls. 37 * </p> 38 * <p> 39 * Workspaces add value over using the file system directly in that they allow 40 * for comprehensive change tracking (through <code>IResourceDelta</code> s), 41 * various forms of resource metadata (e.g., markers and properties) as well as 42 * support for managing application/tool state (e.g., saving and restoring). 43 * </p> 44 * <p> 45 * The workspace as a whole is thread safe and allows one writer concurrent with 46 * multiple readers. It also supports mechanisms for saving and snapshotting the 47 * current resource state. 48 * </p> 49 * <p> 50 * The workspace is provided by the Resources plug-in and is automatically 51 * created when that plug-in is activated. The default workspace data area 52 * (i.e., where its resources are stored) overlap exactly with the platform's 53 * data area. That is, by default, the workspace's projects are found directly 54 * in the platform's data area. Individual project locations can be specified 55 * explicitly. 56 * </p> 57 * <p> 58 * The workspace resource namespace is always case-sensitive and 59 * case-preserving. Thus the workspace allows multiple sibling resources to exist 60 * with names that differ only in case. The workspace also imposes no 61 * restrictions on valid characters in resource names, the length of resource names, 62 * or the size of resources on disk. In situations where one or more resources 63 * are stored in a file system that is not case-sensitive, or that imposes restrictions 64 * on resource names, any failure to store or retrieve those resources will 65 * be propagated back to the caller of workspace API. 66 * </p> 67 * <p> 68 * Workspaces implement the <code>IAdaptable</code> interface; extensions are 69 * managed by the platform's adapter manager. 70 * </p> 71 * 72 * @noimplement This interface is not intended to be implemented by clients. 73 * @noextend This interface is not intended to be extended by clients. 74 */ 75 public interface IWorkspace extends IAdaptable { 76 /** 77 * flag constant (bit mask value 1) indicating that resource change 78 * notifications should be avoided during the invocation of a compound 79 * resource changing operation. 80 * 81 * @see IWorkspace#run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor) 82 * @since 3.0 83 */ 84 int AVOID_UPDATE = 1; 85 86 /** 87 * Constant that can be passed to {@link #validateEdit(org.eclipse.core.resources.IFile[], Object)} 88 * to indicate that the caller does not have access to a UI context but would still 89 * like to have UI-based validation if possible. 90 * @since 3.3 91 * @see #validateEdit(IFile[], Object) 92 */ 93 Object VALIDATE_PROMPT = FileModificationValidationContext.VALIDATE_PROMPT; 94 95 /** 96 * The name of the IWorkspace OSGi service (value "org.eclipse.core.resources.IWorkspace"). 97 * @since 3.5 98 */ 99 String SERVICE_NAME = IWorkspace.class.getName(); 100 101 /** 102 * Adds the given listener for resource change events to this workspace. Has 103 * no effect if an identical listener is already registered. 104 * <p> 105 * This method is equivalent to: 106 * </p> 107 * 108 * <pre> 109 * addResourceChangeListener(listener, IResourceChangeEvent.PRE_CLOSE | IResourceChangeEvent.PRE_DELETE | IResourceChangeEvent.POST_CHANGE); 110 * </pre> 111 * 112 * 113 * @param listener the listener 114 * @see IResourceChangeListener 115 * @see IResourceChangeEvent 116 * @see #addResourceChangeListener(IResourceChangeListener, int) 117 * @see #removeResourceChangeListener(IResourceChangeListener) 118 */ addResourceChangeListener(IResourceChangeListener listener)119 void addResourceChangeListener(IResourceChangeListener listener); 120 121 /** 122 * Adds the given listener for the specified resource change events to this 123 * workspace. Has no effect if an identical listener is already registered 124 * for these events. After completion of this method, the given listener 125 * will be registered for exactly the specified events. If they were 126 * previously registered for other events, they will be de-registered. 127 * <p> 128 * Once registered, a listener starts receiving notification of changes to 129 * resources in the workspace. The resource deltas in the resource change 130 * event are rooted at the workspace root. Most resource change 131 * notifications occur well after the fact; the exception is 132 * pre-notification of impending project closures and deletions. The 133 * listener continues to receive notifications until it is replaced or 134 * removed. 135 * </p> 136 * <p> 137 * Listeners can listen for several types of event as defined in 138 * <code>IResourceChangeEvent</code>. Clients are free to register for 139 * any number of event types however if they register for more than one, it 140 * is their responsibility to ensure they correctly handle the case where 141 * the same resource change shows up in multiple notifications. Clients are 142 * guaranteed to receive only the events for which they are registered. 143 * </p> 144 * 145 * @param listener the listener 146 * @param eventMask the bit-wise OR of all event types of interest to the 147 * listener 148 * @see IResourceChangeListener 149 * @see IResourceChangeEvent 150 * @see #removeResourceChangeListener(IResourceChangeListener) 151 */ addResourceChangeListener(IResourceChangeListener listener, int eventMask)152 void addResourceChangeListener(IResourceChangeListener listener, int eventMask); 153 154 /** 155 * Registers the given plug-in's workspace save participant, and returns an 156 * object describing the workspace state at the time of the last save in 157 * which the plug-in participated. 158 * <p> 159 * Once registered, the workspace save participant will actively participate 160 * in the saving of this workspace. 161 * </p> 162 * 163 * @param plugin the plug-in 164 * @param participant the participant 165 * @return the last saved state in which the plug-in participated, or 166 * <code>null</code> if the plug-in has not participated before 167 * @exception CoreException if the method fails to add the participant. 168 * Reasons include: 169 * <ul> 170 * <li>The previous state could not be recovered.</li> 171 * </ul> 172 * @see ISaveParticipant 173 * @see #removeSaveParticipant(Plugin) 174 * @deprecated Use {@link #addSaveParticipant(String, ISaveParticipant)} instead 175 */ 176 @Deprecated addSaveParticipant(Plugin plugin, ISaveParticipant participant)177 ISavedState addSaveParticipant(Plugin plugin, ISaveParticipant participant) throws CoreException; 178 179 /** 180 * Registers the given plug-in's workspace save participant, and returns an 181 * object describing the workspace state at the time of the last save in 182 * which the bundle participated. 183 * <p> 184 * Once registered, the workspace save participant will actively participate 185 * in the saving of this workspace. 186 * </p> 187 * 188 * @param pluginId the unique identifier of the plug-in 189 * @param participant the participant 190 * @return the last saved state in which the plug-in participated, or 191 * <code>null</code> if the plug-in has not participated before 192 * @exception CoreException if the method fails to add the participant. 193 * Reasons include: 194 * <ul> 195 * <li>The previous state could not be recovered.</li> 196 * </ul> 197 * @see ISaveParticipant 198 * @see #removeSaveParticipant(String) 199 * @since 3.6 200 */ addSaveParticipant(String pluginId, ISaveParticipant participant)201 ISavedState addSaveParticipant(String pluginId, ISaveParticipant participant) throws CoreException; 202 203 /** 204 * Builds all projects in this workspace. Projects are built in the order 205 * specified in this workspace's description. Projects not mentioned in the 206 * order or for which the order cannot be determined are built in an 207 * undefined order after all other projects have been built. If no order is 208 * specified, the workspace computes an order determined by project 209 * references. 210 * <p> 211 * This method may change resources; these changes will be reported in a 212 * subsequent resource change event. 213 * </p> 214 * <p> 215 * This method is long-running; progress and cancellation are provided by 216 * the given progress monitor. 217 * </p> 218 * 219 * @param kind the kind of build being requested. Valid values are 220 * <ul> 221 * <li>{@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.</li> 222 * <li>{@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.</li> 223 * <li>{@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does 224 * not actually build anything, but rather discards all problems and build states.</li> 225 * </ul> 226 * @param monitor a progress monitor, or <code>null</code> if progress 227 * reporting is not desired 228 * @exception CoreException if the build fails. 229 * The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED} 230 * code, but it could also be any other status code; it might 231 * also be a {@link MultiStatus}. 232 * @exception OperationCanceledException if the operation is canceled. 233 * Cancelation can occur even if no progress monitor is provided. 234 * 235 * @see IWorkspace#build(IBuildConfiguration[], int, boolean, IProgressMonitor) 236 * @see IProject#build(int, IProgressMonitor) 237 * @see #computeProjectOrder(IProject[]) 238 * @see IncrementalProjectBuilder#FULL_BUILD 239 * @see IncrementalProjectBuilder#INCREMENTAL_BUILD 240 * @see IncrementalProjectBuilder#CLEAN_BUILD 241 * @see IResourceRuleFactory#buildRule() 242 */ build(int kind, IProgressMonitor monitor)243 void build(int kind, IProgressMonitor monitor) throws CoreException; 244 245 /** 246 * Build the build configurations specified in the passed in build configuration array. 247 * <p> 248 * Build order is determined by the workspace description and the project build configuration 249 * reference graph. 250 * </p> 251 * <p> 252 * If buildReferences is true, build configurations reachable through the build configuration graph are 253 * built as part of this build invocation. 254 * </p> 255 * <p> 256 * This method may change resources; these changes will be reported in a 257 * subsequent resource change event. 258 * </p> 259 * <p> 260 * This method is long-running; progress and cancellation are provided by 261 * the given progress monitor. 262 * </p> 263 * @param buildConfigs array of configurations to build 264 * @param kind the kind of build being requested. Valid values are 265 * <ul> 266 * <li>{@link IncrementalProjectBuilder#FULL_BUILD}- indicates a full build.</li> 267 * <li>{@link IncrementalProjectBuilder#INCREMENTAL_BUILD}- indicates a incremental build.</li> 268 * <li>{@link IncrementalProjectBuilder#CLEAN_BUILD}- indicates a clean request. Clean does 269 * not actually build anything, but rather discards all problems and build states.</li> 270 * </ul> 271 * @param buildReferences boolean indicating if references should be transitively built. 272 * @param monitor a progress monitor, or <code>null</code> if progress 273 * reporting is not desired 274 * @exception CoreException if the build fails. 275 * The status contained in the exception may be a generic {@link IResourceStatus#BUILD_FAILED} 276 * code, but it could also be any other status code; it might 277 * also be a {@link MultiStatus}. 278 * @exception OperationCanceledException if the operation is canceled. 279 * Cancellation can occur even if no progress monitor is provided. 280 * 281 * @see IProject#build(int, IProgressMonitor) 282 * @see IncrementalProjectBuilder#FULL_BUILD 283 * @see IncrementalProjectBuilder#INCREMENTAL_BUILD 284 * @see IncrementalProjectBuilder#CLEAN_BUILD 285 * @see IResourceRuleFactory#buildRule() 286 * @since 3.7 287 */ build(IBuildConfiguration[] buildConfigs, int kind, boolean buildReferences, IProgressMonitor monitor)288 void build(IBuildConfiguration[] buildConfigs, int kind, boolean buildReferences, IProgressMonitor monitor) throws CoreException; 289 290 /** 291 * Checkpoints the operation currently in progress. This method is used in 292 * the middle of a group of operations to force a background autobuild (if 293 * the build argument is true) and send an interim notification of resource 294 * change events. 295 * <p> 296 * When invoked in the dynamic scope of a call to the 297 * <code>IWorkspace.run</code> method, this method reports a single 298 * resource change event describing the net effect of all changes done to 299 * resources since the last round of notifications. When the outermost 300 * <code>run</code> method eventually completes, it will do another 301 * autobuild (if enabled) and report the resource changes made after this 302 * call. 303 * </p> 304 * <p> 305 * This method has no effect if invoked outside the dynamic scope of a call 306 * to the <code>IWorkspace.run</code> method. 307 * </p> 308 * <p> 309 * This method should be used under controlled circumstance (e.g., to break 310 * up extremely long-running operations). 311 * </p> 312 * 313 * @param build whether or not to run a build 314 * @see IWorkspace#run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor) 315 */ checkpoint(boolean build)316 void checkpoint(boolean build); 317 318 /** 319 * Returns the prerequisite ordering of the given projects. The computation 320 * is done by interpreting the projects' active build configuration references 321 * as dependency relationships. 322 * For example if A references B and C, and C references B, this method, 323 * given the list A, B, C will return the order B, C, A. That is, projects 324 * with no dependencies are listed first. 325 * <p> 326 * The return value is a two element array of project arrays. The first 327 * project array is the list of projects which could be sorted (as outlined 328 * above). The second element of the return value is an array of the 329 * projects which are ambiguously ordered (e.g., they are part of a cycle). 330 * </p> 331 * <p> 332 * Cycles and ambiguities are handled by elimination. Projects involved in 333 * cycles are simply cut out of the ordered list and returned in an 334 * undefined order. Closed and non-existent projects are ignored and do not 335 * appear in the returned value at all. 336 * </p> 337 * 338 * @param projects the projects to order 339 * @return the projects in sorted order and a list of projects which could 340 * not be ordered 341 * @deprecated Replaced by <code>IWorkspace.computeProjectOrder</code>, 342 * which produces a more usable result when there are cycles in project 343 * reference graph. 344 */ 345 @Deprecated computePrerequisiteOrder(IProject[] projects)346 IProject[][] computePrerequisiteOrder(IProject[] projects); 347 348 /** 349 * Data structure for holding the multi-part outcome of 350 * <code>IWorkspace.computeProjectOrder</code>. 351 * <p> 352 * This class is not intended to be instantiated by clients. 353 * </p> 354 * 355 * @see IWorkspace#computeProjectOrder(IProject[]) 356 * @since 2.1 357 */ 358 public final class ProjectOrder { 359 /** 360 * Creates an instance with the given values. 361 * <p> 362 * This class is not intended to be instantiated by clients. 363 * </p> 364 * 365 * @param projects initial value of <code>projects</code> field 366 * @param hasCycles initial value of <code>hasCycles</code> field 367 * @param knots initial value of <code>knots</code> field 368 */ ProjectOrder(IProject[] projects, boolean hasCycles, IProject[][] knots)369 public ProjectOrder(IProject[] projects, boolean hasCycles, IProject[][] knots) { 370 this.projects = projects; 371 this.hasCycles = hasCycles; 372 this.knots = knots; 373 } 374 375 /** 376 * A list of projects ordered so as to honor the project reference, and 377 * build configuration reference, relationships between these projects 378 * wherever possible. 379 * The elements are a subset of the ones passed as the <code>projects</code> 380 * parameter to <code>IWorkspace.computeProjectOrder</code>, where 381 * inaccessible (closed or non-existent) projects have been omitted. 382 */ 383 public IProject[] projects; 384 /** 385 * Indicates whether any of the accessible projects in 386 * <code>projects</code> are involved in non-trivial cycles. 387 * <code>true</code> if the reference graph contains at least 388 * one cycle involving two or more of the projects in 389 * <code>projects</code>, and <code>false</code> if none of the 390 * projects in <code>projects</code> are involved in cycles. 391 */ 392 public boolean hasCycles; 393 /** 394 * A list of knots in the project reference graph. This list is empty if 395 * the project reference graph does not contain cycles. If the project 396 * reference graph contains cycles, each element is a knot of two or 397 * more accessible projects from <code>projects</code> that are 398 * involved in a cycle of mutually dependent references. 399 */ 400 public IProject[][] knots; 401 } 402 403 /** 404 * Computes a total ordering of the given projects based on both static and 405 * dynamic project references. If an existing and open project P references 406 * another existing and open project Q also included in the list, then Q 407 * should come before P in the resulting ordering. Closed and non-existent 408 * projects are ignored, and will not appear in the result. References to 409 * non-existent or closed projects are also ignored, as are any 410 * self-references. The total ordering is always consistent with the global 411 * total ordering of all open projects in the workspace. 412 * <p> 413 * When there are choices, the choice is made in a reasonably stable way. 414 * For example, given an arbitrary choice between two projects, the one with 415 * the lower collating project name is usually selected. 416 * </p> 417 * <p> 418 * When the project reference graph contains cyclic references, it is 419 * impossible to honor all of the relationships. In this case, the result 420 * ignores as few relationships as possible. For example, if P2 references 421 * P1, P4 references P3, and P2 and P3 reference each other, then exactly 422 * one of the relationships between P2 and P3 will have to be ignored. The 423 * outcome will be either [P1, P2, P3, P4] or [P1, P3, P2, P4]. The result 424 * also contains complete details of any cycles present. 425 * </p> 426 * <p> 427 * This method is time-consuming and should not be called unnecessarily. 428 * There are a very limited set of changes to a workspace that could affect 429 * the outcome: creating, renaming, or deleting a project; opening or 430 * closing a project; adding or removing a project reference. 431 * </p> 432 * 433 * @param projects the projects to order 434 * @return result describing the project order 435 * @since 2.1 436 */ computeProjectOrder(IProject[] projects)437 ProjectOrder computeProjectOrder(IProject[] projects); 438 439 /** 440 * Copies the given sibling resources so that they are located as members of 441 * the resource at the given path; the names of the copies are the same as 442 * the corresponding originals. 443 * <p> 444 * This is a convenience method, fully equivalent to: 445 * </p> 446 * 447 * <pre> 448 * copy(resources, destination, (force ? IResource.FORCE : IResource.NONE), monitor); 449 * </pre> 450 * 451 * <p> 452 * This method changes resources; these changes will be reported in a 453 * subsequent resource change event that will include an indication that the 454 * resources have been added to the new parent. 455 * </p> 456 * <p> 457 * This method is long-running; progress and cancellation are provided by 458 * the given progress monitor. 459 * </p> 460 * 461 * @param resources the resources to copy 462 * @param destination the destination container path 463 * @param force a flag controlling whether resources that are not in sync 464 * with the local file system will be tolerated 465 * @param monitor a progress monitor, or <code>null</code> if progress 466 * reporting is not desired 467 * @return a status object with code <code>OK</code> if there were no 468 * problems; otherwise a description (possibly a multi-status) consisting of 469 * low-severity warnings or informational messages 470 * @exception CoreException if the method fails to copy some resources. The 471 * status contained in the exception may be a multi-status indicating where 472 * the individual failures occurred. 473 * @exception OperationCanceledException if the operation is canceled. 474 * Cancelation can occur even if no progress monitor is provided. 475 * @see #copy(IResource[],IPath,int,IProgressMonitor) 476 */ copy(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor)477 IStatus copy(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException; 478 479 /** 480 * Copies the given sibling resources so that they are located as members of 481 * the resource at the given path; the names of the copies are the same as 482 * the corresponding originals. 483 * <p> 484 * This method can be expressed as a series of calls to 485 * <code>IResource.copy(IPath,int,IProgressMonitor)</code>, with "best 486 * effort" semantics: 487 * </p> 488 * <ul> 489 * <li>Resources are copied in the order specified, using the given update 490 * flags.</li> 491 * <li>Duplicate resources are only copied once.</li> 492 * <li>The method fails if the resources are not all siblings.</li> 493 * <li>The failure of an individual copy does not necessarily prevent the 494 * method from attempting to copy other resources.</li> 495 * <li>The method fails if there are projects among the resources.</li> 496 * <li>The method fails if the path of the resources is a prefix of the 497 * destination path.</li> 498 * <li>This method also fails if one or more of the individual resource 499 * copy steps fails.</li> 500 * </ul> 501 * <p> 502 * After successful completion, corresponding new resources will now exist 503 * as members of the resource at the given path. 504 * </p> 505 * <p> 506 * The supplied path may be absolute or relative. Absolute paths fully 507 * specify the new location for the resource, including its project. 508 * Relative paths are considered to be relative to the container of the 509 * resources being copied. A trailing separator is ignored. 510 * </p> 511 * <p> 512 * This method changes resources; these changes will be reported in a 513 * subsequent resource change event that will include an indication that the 514 * resources have been added to the new parent. 515 * </p> 516 * <p> 517 * This method is long-running; progress and cancellation are provided by 518 * the given progress monitor. 519 * </p> 520 * 521 * @param resources the resources to copy 522 * @param destination the destination container path 523 * @param updateFlags bit-wise or of update flag constants 524 * @param monitor a progress monitor, or <code>null</code> if progress 525 * reporting is not desired 526 * @return a status object with code <code>OK</code> if there were no 527 * problems; otherwise a description (possibly a multi-status) consisting of 528 * low-severity warnings or informational messages 529 * @exception CoreException if the method fails to copy some resources. The 530 * status contained in the exception may be a multi-status indicating where 531 * the individual failures occurred. Reasons include: 532 * <ul> 533 * <li>One of the resources does not exist.</li> 534 * <li>The resources are not siblings.</li> 535 * <li>One of the resources, or one of its descendents, is not local.</li> 536 * <li>The resource corresponding to the destination path does not exist. 537 * </li> 538 * <li>The resource corresponding to the parent destination path is a 539 * closed project.</li> 540 * <li>A corresponding target resource does exist.</li> 541 * <li>A resource of a different type exists at the target path.</li> 542 * <li>One of the resources is a project.</li> 543 * <li>The path of one of the resources is a prefix of the destination 544 * path.</li> 545 * <li>One of the resources, or one of its descendents, is out of sync with 546 * the local file system and <code>FORCE</code> is not specified.</li> 547 * <li>Resource changes are disallowed during certain types of resource 548 * change event notification. See <code>IResourceChangeEvent</code> for 549 * more details.</li> 550 * </ul> 551 * @exception OperationCanceledException if the operation is canceled. 552 * Cancelation can occur even if no progress monitor is provided. 553 * @see IResource#copy(IPath,int,IProgressMonitor) 554 * @see IResourceRuleFactory#copyRule(IResource, IResource) 555 * @since 2.0 556 */ copy(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor)557 IStatus copy(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException; 558 559 /** 560 * Deletes the given resources. 561 * <p> 562 * This is a convenience method, fully equivalent to: 563 * </p> 564 * 565 * <pre> 566 * delete(resources, IResource.KEEP_HISTORY | (force ? IResource.FORCE : IResource.NONE), monitor); 567 * </pre> 568 * 569 * <p> 570 * This method changes resources; these changes will be reported in a 571 * subsequent resource change event. 572 * </p> 573 * <p> 574 * This method is long-running; progress and cancellation are provided by 575 * the given progress monitor. 576 * </p> 577 * 578 * @param resources the resources to delete 579 * @param force a flag controlling whether resources that are not in sync 580 * with the local file system will be tolerated 581 * @param monitor a progress monitor, or <code>null</code> if progress 582 * reporting is not desired 583 * @return status with code <code>OK</code> if there were no problems; 584 * otherwise a description (possibly a multi-status) consisting of 585 * low-severity warnings or informational messages 586 * @exception CoreException if the method fails to delete some resource. The 587 * status contained in the exception is a multi-status indicating where the 588 * individual failures occurred. 589 * @exception OperationCanceledException if the operation is canceled. 590 * Cancelation can occur even if no progress monitor is provided. 591 * @see #delete(IResource[],int,IProgressMonitor) 592 */ delete(IResource[] resources, boolean force, IProgressMonitor monitor)593 IStatus delete(IResource[] resources, boolean force, IProgressMonitor monitor) throws CoreException; 594 595 /** 596 * Deletes the given resources. 597 * <p> 598 * This method can be expressed as a series of calls to 599 * <code>IResource.delete(int,IProgressMonitor)</code>. 600 * </p> 601 * <p> 602 * The semantics of multiple deletion are: 603 * </p> 604 * <ul> 605 * <li>Resources are deleted in the order presented, using the given update 606 * flags.</li> 607 * <li>Resources that do not exist are ignored.</li> 608 * <li>An individual deletion fails if the resource still exists 609 * afterwards.</li> 610 * <li>The failure of an individual deletion does not prevent the method 611 * from attempting to delete other resources.</li> 612 * <li>This method fails if one or more of the individual resource 613 * deletions fails; that is, if at least one of the resources in the list 614 * still exists at the end of this method.</li> 615 * </ul> 616 * <p> 617 * This method changes resources; these changes will be reported in a 618 * subsequent resource change event. 619 * </p> 620 * <p> 621 * This method is long-running; progress and cancellation are provided by 622 * the given progress monitor. 623 * </p> 624 * 625 * @param resources the resources to delete 626 * @param updateFlags bit-wise or of update flag constants 627 * @param monitor a progress monitor, or <code>null</code> if progress 628 * reporting is not desired 629 * @return status with code <code>OK</code> if there were no problems; 630 * otherwise a description (possibly a multi-status) consisting of 631 * low-severity warnings or informational messages 632 * @exception CoreException if the method fails to delete some resource. The 633 * status contained in the exception is a multi-status indicating where the 634 * individual failures occurred. 635 * @exception OperationCanceledException if the operation is canceled. 636 * Cancelation can occur even if no progress monitor is provided. 637 * @see IResource#delete(int,IProgressMonitor) 638 * @see IResourceRuleFactory#deleteRule(IResource) 639 * @since 2.0 640 */ delete(IResource[] resources, int updateFlags, IProgressMonitor monitor)641 IStatus delete(IResource[] resources, int updateFlags, IProgressMonitor monitor) throws CoreException; 642 643 /** 644 * Removes the given markers from the resources with which they are 645 * associated. Markers that do not exist are ignored. 646 * <p> 647 * This method changes resources; these changes will be reported in a 648 * subsequent resource change event. 649 * </p> 650 * 651 * @param markers the markers to remove 652 * @exception CoreException if this method fails. Reasons include: 653 * <ul> 654 * <li>Resource changes are disallowed during certain types of resource 655 * change event notification. See <code>IResourceChangeEvent</code> for 656 * more details.</li> 657 * </ul> 658 * @see IResourceRuleFactory#markerRule(IResource) 659 */ deleteMarkers(IMarker[] markers)660 void deleteMarkers(IMarker[] markers) throws CoreException; 661 662 /** 663 * Forgets any resource tree being saved for the plug-in with the given 664 * name. If the plug-in id is <code>null</code>, all trees are forgotten. 665 * <p> 666 * Clients should not call this method unless they have a reason to do so. A 667 * plug-in which uses <code>ISaveContext.needDelta</code> in the process 668 * of a save indicates that it would like to be fed the resource delta the 669 * next time it is reactivated. If a plug-in never gets reactivated (or if 670 * it fails to successfully register to participate in workspace saves), the 671 * workspace nevertheless retains the necessary information to generate the 672 * resource delta if asked. This method allows such a long term leak to be 673 * plugged. 674 * </p> 675 * 676 * @param pluginId the unique identifier of the plug-in, or <code>null</code> 677 * @see ISaveContext#needDelta() 678 */ forgetSavedTree(String pluginId)679 void forgetSavedTree(String pluginId); 680 681 /** 682 * Returns all filter matcher descriptors known to this workspace. Returns an empty 683 * array if there are no installed filter matchers. 684 * 685 * @return the filter matcher descriptors known to this workspace 686 * @since 3.6 687 */ getFilterMatcherDescriptors()688 IFilterMatcherDescriptor[] getFilterMatcherDescriptors(); 689 690 /** 691 * Returns the filter descriptor with the given unique identifier, or 692 * <code>null</code> if there is no such filter. 693 * 694 * @param filterMatcherId the filter matcher extension identifier (e.g. 695 * <code>"com.example.coolFilter"</code>). 696 * @return the filter matcher descriptor, or <code>null</code> 697 * @since 3.6 698 */ getFilterMatcherDescriptor(String filterMatcherId)699 IFilterMatcherDescriptor getFilterMatcherDescriptor(String filterMatcherId); 700 701 /** 702 * Returns all nature descriptors known to this workspace. Returns an empty 703 * array if there are no installed natures. 704 * 705 * @return the nature descriptors known to this workspace 706 * @since 2.0 707 */ getNatureDescriptors()708 IProjectNatureDescriptor[] getNatureDescriptors(); 709 710 /** 711 * Returns the nature descriptor with the given unique identifier, or 712 * <code>null</code> if there is no such nature. 713 * 714 * @param natureId the nature extension identifier (e.g. 715 * <code>"com.example.coolNature"</code>). 716 * @return the nature descriptor, or <code>null</code> 717 * @since 2.0 718 */ getNatureDescriptor(String natureId)719 IProjectNatureDescriptor getNatureDescriptor(String natureId); 720 721 /** 722 * Finds all dangling project references in this workspace. Projects which 723 * are not open are ignored. Returns a map with one entry for each open 724 * project in the workspace that has at least one dangling project 725 * reference; the value of the entry is an array of projects which are 726 * referenced by that project but do not exist in the workspace. Returns an 727 * empty Map if there are no projects in the workspace. 728 * 729 * @return a map (key type: <code>IProject</code>, value type: 730 * <code>IProject[]</code>) from project to dangling project references 731 */ getDanglingReferences()732 Map<IProject, IProject[]> getDanglingReferences(); 733 734 /** 735 * Returns the workspace description. This object is responsible for 736 * defining workspace preferences. The returned value is a modifiable copy 737 * but changes are not automatically applied to the workspace. In order to 738 * changes take effect, <code>IWorkspace.setDescription</code> needs to be 739 * called. The workspace description values are store in the preference 740 * store. 741 * 742 * @return the workspace description 743 * @see #setDescription(IWorkspaceDescription) 744 */ getDescription()745 IWorkspaceDescription getDescription(); 746 747 /** 748 * Returns the root resource of this workspace. 749 * 750 * @return the workspace root 751 */ getRoot()752 IWorkspaceRoot getRoot(); 753 754 /** 755 * Returns a factory for obtaining scheduling rules prior to modifying 756 * resources in the workspace. 757 * 758 * @see IResourceRuleFactory 759 * @return a resource rule factory 760 * @since 3.0 761 */ getRuleFactory()762 IResourceRuleFactory getRuleFactory(); 763 764 /** 765 * Returns the synchronizer for this workspace. 766 * 767 * @return the synchronizer 768 * @see ISynchronizer 769 */ getSynchronizer()770 ISynchronizer getSynchronizer(); 771 772 /** 773 * Returns whether this workspace performs autobuilds. 774 * 775 * @return <code>true</code> if autobuilding is on, <code>false</code> 776 * otherwise 777 */ isAutoBuilding()778 boolean isAutoBuilding(); 779 780 /** 781 * Returns whether the workspace tree is currently locked. Resource changes 782 * are disallowed during certain types of resource change event 783 * notification. See <code>IResourceChangeEvent</code> for more details. 784 * 785 * @return boolean <code>true</code> if the workspace tree is locked, 786 * <code>false</code> otherwise 787 * @see IResourceChangeEvent 788 * @since 2.1 789 */ isTreeLocked()790 boolean isTreeLocked(); 791 792 /** 793 * Reads the project description file (".project") from the given location 794 * in the local file system. This object is useful for discovering the 795 * correct name for a project before importing it into the workspace. 796 * <p> 797 * The returned value is writeable. 798 * </p> 799 * 800 * @param projectDescriptionFile the path in the local file system of an 801 * existing project description file 802 * @return a new project description 803 * @exception CoreException if the operation failed. Reasons include: 804 * <ul> 805 * <li>The project description file does not exist.</li> 806 * <li>The file cannot be opened or read.</li> 807 * <li>The file cannot be parsed as a legal project description.</li> 808 * </ul> 809 * @see #newProjectDescription(String) 810 * @see IProject#getDescription() 811 * @since 2.0 812 */ loadProjectDescription(IPath projectDescriptionFile)813 IProjectDescription loadProjectDescription(IPath projectDescriptionFile) throws CoreException; 814 815 /** 816 * Reads the project description file (".project") from the given InputStream. 817 * This object will not attempt to set the location since the project may not 818 * have a valid location on the local file system. 819 * This object is useful for discovering the correct name for a project before 820 * importing it into the workspace. 821 * <p> 822 * The returned value is writeable. 823 * </p> 824 * 825 * @param projectDescriptionFile an InputStream pointing to an existing project 826 * description file 827 * @return a new project description 828 * @exception CoreException if the operation failed. Reasons include: 829 * <ul> 830 * <li>The stream could not be read.</li> 831 * <li>The stream does not contain a legal project description.</li> 832 * </ul> 833 * @see #newProjectDescription(String) 834 * @see IProject#getDescription() 835 * @see IWorkspace#loadProjectDescription(IPath) 836 * @since 3.1 837 */ loadProjectDescription(InputStream projectDescriptionFile)838 IProjectDescription loadProjectDescription(InputStream projectDescriptionFile) throws CoreException; 839 840 /** 841 * Moves the given sibling resources so that they are located as members of 842 * the resource at the given path; the names of the new members are the 843 * same. 844 * <p> 845 * This is a convenience method, fully equivalent to: 846 * </p> 847 * 848 * <pre> 849 * move(resources, destination, IResource.KEEP_HISTORY | (force ? IResource.FORCE : IResource.NONE), monitor); 850 * </pre> 851 * 852 * <p> 853 * This method changes resources; these changes will be reported in a 854 * subsequent resource change event that will include an indication that the 855 * resources have been removed from their parent and that corresponding 856 * resources have been added to the new parent. Additional information 857 * provided with resource delta shows that these additions and removals are 858 * pairwise related. 859 * </p> 860 * <p> 861 * This method is long-running; progress and cancellation are provided by 862 * the given progress monitor. 863 * </p> 864 * 865 * @param resources the resources to move 866 * @param destination the destination container path 867 * @param force a flag controlling whether resources that are not in sync 868 * with the local file system will be tolerated 869 * @param monitor a progress monitor, or <code>null</code> if progress 870 * reporting is not desired 871 * @return status with code <code>OK</code> if there were no problems; 872 * otherwise a description (possibly a multi-status) consisting of 873 * low-severity warnings or informational messages. 874 * @exception CoreException if the method fails to move some resources. The 875 * status contained in the exception may be a multi-status indicating where 876 * the individual failures occurred. 877 * @exception OperationCanceledException if the operation is canceled. 878 * Cancelation can occur even if no progress monitor is provided. 879 * @see #move(IResource[],IPath,int,IProgressMonitor) 880 */ move(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor)881 IStatus move(IResource[] resources, IPath destination, boolean force, IProgressMonitor monitor) throws CoreException; 882 883 /** 884 * Moves the given sibling resources so that they are located as members of 885 * the resource at the given path; the names of the new members are the 886 * same. 887 * <p> 888 * This method can be expressed as a series of calls to 889 * <code>IResource.move</code>, with "best effort" semantics: 890 * </p> 891 * <ul> 892 * <li>Resources are moved in the order specified.</li> 893 * <li>Duplicate resources are only moved once.</li> 894 * <li>The <code>force</code> flag has the same meaning as it does on the 895 * corresponding single-resource method.</li> 896 * <li>The method fails if the resources are not all siblings.</li> 897 * <li>The method fails the path of any of the resources is a prefix of the 898 * destination path.</li> 899 * <li>The failure of an individual move does not necessarily prevent the 900 * method from attempting to move other resources.</li> 901 * <li>This method also fails if one or more of the individual resource 902 * moves fails; that is, if at least one of the resources in the list still 903 * exists at the end of this method.</li> 904 * <li>History is kept for moved files. When projects are moved, no history 905 * is kept</li> 906 * </ul> 907 * <p> 908 * After successful completion, the resources and descendents will no longer 909 * exist; but corresponding new resources will now exist as members of the 910 * resource at the given path. 911 * </p> 912 * <p> 913 * The supplied path may be absolute or relative. Absolute paths fully 914 * specify the new location for the resource, including its project. 915 * Relative paths are considered to be relative to the container of the 916 * resources being moved. A trailing separator is ignored. 917 * </p> 918 * <p> 919 * This method changes resources; these changes will be reported in a 920 * subsequent resource change event that will include an indication that the 921 * resources have been removed from their parent and that corresponding 922 * resources have been added to the new parent. Additional information 923 * provided with resource delta shows that these additions and removals are 924 * pairwise related. 925 * </p> 926 * <p> 927 * This method is long-running; progress and cancellation are provided by 928 * the given progress monitor. 929 * </p> 930 * 931 * @param resources the resources to move 932 * @param destination the destination container path 933 * @param updateFlags bit-wise or of update flag constants 934 * @param monitor a progress monitor, or <code>null</code> if progress 935 * reporting is not desired 936 * @return status with code <code>OK</code> if there were no problems; 937 * otherwise a description (possibly a multi-status) consisting of 938 * low-severity warnings or informational messages. 939 * @exception CoreException if the method fails to move some resources. The 940 * status contained in the exception may be a multi-status indicating where 941 * the individual failures occurred. Reasons include: 942 * <ul> 943 * <li>One of the resources does not exist.</li> 944 * <li>The resources are not siblings.</li> 945 * <li>One of the resources, or one of its descendents, is not local.</li> 946 * <li>The resource corresponding to the destination path does not exist. 947 * </li> 948 * <li>The resource corresponding to the parent destination path is a 949 * closed project.</li> 950 * <li>A corresponding target resource does exist.</li> 951 * <li>A resource of a different type exists at the target path.</li> 952 * <li>The path of one of the resources is a prefix of the destination 953 * path.</li> 954 * <li>One of the resources, or one of its descendents, is out of sync with 955 * the local file system and <code>FORCE</code> is <code>false</code>. 956 * </li> 957 * <li>Resource changes are disallowed during certain types of resource 958 * change event notification. See <code>IResourceChangeEvent</code> for 959 * more details.</li> 960 * </ul> 961 * @exception OperationCanceledException if the operation is canceled. 962 * Cancelation can occur even if no progress monitor is provided. 963 * @see IResource#move(IPath,int,IProgressMonitor) 964 * @see IResourceRuleFactory#moveRule(IResource, IResource) 965 * @since 2.0 966 */ move(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor)967 IStatus move(IResource[] resources, IPath destination, int updateFlags, IProgressMonitor monitor) throws CoreException; 968 969 /** 970 * Returns a new build configuration for the project, with the given name. 971 * The name is a human readable unique name for the build configuration in the 972 * project. The project need not exist. 973 *<p> 974 * This API can be used to create {@link IBuildConfiguration}s that will be used as references 975 * to {@link IBuildConfiguration}s in other projects. These references are set using 976 * {@link IProjectDescription#setBuildConfigReferences(String, IBuildConfiguration[])} 977 * and may have a <code>null</code> configuration name which will resolve to the referenced 978 * project's active configuration when the reference is used. 979 *</p> 980 *<p> 981 * Build configuration do not become part of a project 982 * description until set using {@link IProjectDescription#setBuildConfigs(String[])}. 983 *</p> 984 * 985 * @param projectName the name of the project on which the configuration will exist 986 * @param configName the name of the new build configuration 987 * @return a build configuration 988 * @see IProjectDescription#setBuildConfigs(String[]) 989 * @see IProjectDescription#setBuildConfigReferences(String, IBuildConfiguration[]) 990 * @see IBuildConfiguration 991 * @since 3.7 992 */ newBuildConfig(String projectName, String configName)993 IBuildConfiguration newBuildConfig(String projectName, String configName); 994 995 /** 996 * Creates and returns a new project description for a project with the 997 * given name. This object is useful when creating, moving or copying 998 * projects. 999 * <p> 1000 * The project description is initialized to: 1001 * </p> 1002 * <ul> 1003 * <li>the given project name</li> 1004 * <li>no references to other projects</li> 1005 * <li>an empty build spec</li> 1006 * <li>an empty comment</li> 1007 * </ul> 1008 * <p> 1009 * The returned value is writeable. 1010 * </p> 1011 * 1012 * @param projectName the name of the project 1013 * @return a new project description 1014 * @see IProject#getDescription() 1015 * @see IProject#create(IProjectDescription, IProgressMonitor) 1016 * @see IResource#copy(IProjectDescription, int, IProgressMonitor) 1017 * @see IProject#move(IProjectDescription, boolean, IProgressMonitor) 1018 */ newProjectDescription(String projectName)1019 IProjectDescription newProjectDescription(String projectName); 1020 1021 /** 1022 * Removes the given resource change listener from this workspace. Has no 1023 * effect if an identical listener is not registered. 1024 * 1025 * @param listener the listener 1026 * @see IResourceChangeListener 1027 * @see #addResourceChangeListener(IResourceChangeListener) 1028 */ removeResourceChangeListener(IResourceChangeListener listener)1029 void removeResourceChangeListener(IResourceChangeListener listener); 1030 1031 /** 1032 * Removes the workspace save participant for the given plug-in from this 1033 * workspace. If no such participant is registered, no action is taken. 1034 * <p> 1035 * Once removed, the workspace save participant no longer actively 1036 * participates in any future saves of this workspace. 1037 * </p> 1038 * 1039 * @param plugin the plug-in 1040 * @see ISaveParticipant 1041 * @see #addSaveParticipant(Plugin, ISaveParticipant) 1042 * @deprecated Use {@link #removeSaveParticipant(String)} instead 1043 */ 1044 @Deprecated removeSaveParticipant(Plugin plugin)1045 void removeSaveParticipant(Plugin plugin); 1046 1047 /** 1048 * Removes the workspace save participant for the given plug-in from this 1049 * workspace. If no such participant is registered, no action is taken. 1050 * <p> 1051 * Once removed, the workspace save participant no longer actively 1052 * participates in any future saves of this workspace. 1053 * </p> 1054 * 1055 * @param pluginId the unique identifier of the plug-in 1056 * @see ISaveParticipant 1057 * @see #addSaveParticipant(String, ISaveParticipant) 1058 * @since 3.6 1059 */ removeSaveParticipant(String pluginId)1060 void removeSaveParticipant(String pluginId); 1061 1062 /** 1063 * Runs the given action as an atomic workspace operation. 1064 * <p> 1065 * After running a method that modifies resources in the workspace, 1066 * registered listeners receive after-the-fact notification of what just 1067 * transpired, in the form of a resource change event. This method allows 1068 * clients to call a number of methods that modify resources and only have 1069 * resource change event notifications reported at the end of the entire 1070 * batch. 1071 * </p> 1072 * <p> 1073 * If this method is called outside the dynamic scope of another such call, 1074 * this method runs the action and then reports a single resource change 1075 * event describing the net effect of all changes done to resources by the 1076 * action. 1077 * </p> 1078 * <p> 1079 * If this method is called in the dynamic scope of another such call, this 1080 * method simply runs the action. 1081 * </p> 1082 * <p> 1083 * The supplied scheduling rule is used to determine whether this operation 1084 * can be run simultaneously with workspace changes in other threads. If the 1085 * scheduling rule conflicts with another workspace change that is currently 1086 * running, the calling thread will be blocked until that change completes. 1087 * If the action attempts to make changes to the workspace that were not 1088 * specified in the scheduling rule, it will fail. If no scheduling rule is 1089 * supplied, there are no scheduling restrictions for this operation. 1090 * If a non-<code>null</code> scheduling rule is supplied, this operation 1091 * must always support cancelation in the case where this operation becomes 1092 * blocked by a long running background operation. 1093 * </p> 1094 * <p> 1095 * The AVOID_UPDATE flag controls whether periodic resource change 1096 * notifications should occur during the scope of this call. If this flag is 1097 * specified, and no other threads modify the workspace concurrently, then 1098 * all resource change notifications will be deferred until the end of this 1099 * call. If this flag is not specified, the platform may decide to broadcast 1100 * periodic resource change notifications during the scope of this call. 1101 * </p> 1102 * <p> 1103 * Flags other than <code>AVOID_UPDATE</code> are ignored. 1104 * </p> 1105 * 1106 * @param action the action to perform 1107 * @param rule the scheduling rule to use when running this operation, or 1108 * <code>null</code> if there are no scheduling restrictions for this 1109 * operation. 1110 * @param flags bit-wise or of flag constants (only AVOID_UPDATE is relevant 1111 * here) 1112 * @param monitor a progress monitor, or <code>null</code> if progress 1113 * reporting is not desired. 1114 * @exception CoreException if the operation failed. 1115 * @exception OperationCanceledException if the operation is canceled. If a 1116 * non-<code>null</code> scheduling rule is supplied, cancelation can occur 1117 * even if no progress monitor is provided. 1118 * 1119 * @see #AVOID_UPDATE 1120 * @see IResourceRuleFactory 1121 * @since 3.11 1122 */ run(ICoreRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor)1123 void run(ICoreRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException; 1124 1125 /** 1126 * Runs the given action as an atomic workspace operation. 1127 * <p> 1128 * This is a convenience method, fully equivalent to: 1129 * </p> 1130 * 1131 * <pre> 1132 * workspace.run(action, workspace.getRoot(), IWorkspace.AVOID_UPDATE, monitor); 1133 * </pre> 1134 * 1135 * 1136 * @param action the action to perform 1137 * @param monitor a progress monitor, or <code>null</code> if progress 1138 * reporting is not desired 1139 * @exception CoreException if the operation failed. 1140 * @exception OperationCanceledException if the operation is canceled. 1141 * Cancelation can occur even if no progress monitor is provided. 1142 * 1143 * @see #run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor) 1144 * @since 3.11 1145 */ run(ICoreRunnable action, IProgressMonitor monitor)1146 void run(ICoreRunnable action, IProgressMonitor monitor) throws CoreException; 1147 1148 /** 1149 * Identical to {@link #run(ICoreRunnable, ISchedulingRule, int, IProgressMonitor)}. 1150 * New code should use that method. 1151 * 1152 * @param action the action to perform 1153 * @param rule the scheduling rule to use when running this operation, or 1154 * <code>null</code> if there are no scheduling restrictions for this 1155 * operation. 1156 * @param flags bit-wise or of flag constants (only AVOID_UPDATE is relevant 1157 * here) 1158 * @param monitor a progress monitor, or <code>null</code> if progress 1159 * reporting is not desired. 1160 * @exception CoreException if the operation failed. 1161 * @since 3.0 1162 */ run(IWorkspaceRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor)1163 void run(IWorkspaceRunnable action, ISchedulingRule rule, int flags, IProgressMonitor monitor) throws CoreException; 1164 1165 /** 1166 * Identical to {@link #run(ICoreRunnable, IProgressMonitor)}. 1167 * New code should use that method. 1168 * 1169 * @param action the action to perform 1170 * @param monitor a progress monitor, or <code>null</code> if progress 1171 * reporting is not desired 1172 * @exception CoreException if the operation failed. 1173 */ run(IWorkspaceRunnable action, IProgressMonitor monitor)1174 void run(IWorkspaceRunnable action, IProgressMonitor monitor) throws CoreException; 1175 1176 /** 1177 * Saves this workspace's valuable state on disk. Consults with all 1178 * registered plug-ins so that they can coordinate the saving of their 1179 * persistent state as well. 1180 * <p> 1181 * The <code>full</code> parameter indicates whether a full save or a 1182 * snapshot is being requested. Snapshots save the workspace information 1183 * that is considered hard to be recomputed in the unlikely event of a 1184 * crash. It includes parts of the workspace tree, workspace and projects 1185 * descriptions, markers and sync information. Full saves are heavy weight 1186 * operations which save the complete workspace state. 1187 * </p> 1188 * <p> 1189 * To ensure that all outstanding changes to the workspace have been 1190 * reported to interested parties prior to saving, a full save cannot be 1191 * used within the dynamic scope of an <code>IWorkspace.run</code> 1192 * invocation. Snapshots can be called any time and are interpreted by the 1193 * workspace as a hint that a snapshot is required. The workspace will 1194 * perform the snapshot when possible. Even as a hint, snapshots should only 1195 * be called when necessary as they impact system performance. Although 1196 * saving does not change the workspace per se, its execution is serialized 1197 * like methods that write the workspace. 1198 * </p> 1199 * <p> 1200 * The workspace is comprised of several different kinds of data with 1201 * varying degrees of importance. The most important data, the resources 1202 * themselves and their persistent properties, are written to disk 1203 * immediately; other data are kept in volatile memory and only written to 1204 * disk periodically; and other data are maintained in memory and never 1205 * written out. The following table summarizes what gets saved when:</p> 1206 * <ul> 1207 * <li>creating or deleting resource - immediately</li> 1208 * <li>setting contents of file - immediately</li> 1209 * <li>changes to project description - immediately</li> 1210 * <li>session properties - never</li> 1211 * <li>changes to persistent properties - immediately</li> 1212 * <li>markers -<code>save</code></li> 1213 * <li>synchronizer info -<code>save</code></li> 1214 * <li>shape of the workspace resource tree -<code>save</code></li> 1215 * <li>list of active plug-ins - never</li> 1216 * </ul> 1217 * <p> 1218 * Resource-based plug-in also have data with varying degrees of importance. 1219 * Each plug-in gets to decide the policy for protecting its data, either 1220 * immediately, never, or at <code>save</code> time. For the latter, the 1221 * plug-in coordinates its actions with the workspace (see 1222 * <code>ISaveParticipant</code> for details). 1223 * </p> 1224 * <p> 1225 * If the platform is shutdown (or crashes) after saving the workspace, any 1226 * information written to disk by the last successful workspace 1227 * <code>save</code> will be restored the next time the workspace is 1228 * reopened for the next session. Naturally, information that is written to 1229 * disk immediately will be as of the last time it was changed. 1230 * </p> 1231 * <p> 1232 * The workspace provides a general mechanism for keeping concerned parties 1233 * apprised of any and all changes to resources in the workspace ( 1234 * <code>IResourceChangeListener</code>). It is even possible for a 1235 * plug-in to find out about changes to resources that happen between 1236 * workspace sessions (see <code>IWorkspace.addSaveParticipant</code>). 1237 * </p> 1238 * <p> 1239 * At certain points during this method, the entire workspace resource tree 1240 * must be locked to prevent resources from being changed (read access to 1241 * resources is permitted). 1242 * </p> 1243 * <p> 1244 * Implementation note: The execution sequence is as follows. 1245 * <ul> 1246 * <li>A long-term lock on the workspace is taken out to prevent further 1247 * changes to workspace until the save is done.</li> 1248 * <li>The list of saveable resource tree snapshots is initially empty. 1249 * </li> 1250 * <li>A different <code>ISaveContext</code> object is created for each 1251 * registered workspace save participant plug-in, reflecting the kind of 1252 * save (<code>ISaveContext.getKind</code>), the previous save number in 1253 * which this plug-in actively participated, and the new save number (= 1254 * previous save number plus 1).</li> 1255 * <li>Each registered workspace save participant is sent 1256 * <code>prepareToSave(context)</code>, passing in its own context 1257 * object. 1258 * <ul> 1259 * <li>Plug-in suspends all activities until further notice.</li> 1260 * </ul> 1261 * If <code>prepareToSave</code> fails (throws an exception), the problem 1262 * is logged and the participant is marked as unstable.</li> 1263 * <li>In dependent-before-prerequisite order, each registered workspace 1264 * save participant is sent <code>saving(context)</code>, passing in its 1265 * own context object. 1266 * <ul> 1267 * <li>Plug-in decides whether it wants to actively participate in this 1268 * save. The plug-in only needs to actively participate if some of its 1269 * important state has changed since the last time it actively participated. 1270 * If it does decide to actively participate, it writes its important state 1271 * to a brand new file in its plug-in state area under a generated file name 1272 * based on <code>context.getStateNumber()</code> and calls 1273 * <code>context.needStateNumber()</code> to indicate that it has actively 1274 * participated. If upon reactivation the plug-in will want a resource delta 1275 * covering all changes between now and then, the plug-in should invoke 1276 * <code>context.needDelta()</code> to request this now; otherwise, a 1277 * resource delta for the intervening period will not be available on 1278 * reactivation.</li> 1279 * </ul> 1280 * If <code>saving</code> fails (throws an exception), the problem is 1281 * logged and the participant is marked as unstable.</li> 1282 * <li>The plug-in save table contains an entry for each plug-in that has 1283 * registered to participate in workspace saves at some time in the past 1284 * (the list of plug-ins increases monotonically). Each entry records the 1285 * save number of the last successful save in which that plug-in actively 1286 * participated, and, optionally, a saved resource tree (conceptually, this 1287 * is a complete tree; in practice, it is compressed into a special delta 1288 * tree representation). A copy of the plug-in save table is made. Entries 1289 * are created or modified for each registered plug-in to record the 1290 * appropriate save number (either the previous save number, or the previous 1291 * save number plus 1, depending on whether the participant was active and 1292 * asked for a new number).</li> 1293 * <li>The workspace tree, the modified copy of the plug-in save table, all 1294 * markers, etc. and all saveable resource tree snapshots are written to 1295 * disk as <b>one atomic operation </b>.</li> 1296 * <li>The long-term lock on the workspace is released.</li> 1297 * <li>If the atomic save succeeded: 1298 * <ul> 1299 * <li>The modified copy of the plug-in save table becomes the new plug-in 1300 * save table.</li> 1301 * <li>In prerequisite-before-dependent order, each registered workspace 1302 * save participant is sent <code>doneSaving(context)</code>, passing in 1303 * its own context object. 1304 * <ul> 1305 * <li>Plug-in may perform clean up by deleting obsolete state files in its 1306 * plug-in state area.</li> 1307 * <li>Plug-in resumes its normal activities.</li> 1308 * </ul> 1309 * If <code>doneSaving</code> fails (throws an exception), the problem is 1310 * logged and the participant is marked as unstable. (The state number in 1311 * the save table is not rolled back just because of this instability.) 1312 * </li> 1313 * <li>The workspace save operation returns.</li> 1314 * </ul> 1315 * <li>If it failed:</li> 1316 * <li><ul> 1317 * <li>The workspace previous state is restored.</li> 1318 * <li>In prerequisite-before-dependent order, each registered workspace 1319 * save participant is sent <code>rollback(context)</code>, passing in 1320 * its own context object. 1321 * </li> 1322 * <li><ul> 1323 * <li>Plug-in may perform clean up by deleting newly-created but obsolete 1324 * state file in its plug-in state area.</li> 1325 * <li>Plug-in resumes its normal activities.</li> 1326 * </ul></li><li> 1327 * If <code>rollback</code> fails (throws an exception), the problem is 1328 * logged and the participant is marked as unstable. (The state number in 1329 * the save table is rolled back anyway.)</li> 1330 * <li>The workspace save operation fails.</li> 1331 * </ul> 1332 * </li> 1333 * </ul> 1334 * <p> 1335 * After a full save, the platform can be shutdown. This will cause the 1336 * Resources plug-in and all the other plug-ins to shutdown, without 1337 * disturbing the saved workspace on disk. 1338 * </p> 1339 * <p> 1340 * When the platform is later restarted, activating the Resources plug-in 1341 * opens the saved workspace. This reads into memory the workspace's 1342 * resource tree, plug-in save table, and saved resource tree snapshots 1343 * (everything that was written to disk in the atomic operation above). 1344 * Later, when a plug-in gets reactivated and registers to participate in 1345 * workspace saves, it is handed back the info from its entry in the plug-in 1346 * save table, if it has one. It gets back the number of the last save in 1347 * which it actively participated and, possibly, a resource delta. 1348 * </p> 1349 * <p> 1350 * The only source of long term garbage would come from a plug-in that never 1351 * gets reactivated, or one that gets reactivated but fails to register for 1352 * workspace saves. (There is no such problem with a plug-in that gets 1353 * uninstalled; its easy enough to scrub its state areas and delete its 1354 * entry in the plug-in save table.) 1355 * </p> 1356 * 1357 * @param full <code>true</code> if this is a full save, and 1358 * <code>false</code> if this is only a snapshot for protecting against 1359 * crashes 1360 * @param monitor a progress monitor, or <code>null</code> if progress 1361 * reporting is not desired 1362 * @return a status that may contain warnings, such as the failure of an 1363 * individual participant 1364 * @exception CoreException if this method fails to save the state of this 1365 * workspace. Reasons include: 1366 * <ul> 1367 * <li>The operation cannot be batched with others.</li> 1368 * </ul> 1369 * @exception OperationCanceledException if the operation is canceled. 1370 * Cancelation can occur even if no progress monitor is provided. 1371 * @see #addSaveParticipant(Plugin, ISaveParticipant) 1372 */ save(boolean full, IProgressMonitor monitor)1373 IStatus save(boolean full, IProgressMonitor monitor) throws CoreException; 1374 1375 /** 1376 * Sets the workspace description. Its values are stored in the preference 1377 * store. 1378 * 1379 * @param description the new workspace description. 1380 * @see #getDescription() 1381 * @exception CoreException if the method fails. Reasons include: 1382 * <ul> 1383 * <li>There was a problem setting the workspace description.</li> 1384 * </ul> 1385 */ setDescription(IWorkspaceDescription description)1386 void setDescription(IWorkspaceDescription description) throws CoreException; 1387 1388 /** 1389 * Returns a copy of the given set of natures sorted in prerequisite order. 1390 * For each nature, it is guaranteed that all of its prerequisites will 1391 * precede it in the resulting array. 1392 * 1393 * <p> 1394 * Natures that are missing from the install or are involved in a 1395 * prerequisite cycle are sorted arbitrarily. Duplicate nature IDs are 1396 * removed, so the returned array may be smaller than the original. 1397 * </p> 1398 * 1399 * @param natureIds a valid set of nature extension identifiers 1400 * @return the set of nature Ids sorted in prerequisite order 1401 * @see #validateNatureSet(String[]) 1402 * @since 2.0 1403 */ sortNatureSet(String[] natureIds)1404 String[] sortNatureSet(String[] natureIds); 1405 1406 /** 1407 * Advises that the caller intends to modify the contents of the given files 1408 * in the near future and asks whether modifying all these files would be 1409 * reasonable. The files must all exist. This method is used to give the VCM 1410 * component an opportunity to check out (or otherwise prepare) the files if 1411 * required. (It is provided in this component rather than in the UI so that 1412 * "core" (i.e., head-less) clients can use it. Similarly, it is located 1413 * outside the VCM component for the convenience of clients that must also 1414 * operate in configurations without VCM.) 1415 * <p> 1416 * A client (such as an editor) should perform a <code>validateEdit</code> 1417 * on a file whenever it finds itself in the following position: (a) the 1418 * file is marked read-only, and (b) the client believes it likely (not 1419 * necessarily certain) that it will modify the file's contents at some 1420 * point. A case in point is an editor that has a buffer opened on a file. 1421 * When the user starts to dirty the buffer, the editor should check to see 1422 * whether the file is read-only. If it is, it should call 1423 * <code>validateEdit</code>, and can reasonably expect this call, when 1424 * successful, to cause the file to become read-write. An editor should also 1425 * be sensitive to a file becoming read-only again even after a successful 1426 * <code>validateEdit</code> (e.g., due to the user checking in the file 1427 * in a different view); the editor should again call 1428 * <code>validateEdit</code> if the file is read-only before attempting to 1429 * save the contents of the file. 1430 * </p> 1431 * <p> 1432 * By passing a UI context, the caller indicates that the VCM component may 1433 * contact the user to help decide how best to proceed. If no UI context is 1434 * provided, the VCM component will make its decision without additional 1435 * interaction with the user. If OK is returned, the caller can safely 1436 * assume that all of the given files haven been prepared for modification 1437 * and that there is good reason to believe that 1438 * <code>IFile.setContents</code> (or <code>appendContents</code>) 1439 * would be successful on any of them. If the result is not OK, modifying 1440 * the given files might not succeed for the reason(s) indicated. 1441 * </p> 1442 * <p> 1443 * If a shell is passed in as the context, the VCM component may bring up a 1444 * dialogs to query the user or report difficulties; the shell should be 1445 * used to parent any such dialogs; the caller may safely assume that the 1446 * reasons for failure will have been made clear to the user. If 1447 * {@link IWorkspace#VALIDATE_PROMPT} is passed 1448 * as the context, this indicates that the caller does not have access to 1449 * a UI context but would still like the user to be prompted if required. 1450 * If <code>null</code> is passed, the user should not be contacted; any 1451 * failures should be reported via the result; the caller may chose to 1452 * present these to the user however they see fit. The ideal implementation 1453 * of this method is transactional; no files would be affected unless the 1454 * go-ahead could be given. (In practice, there may be no feasible way to 1455 * ensure such changes get done atomically.) 1456 * </p> 1457 * <p> 1458 * The method calls <code>FileModificationValidator.validateEdit</code> 1459 * for the file modification validator (if provided by the VCM plug-in). 1460 * When there is no file modification validator, this method returns a 1461 * status with an <code>IResourceStatus.READ_ONLY_LOCAL</code> code if one 1462 * of the files is read-only, and a status with an <code>IStatus.OK</code> 1463 * code otherwise. 1464 * </p> 1465 * <p> 1466 * This method may be called from any thread. If the UI context is used, it 1467 * is the responsibility of the implementor of 1468 * <code>FileModificationValidator.validateEdit</code> to interact with 1469 * the UI context in an appropriate thread. 1470 * </p> 1471 * 1472 * @param files the files that are to be modified; these files must all 1473 * exist in the workspace 1474 * @param context either {@link IWorkspace#VALIDATE_PROMPT}, 1475 * or the <code>org.eclipse.swt.widgets.Shell</code> that is 1476 * to be used to parent any dialogs with the user, or <code>null</code> if 1477 * there is no UI context (declared as an <code>Object</code> to avoid any 1478 * direct references on the SWT component) 1479 * @return a status object that is <code>OK</code> if things are fine, 1480 * otherwise a status describing reasons why modifying the given files is not 1481 * reasonable. A status with a severity of <code>CANCEL</code> is returned 1482 * if the validation was canceled, indicating the edit should not proceed. 1483 * @see IResourceRuleFactory#validateEditRule(IResource[]) 1484 * @since 2.0 1485 */ validateEdit(IFile[] files, Object context)1486 IStatus validateEdit(IFile[] files, Object context); 1487 1488 /** 1489 * Validates that the given resource will not (or would not, if the resource 1490 * doesn't exist in the workspace yet) be filtered out from the workspace by 1491 * its parent resource filters. 1492 * <p> 1493 * Note that if the resource or its parent doesn't exist yet in the workspace, 1494 * it is possible that it will still be effectively filtered out once the resource 1495 * and/or its parent is created, even though this method doesn't report it. 1496 * 1497 * But if this method reports the resource as filtered, even though it, or its 1498 * parent, doesn't exist in the workspace yet, it means that the resource will 1499 * be filtered out by its parent resource filters once it exists in the workspace. 1500 * </p> 1501 * <p> 1502 * This method will return a status with severity <code>IStatus.ERROR</code> 1503 * if the resource will be filtered out - removed - out of the workspace by 1504 * its parent resource filters. 1505 * </p> 1506 * <p> 1507 * Note: linked resources and virtual folders are never filtered out by their 1508 * parent resource filters. 1509 * 1510 * @param resource the resource to validate the location for 1511 * @return a status object with code <code>IStatus.OK</code> if the given 1512 * resource is not filtered by its parent resource filters, otherwise a status 1513 * object with severity <code>IStatus.ERROR</code> indicating that it will 1514 * @see IStatus#OK 1515 * @since 3.6 1516 */ validateFiltered(IResource resource)1517 IStatus validateFiltered(IResource resource); 1518 1519 /** 1520 * Validates the given path as the location of the given resource on disk. 1521 * The path must be either an absolute file system path, or a relative path 1522 * whose first segment is the name of a defined workspace path variable. In 1523 * addition to the restrictions for paths in general (see <code>IPath. 1524 * isValidPath</code>), 1525 * a link location must also obey the following rules: 1526 * <ul> 1527 * <li>must not overlap with the platform's metadata directory</li> 1528 * <li>must not be the same as or a parent of the root directory of the 1529 * project the linked resource is contained in</li> 1530 * </ul> 1531 * <p> 1532 * This method also checks that the given resource can legally become a 1533 * linked resource. This includes the following restrictions:</p> 1534 * <ul> 1535 * <li>must have a project as its immediate parent</li> 1536 * <li>project natures and the team hook may disallow linked resources on 1537 * projects they are associated with</li> 1538 * <li>the global workspace preference to disable linking, 1539 * <code>ResourcesPlugin.PREF_DISABLE_LINKING</code> must not be set to 1540 * "true"</li> 1541 * </ul> 1542 * <p> 1543 * This method will return a status with severity <code>IStatus.ERROR</code> 1544 * if the location does not obey the above rules. Also, this method will 1545 * return a status with severity <code>IStatus.WARNING</code> if the 1546 * location overlaps the location of any existing resource in the workspace. 1547 * </p> 1548 * <p> 1549 * Note: this method does not consider whether files or directories exist in 1550 * the file system at the specified path. 1551 * 1552 * @param resource the resource to validate the location for 1553 * @param location the location of the linked resource contents on disk 1554 * @return a status object with code <code>IStatus.OK</code> if the given 1555 * location is valid as the linked resource location, otherwise a status 1556 * object with severity <code>IStatus.WARNING</code> or 1557 * <code>IStatus.ERROR</code> indicating what is wrong with the location 1558 * @see IStatus#OK 1559 * @see ResourcesPlugin#PREF_DISABLE_LINKING 1560 * @since 2.1 1561 */ validateLinkLocation(IResource resource, IPath location)1562 IStatus validateLinkLocation(IResource resource, IPath location); 1563 1564 /** 1565 * Validates the given {@link URI} as the location of the given resource on disk. 1566 * The location must be either an absolute URI, or a relative URI 1567 * whose first segment is the name of a defined workspace path variable. 1568 * A link location must obey the following rules: 1569 * <ul> 1570 * <li>must not overlap with the platform's metadata directory</li> 1571 * <li>must not be the same as or a parent of the root directory of the 1572 * project the linked resource is contained in</li> 1573 * </ul> 1574 * <p> 1575 * This method also checks that the given resource can legally become a 1576 * linked resource. This includes the following restrictions: 1577 * <ul> 1578 * <li>must have a project as its immediate parent</li> 1579 * <li>project natures and the team hook may disallow linked resources on 1580 * projects they are associated with</li> 1581 * <li>the global workspace preference to disable linking, 1582 * <code>ResourcesPlugin.PREF_DISABLE_LINKING</code> must not be set to 1583 * "true"</li> 1584 * </ul> 1585 * <p> 1586 * This method will return a status with severity <code>IStatus.ERROR</code> 1587 * if the location does not obey the above rules. Also, this method will 1588 * return a status with severity <code>IStatus.WARNING</code> if the 1589 * location overlaps the location of any existing resource in the workspace. 1590 * </p> 1591 * <p> 1592 * Note: this method does not consider whether files or directories exist in 1593 * the file system at the specified location. 1594 * 1595 * @param resource the resource to validate the location for 1596 * @param location the location of the linked resource contents in some file system 1597 * @return a status object with code <code>IStatus.OK</code> if the given 1598 * location is valid as the linked resource location, otherwise a status 1599 * object with severity <code>IStatus.WARNING</code> or 1600 * <code>IStatus.ERROR</code> indicating what is wrong with the location 1601 * @see IStatus#OK 1602 * @see ResourcesPlugin#PREF_DISABLE_LINKING 1603 * @since 3.2 1604 */ validateLinkLocationURI(IResource resource, URI location)1605 IStatus validateLinkLocationURI(IResource resource, URI location); 1606 1607 /** 1608 * Validates the given string as the name of a resource valid for one of the 1609 * given types. 1610 * <p> 1611 * In addition to the basic restrictions on paths in general (see 1612 * {@link IPath#isValidSegment(String)}), a resource name must also not 1613 * contain any characters or substrings that are not valid on the file system 1614 * on which workspace root is located. In addition, the names "." and ".." 1615 * are reserved due to their special meaning in file system paths. 1616 * </p> 1617 * <p> 1618 * This validation check is done automatically as a resource is created (but 1619 * not when the resource handle is constructed); this means that any 1620 * resource that exists can be safely assumed to have a valid name and path. 1621 * Note that the name of the workspace root resource is inherently invalid. 1622 * </p> 1623 * 1624 * @param segment the name segment to be checked 1625 * @param typeMask bitwise-or of the resource type constants ( 1626 * <code>FILE</code>,<code>FOLDER</code>,<code>PROJECT</code> or 1627 * <code>ROOT</code>) indicating expected resource type(s) 1628 * @return a status object with code <code>IStatus.OK</code> if the given 1629 * string is valid as a resource name, otherwise a status object indicating 1630 * what is wrong with the string 1631 * @see IResource#PROJECT 1632 * @see IResource#FOLDER 1633 * @see IResource#FILE 1634 * @see IStatus#OK 1635 */ validateName(String segment, int typeMask)1636 IStatus validateName(String segment, int typeMask); 1637 1638 /** 1639 * Validates that each of the given natures exists, and that all nature 1640 * constraints are satisfied within the given set. 1641 * <p> 1642 * The following conditions apply to validation of a set of natures: 1643 * </p> 1644 * <ul> 1645 * <li>all natures in the set exist in the plug-in registry 1646 * <li>all prerequisites of each nature are present in the set 1647 * <li>there are no cycles in the prerequisite graph of the set 1648 * <li>there are no two natures in the set that specify one-of-nature 1649 * inclusion in the same group. 1650 * <li>there are no two natures in the set with the same id 1651 * </ul> 1652 * <p> 1653 * An empty nature set is always valid. 1654 * </p> 1655 * 1656 * @param natureIds an array of nature extension identifiers 1657 * @return a status object with code <code>IStatus.OK</code> if the given 1658 * set of natures is valid, otherwise a status object indicating what is 1659 * wrong with the set 1660 * @since 2.0 1661 */ validateNatureSet(String[] natureIds)1662 IStatus validateNatureSet(String[] natureIds); 1663 1664 /** 1665 * Validates the given string as a path for a resource of the given type(s). 1666 * <p> 1667 * In addition to the restrictions for paths in general (see 1668 * <code>IPath.isValidPath</code>), a resource path should also obey the 1669 * following rules: 1670 * </p> 1671 * <ul> 1672 * <li>a resource path should be an absolute path with no device id 1673 * <li>its segments should be valid names according to 1674 * <code>validateName</code> 1675 * <li>a path for the workspace root must be the canonical root path 1676 * <li>a path for a project should have exactly 1 segment 1677 * <li>a path for a file or folder should have more than 1 segment 1678 * <li>the first segment should be a valid project name 1679 * <li>the second through penultimate segments should be valid folder names 1680 * <li>the last segment should be a valid name of the given type 1681 * </ul> 1682 * <p> 1683 * Note: this method does not consider whether a resource at the specified 1684 * path exists. 1685 * </p> 1686 * <p> 1687 * This validation check is done automatically as a resource is created (but 1688 * not when the resource handle is constructed); this means that any 1689 * resource that exists can be safely assumed to have a valid name and path. 1690 * </p> 1691 * 1692 * @param path the path string to be checked 1693 * @param typeMask bitwise-or of the resource type constants ( 1694 * <code>FILE</code>,<code>FOLDER</code>,<code>PROJECT</code>, or 1695 * <code>ROOT</code>) indicating expected resource type(s) 1696 * @return a status object with code <code>IStatus.OK</code> if the given 1697 * path is valid as a resource path, otherwise a status object indicating 1698 * what is wrong with the string 1699 * @see IResource#PROJECT 1700 * @see IResource#FOLDER 1701 * @see IResource#FILE 1702 * @see IStatus#OK 1703 * @see IResourceStatus#getPath() 1704 */ validatePath(String path, int typeMask)1705 IStatus validatePath(String path, int typeMask); 1706 1707 /** 1708 * Validates the given path as the location of the given project on disk. 1709 * The path must be either an absolute file system path, or a relative path 1710 * whose first segment is the name of a defined workspace path variable. In 1711 * addition to the restrictions for paths in general (see <code>IPath. 1712 * isValidPath</code>), 1713 * a location path should also obey the following rules: 1714 * <ul> 1715 * <li>must not be the same as another open or closed project</li> 1716 * <li>must not occupy the default location for any project, whether existing or not</li> 1717 * <li>must not be the same as or a parent of the platform's working directory</li> 1718 * <li>must not be the same as or a child of the location of any existing 1719 * linked resource in the given project</li> 1720 * </ul> 1721 * <p> 1722 * Note: this method does not consider whether files or directories exist in 1723 * the file system at the specified path. 1724 * </p> 1725 * 1726 * @param project the project to validate the location for, can be <code>null</code> 1727 * if non default project location is validated 1728 * @param location the location of the project contents on disk, or <code>null</code> 1729 * if the default project location is used 1730 * @return a status object with code <code>IStatus.OK</code> if the given 1731 * location is valid as the project content location, otherwise a status 1732 * object indicating what is wrong with the location 1733 * @see IProjectDescription#getLocationURI() 1734 * @see IProjectDescription#setLocation(IPath) 1735 * @see IStatus#OK 1736 */ validateProjectLocation(IProject project, IPath location)1737 IStatus validateProjectLocation(IProject project, IPath location); 1738 1739 /** 1740 * Validates the given URI as the location of the given project. 1741 * The location must be either an absolute URI, or a relative URI 1742 * whose first segment is the name of a defined workspace path variable. 1743 * A project location must obey the following rules: 1744 * <ul> 1745 * <li>must not be the same as another open or closed project</li> 1746 * <li>must not occupy the default location for any project, whether existing or not</li> 1747 * <li>must not be the same as or a parent of the platform's working directory</li> 1748 * <li>must not be the same as or a child of the location of any existing 1749 * linked resource in the given project</li> 1750 * </ul> 1751 * <p> 1752 * Note: this method does not consider whether files or directories exist in 1753 * the file system at the specified path. 1754 * </p> 1755 * 1756 * @param project the project to validate the location for, can be <code>null</code> 1757 * if non default project location is validated 1758 * @param location the location of the project contents on disk, or <code>null</code> 1759 * if the default project location is used 1760 * @return a status object with code <code>IStatus.OK</code> if the given 1761 * location is valid as the project content location, otherwise a status 1762 * object indicating what is wrong with the location 1763 * @see IProjectDescription#getLocationURI() 1764 * @see IProjectDescription#setLocationURI(URI) 1765 * @see IStatus#OK 1766 * @since 3.2 1767 */ validateProjectLocationURI(IProject project, URI location)1768 IStatus validateProjectLocationURI(IProject project, URI location); 1769 1770 /** 1771 * Returns the path variable manager for this workspace. 1772 * 1773 * @return the path variable manager 1774 * @see IPathVariableManager 1775 * @since 2.1 1776 */ getPathVariableManager()1777 IPathVariableManager getPathVariableManager(); 1778 } 1779