IPackageFragmentRoot


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-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 org.eclipse.jdt.core;
20  
21  import org.eclipse.core.runtime.IPath;
22  import org.eclipse.core.runtime.IProgressMonitor; 
23  
24  /**
25   * A package fragment root contains a set of package fragments.
26   * It corresponds to an underlying resource which is either a folder,
27   * JAR, or zip.  In the case of a folder, all descendant folders represent
28   * package fragments.  For a given child folder representing a package fragment, 
29   * the corresponding package name is composed of the folder names between the folder 
30   * for this root and the child folder representing the package, separated by '.'.
31   * In the case of a JAR or zip, the contents of the archive dictates 
32   * the set of package fragments in an analogous manner.
33   * Package fragment roots need to be opened before they can be navigated or manipulated.
34   * The children are of type <code>IPackageFragment</code>, and are in no particular order.
35   * <p>
36   * This interface is not intended to be implemented by clients.
37   * </p>
38   */
39  public interface IPackageFragmentRoot
40      extends IParent, IJavaElement, IOpenable {
41      /**
42       * Kind constant for a source path root. Indicates this root
43       * only contains source files.
44       */
45      int K_SOURCE = 1;
46      /**
47       * Kind constant for a binary path root. Indicates this
48       * root only contains binary files.
49       */
50      int K_BINARY = 2;
51      /**
52       * Empty root path
53       */
54      String   DEFAULT_PACKAGEROOT_PATH = ""; //$NON-NLS-1$
55      /**
56       * Update model flag constant (bit mask value 1) indicating that the operation
57       * is to not copy/move/delete the package fragment root resource.
58       * @since 2.1
59       */
60      int NO_RESOURCE_MODIFICATION = 1;
61      /**
62       * Update model flag constant (bit mask value 2) indicating that the operation
63       * is to update the classpath of the originating project.
64       * @since 2.1
65       */
66      int ORIGINATING_PROJECT_CLASSPATH = 2;
67      /**
68       * Update model flag constant (bit mask value 4) indicating that the operation
69       * is to update the classpath of all referring projects except the originating project.
70       * @since 2.1
71       */
72      int OTHER_REFERRING_PROJECTS_CLASSPATH = 4;
73      /**
74       * Update model flag constant (bit mask value 8) indicating that the operation
75       * is to update the classpath of the destination project.
76       * @since 2.1
77       */
78      int DESTINATION_PROJECT_CLASSPATH = 8;  
79      /**
80       * Update model flag constant (bit mask value 16) indicating that the operation
81       * is to replace the resource and the destination project's classpath entry.
82       * @since 2.1
83       */
84      int REPLACE = 16;   
85      /**
86       * Attaches the source archive identified by the given absolute path to this
87       * binary package fragment root. <code>rootPath</code> specifies the location 
88       * of the root within the archive or folder (empty specifies the default root 
89       * and <code>null</code> specifies the root path should be detected).
90       * Once a source archive or folder is attached to the package fragment root,
91       * the <code>getSource</code> and <code>getSourceRange</code>
92       * methods become operational for binary types/members.
93       * To detach a source archive or folder from a package fragment root, specify 
94       * <code>null</code> as the source path.
95       *
96       * @param sourcePath the given absolute path to the source archive or folder
97       * @param rootPath specifies the location of the root within the archive 
98       *              (empty specifies the default root and <code>null</code> specifies 
99       *               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, IProgressMonitor monitor)
110         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, int updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor) throws JavaModelException;
172     /**
173      * Creates and returns a package fragment in this root with the 
174      * given dot-separated package name.  An empty string specifies the default package. 
175      * This has the side effect of creating all package
176      * fragments that are a prefix of the new package fragment which
177      * do not exist yet. If the package fragment already exists, this
178      * has no effect.
179      *
180      * For a description of the <code>force</code> flag, see <code>IFolder.create</code>.
181      *
182      * @param name the given dot-separated package name
183      * @param force a flag controlling how to deal with resources that
184      *    are not in sync with the local file system
185      * @param monitor the given progress monitor
186      * @exception JavaModelException if the element could not be created. Reasons include:
187      * <ul>
188      * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
189      * <li> A <code>CoreException</code> occurred while creating an underlying resource
190      * <li> This package fragment root is read only (READ_ONLY)
191      * <li> The name is not a valid package name (INVALID_NAME)
192      * </ul>
193      * @return a package fragment in this root with the given dot-separated package name
194      * @see org.eclipse.core.resources.IFolder#create(boolean, boolean, IProgressMonitor)
195      */
196     IPackageFragment createPackageFragment(
197         String   name,
198         boolean force,
199         IProgressMonitor monitor)
200         throws JavaModelException;
201     /**
202      * Deletes the resource of this package fragment root as specified by
203      * <code>IResource.delete(int, IProgressMonitor)</code> but excluding nested
204      * source folders.
205      * <p>
206      * If <code>NO_RESOURCE_MODIFICATION</code> is specified in 
207      * <code>updateModelFlags</code> or if this package fragment root is external, 
208      * this operation doesn't delete the resource. <code>updateResourceFlags</code> 
209      * is then ignored.
210      * </p><p>
211      * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in 
212      * <code>updateModelFlags</code>, update the raw classpath of this package 
213      * fragment root's project by removing the corresponding classpath entry.
214      * </p><p>
215      * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in 
216      * <code>updateModelFlags</code>, update the raw classpaths of all other Java
217      * projects referring to this root's resource by removing the corresponding classpath 
218      * entries.
219      * </p><p>
220      * If no flags is specified in <code>updateModelFlags</code> (using 
221      * <code>IResource.NONE</code>), the default behavior applies: the
222      * resource is deleted (if this package fragment root is not external) and no
223      * classpaths are updated.
224      * </p>
225      * 
226      * @param updateResourceFlags bit-wise or of update resource flag constants
227      *   (<code>IResource.FORCE</code> and <code>IResource.KEEP_HISTORY</code>)
228      * @param updateModelFlags bit-wise or of update resource flag constants
229      *   (<code>ORIGINATING_PROJECT_CLASSPATH</code>,
230      *   <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and 
231      *   <code>NO_RESOURCE_MODIFICATION</code>)
232      * @param monitor a progress monitor
233      * 
234      * @exception JavaModelException if this root could not be deleted. Reasons
235      * include:
236      * <ul>
237      * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li>
238      * <li> A <code>CoreException</code> occurred while deleting the resource 
239      * or updating a classpath
240      * </li>
241      * </ul>
242      * @see org.eclipse.core.resources.IResource#delete(boolean, IProgressMonitor)
243      * @since 2.1
244      */
245     void delete(int updateResourceFlags, int updateModelFlags, IProgressMonitor monitor) throws JavaModelException;
246     /**
247      * Returns this package fragment root's kind encoded as an integer.
248      * A package fragment root can contain source files (i.e. files with one 
249      * of the {@link JavaCore#getJavaLikeExtensions() Java-like extensions},
250      * or <code>.class</code> files, but not both.
251      * If the underlying folder or archive contains other kinds of files, they are ignored.
252      * In particular, <code>.class</code> files are ignored under a source package fragment root,
253      * and source files are ignored under a binary package fragment root.
254      *
255      * @exception JavaModelException if this element does not exist or if an
256      *      exception occurs while accessing its corresponding resource.
257      * @return this package fragment root's kind encoded as an integer
258      * @see IPackageFragmentRoot#K_SOURCE
259      * @see IPackageFragmentRoot#K_BINARY
260      */
261     int getKind() throws JavaModelException;
262     
263     /**
264      * Returns an array of non-Java resources contained in this package fragment root.
265      * <p>
266      * Non-Java resources includes other files and folders located in the same
267      * directories as the compilation units or class files under this package
268      * fragment root. Resources excluded from this package fragment root
269      * by virtue of inclusion/exclusion patterns on the corresponding source classpath
270      * entry are considered non-Java resources and will appear in the result
271      * (possibly in a folder). Thus when a nested source folder is excluded, it will appear
272      * in the non-Java resources of the outer folder.
273      * </p><p>
274      * Since 3.3, if this package fragment root is an archive, the non-Java resources
275      * are a tree of {@link IJarEntryResource}s. One can navigate this tree using
276      * the {@link IJarEntryResource#getChildren()} and 
277      * {@link IJarEntryResource#getParent()} methods.
278      * </p>
279      * 
280      * @return an array of non-Java resources (<code>IFile</code>s, 
281      *              <code>IFolder</code>s, or <code>IStorage</code>s if the
282      *              package fragment root is in archive) contained in this package 
283      *              fragment root
284      * @exception JavaModelException if this element does not exist or if an
285      *      exception occurs while accessing its corresponding resource.
286      * @see IClasspathEntry#getInclusionPatterns()
287      * @see IClasspathEntry#getExclusionPatterns()
288      */
289     Object  [] getNonJavaResources() throws JavaModelException;
290     
291     /**
292      * Returns the package fragment with the given package name.
293      * An empty string indicates the default package.
294      * This is a handle-only operation.  The package fragment
295      * may or may not exist.
296      * 
297      * @param packageName the given package name
298      * @return the package fragment with the given package name
299      */
300     IPackageFragment getPackageFragment(String   packageName);
301     
302 
303     /**
304      * Returns the first raw classpath entry that corresponds to this package
305      * fragment root.
306      * A raw classpath entry corresponds to a package fragment root if once resolved
307      * this entry's path is equal to the root's path. 
308      * 
309      * @exception JavaModelException if this element does not exist or if an
310      *      exception occurs while accessing its corresponding resource.
311      * @return the first raw classpath entry that corresponds to this package fragment root
312      * @since 2.0
313      */
314     IClasspathEntry getRawClasspathEntry() throws JavaModelException;
315     
316     /**
317      * Returns the absolute path to the source archive attached to
318      * this package fragment root's binary archive.
319      *
320      * @return the absolute path to the corresponding source archive, 
321      *   or <code>null</code> if this package fragment root's binary archive
322      *   has no corresponding source archive, or if this package fragment root
323      *   is not a binary archive
324      * @exception JavaModelException if this operation fails
325      */
326     IPath getSourceAttachmentPath() throws JavaModelException;
327     
328     /**
329      * Returns the path within this package fragment root's source archive. 
330      * An empty path indicates that packages are located at the root of the
331      * source archive.
332      *
333      * @return the path within the corresponding source archive, 
334      *   or <code>null</code> if this package fragment root's binary archive
335      *   has no corresponding source archive, or if this package fragment root
336      *   is not a binary archive
337      * @exception JavaModelException if this operation fails
338      */
339     IPath getSourceAttachmentRootPath() throws JavaModelException;
340     
341     /**
342      * Returns whether this package fragment root's underlying
343      * resource is a binary archive (a JAR or zip file).
344      * <p>
345      * This is a handle-only method.
346      * </p>
347      * 
348      * @return true if this package fragment root's underlying resource is a binary archive, false otherwise
349      */
350     public boolean isArchive();
351     
352     /**
353      * Returns whether this package fragment root is external
354      * to the workbench (that is, a local file), and has no
355      * underlying resource.
356      * <p>
357      * This is a handle-only method.
358      * </p>
359      * 
360      * @return true if this package fragment root is external
361      * to the workbench (that is, a local file), and has no
362      * underlying resource, false otherwise
363      */
364     boolean isExternal();
365     
366     /**
367      * Moves the resource of this package fragment root to the destination path
368      * as specified by <code>IResource.move(IPath,int,IProgressMonitor)</code>
369      * but excluding nested source folders.
370      * <p>
371      * If <code>NO_RESOURCE_MODIFICATION</code> is specified in 
372      * <code>updateModelFlags</code> or if this package fragment root is external, 
373      * this operation doesn't move the resource. <code>updateResourceFlags</code> 
374      * is then ignored.
375      * </p><p>
376      * If <code>DESTINATION_PROJECT_CLASSPATH</code> is specified in 
377      * <code>updateModelFlags</code>, updates the classpath of the 
378      * destination's project (if it is a Java project). If a non-<code>null</code> 
379      * sibling is specified, a copy of this root's classpath entry is inserted before the 
380      * sibling on the destination project's raw classpath. If <code>null</code> is 
381      * specified, the classpath entry is added at the end of the raw classpath.
382      * </p><p>
383      * If <code>ORIGINATING_PROJECT_CLASSPATH</code> is specified in 
384      * <code>updateModelFlags</code>, update the raw classpath of this package 
385      * fragment root's project by removing the corresponding classpath entry.
386      * </p><p>
387      * If <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> is specified in 
388      * <code>updateModelFlags</code>, update the raw classpaths of all other Java
389      * projects referring to this root's resource by removing the corresponding classpath 
390      * entries.
391      * </p><p>
392      * If <code>REPLACE</code> is specified in <code>updateModelFlags</code>,
393      * overwrites the resource at the destination path if any.
394      * If the same classpath entry already exists on the destination project's raw
395      * classpath, then the sibling is ignored and the new classpath entry replaces the 
396      * existing one.
397      * </p><p>
398      * If no flags is specified in <code>updateModelFlags</code> (using 
399      * <code>IResource.NONE</code>), the default behavior applies: the
400      * resource is moved (if this package fragment root is not external) and no
401      * classpaths are updated.
402      * </p>
403      * 
404      * @param destination the destination path
405      * @param updateResourceFlags bit-wise or of update flag constants
406      * (<code>IResource.FORCE</code>, <code>IResource.KEEP_HISTORY</code> 
407      * and <code>IResource.SHALLOW</code>)
408      * @param updateModelFlags bit-wise or of update resource flag constants
409      *   (<code>DESTINATION_PROJECT_CLASSPATH</code>,
410      *   <code>ORIGINATING_PROJECT_CLASSPATH</code>,
411      *   <code>OTHER_REFERRING_PROJECTS_CLASSPATH</code> and 
412      *   <code>NO_RESOURCE_MODIFICATION</code>)
413      * @param sibling the classpath entry before which a copy of the classpath
414      * entry should be inserted or <code>null</code> if the classpath entry should
415      * be inserted at the end
416      * @param monitor a progress monitor
417      * 
418      * @exception JavaModelException if this root could not be moved. Reasons
419      * include:
420      * <ul>
421      * <li> This root does not exist (ELEMENT_DOES_NOT_EXIST)</li>
422      * <li> A <code>CoreException</code> occurred while copying the
423      * resource or updating a classpath</li>
424      * <li>
425      * The destination is not inside an existing project and <code>updateModelFlags</code>
426      * has been specified as <code>DESTINATION_PROJECT_CLASSPATH</code> 
427      * (INVALID_DESTINATION)</li>
428      * <li> The sibling is not a classpath entry on the destination project's
429      * raw classpath (INVALID_SIBLING)</li>
430      * <li> The same classpath entry already exists on the destination project's
431      * classpath (NAME_COLLISION) and <code>updateModelFlags</code>
432      * has not been specified as <code>REPLACE</code></li>
433      * </ul>
434      * @see org.eclipse.core.resources.IResource#move(IPath, boolean, IProgressMonitor)
435      * @since 2.1
436      */
437     void move(IPath destination, int updateResourceFlags, int updateModelFlags, IClasspathEntry sibling, IProgressMonitor monitor) throws JavaModelException;
438 }
439
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags