IPackageFragment


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   *******************************************************************************/
11  package org.eclipse.jdt.core;
12  
13  import org.eclipse.core.runtime.IProgressMonitor;
14  
15  /**
16   * A package fragment is a portion of the workspace corresponding to an entire package,
17   * or to a portion thereof. The distinction between a package fragment and a package
18   * is that a package with some name is the union of all package fragments in the class path
19   * which have the same name.
20   * <p>
21   * Package fragments elements need to be opened before they can be navigated or manipulated.
22   * The children are of type <code>ICompilationUnit</code> (representing a source file) or 
23   * <code>IClassFile</code> (representing a binary class file).
24   * The children are listed in no particular order.
25   * </p>
26   * <p>
27   * This interface is not intended to be implemented by clients.
28   * </p>
29   */
30  public interface IPackageFragment extends IParent, IJavaElement, IOpenable, ISourceManipulation {
31  
32      /** 
33       * <p>
34       * The name of package fragment for the default package (value: the empty 
35       * string, <code>""</code>).
36       * </p>
37      */
38      public static final String   DEFAULT_PACKAGE_NAME = ""; //$NON-NLS-1$
39      /**
40       * Returns whether this fragment contains at least one Java resource.
41       * @return true if this fragment contains at least one Java resource, false otherwise
42       * @exception JavaModelException if this element does not exist or if an
43       *      exception occurs while accessing its corresponding resource.
44       */
45      boolean containsJavaResources() throws JavaModelException;
46      /**
47       * Creates and returns a compilation unit in this package fragment 
48       * with the specified name and contents. No verification is performed
49       * on the contents.
50       *
51       * <p>It is possible that a compilation unit with the same name already exists in this 
52       * package fragment.
53       * The value of the <code>force</code> parameter effects the resolution of
54       * such a conflict:<ul>
55       * <li> <code>true</code> - in this case the compilation is created with the new contents</li>
56       * <li> <code>false</code> - in this case a <code>JavaModelException</code> is thrown</li>
57       * </ul>
58       *
59       * @param contents the given contents
60       * @param force specify how to handle conflict is the same name already exists
61       * @param monitor the given progress monitor
62       * @param name the given name
63       * @exception JavaModelException if the element could not be created. Reasons include:
64       * <ul>
65       * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
66       * <li> A <code>CoreException</code> occurred while creating an underlying resource
67       * <li> The name is not a valid compilation unit name (INVALID_NAME)
68       * <li> The contents are <code>null</code> (INVALID_CONTENTS)
69       * </ul>
70       * @return a compilation unit in this package fragment 
71       * with the specified name and contents
72       */
73      ICompilationUnit createCompilationUnit(String   name, String   contents, boolean force, IProgressMonitor monitor) throws JavaModelException;
74      /**
75       * Returns the class file with the specified name
76       * in this package (for example, <code>"Object.class"</code>).
77       * The ".class" suffix is required.
78       * This is a handle-only method.  The class file may or may not be present.
79       * @param name the given name
80       * @return the class file with the specified name in this package
81       */
82      IClassFile getClassFile(String   name);
83      /**
84       * Returns all of the class files in this package fragment.
85       *
86       * <p>Note: it is possible that a package fragment contains only
87       * compilation units (in other words, its kind is <code>K_SOURCE</code>), in
88       * which case this method returns an empty collection.
89       *
90       * @exception JavaModelException if this element does not exist or if an
91       *      exception occurs while accessing its corresponding resource.
92       * @return all of the class files in this package fragment
93       */
94      IClassFile[] getClassFiles() throws JavaModelException;
95      /**
96       * Returns the compilation unit with the specified name
97       * in this package (for example, <code>"Object.java"</code>).
98       * The name has to be a valid compilation unit name.
99       * This is a handle-only method.  The compilation unit may or may not be present.
100      * 
101      * @param name the given name
102      * @return the compilation unit with the specified name in this package
103      * @see JavaConventions#validateCompilationUnitName(String name, String sourceLevel, String complianceLevel)
104      */
105     ICompilationUnit getCompilationUnit(String   name);
106     /**
107      * Returns all of the compilation units in this package fragment.
108      *
109      * <p>Note: it is possible that a package fragment contains only
110      * class files (in other words, its kind is <code>K_BINARY</code>), in which
111      * case this method returns an empty collection.
112      * </p>
113      *
114      * @exception JavaModelException if this element does not exist or if an
115      *      exception occurs while accessing its corresponding resource.
116      * @return all of the compilation units in this package fragment
117      */
118     ICompilationUnit[] getCompilationUnits() throws JavaModelException;
119     /**
120      * Returns all of the compilation units in this package fragment that are 
121      * in working copy mode and that have the given owner.
122      * <p>
123      * Only existing working copies are returned. So a compilation unit handle that has no 
124      * corresponding resource on disk will be included if and only if is in working copy mode.
125      * </p>
126      * <p>Note: it is possible that a package fragment contains only
127      * class files (in other words, its kind is <code>K_BINARY</code>), in which
128      * case this method returns an empty collection.
129      * </p>
130      *
131      * @param owner the owner of the returned compilation units
132      * @exception JavaModelException if this element does not exist or if an
133      *      exception occurs while accessing its corresponding resource.
134      * @return all of the compilation units in this package fragment
135      * @since 3.0
136      */
137     ICompilationUnit[] getCompilationUnits(WorkingCopyOwner owner) throws JavaModelException;
138     /**
139      * Returns the dot-separated package name of this fragment, for example
140      * <code>"java.lang"</code>, or <code>""</code> (the empty string),
141      * for the default package.
142      * 
143      * @return the dot-separated package name of this fragment
144      */
145     String   getElementName();
146     /**
147      * Returns this package fragment's root kind encoded as an integer.
148      * A package fragment can contain source files (i.e. files with one of 
149      * the {@link JavaCore#getJavaLikeExtensions() Java-like extensions}),
150      * or <code>.class</code> files. This is a convenience method.
151      *
152      * @exception JavaModelException if this element does not exist or if an
153      *      exception occurs while accessing its corresponding resource.
154      * @return this package fragment's root kind encoded as an integer
155      * @see IPackageFragmentRoot#K_SOURCE
156      * @see IPackageFragmentRoot#K_BINARY
157      */
158     int getKind() throws JavaModelException;
159     /**
160      * Returns an array of non-Java resources contained in this package fragment.
161      * <p>
162      * Non-Java resources includes other files and folders located in the same
163      * directory as the compilation units or class files for this package 
164      * fragment. Source files excluded from this package by virtue of 
165      * inclusion/exclusion patterns on the corresponding source classpath entry
166      * are considered non-Java resources and will appear in the result
167      * (possibly in a folder).
168      * </p><p>
169      * Since 3.3, if this package fragment is inside an archive, the non-Java resources
170      * are a tree of {@link IJarEntryResource}s. One can navigate this tree using
171      * the {@link IJarEntryResource#getChildren()} and 
172      * {@link IJarEntryResource#getParent()} methods.
173      * </p>
174      * 
175      * @exception JavaModelException if this element does not exist or if an
176      *      exception occurs while accessing its corresponding resource.
177      * @return an array of non-Java resources (<code>IFile</code>s, 
178      *              <code>IFolder</code>s, or <code>IStorage</code>s if the
179      *              package fragment is in an archive) contained in this package 
180      *              fragment
181      * @see IClasspathEntry#getInclusionPatterns()
182      * @see IClasspathEntry#getExclusionPatterns()
183      */
184     Object  [] getNonJavaResources() throws JavaModelException;
185     /**
186      * Returns whether this package fragment's name is
187      * a prefix of other package fragments in this package fragment's
188      * root.
189      *
190      * @exception JavaModelException if this element does not exist or if an
191      *      exception occurs while accessing its corresponding resource.
192      * @return true if this package fragment's name is a prefix of other package fragments in this package fragment's root, false otherwise
193      */
194     boolean hasSubpackages() throws JavaModelException;
195     /**
196      * Returns whether this package fragment is a default package.
197      * This is a handle-only method.
198      * 
199      * @return true if this package fragment is a default package
200      */
201     boolean isDefaultPackage();
202 }
203
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags