Skip to main content
summaryrefslogtreecommitdiffstats
blob: c2434d349bd36377c8a4e65e1cc157b4595b3f38 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
package org.eclipse.jdt.core;

/*
 * (c) Copyright IBM Corp. 2000, 2001.
 * All Rights Reserved.
 */
 
import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IPath;

import org.eclipse.jdt.core.eval.IEvaluationContext;

/**
 * A Java project represents a view of a project resource in terms of Java 
 * elements such as package fragments, types, methods and fields.
 * A project may contain several package roots, which contain package fragments. 
 * A package root corresponds to an underlying folder or JAR.
 * <p>
 * Each Java project has a classpath, defining which folders contain source code and
 * where required libraries are located. Each Java project also has an output location,
 * defining where the builder writes <code>.class</code> files. A project that
 * references packages in another project can access the packages by including
 * the required project in a classpath entry. The Java model will present the
 * source elements in the required project, and when building, the compiler will
 * use the binaries from that project (that is, the output location of the 
 * required project is used as a library). The classpath format is a sequence 
 * of classpath entries describing the location and contents of package fragment
 * roots.
 * </p>
 * Java project elements need to be opened before they can be navigated or manipulated.
 * The children of a Java project are the package fragment roots that are 
 * defined by the classpath and contained in this project (in other words, it
 * does not include package fragment roots for other projects).
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients. An instance
 * of one of these handles can be created via 
 * <code>JavaCore.create(project)</code>.
 * </p>
 *
 * @see JavaCore#create(org.eclipse.core.resources.IProject)
 * @see IClasspathEntry
 */
public interface IJavaProject extends IParent, IJavaElement, IOpenable {

/**
 * Returns the <code>IJavaElement</code> corresponding to the given
 * classpath-relative path, or <code>null</code> if no such 
 * <code>IJavaElement</code> is found. The result is one of an
 * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
 * <code>IPackageFragment</code>. 
 *
 * <p>For example, the path "java/lang/Object.java", would result in the
 * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
 * "java.lang.Object". The path "java/lang" would result in the
 * <code>IPackageFragment</code> for "java.lang".
 *
 * @exception JavaModelException if the given path is <code>null</code>
 *  or absolute
 */
IJavaElement findElement(IPath path) throws JavaModelException;
/**
 * Returns the first existing package fragment on this project's classpath
 * whose path matches the given (absolute) path, or <code>null</code> if none
 * exist.
 * The path can be:
 * 	- internal to the workbench: "/Project/src"
 *  - external to the workbench: "c:/jdk/classes.zip/java/lang"
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPackageFragment findPackageFragment(IPath path) throws JavaModelException;
/**
 * Returns the existing package fragment root on this project's classpath
 * whose path matches the given (absolute) path, or <code>null</code> if
 * one does not exist.
 * The path can be:
 *	- internal to the workbench: "/Compiler/src"
 *	- external to the workbench: "c:/jdk/classes.zip"
 * 
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPackageFragmentRoot findPackageFragmentRoot(IPath path) throws JavaModelException;
/**
 * Returns all of the existing package fragment roots that exist
 * on the classpath, in the order they are defined by the classpath.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPackageFragmentRoot[] getAllPackageFragmentRoots() throws JavaModelException;
/**
 * Returns an array of non-Java resources directly contained in this project.
 * It does not transitively answer non-Java resources contained in folders;
 * these would have to be explicitly iterated over.
 */
Object[] getNonJavaResources() throws JavaModelException;
/**
 * Returns the full path to the location where the builder writes 
 * <code>.class</code> files.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPath getOutputLocation() throws JavaModelException;
/**
 * Returns a package fragment root for the JAR at the specified file system path.
 * This is a handle-only method.  The underlying <code>java.io.File</code>
 * may or may not exist. No resource is associated with this local JAR
 * package fragment root.
 */
IPackageFragmentRoot getPackageFragmentRoot(String jarPath);
/**
 * Returns a package fragment root for the given resource, which
 * must either be a folder representing the top of a package hierarchy,
 * or a <code>.jar</code> or <code>.zip</code> file.
 * This is a handle-only method.  The underlying resource may or may not exist. 
 */
IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
/**
 * Returns all of the  package fragment roots contained in this
 * project, identified on this project's resolved classpath. The result
 * does not include package fragment roots in other projects referenced
 * on this project's classpath.
 *
 * <p>NOTE: This is equivalent to <code>getChildren()</code>.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
/**
 * Returns the existing package fragment roots identified by the given entry.
 * Note that a classpath entry that refers to another project may
 * have more than one root (if that project has more than on root
 * containing source), and classpath entries within the current
 * project identify a single root.
 *
 * If the classpath entry denotes a variable, it will be resolved and returning
 * the roots of the target entry (empty if not resolvable).
 */
IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
/**
 * Returns all package fragments in all package fragment roots contained
 * in this project. This is a convenience method.
 *
 * Note that the package fragment roots corresponds to the resolved
 * classpath of the project.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
IPackageFragment[] getPackageFragments() throws JavaModelException;
/**
 * Returns the <code>IProject</code> on which this <code>IJavaProject</code>
 * was created. This is handle-only method.
 */
IProject getProject();
/**
 * Returns the raw classpath for the project, as a list of classpath entries. This corresponds to the exact set
 * of entries which were assigned using <code>setRawClasspath</code>, in particular such a classpath may contain
 * classpath variable entries. Classpath variable entries can be resolved individually (see <code>JavaCore#getClasspathVariable</code>),
 * or the full classpath can be resolved at once using the helper method <code>getResolvedClasspath</code>.
 * <p>
 * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
 * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
 * can simply refer to some variables defining the proper locations of these external JARs.
 * <p>
 * @exception JavaModelException in one of the corresponding situation:
 * <ul>
 *    <li> this element does not exist </li>
 *    <li> an exception occurs while accessing its corresponding resource </li>
 * </ul>
 * @see IClasspathEntry
 */
IClasspathEntry[] getRawClasspath() throws JavaModelException;
/**
 * Returns the names of the projects that are directly required by this
 * project. A project is required if it is in its classpath.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 */
String[] getRequiredProjectNames() throws JavaModelException;
/**
 * This is a helper method returning the resolved classpath for the project, as a list of classpath entries, 
 * where all classpath variable entries have been resolved and substituted with their final target entries.
 * <p>
 * A resolved classpath corresponds to a particular instance of the raw classpath bound in the context of 
 * the current values of the referred variables, and thus should not be persisted.
 * <p>
 * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
 * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
 * can simply refer to some variables defining the proper locations of these external JARs.
 * <p>
 * The boolean argument <code>ignoreUnresolvedVariable</code> allows to specify how to handle unresolvable variables,
 * when set to <code>true</code>, missing variables are simply ignored, the resulting path is then only formed of the
 * resolvable entries, without any indication about which variable(s) was ignored. When set to <code>false</code>, a
 * JavaModelException will be thrown for the first unresolved variable (from left to right).
 * 
 * @exception JavaModelException in one of the corresponding situation:
 * <ul>
 *    <li> this element does not exist </li>
 *    <li> an exception occurs while accessing its corresponding resource </li>
 *    <li> a classpath variable was not resolvable and <code>ignoreUnresolvedVariable</code> was set to <code>false</code>. </li>
 * </ul>
 * @see IClasspathEntry
 */
IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedVariable) throws JavaModelException;
/**
 * Returns whether this project has been built at least once and thus whether it has a build state.
 */
