001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: * IBM Corporation - specified that a source archive or a source folder can be attached to a binary
011: * package fragment root.
012: * IBM Corporation - added root manipulation APIs: copy, delete, move
013: * IBM Corporation - added DESTINATION_PROJECT_CLASSPATH
014: * IBM Corporation - added OTHER_REFERRING_PROJECTS_CLASSPATH
015: * IBM Corporation - added NO_RESOURCE_MODIFICATION
016: * IBM Corporation - added REPLACE
017: * IBM Corporation - added ORIGINATING_PROJECT_CLASSPATH
018: *******************************************************************************/package org.eclipse.jdt.core;
019:
020: import org.eclipse.core.runtime.IPath;
021: import org.eclipse.core.runtime.IProgressMonitor;
022:
023: /**
024: * A package fragment root contains a set of package fragments.
025: * It corresponds to an underlying resource which is either a folder,
026: * JAR, or zip. In the case of a folder, all descendant folders represent
027: * package fragments. For a given child folder representing a package fragment,
028: * the corresponding package name is composed of the folder names between the folder
029: * for this root and the child folder representing the package, separated by '.'.
030: * In the case of a JAR or zip, the contents of the archive dictates
031: * the set of package fragments in an analogous manner.
032: * Package fragment roots need to be opened before they can be navigated or manipulated.
033: * The children are of type <code>IPackageFragment</code>, and are in no particular order.
034: * <p>
035: * This interface is not intended to be implemented by clients.
036: * </p>
037: */
038: public interface IPackageFragmentRoot extends IParent, IJavaElement,
039: IOpenable {
040: /**
041: * Kind constant for a source path root. Indicates this root
042: * only contains source files.
043: */
044: int K_SOURCE = 1;
045: /**
046: * Kind constant for a binary path root. Indicates this
047: * root only contains binary files.
048: */
049: int K_BINARY = 2;
050: /**
051: * Empty root path
052: */
053: String DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$
054: /**
055: * Update model flag constant (bit mask value 1) indicating that the operation
056: * is to not copy/move/delete the package fragment root resource.
057: * @since 2.1
058: */
059: int NO_RESOURCE_MODIFICATION = 1;
060: /**
061: * Update model flag constant (bit mask value 2) indicating that the operation
062: * is to update the classpath of the originating project.
063: * @since 2.1
064: */
065: int ORIGINATING_PROJECT_CLASSPATH = 2;
066: /**
067: * Update model flag constant (bit mask value 4) indicating that the operation
068: * is to update the classpath of all referring projects except the originating project.
069: * @since 2.1
070: */
071: int OTHER_REFERRING_PROJECTS_CLASSPATH = 4;
072: /**
073: * Update model flag constant (bit mask value 8) indicating that the operation
074: * is to update the classpath of the destination project.
075: * @since 2.1
076: */
077: int DESTINATION_PROJECT_CLASSPATH = 8;
078: /**
079: * Update model flag constant (bit mask value 16) indicating that the operation
080: * is to replace the resource and the destination project's classpath entry.
081: * @since 2.1
082: */
083: int REPLACE = 16;
084:
085: /**
086: * Attaches the source archive identified by the given absolute path to this
087: * binary package fragment root. <code>rootPath</code> specifies the location
088: * of the root within the archive or folder (empty specifies the default root
089: * and <code>null</code> specifies the root path should be detected).
090: * Once a source archive or folder is attached to the package fragment root,
091: * the <code>getSource</code> and <code>getSourceRange</code>
092: * methods become operational for binary types/members.
093: * To detach a source archive or folder from a package fragment root, specify
094: * <code>null</code> as the source path.
095: *
096: * @param sourcePath the given absolute path to the source archive or folder
097: * @param rootPath specifies the location of the root within the archive
098: * (empty specifies the default root and <code>null</code> specifies
099: * automatic detection of the root path)
100: * @param monitor the given progress monitor
101: * @exception JavaModelException if this operation fails. Reasons include:
102: * <ul>
103: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
104: * <li> A <code>CoreException</code> occurred while updating a server property
105: * <li> This package fragment root is not of kind binary (INVALID_ELEMENT_TYPES)
106: * <li> The path provided is not absolute (RELATIVE_PATH)
107: * </ul>
108: */
109: void attachSource(IPath sourcePath, IPath rootPath,
110: IProgressMonitor monitor) throws JavaModelException;
111:
112: /**
113: * Copies the resource of this package fragment root to the destination path
114: * as specified by <code>IResource.copy(IPath, int, IProgressMonitor)</code>
115: * but excluding nested source folders.
116: * <p>
117: * If <code>NO_RESOURCE_MODIFICATION</code> is specified in
118: * <code>updateModelFlags</code> or if this package fragment root is external,
119: * this operation doesn't copy the resource. <code>updateResourceFlags</code>
120: * is then ignored.
121: * </p><p>
122: * If <code>DESTINATION_PROJECT_CLASSPATH</code> is specified in
123: * <code>updateModelFlags</code>, updates the classpath of the
124: * destination's project (if it is a Java project). If a non-<code>null</code>
125: * sibling is specified, a copy of this root's classpath entry is inserted before the
126: * sibling on the destination project's raw classpath. If <code>null</code> is
127: * specified, the classpath entry is added at the end of the raw classpath.
128: * </p><p>
129: * If <code>REPLACE</code> is specified in <code>updateModelFlags</code>,
130: * overwrites the resource at the destination path if any.
131: * If the same classpath entry already exists on the destination project's raw
132: * classpath, then the sibling is ignored and the new classpath entry replaces the
133: * existing one.
134: * </p><p>
135: * If no flags is specified in <code>updateModelFlags</code> (using
136: * <code>IResource.NONE</code>), the default behavior applies: the
137: * resource is copied (if this package fragment root is not external) and the
138: * classpath is not updated.
139: * </p>
140: *
141: * @param destination the destination path
142: * @param updateResourceFlags bit-wise or of update resource flag constants
143: * (<code>IResource.FORCE</code> and <code>IResource.SHALLOW</code>)
144: * @param updateModelFlags bit-wise or of update resource flag constants
145: * (<code>DESTINATION_PROJECT_CLASSPATH</code> and
146: * <code>NO_RESOURCE_MODIFICATION</code>)
147: * @param sibling the classpath entry before which a copy of the classpath
148: * entry should be inserted or <code>null</code> if the classpath entry should
149: * be inserted at the end
150: * @param monitor a progress monitor
151: *
152: * @exception JavaModelException if this root could not be copied. Reasons
153: * include:
154: * <ul>
155: * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li>
156: * <li> A <code>CoreException</code> occurred while copying the
157: * resource or updating a classpath</li>
158: * <li>
159: * The destination is not inside an existing project and <code>updateModelFlags</code>
160: * has been specified as <code>DESTINATION_PROJECT_CLASSPATH</code>
161: * (INVALID_DESTINATION)</li>
162: * <li> The sibling is not a classpath entry on the destination project's
163: * raw classpath (INVALID_SIBLING)</li>
164: * <li> The same classpath entry already exists on the destination project's
165: * classpath (NAME_COLLISION) and <code>updateModelFlags</code>
166: * has not been specified as <code>REPLACE</code></li>
167: * </ul>
168: * @see org.eclipse.core.resources.IResource#copy(IPath, boolean, IProgressMonitor)
169: * @since 2.1
170: */
171: void copy(IPath destination, int updateResourceFlags,
172: int updateModelFlags, IClasspathEntry sibling,
173: IProgressMonitor monitor) throws JavaModelException;
174:
175: /**
176: * Creates and returns a package fragment in this root with the
177: * given dot-separated package name. An empty string specifies the default package.
178: * This has the side effect of creating all package
179: * fragments that are a prefix of the new package fragment which
180: * do not exist yet. If the package fragment already exists, this
181: * has no effect.
182: *
183: * For a description of the <code>force</code> flag, see <code>IFolder.create</code>.
184: *
185: * @param name the given dot-separated package name
186: * @param force a flag controlling how to deal with resources that
187: * are not in sync with the local file system
188: * @param monitor the given progress monitor
189: * @exception JavaModelException if the element could not be created. Reasons include:
190: * <ul>
191: * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
192: * <li> A <code>CoreException</code> occurred while creating an underlying resource
193: * <li> This package fragment root is read only (READ_ONLY)
194: * <li> The name is not a valid package name (INVALID_NAME)
195: * </ul>
196: * @return a package fragment in this root with the given dot-separated package name
197: * @see org.eclipse.core.resources.IFolder#create(boolean, boolean, IProgressMonitor)
198: */
199: IPackageFragment createPackageFragment(String name, boolean force,
200: IProgressMonitor monitor) throws JavaModelException;
201:
202: /**
203: * Deletes the resource of this package fragment root as specified by
204: * <code>IResource.delete(int, IProgressMonitor)</code> but excluding nested
205: * source folders.
206: * <p>
207: * If <code>NO_RESOURCE_MODIFICATION</code> is specified in
208: * <code>updateModelFlags</code> or if this package fragment root is external,
209: * this operation doesn't delete the resource. <code>updateResourceFlags</code>
210: * is then ignored.
211: * </p><p>
212: * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in
213: * <code>updateModelFlags</code>, update the raw classpath of this package
214: * fragment root's project by removing the corresponding classpath entry.
215: * </p><p>
216: * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in
217: * <code>updateModelFlags</code>, update the raw classpaths of all other Java
218: * projects referring to this root's resource by removing the corresponding classpath
219: * entries.
220: * </p><p>
221: * If no flags is specified in <code>updateModelFlags</code> (using
222: * <code>IResource.NONE</code>), the default behavior applies: the
223: * resource is deleted (if this package fragment root is not external) and no
224: * classpaths are updated.
225: * </p>
226: *
227: * @param updateResourceFlags bit-wise or of update resource flag constants
228: * (<code>IResource.FORCE</code> and <code>IResource.KEEP_HISTORY</code>)
229: * @param updateModelFlags bit-wise or of update resource flag constants
230: * (<code>ORIGINATING_PROJECT_CLASSPATH</code>,
231: * <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and
232: * <code>NO_RESOURCE_MODIFICATION</code>)
233: * @param monitor a progress monitor
234: *
235: * @exception JavaModelException if this root could not be deleted. Reasons
236: * include:
237: * <ul>
238: * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li>
239: * <li> A <code>CoreException</code> occurred while deleting the resource
240: * or updating a classpath
241: * </li>
242: * </ul>
243: * @see org.eclipse.core.resources.IResource#delete(boolean, IProgressMonitor)
244: * @since 2.1
245: */
246: void delete(int updateResourceFlags, int updateModelFlags,
247: IProgressMonitor monitor) throws JavaModelException;
248:
249: /**
250: * Returns this package fragment root's kind encoded as an integer.
251: * A package fragment root can contain source files (i.e. files with one
252: * of the {@link JavaCore#getJavaLikeExtensions() Java-like extensions},
253: * or <code>.class</code> files, but not both.
254: * If the underlying folder or archive contains other kinds of files, they are ignored.
255: * In particular, <code>.class</code> files are ignored under a source package fragment root,
256: * and source files are ignored under a binary package fragment root.
257: *
258: * @exception JavaModelException if this element does not exist or if an
259: * exception occurs while accessing its corresponding resource.
260: * @return this package fragment root's kind encoded as an integer
261: * @see IPackageFragmentRoot#K_SOURCE
262: * @see IPackageFragmentRoot#K_BINARY
263: */
264: int getKind() throws JavaModelException;
265:
266: /**
267: * Returns an array of non-Java resources contained in this package fragment root.
268: * <p>
269: * Non-Java resources includes other files and folders located in the same
270: * directories as the compilation units or class files under this package
271: * fragment root. Resources excluded from this package fragment root
272: * by virtue of inclusion/exclusion patterns on the corresponding source classpath
273: * entry are considered non-Java resources and will appear in the result
274: * (possibly in a folder). Thus when a nested source folder is excluded, it will appear
275: * in the non-Java resources of the outer folder.
276: * </p><p>
277: * Since 3.3, if this package fragment root is an archive, the non-Java resources
278: * are a tree of {@link IJarEntryResource}s. One can navigate this tree using
279: * the {@link IJarEntryResource#getChildren()} and
280: * {@link IJarEntryResource#getParent()} methods.
281: * </p>
282: *
283: * @return an array of non-Java resources (<code>IFile</code>s,
284: * <code>IFolder</code>s, or <code>IStorage</code>s if the
285: * package fragment root is in archive) contained in this package
286: * fragment root
287: * @exception JavaModelException if this element does not exist or if an
288: * exception occurs while accessing its corresponding resource.
289: * @see IClasspathEntry#getInclusionPatterns()
290: * @see IClasspathEntry#getExclusionPatterns()
291: */
292: Object[] getNonJavaResources() throws JavaModelException;
293:
294: /**
295: * Returns the package fragment with the given package name.
296: * An empty string indicates the default package.
297: * This is a handle-only operation. The package fragment
298: * may or may not exist.
299: *
300: * @param packageName the given package name
301: * @return the package fragment with the given package name
302: */
303: IPackageFragment getPackageFragment(String packageName);
304:
305: /**
306: * Returns the first raw classpath entry that corresponds to this package
307: * fragment root.
308: * A raw classpath entry corresponds to a package fragment root if once resolved
309: * this entry's path is equal to the root's path.
310: *
311: * @exception JavaModelException if this element does not exist or if an
312: * exception occurs while accessing its corresponding resource.
313: * @return the first raw classpath entry that corresponds to this package fragment root
314: * @since 2.0
315: */
316: IClasspathEntry getRawClasspathEntry() throws JavaModelException;
317:
318: /**
319: * Returns the absolute path to the source archive attached to
320: * this package fragment root's binary archive.
321: *
322: * @return the absolute path to the corresponding source archive,
323: * or <code>null</code> if this package fragment root's binary archive
324: * has no corresponding source archive, or if this package fragment root
325: * is not a binary archive
326: * @exception JavaModelException if this operation fails
327: */
328: IPath getSourceAttachmentPath() throws JavaModelException;
329:
330: /**
331: * Returns the path within this package fragment root's source archive.
332: * An empty path indicates that packages are located at the root of the
333: * source archive.
334: *
335: * @return the path within the corresponding source archive,
336: * or <code>null</code> if this package fragment root's binary archive
337: * has no corresponding source archive, or if this package fragment root
338: * is not a binary archive
339: * @exception JavaModelException if this operation fails
340: */
341: IPath getSourceAttachmentRootPath() throws JavaModelException;
342:
343: /**
344: * Returns whether this package fragment root's underlying
345: * resource is a binary archive (a JAR or zip file).
346: * <p>
347: * This is a handle-only method.
348: * </p>
349: *
350: * @return true if this package fragment root's underlying resource is a binary archive, false otherwise
351: */
352: public boolean isArchive();
353:
354: /**
355: * Returns whether this package fragment root is external
356: * to the workbench (that is, a local file), and has no
357: * underlying resource.
358: * <p>
359: * This is a handle-only method.
360: * </p>
361: *
362: * @return true if this package fragment root is external
363: * to the workbench (that is, a local file), and has no
364: * underlying resource, false otherwise
365: */
366: boolean isExternal();
367:
368: /**
369: * Moves the resource of this package fragment root to the destination path
370: * as specified by <code>IResource.move(IPath,int,IProgressMonitor)</code>
371: * but excluding nested source folders.
372: * <p>
373: * If <code>NO_RESOURCE_MODIFICATION</code> is specified in
374: * <code>updateModelFlags</code> or if this package fragment root is external,
375: * this operation doesn't move the resource. <code>updateResourceFlags</code>
376: * is then ignored.
377: * </p><p>
378: * If <code>DESTINATION_PROJECT_CLASSPATH</code> is specified in
379: * <code>updateModelFlags</code>, updates the classpath of the
380: * destination's project (if it is a Java project). If a non-<code>null</code>
381: * sibling is specified, a copy of this root's classpath entry is inserted before the
382: * sibling on the destination project's raw classpath. If <code>null</code> is
383: * specified, the classpath entry is added at the end of the raw classpath.
384: * </p><p>
385: * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in
386: * <code>updateModelFlags</code>, update the raw classpath of this package
387: * fragment root's project by removing the corresponding classpath entry.
388: * </p><p>
389: * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in
390: * <code>updateModelFlags</code>, update the raw classpaths of all other Java
391: * projects referring to this root's resource by removing the corresponding classpath
392: * entries.
393: * </p><p>
394: * If <code>REPLACE</code> is specified in <code>updateModelFlags</code>,
395: * overwrites the resource at the destination path if any.
396: * If the same classpath entry already exists on the destination project's raw
397: * classpath, then the sibling is ignored and the new classpath entry replaces the
398: * existing one.
399: * </p><p>
400: * If no flags is specified in <code>updateModelFlags</code> (using
401: * <code>IResource.NONE</code>), the default behavior applies: the
402: * resource is moved (if this package fragment root is not external) and no
403: * classpaths are updated.
404: * </p>
405: *
406: * @param destination the destination path
407: * @param updateResourceFlags bit-wise or of update flag constants
408: * (<code>IResource.FORCE</code>, <code>IResource.KEEP_HISTORY</code>
409: * and <code>IResource.SHALLOW</code>)
410: * @param updateModelFlags bit-wise or of update resource flag constants
411: * (<code>DESTINATION_PROJECT_CLASSPATH</code>,
412: * <code>ORIGINATING_PROJECT_CLASSPATH</code>,
413: * <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and
414: * <code>NO_RESOURCE_MODIFICATION</code>)
415: * @param sibling the classpath entry before which a copy of the classpath
416: * entry should be inserted or <code>null</code> if the classpath entry should
417: * be inserted at the end
418: * @param monitor a progress monitor
419: *
420: * @exception JavaModelException if this root could not be moved. Reasons
421: * include:
422: * <ul>
423: * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li>
424: * <li> A <code>CoreException</code> occurred while copying the
425: * resource or updating a classpath</li>
426: * <li>
427: * The destination is not inside an existing project and <code>updateModelFlags</code>
428: * has been specified as <code>DESTINATION_PROJECT_CLASSPATH</code>
429: * (INVALID_DESTINATION)</li>
430: * <li> The sibling is not a classpath entry on the destination project's
431: * raw classpath (INVALID_SIBLING)</li>
432: * <li> The same classpath entry already exists on the destination project's
433: * classpath (NAME_COLLISION) and <code>updateModelFlags</code>
434: * has not been specified as <code>REPLACE</code></li>
435: * </ul>
436: * @see org.eclipse.core.resources.IResource#move(IPath, boolean, IProgressMonitor)
437: * @since 2.1
438: */
439: void move(IPath destination, int updateResourceFlags,
440: int updateModelFlags, IClasspathEntry sibling,
441: IProgressMonitor monitor) throws JavaModelException;
442: }
|