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  * 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.
32  * <p>
33  * This interface is not intended to be implemented by clients.
34  * </p>
35  */
36 public interface IPackageFragmentRoot extends IParent, IJavaElement, IOpenable {
37 	/**
38 	 * Kind constant for a source path root. Indicates this root only contains
39 	 * source files.
40 	 */
41 	int K_SOURCE = 1;
42 
43 	/**
44 	 * Kind constant for a binary path root. Indicates this root only contains
45 	 * binary files.
46 	 */
47 	int K_BINARY = 2;
48 
49 	/**
50 	 * Empty root path
51 	 */
52 	String DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$
53 
54 	/**
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.
57 	 *
58 	 * @since 2.1
59 	 */
60 	int NO_RESOURCE_MODIFICATION = 1;
61 
62 	/**
63 	 * Update model flag constant (bit mask value 2) indicating that the
64 	 * operation is to update the classpath of the originating project.
65 	 *
66 	 * @since 2.1
67 	 */
68 	int ORIGINATING_PROJECT_CLASSPATH = 2;
69 
70 	/**
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.
74 	 *
75 	 * @since 2.1
76 	 */
77 	int OTHER_REFERRING_PROJECTS_CLASSPATH = 4;
78 
79 	/**
80 	 * Update model flag constant (bit mask value 8) indicating that the
81 	 * operation is to update the classpath of the destination project.
82 	 *
83 	 * @since 2.1
84 	 */
85 	int DESTINATION_PROJECT_CLASSPATH = 8;
86 
87 	/**
88 	 * Update model flag constant (bit mask value 16) indicating that the
89 	 * operation is to replace the resource and the destination project's
90 	 * classpath entry.
91 	 *
92 	 * @since 2.1
93 	 */
94 	int REPLACE = 16;
95 
96 	/**
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.
106 	 *
107 	 * @param sourcePath
108 	 *            the given absolute path to the source archive or folder
109 	 * @param rootPath
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)
113 	 * @param monitor
114 	 *            the given progress monitor
115 	 * @exception JavaModelException
116 	 *                if this operation fails. Reasons include:
117 	 *                <ul>
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)
125 	 *                </ul>
126 	 */
127 	// void attachSource(IPath sourcePath, IPath rootPath, IProgressMonitor
128 	// monitor)
129 	// throws JavaModelException;
130 	/**
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.
134 	 * <p>
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.
139 	 * </p>
140 	 * <p>
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.
148 	 * </p>
149 	 * <p>
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.
155 	 * </p>
156 	 * <p>
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.
161 	 * </p>
162 	 *
163 	 * @param destination
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>)
171 	 * @param sibling
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
175 	 * @param monitor
176 	 *            a progress monitor
177 	 *
178 	 * @exception JavaModelException
179 	 *                if this root could not be copied. Reasons include:
180 	 *                <ul>
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>
194 	 *                </ul>
195 	 * @see org.eclipse.core.resources.IResource#copy
196 	 * @since 2.1
197 	 */
198 	// void copy(IPath destination, int updateResourceFlags, int
199 	// updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor)
200 	// throws JavaModelException;
201 	/**
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.
207 	 *
208 	 * For a description of the <code>force</code> flag, see
209 	 * <code>IFolder.create</code>.
210 	 *
211 	 * @param name
212 	 *            the given dot-separated package name
213 	 * @param force
214 	 *            a flag controlling how to deal with resources that are not in
215 	 *            sync with the local file system
216 	 * @param monitor
217 	 *            the given progress monitor
218 	 * @exception JavaModelException
219 	 *                if the element could not be created. Reasons include:
220 	 *                <ul>
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)
227 	 *                </ul>
228 	 * @return a package fragment in this root with the given dot-separated
229 	 *         package name
230 	 * @see org.eclipse.core.resources.IFolder#create
231 	 */
232 	// IPackageFragment createPackageFragment(
233 	// String name,
234 	// boolean force,
235 	// IProgressMonitor monitor)
236 	// throws JavaModelException;
237 	/**
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.
241 	 * <p>
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.
246 	 * </p>
247 	 * <p>
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
251 	 * entry.
252 	 * </p>
253 	 * <p>
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.
258 	 * </p>
259 	 * <p>
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.
264 	 * </p>
265 	 *
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>)
273 	 * @param monitor
274 	 *            a progress monitor
275 	 *
276 	 * @exception JavaModelException
277 	 *                if this root could not be deleted. Reasons include:
278 	 *                <ul>
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>
282 	 *                </ul>
283 	 * @see org.eclipse.core.resources.IResource#delete
284 	 * @since 2.1
285 	 */
286 	// void delete(int updateResourceFlags, int updateModelFlags,
287 	// IProgressMonitor monitor) throws JavaModelException;
288 	/**
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
295 	 * fragment root.
296 	 *
297 	 * @see IPackageFragmentRoot#K_SOURCE
298 	 * @see IPackageFragmentRoot#K_BINARY
299 	 *
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
304 	 */
getKind()305 	int getKind() throws JavaModelException;
306 
307 	/**
308 	 * Returns an array of non-Java resources contained in this package fragment
309 	 * root.
310 	 * <p>
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.
318 	 * </p>
319 	 *
320 	 * @return an array of non-Java resources contained in this package fragment
321 	 *         root
322 	 * @see IClasspathEntry#getExclusionPatterns
323 	 */
324 	// Object[] getNonJavaResources() throws JavaModelException;
325 	/**
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.
329 	 *
330 	 * @param packageName
331 	 *            the given package name
332 	 * @return the package fragment with the given package name
333 	 */
getPackageFragment(String packageName)334 	IPackageFragment getPackageFragment(String packageName);
335 
336 	/**
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.
340 	 *
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
345 	 *         fragment root
346 	 * @since 2.0
347 	 */
348 	// IClasspathEntry getRawClasspathEntry() throws JavaModelException;
349 	/**
350 	 * Returns the absolute path to the source archive attached to this package
351 	 * fragment root's binary archive.
352 	 *
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
359 	 */
360 	// IPath getSourceAttachmentPath() throws JavaModelException;
361 	/**
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
364 	 * archive.
365 	 *
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
372 	 */
373 	// IPath getSourceAttachmentRootPath() throws JavaModelException;
374 	/**
375 	 * Returns whether this package fragment root's underlying resource is a
376 	 * binary archive (a JAR or zip file).
377 	 *
378 	 * @return true if this package fragment root's underlying resource is a
379 	 *         binary archive, false otherwise
380 	 */
isArchive()381 	public boolean isArchive();
382 
383 	/**
384 	 * Returns whether this package fragment root is external to the workbench
385 	 * (that is, a local file), and has no underlying resource.
386 	 *
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
389 	 *         otherwise
390 	 */
isExternal()391 	boolean isExternal();
392 
393 	/**
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.
397 	 * <p>
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.
402 	 * </p>
403 	 * <p>
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.
411 	 * </p>
412 	 * <p>
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
416 	 * entry.
417 	 * </p>
418 	 * <p>
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.
423 	 * </p>
424 	 * <p>
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.
430 	 * </p>
431 	 * <p>
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.
436 	 * </p>
437 	 *
438 	 * @param destination
439 	 *            the destination path
440 	 * @param updateFlags
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>)
449 	 * @param sibling
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
453 	 * @param monitor
454 	 *            a progress monitor
455 	 *
456 	 * @exception JavaModelException
457 	 *                if this root could not be moved. Reasons include:
458 	 *                <ul>
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>
472 	 *                </ul>
473 	 * @see org.eclipse.core.resources.IResource#move
474 	 * @since 2.1
475 	 */
476 	// void move(IPath destination, int updateResourceFlags, int
477 	// updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor)
478 	// throws JavaModelException;
479 }