net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IPackageFragmentRoot.java

   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          */
 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          */
 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          */
 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          */
 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 }