public boolean hasBuildState();
/**
 * Returns whether setting this projec's classpath to the given classpath entries
 * would result in a cycle.
 *
 * If the set of entries contains some variables, these are resolved in order to determine
 * cycles.
 */
public boolean hasClasspathCycle(IClasspathEntry[] entries);
/**
 * Creates a new evaluation context.
 */
IEvaluationContext newEvaluationContext();
/**
 * Creates and returns a type hierarchy for all types in the given
 * region, considering subtypes within that region.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 *
 * @exception IllegalArgumentException if region is <code>null</code>
 */
ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor) throws JavaModelException;
/**
 * Creates and returns a type hierarchy for the given type considering
 * subtypes in the specified region.
 *
 * @exception JavaModelException if this element does not exist or if an
 *		exception occurs while accessing its corresponding resource
 *
 * @exception IllegalArgumentException if type or region is <code>null</code>
 */
ITypeHierarchy newTypeHierarchy(IType type, IRegion region, IProgressMonitor monitor) throws JavaModelException;
/**
 * Sets the output location of this project to the location
 * described by the given absolute path.
 * <p>
 *
 * @exception JavaModelException if the classpath could not be set. Reasons include:
 * <ul>
 *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 *	<li>The path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
 *	<li>The path is not an absolute path (<code>RELATIVE_PATH</code>)
 *  <li>The path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
 * </ul>
 */
void setOutputLocation(IPath path, IProgressMonitor monitor) throws JavaModelException;
/**
 * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
 * classpath variable entries. Classpath variable entries can be resolved individually (see <code>JavaCore#getClasspathVariable</code>),
 * or the full classpath can be resolved at once using the helper method <code>getResolvedClasspath</code>.
 * <p>
 * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
 * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
 * can simply refer to some variables defining the proper locations of these external JARs.
 * <p>
 * Setting the classpath to <code>null</code> specifies a default classpath
 * (the project root). Setting the classpath to an empty array specifies an
 * empty classpath.
 * <p>
 * If a cycle is detected while setting this classpath, an error marker will be added
 * to the project closing the cycle.
 * To avoid this problem, use <code>hasClasspathCycle(IClasspathEntry[] entries)</code>
 * before setting the classpath.
 *
 * @exception JavaModelException if the classpath could not be set. Reasons include:
 * <ul>
 * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
 * <li> Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
 * <li> A entry of kind <code>CPE_PROJECT</code> refers to this project (INVALID_PATH)
 * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
 * </ul>
 * @see IClasspathEntry
 */
void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor) throws JavaModelException;
}

Back to the top