1 /******************************************************************************* 2 * Copyright (c) 2000, 2003 IBM Corporation and others. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Common Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/cpl-v10.html 7 * 8 * Contributors: 9 * IBM Corporation - initial API and implementation 10 * IBM Corporation - specified that a source archive or a source folder can be attached to a binary 11 * package fragment root. 12 * IBM Corporation - added root manipulation APIs: copy, delete, move 13 * IBM Corporation - added DESTINATION_PROJECT_CLASSPATH 14 * IBM Corporation - added OTHER_REFERRING_PROJECTS_CLASSPATH 15 * IBM Corporation - added NO_RESOURCE_MODIFICATION 16 * IBM Corporation - added REPLACE 17 * IBM Corporation - added ORIGINATING_PROJECT_CLASSPATH 18 *******************************************************************************/ 19 package net.sourceforge.phpdt.core; 20 21 /** 22 * A package fragment root contains a set of package fragments. It corresponds 23 * to an underlying resource which is either a folder, JAR, or zip. In the case 24 * of a folder, all descendant folders represent package fragments. For a given 25 * child folder representing a package fragment, the corresponding package name 26 * is composed of the folder names between the folder for this root and the 27 * child folder representing the package, separated by '.'. In the case of a JAR 28 * or zip, the contents of the archive dictates the set of package fragments in 29 * an analogous manner. Package fragment roots need to be opened before they can 30 * be navigated or manipulated. The children are of type 31 * <code>IPackageFragment</code>, and are in no particular order. 32 * <p> 33 * This interface is not intended to be implemented by clients. 34 * </p> 35 */ 36 public interface IPackageFragmentRoot extends IParent, IJavaElement, IOpenable { 37 /** 38 * Kind constant for a source path root. Indicates this root only contains 39 * source files. 40 */ 41 int K_SOURCE = 1; 42 43 /** 44 * Kind constant for a binary path root. Indicates this root only contains 45 * binary files. 46 */ 47 int K_BINARY = 2; 48 49 /** 50 * Empty root path 51 */ 52 String DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$ 53 54 /** 55 * Update model flag constant (bit mask value 1) indicating that the 56 * operation is to not copy/move/delete the package fragment root resource. 57 * 58 * @since 2.1 59 */ 60 int NO_RESOURCE_MODIFICATION = 1; 61 62 /** 63 * Update model flag constant (bit mask value 2) indicating that the 64 * operation is to update the classpath of the originating project. 65 * 66 * @since 2.1 67 */ 68 int ORIGINATING_PROJECT_CLASSPATH = 2; 69 70 /** 71 * Update model flag constant (bit mask value 4) indicating that the 72 * operation is to update the classpath of all referring projects except the 73 * originating project. 74 * 75 * @since 2.1 76 */ 77 int OTHER_REFERRING_PROJECTS_CLASSPATH = 4; 78 79 /** 80 * Update model flag constant (bit mask value 8) indicating that the 81 * operation is to update the classpath of the destination project. 82 * 83 * @since 2.1 84 */ 85 int DESTINATION_PROJECT_CLASSPATH = 8; 86 87 /** 88 * Update model flag constant (bit mask value 16) indicating that the 89 * operation is to replace the resource and the destination project's 90 * classpath entry. 91 * 92 * @since 2.1 93 */ 94 int REPLACE = 16; 95 96 /** 97 * Attaches the source archive identified by the given absolute path to this 98 * binary package fragment root. <code>rootPath</code> specifies the 99 * location of the root within the archive or folder (empty specifies the 100 * default root and <code>null</code> specifies the root path should be 101 * detected). Once a source archive or folder is attached to the package 102 * fragment root, the <code>getSource</code> and 103 * <code>getSourceRange</code> methods become operational for binary 104 * types/members. To detach a source archive or folder from a package 105 * fragment root, specify <code>null</code> as the source path. 106 * 107 * @param sourcePath 108 * the given absolute path to the source archive or folder 109 * @param rootPath 110 * specifies the location of the root within the archive (empty 111 * specifies the default root and <code>null</code> specifies 112 * automatic detection of the root path) 113 * @param monitor 114 * the given progress monitor 115 * @exception JavaModelException 116 * if this operation fails. Reasons include: 117 * <ul> 118 * <li> This Java element does not exist 119 * (ELEMENT_DOES_NOT_EXIST)</li> 120 * <li> A <code>CoreException</code> occurred while 121 * updating a server property 122 * <li> This package fragment root is not of kind binary 123 * (INVALID_ELEMENT_TYPES) 124 * <li> The path provided is not absolute (RELATIVE_PATH) 125 * </ul> 126 */ 127 // void attachSource(IPath sourcePath, IPath rootPath, IProgressMonitor 128 // monitor) 129 // throws JavaModelException; 130 /** 131 * Copies the resource of this package fragment root to the destination path 132 * as specified by <code>IResource.copy(IPath, int, IProgressMonitor)</code> 133 * but excluding nested source folders. 134 * <p> 135 * If <code>NO_RESOURCE_MODIFICATION</code> is specified in 136 * <code>updateModelFlags</code> or if this package fragment root is 137 * external, this operation doesn't copy the resource. 138 * <code>updateResourceFlags</code> is then ignored. 139 * </p> 140 * <p> 141 * If <code>DESTINATION_PROJECT_CLASSPATH</code> is specified in 142 * <code>updateModelFlags</code>, updates the classpath of the 143 * destination's project (if it is a Java project). If a non-<code>null</code> 144 * sibling is specified, a copy of this root's classpath entry is inserted 145 * before the sibling on the destination project's raw classpath. If 146 * <code>null</code> is specified, the classpath entry is added at the end 147 * of the raw classpath. 148 * </p> 149 * <p> 150 * If <code>REPLACE</code> is specified in <code>updateModelFlags</code>, 151 * overwrites the resource at the destination path if any. If the same 152 * classpath entry already exists on the destination project's raw 153 * classpath, then the sibling is ignored and the new classpath entry 154 * replaces the existing one. 155 * </p> 156 * <p> 157 * If no flags is specified in <code>updateModelFlags</code> (using 158 * <code>IResource.NONE</code>), the default behavior applies: the 159 * resource is copied (if this package fragment root is not external) and 160 * the classpath is not updated. 161 * </p> 162 * 163 * @param destination 164 * the destination path 165 * @param updateResourceFlags 166 * bit-wise or of update resource flag constants (<code>IResource.FORCE</code> 167 * and <code>IResource.SHALLOW</code>) 168 * @param updateModelFlags 169 * bit-wise or of update resource flag constants (<code>DESTINATION_PROJECT_CLASSPATH</code> 170 * and <code>NO_RESOURCE_MODIFICATION</code>) 171 * @param sibling 172 * the classpath entry before which a copy of the classpath entry 173 * should be inserted or <code>null</code> if the classpath 174 * entry should be inserted at the end 175 * @param monitor 176 * a progress monitor 177 * 178 * @exception JavaModelException 179 * if this root could not be copied. Reasons include: 180 * <ul> 181 * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li> 182 * <li> A <code>CoreException</code> occurred while copying 183 * the resource or updating a classpath</li> 184 * <li> The destination is not inside an existing project and 185 * <code>updateModelFlags</code> has been specified as 186 * <code>DESTINATION_PROJECT_CLASSPATH</code> 187 * (INVALID_DESTINATION)</li> 188 * <li> The sibling is not a classpath entry on the 189 * destination project's raw classpath (INVALID_SIBLING)</li> 190 * <li> The same classpath entry already exists on the 191 * destination project's classpath (NAME_COLLISION) and 192 * <code>updateModelFlags</code> has not been specified as 193 * <code>REPLACE</code></li> 194 * </ul> 195 * @see org.eclipse.core.resources.IResource#copy 196 * @since 2.1 197 */ 198 // void copy(IPath destination, int updateResourceFlags, int 199 // updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor) 200 // throws JavaModelException; 201 /** 202 * Creates and returns a package fragment in this root with the given 203 * dot-separated package name. An empty string specifies the default 204 * package. This has the side effect of creating all package fragments that 205 * are a prefix of the new package fragment which do not exist yet. If the 206 * package fragment already exists, this has no effect. 207 * 208 * For a description of the <code>force</code> flag, see 209 * <code>IFolder.create</code>. 210 * 211 * @param name 212 * the given dot-separated package name 213 * @param force 214 * a flag controlling how to deal with resources that are not in 215 * sync with the local file system 216 * @param monitor 217 * the given progress monitor 218 * @exception JavaModelException 219 * if the element could not be created. Reasons include: 220 * <ul> 221 * <li> This Java element does not exist 222 * (ELEMENT_DOES_NOT_EXIST)</li> 223 * <li> A <code>CoreException</code> occurred while 224 * creating an underlying resource 225 * <li> This package fragment root is read only (READ_ONLY) 226 * <li> The name is not a valid package name (INVALID_NAME) 227 * </ul> 228 * @return a package fragment in this root with the given dot-separated 229 * package name 230 * @see org.eclipse.core.resources.IFolder#create 231 */ 232 // IPackageFragment createPackageFragment( 233 // String name, 234 // boolean force, 235 // IProgressMonitor monitor) 236 // throws JavaModelException; 237 /** 238 * Deletes the resource of this package fragment root as specified by 239 * <code>IResource.delete(int, IProgressMonitor)</code> but excluding 240 * nested source folders. 241 * <p> 242 * If <code>NO_RESOURCE_MODIFICATION</code> is specified in 243 * <code>updateModelFlags</code> or if this package fragment root is 244 * external, this operation doesn't delete the resource. 245 * <code>updateResourceFlags</code> is then ignored. 246 * </p> 247 * <p> 248 * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in 249 * <code>updateModelFlags</code>, update the raw classpath of this 250 * package fragment root's project by removing the corresponding classpath 251 * entry. 252 * </p> 253 * <p> 254 * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in 255 * <code>updateModelFlags</code>, update the raw classpaths of all other 256 * Java projects referring to this root's resource by removing the 257 * corresponding classpath entries. 258 * </p> 259 * <p> 260 * If no flags is specified in <code>updateModelFlags</code> (using 261 * <code>IResource.NONE</code>), the default behavior applies: the 262 * resource is deleted (if this package fragment root is not external) and 263 * no classpaths are updated. 264 * </p> 265 * 266 * @param updateResourceFlags 267 * bit-wise or of update resource flag constants (<code>IResource.FORCE</code> 268 * and <code>IResource.KEEP_HISTORY</code>) 269 * @param updateModelFlags 270 * bit-wise or of update resource flag constants (<code>ORIGINATING_PROJECT_CLASSPATH</code>, 271 * <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and 272 * <code>NO_RESOURCE_MODIFICATION</code>) 273 * @param monitor 274 * a progress monitor 275 * 276 * @exception JavaModelException 277 * if this root could not be deleted. Reasons include: 278 * <ul> 279 * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li> 280 * <li> A <code>CoreException</code> occurred while 281 * deleting the resource or updating a classpath </li> 282 * </ul> 283 * @see org.eclipse.core.resources.IResource#delete 284 * @since 2.1 285 */ 286 // void delete(int updateResourceFlags, int updateModelFlags, 287 // IProgressMonitor monitor) throws JavaModelException; 288 /** 289 * Returns this package fragment root's kind encoded as an integer. A 290 * package fragment root can contain <code>.java</code> source files, or 291 * <code>.class</code> files, but not both. If the underlying folder or 292 * archive contains other kinds of files, they are ignored. In particular, 293 * <code>.class</code> files are ignored under a source package fragment 294 * root, and <code>.java</code> files are ignored under a binary package 295 * fragment root. 296 * 297 * @see IPackageFragmentRoot#K_SOURCE 298 * @see IPackageFragmentRoot#K_BINARY 299 * 300 * @exception JavaModelException 301 * if this element does not exist or if an exception occurs 302 * while accessing its corresponding resource. 303 * @return this package fragment root's kind encoded as an integer 304 */ getKind()305 int getKind() throws JavaModelException; 306 307 /** 308 * Returns an array of non-Java resources contained in this package fragment 309 * root. 310 * <p> 311 * Non-Java resources includes other files and folders located in the same 312 * directories as the compilation units or class files under this package 313 * fragment root. Resources excluded from this package fragment root by one 314 * or more exclusion patterns on the corresponding source classpath entry 315 * are considered non-Java resources and will appear in the result (possibly 316 * in a folder). Thus when a nested source folder is excluded, it will 317 * appear in the non-Java resources of the outer folder. 318 * </p> 319 * 320 * @return an array of non-Java resources contained in this package fragment 321 * root 322 * @see IClasspathEntry#getExclusionPatterns 323 */ 324 // Object[] getNonJavaResources() throws JavaModelException; 325 /** 326 * Returns the package fragment with the given package name. An empty string 327 * indicates the default package. This is a handle-only operation. The 328 * package fragment may or may not exist. 329 * 330 * @param packageName 331 * the given package name 332 * @return the package fragment with the given package name 333 */ getPackageFragment(String packageName)334 IPackageFragment getPackageFragment(String packageName); 335 336 /** 337 * Returns the first raw classpath entry that corresponds to this package 338 * fragment root. A raw classpath entry corresponds to a package fragment 339 * root if once resolved this entry's path is equal to the root's path. 340 * 341 * @exception JavaModelException 342 * if this element does not exist or if an exception occurs 343 * while accessing its corresponding resource. 344 * @return the first raw classpath entry that corresponds to this package 345 * fragment root 346 * @since 2.0 347 */ 348 // IClasspathEntry getRawClasspathEntry() throws JavaModelException; 349 /** 350 * Returns the absolute path to the source archive attached to this package 351 * fragment root's binary archive. 352 * 353 * @return the absolute path to the corresponding source archive, or 354 * <code>null</code> if this package fragment root's binary 355 * archive has no corresponding source archive, or if this package 356 * fragment root is not a binary archive 357 * @exception JavaModelException 358 * if this operation fails 359 */ 360 // IPath getSourceAttachmentPath() throws JavaModelException; 361 /** 362 * Returns the path within this package fragment root's source archive. An 363 * empty path indicates that packages are located at the root of the source 364 * archive. 365 * 366 * @return the path within the corresponding source archive, or 367 * <code>null</code> if this package fragment root's binary 368 * archive has no corresponding source archive, or if this package 369 * fragment root is not a binary archive 370 * @exception JavaModelException 371 * if this operation fails 372 */ 373 // IPath getSourceAttachmentRootPath() throws JavaModelException; 374 /** 375 * Returns whether this package fragment root's underlying resource is a 376 * binary archive (a JAR or zip file). 377 * 378 * @return true if this package fragment root's underlying resource is a 379 * binary archive, false otherwise 380 */ isArchive()381 public boolean isArchive(); 382 383 /** 384 * Returns whether this package fragment root is external to the workbench 385 * (that is, a local file), and has no underlying resource. 386 * 387 * @return true if this package fragment root is external to the workbench 388 * (that is, a local file), and has no underlying resource, false 389 * otherwise 390 */ isExternal()391 boolean isExternal(); 392 393 /** 394 * Moves the resource of this package fragment root to the destination path 395 * as specified by <code>IResource.move(IPath,int,IProgressMonitor)</code> 396 * but excluding nested source folders. 397 * <p> 398 * If <code>NO_RESOURCE_MODIFICATION</code> is specified in 399 * <code>updateModelFlags</code> or if this package fragment root is 400 * external, this operation doesn't move the resource. 401 * <code>updateResourceFlags</code> is then ignored. 402 * </p> 403 * <p> 404 * If <code>DESTINATION_PROJECT_CLASSPATH</code> is specified in 405 * <code>updateModelFlags</code>, updates the classpath of the 406 * destination's project (if it is a Java project). If a non-<code>null</code> 407 * sibling is specified, a copy of this root's classpath entry is inserted 408 * before the sibling on the destination project's raw classpath. If 409 * <code>null</code> is specified, the classpath entry is added at the end 410 * of the raw classpath. 411 * </p> 412 * <p> 413 * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in 414 * <code>updateModelFlags</code>, update the raw classpath of this 415 * package fragment root's project by removing the corresponding classpath 416 * entry. 417 * </p> 418 * <p> 419 * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in 420 * <code>updateModelFlags</code>, update the raw classpaths of all other 421 * Java projects referring to this root's resource by removing the 422 * corresponding classpath entries. 423 * </p> 424 * <p> 425 * If <code>REPLACE</code> is specified in <code>updateModelFlags</code>, 426 * overwrites the resource at the destination path if any. If the same 427 * classpath entry already exists on the destination project's raw 428 * classpath, then the sibling is ignored and the new classpath entry 429 * replaces the existing one. 430 * </p> 431 * <p> 432 * If no flags is specified in <code>updateModelFlags</code> (using 433 * <code>IResource.NONE</code>), the default behavior applies: the 434 * resource is moved (if this package fragment root is not external) and no 435 * classpaths are updated. 436 * </p> 437 * 438 * @param destination 439 * the destination path 440 * @param updateFlags 441 * bit-wise or of update flag constants (<code>IResource.FORCE</code>, 442 * <code>IResource.KEEP_HISTORY</code> and 443 * <code>IResource.SHALLOW</code>) 444 * @param updateModelFlags 445 * bit-wise or of update resource flag constants (<code>DESTINATION_PROJECT_CLASSPATH</code>, 446 * <code>ORIGINATING_PROJECT_CLASSPATH</code>, 447 * <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and 448 * <code>NO_RESOURCE_MODIFICATION</code>) 449 * @param sibling 450 * the classpath entry before which a copy of the classpath entry 451 * should be inserted or <code>null</code> if the classpath 452 * entry should be inserted at the end 453 * @param monitor 454 * a progress monitor 455 * 456 * @exception JavaModelException 457 * if this root could not be moved. Reasons include: 458 * <ul> 459 * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li> 460 * <li> A <code>CoreException</code> occurred while copying 461 * the resource or updating a classpath</li> 462 * <li> The destination is not inside an existing project and 463 * <code>updateModelFlags</code> has been specified as 464 * <code>DESTINATION_PROJECT_CLASSPATH</code> 465 * (INVALID_DESTINATION)</li> 466 * <li> The sibling is not a classpath entry on the 467 * destination project's raw classpath (INVALID_SIBLING)</li> 468 * <li> The same classpath entry already exists on the 469 * destination project's classpath (NAME_COLLISION) and 470 * <code>updateModelFlags</code> has not been specified as 471 * <code>REPLACE</code></li> 472 * </ul> 473 * @see org.eclipse.core.resources.IResource#move 474 * @since 2.1 475 */ 476 // void move(IPath destination, int updateResourceFlags, int 477 // updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor) 478 // throws JavaModelException; 479 }