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 * 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;
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.
33 * This interface is not intended to be implemented by clients.
36 public interface IPackageFragmentRoot extends IParent, IJavaElement, IOpenable {
38 * Kind constant for a source path root. Indicates this root only contains
44 * Kind constant for a binary path root. Indicates this root only contains
52 String DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$
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.
60 int NO_RESOURCE_MODIFICATION = 1;
63 * Update model flag constant (bit mask value 2) indicating that the
64 * operation is to update the classpath of the originating project.
68 int ORIGINATING_PROJECT_CLASSPATH = 2;
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.
77 int OTHER_REFERRING_PROJECTS_CLASSPATH = 4;
80 * Update model flag constant (bit mask value 8) indicating that the
81 * operation is to update the classpath of the destination project.
85 int DESTINATION_PROJECT_CLASSPATH = 8;
88 * Update model flag constant (bit mask value 16) indicating that the
89 * operation is to replace the resource and the destination project's
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.
108 * the given absolute path to the source archive or folder
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)
114 * the given progress monitor
115 * @exception JavaModelException
116 * if this operation fails. Reasons include:
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)
127 // void attachSource(IPath sourcePath, IPath rootPath, IProgressMonitor
129 // throws JavaModelException;
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.
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.
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.
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.
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.
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>)
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
178 * @exception JavaModelException
179 * if this root could not be copied. Reasons include:
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>
195 * @see org.eclipse.core.resources.IResource#copy
198 // void copy(IPath destination, int updateResourceFlags, int
199 // updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor)
200 // throws JavaModelException;
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.
208 * For a description of the <code>force</code> flag, see
209 * <code>IFolder.create</code>.
212 * the given dot-separated package name
214 * a flag controlling how to deal with resources that are not in
215 * sync with the local file system
217 * the given progress monitor
218 * @exception JavaModelException
219 * if the element could not be created. Reasons include:
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)
228 * @return a package fragment in this root with the given dot-separated
230 * @see org.eclipse.core.resources.IFolder#create
232 // IPackageFragment createPackageFragment(
235 // IProgressMonitor monitor)
236 // throws JavaModelException;
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.
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.
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
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.
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.
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>)
276 * @exception JavaModelException
277 * if this root could not be deleted. Reasons include:
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>
283 * @see org.eclipse.core.resources.IResource#delete
286 // void delete(int updateResourceFlags, int updateModelFlags,
287 // IProgressMonitor monitor) throws JavaModelException;
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
297 * @see IPackageFragmentRoot#K_SOURCE
298 * @see IPackageFragmentRoot#K_BINARY
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
305 int getKind() throws JavaModelException;
308 * Returns an array of non-Java resources contained in this package fragment
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.
320 * @return an array of non-Java resources contained in this package fragment
322 * @see IClasspathEntry#getExclusionPatterns
324 // Object[] getNonJavaResources() throws JavaModelException;
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.
331 * the given package name
332 * @return the package fragment with the given package name
334 IPackageFragment getPackageFragment(String packageName);
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.
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
348 // IClasspathEntry getRawClasspathEntry() throws JavaModelException;
350 * Returns the absolute path to the source archive attached to this package
351 * fragment root's binary archive.
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
360 // IPath getSourceAttachmentPath() throws JavaModelException;
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
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
373 // IPath getSourceAttachmentRootPath() throws JavaModelException;
375 * Returns whether this package fragment root's underlying resource is a
376 * binary archive (a JAR or zip file).
378 * @return true if this package fragment root's underlying resource is a
379 * binary archive, false otherwise
381 public boolean isArchive();
384 * Returns whether this package fragment root is external to the workbench
385 * (that is, a local file), and has no underlying resource.
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
391 boolean isExternal();
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.
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.
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.
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
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.
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.
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.
439 * the destination path
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>)
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
456 * @exception JavaModelException
457 * if this root could not be moved. Reasons include:
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>
473 * @see org.eclipse.core.resources.IResource#move
476 // void move(IPath destination, int updateResourceFlags, int
477 // updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor)
478 // throws JavaModelException;