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