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
  17  * package, or to a portion thereof. The distinction between a package fragment
  18  * and a package is that a package with some name is the union of all package
  19  * fragments in the class path which have the same name.
  20  * <p>
  21  * Package fragments elements need to be opened before they can be navigated or
  22  * manipulated. The children are of type <code>ICompilationUnit</code>
  23  * (representing a source file) or <code>IClassFile</code> (representing a
  24  * binary class file). 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         /**
  42          * Returns whether this fragment contains at least one Java resource.
  43          *
  44          * @return true if this fragment contains at least one Java resource, false
  45          *         otherwise
  46          */
  47         // boolean containsJavaResources() throws JavaModelException;
  48         /**
  49          * Creates and returns a compilation unit in this package fragment with the
  50          * specified name and contents. No verification is performed on the
  51          * contents.
  52          *
  53          * <p>
  54          * It is possible that a compilation unit with the same name already exists
  55          * in this package fragment. The value of the <code>force</code> parameter
  56          * effects the resolution of such a conflict:
  57          * <ul>
  58          * <li> <code>true</code> - in this case the compilation is created with
  59          * the new contents</li>
  60          * <li> <code>false</code> - in this case a
  61          * <code>JavaModelException</code> is thrown</li>
  62          * </ul>
  63          *
  64          * @param contents
  65          *            the given contents
  66          * @param force
  67          *            specify how to handle conflict is the same name already exists
  68          * @param monitor
  69          *            the given progress monitor
  70          * @param name
  71          *            the given name
  72          * @exception JavaModelException
  73          *                if the element could not be created. Reasons include:
  74          *                <ul>
  75          *                <li> This Java element does not exist
  76          *                (ELEMENT_DOES_NOT_EXIST)</li>
  77          *                <li> A <code>CoreException</code> occurred while
  78          *                creating an underlying resource
  79          *                <li> The name is not a valid compilation unit name
  80          *                (INVALID_NAME)
  81          *                <li> The contents are <code>null</code>
  82          *                (INVALID_CONTENTS)
  83          *                </ul>
  84          * @return a compilation unit in this package fragment with the specified
  85          *         name and contents
  86          */
  87         ICompilationUnit createCompilationUnit(String name, String contents,
  88                         boolean force, IProgressMonitor monitor) throws JavaModelException;
  89
  90         /**
  91          * Returns the class file with the specified name in this package (for
  92          * example, <code>"Object.class"</code>). The ".class" suffix is
  93          * required. This is a handle-only method. The class file may or may not be
  94          * present.
  95          *
  96          * @param name
  97          *            the given name
  98          * @return the class file with the specified name in this package
  99          */
 100         // IClassFile getClassFile(String name);
 101         /**
 102          * Returns all of the class files in this package fragment.
 103          *
 104          * <p>
 105          * Note: it is possible that a package fragment contains only compilation
 106          * units (in other words, its kind is <code>K_SOURCE</code>), in which
 107          * case this method returns an empty collection.
 108          *
 109          * @exception JavaModelException
 110          *                if this element does not exist or if an exception occurs
 111          *                while accessing its corresponding resource.
 112          * @return all of the class files in this package fragment
 113          */
 114         // IClassFile[] getClassFiles() throws JavaModelException;
 115         /**
 116          * Returns the compilation unit with the specified name in this package (for
 117          * example, <code>"Object.java"</code>). The name has to be a valid
 118          * compilation unit name. This is a handle-only method. The compilation unit
 119          * may or may not be present.
 120          *
 121          * @see JavaConventions#validateCompilationUnitName
 122          * @param name
 123          *            the given name
 124          * @return the compilation unit with the specified name in this package
 125          */
 126         ICompilationUnit getCompilationUnit(String name);
 127
 128         /**
 129          * Returns all of the compilation units in this package fragment.
 130          *
 131          * <p>
 132          * Note: it is possible that a package fragment contains only class files
 133          * (in other words, its kind is <code>K_BINARY</code>), in which case
 134          * this method returns an empty collection.
 135          *
 136          * @exception JavaModelException
 137          *                if this element does not exist or if an exception occurs
 138          *                while accessing its corresponding resource.
 139          * @return all of the compilation units in this package fragment
 140          */
 141         ICompilationUnit[] getCompilationUnits() throws JavaModelException;
 142
 143         /**
 144          * Returns the dot-separated package name of this fragment, for example
 145          * <code>"java.lang"</code>, or <code>""</code> (the empty string), for
 146          * the default package.
 147          *
 148          * @return the dot-separated package name of this fragment
 149          */
 150         String getElementName();
 151
 152         /**
 153          * Returns this package fragment's root kind encoded as an integer. A
 154          * package fragment can contain <code>.java</code> source files, or
 155          * <code>.class</code> files. This is a convenience method.
 156          *
 157          * @see IPackageFragmentRoot#K_SOURCE
 158          * @see IPackageFragmentRoot#K_BINARY
 159          *
 160          * @exception JavaModelException
 161          *                if this element does not exist or if an exception occurs
 162          *                while accessing its corresponding resource.
 163          * @return this package fragment's root kind encoded as an integer
 164          */
 165         int getKind() throws JavaModelException;
 166
 167         /**
 168          * Returns an array of non-Java resources contained in this package
 169          * fragment.
 170          * <p>
 171          * Non-Java resources includes other files and folders located in the same
 172          * directory as the compilation units or class files for this package
 173          * fragment. Source files excluded from this package by one or more
 174          * exclusion patterns on the corresponding source classpath entry are
 175          * considered non-Java resources and will appear in the result (possibly in
 176          * a folder).
 177          * </p>
 178          *
 179          * @return an array of non-Java resources contained in this package fragment
 180          * @see IClasspathEntry#getExclusionPatterns
 181          */
 182         // Object[] getNonJavaResources() throws JavaModelException;
 183         /**
 184          * Returns whether this package fragment's name is a prefix of other package
 185          * fragments in this package fragment's root.
 186          *
 187          * @exception JavaModelException
 188          *                if this element does not exist or if an exception occurs
 189          *                while accessing its corresponding resource.
 190          * @return true if this package fragment's name is a prefix of other package
 191          *         fragments in this package fragment's root, false otherwise
 192          */
 193         // boolean hasSubpackages() throws JavaModelException;
 194         /**
 195          * Returns whether this package fragment is a default package. This is a
 196          * handle-only method.
 197          *
 198          * @return true if this package fragment is a default package
 199          */
 200         boolean isDefaultPackage();
 201 }