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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.runtime.IProgressMonitor;
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.
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.
27 * This interface is not intended to be implemented by clients.
30 public interface IPackageFragment extends IParent, IJavaElement, IOpenable {
31 // ISourceManipulation {
35 * The name of package fragment for the default package (value: the empty
36 * string, <code>""</code>).
39 public static final String DEFAULT_PACKAGE_NAME = ""; //$NON-NLS-1$
42 * Returns whether this fragment contains at least one Java resource.
44 * @return true if this fragment contains at least one Java resource, false
47 // boolean containsJavaResources() throws JavaModelException;
49 * Creates and returns a compilation unit in this package fragment with the
50 * specified name and contents. No verification is performed on the
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:
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>
67 * specify how to handle conflict is the same name already exists
69 * the given progress monitor
72 * @exception JavaModelException
73 * if the element could not be created. Reasons include:
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
81 * <li> The contents are <code>null</code>
84 * @return a compilation unit in this package fragment with the specified
87 ICompilationUnit createCompilationUnit(String name, String contents,
88 boolean force, IProgressMonitor monitor) throws JavaModelException;
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
98 * @return the class file with the specified name in this package
100 // IClassFile getClassFile(String name);
102 * Returns all of the class files in this package fragment.
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.
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
114 // IClassFile[] getClassFiles() throws JavaModelException;
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.
121 * @see JavaConventions#validateCompilationUnitName
124 * @return the compilation unit with the specified name in this package
126 ICompilationUnit getCompilationUnit(String name);
129 * Returns all of the compilation units in this package fragment.
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.
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
141 ICompilationUnit[] getCompilationUnits() throws JavaModelException;
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.
148 * @return the dot-separated package name of this fragment
150 String getElementName();
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.
157 * @see IPackageFragmentRoot#K_SOURCE
158 * @see IPackageFragmentRoot#K_BINARY
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
165 int getKind() throws JavaModelException;
168 * Returns an array of non-Java resources contained in this package
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
179 * @return an array of non-Java resources contained in this package fragment
180 * @see IClasspathEntry#getExclusionPatterns
182 // Object[] getNonJavaResources() throws JavaModelException;
184 * Returns whether this package fragment's name is a prefix of other package
185 * fragments in this package fragment's root.
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
193 // boolean hasSubpackages() throws JavaModelException;
195 * Returns whether this package fragment is a default package. This is a
196 * handle-only method.
198 * @return true if this package fragment is a default package
200 boolean isDefaultPackage();