net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IPackageFragment.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  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14
  15 /**
  16  * A package fragment is a portion of the workspace corresponding to an entire package,
  17  * or to a portion thereof. The distinction between a package fragment and a package
  18  * is that a package with some name is the union of all package fragments in the class path
  19  * which have the same name.
  20  * <p>
  21  * Package fragments elements need to be opened before they can be navigated or manipulated.
  22  * The children are of type <code>ICompilationUnit</code> (representing a source file) or
  23  * <code>IClassFile</code> (representing a binary class file).
  24  * The children are listed in no particular order.
  25  * </p>
  26  * <p>
  27  * This interface is not intended to be implemented by clients.
  28  * </p>
  29  */
  30 public interface IPackageFragment extends IParent, IJavaElement, IOpenable {
  31 //ISourceManipulation {
  32
  33         /**
  34          * <p>
  35          * The name of package fragment for the default package (value: the empty
  36          * string, <code>""</code>).
  37          * </p>
  38         */
  39         public static final String DEFAULT_PACKAGE_NAME = ""; //$NON-NLS-1$
  40         /**
  41          * Returns whether this fragment contains at least one Java resource.
  42          * @return true if this fragment contains at least one Java resource, false otherwise
  43          */
  44 //      boolean containsJavaResources() throws JavaModelException;
  45         /**
  46          * Creates and returns a compilation unit in this package fragment
  47          * with the specified name and contents. No verification is performed
  48          * on the contents.
  49          *
  50          * <p>It is possible that a compilation unit with the same name already exists in this
  51          * package fragment.
  52          * The value of the <code>force</code> parameter effects the resolution of
  53          * such a conflict:<ul>
  54          * <li> <code>true</code> - in this case the compilation is created with the new contents</li>
  55          * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
  56          * </ul>
  57          *
  58          * @param contents the given contents
  59          * @param force specify how to handle conflict is the same name already exists
  60          * @param monitor the given progress monitor
  61          * @param name the given name
  62          * @exception JavaModelException if the element could not be created. Reasons include:
  63          * <ul>
  64          * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
  65          * <li> A <code>CoreException</code> occurred while creating an underlying resource
  66          * <li> The name is not a valid compilation unit name (INVALID_NAME)
  67          * <li> The contents are <code>null</code> (INVALID_CONTENTS)
  68          * </ul>
  69          * @return a compilation unit in this package fragment
  70          * with the specified name and contents
  71          */
  72         ICompilationUnit createCompilationUnit(String name, String contents, boolean force, IProgressMonitor monitor) throws JavaModelException;
  73         /**
  74          * Returns the class file with the specified name
  75          * in this package (for example, <code>"Object.class"</code>).
  76          * The ".class" suffix is required.
  77          * This is a handle-only method.  The class file may or may not be present.
  78          * @param name the given name
  79          * @return the class file with the specified name in this package
  80          */
  81 //      IClassFile getClassFile(String name);
  82         /**
  83          * Returns all of the class files in this package fragment.
  84          *
  85          * <p>Note: it is possible that a package fragment contains only
  86          * compilation units (in other words, its kind is <code>K_SOURCE</code>), in
  87          * which case this method returns an empty collection.
  88          *
  89          * @exception JavaModelException if this element does not exist or if an
  90          *              exception occurs while accessing its corresponding resource.
  91          * @return all of the class files in this package fragment
  92          */
  93 //      IClassFile[] getClassFiles() throws JavaModelException;
  94         /**
  95          * Returns the compilation unit with the specified name
  96          * in this package (for example, <code>"Object.java"</code>).
  97          * The name has to be a valid compilation unit name.
  98          * This is a handle-only method.  The compilation unit may or may not be present.
  99          * @see JavaConventions#validateCompilationUnitName
 100          * @param name the given name
 101          * @return the compilation unit with the specified name in this package
 102          */
 103         ICompilationUnit getCompilationUnit(String name);
 104         /**
 105          * Returns all of the compilation units in this package fragment.
 106          *
 107          * <p>Note: it is possible that a package fragment contains only
 108          * class files (in other words, its kind is <code>K_BINARY</code>), in which
 109          * case this method returns an empty collection.
 110          *
 111          * @exception JavaModelException if this element does not exist or if an
 112          *              exception occurs while accessing its corresponding resource.
 113          * @return all of the compilation units in this package fragment
 114          */
 115 //      ICompilationUnit[] getCompilationUnits() throws JavaModelException;
 116         /**
 117          * Returns the dot-separated package name of this fragment, for example
 118          * <code>"java.lang"</code>, or <code>""</code> (the empty string),
 119          * for the default package.
 120          *
 121          * @return the dot-separated package name of this fragment
 122          */
 123         String getElementName();
 124         /**
 125          * Returns this package fragment's root kind encoded as an integer.
 126          * A package fragment can contain <code>.java</code> source files,
 127          * or <code>.class</code> files. This is a convenience method.
 128          *
 129          * @see IPackageFragmentRoot#K_SOURCE
 130          * @see IPackageFragmentRoot#K_BINARY
 131          *
 132          * @exception JavaModelException if this element does not exist or if an
 133          *              exception occurs while accessing its corresponding resource.
 134          * @return this package fragment's root kind encoded as an integer
 135          */
 136 //      int getKind() throws JavaModelException;
 137         /**
 138          * Returns an array of non-Java resources contained in this package fragment.
 139          * <p>
 140          * Non-Java resources includes other files and folders located in the same
 141          * directory as the compilation units or class files for this package
 142          * fragment. Source files excluded from this package by one or more
 143          * exclusion patterns on the corresponding source classpath entry are
 144          * considered non-Java resources and will appear in the result
 145          * (possibly in a folder).
 146          * </p>
 147          *
 148          * @return an array of non-Java resources contained in this package fragment
 149          * @see IClasspathEntry#getExclusionPatterns
 150          */
 151 //      Object[] getNonJavaResources() throws JavaModelException;
 152         /**
 153          * Returns whether this package fragment's name is
 154          * a prefix of other package fragments in this package fragment's
 155          * root.
 156          *
 157          * @exception JavaModelException if this element does not exist or if an
 158          *              exception occurs while accessing its corresponding resource.
 159          * @return true if this package fragment's name is a prefix of other package fragments in this package fragment's root, false otherwise
 160          */
 161 //      boolean hasSubpackages() throws JavaModelException;
 162         /**
 163          * Returns whether this package fragment is a default package.
 164          * This is a handle-only method.
 165          *
 166          * @return true if this package fragment is a default package
 167          */
 168         boolean isDefaultPackage();
 169 }