Gitiles
Code Review Sign In
git.eclipse.org / objectteams / org.eclipse.objectteams / refs/heads/OI2JIRO / . / org.eclipse.jdt.core / notes / API_changes.html
blob: 0ae31a5600458a85d47bd97426fd8afa1e981f93 [file] [log] [blame]
Stephan Herrmann7b7062f2010-04-01 19:56:59 +0000[diff] [blame]1<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
2<html>
3<head>
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5 <meta name="Author" content="IBM">
6 <title>JDT/Core Breaking API changes</title>
7 <link rel="stylesheet" href="../jdt_core_style.css" charset="iso-8859-1" type="text/css">
8</head>
9<body text="#000000" bgcolor="#FFFFFF">
10&nbsp;
11
12<table border=0 cellspacing=5 cellpadding=2 width="100%" >
13 <tr>
14 <td align="left" width="72%" class="title1">
15 <font size="+3"><b>jdt core - Breaking API changes from R2.1 to R3.0</b></font>
16 </td>
17 </tr>
18 <tr>
19 <td align="left" width="72%" class="title2">
20 <font size="-2" color="#8080ff">java development tooling core</font>
21 </td>
22 </tr>
23 <tr><td>&nbsp;</td></tr>
24 <tr>
25 <td align="left" width="72%" class="title3">
26 <font size="-1">
27 This document lists all API changes (breaking or not) that occured between R2.1 and R3.0 and how to migrate from the R2.1 API to
28 the R3.0 API.
29 </font>
30 </td>
31 </tr>
32</table>
33<hr><h1>New API on <code>org.eclipse.jdt.core.dom.AST</code></h1>
34 (in progress) Last edit: 2003/07/18
35<h2>Problem description</h2>
36 Creating an DOM/AST for a compilation unit costs a lot when the user wants only a subpart
37 of the compilation unit to be populated. For example, only the statements of one method are
38 useful and there is no need to create the statements of the other methods.
39 <p>
40 See also <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=40474 ">bug 40474</a>.
41 </p>
42<h2>Problem resolution</h2>
43 Two new APIs have been added on <code>org.eclipse.jdt.core.dom.AST</code>.<br>
44 <ul>
45 <li><pre><code>public static org.eclipse.jdt.core.dom.CompilationUnit parsePartialCompilationUnit(
46 org.eclipse.jdt.core.ICompilationUnit unit,
47 int position,
48 boolean resolveBindings)</code>
49 </pre>
50 </li>
51 <li><pre><code>public static org.eclipse.jdt.core.dom.CompilationUnit parsePartialCompilationUnit(
52 org.eclipse.jdt.core.ICompilationUnit unit,
53 int position,
54 boolean resolveBindings,
55 org.eclipse.jdt.core.WorkingCopyOwner owner)</code>
56 </pre>
57 </ul>
58<h2>Converting to the new API</h2>
59 None.
60
61<hr><h1>IWorkingCopy is removed</h1>
62 (in progress) Last edit: 2003/07/03
63<h2>Problem description</h2>
64 Historically, <code>IWorkingCopy</code> gathered all working copy concerns,
65 and <code>ICompilationUnit</code> implement this interface, though only the
66 factory method makes sense for them; thus their implementation of the working
67 copy features do nothing relevant to clients. <code>IWorkingCopy</code> also
68 implements the spec'ed factory method, but it doesn't work for these.
69 <p>
70 See also <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=36987 ">bug 36987</a>.
71 </p>
72<h2>Problem resolution</h2>
73 Interface <code>IWorkingCopy</code> is removed and all its functionality is moved to <code>ICompilationUnit</code>.
74<h2>Converting to the new API</h2>
75 Clients using <code>IWorkingCopy</code> and <code>ICompilationUnit</code> can
76 adapt to this change by referencing <code>ICompilationUnit</code> instead of
77 <code>IWorkingCopy</code> when a working copy is needed.
78
79<hr><h1>Working copy factory methods return ICompilationUnit</h1>
80 (in progress) Last edit: 2003/07/03
81<h2>Problem description</h2>
82 Working copies were initialy designed to be editable elements on any <code>IJavaElement</code>.
83 Pratice showed that they were used only to edit <code>ICompilationUnit</code>. This imposed
84 downcasting to <code>IWorkingCopy</code> when using the working copy factory methods.
85<h2>Problem resolution</h2>
86 Factory methods that create <code>ICompilationUnits</code> (i.e.
87 <code>getWorkingCopy</code>) now return an <code>ICompilationUint</code> instead of an
88 <code>IJavaElement</code>.
89<h2>Converting to the new API</h2>
90 Clients using factory methods to create working copies can now remove the cast from
91 <code>IJavaElement</code> to <code>IWorkingCopy</code>, <code>ICompilationUint</code>
92 being compatible with <code>IWorkingCopy</code>.
93
94<hr><h1>CharOperation.pathMatch(...) treats non absolute pattern as Ant does</h1>
95 Last edit: 2003/06/11 (-&gt;M2)
96<h2>Problem description</h2>
97 <code>CharOperation.pathMatch(...)</code> used to treat non absolute pattern <code>'foo'</code>
98 as <code>'**/foo'</code> for free. This was inconsistent with Ant patternset rules.
99<h2>Problem resolution</h2>
100 <code>CharOperation.pathMatch(...)</code> no longer treat non absolute pattern <code>'foo'</code>
101 as <code>'**/foo'</code> for free. This has no incidence on
102 source folder exclusion patterns which are implicitely concatenating exclusion patterns to source folder
103 paths when using them. Only direct clients to this <code>CharOperation</code> API will be affected.
104<h2>Converting to the new API</h2>
105 TODO
106
107<hr><h1>Change in syntax error message ID</h1>
108 Last edit: 2003/06/11 (-&gt;M2)
109<h2>Problem description</h2>
110 TODO
111<h2>Problem resolution</h2>
112 The new diagnose of syntax errors use new error messages.
113 <p>The following messages ID are added:</p>
114 <ul>
115 <li>IProblem.ParsingErrorInsertTokenBefore</li>
116 <li>IProblem.ParsingErrorInsertTokenAfter</li>
117 <li>IProblem.ParsingErrorDeleteToken</li>
118 <li>IProblem.ParsingErrorDeleteTokens</li>
119 <li>IProblem.ParsingErrorMergeTokens</li>
120 <li>IProblem.ParsingErrorInvalidToken</li>
121 <li>IProblem.ParsingErrorMisplacedConstruct</li>
122 <li>IProblem.ParsingErrorReplaceTokens</li>
123 <li>IProblem.ParsingErrorNoSuggestionForTokens</li>
124 <li>IProblem.ParsingErrorUnexpectedEOF</li>
125 <li>IProblem.ParsingErrorInsertToComplete</li>
126 <li>IProblem.ParsingErrorInsertToCompleteScope</li>
127 <li>IProblem.ParsingErrorInsertToCompletePhrase</li>
128 </ul>
129 <p>The following messages ID are removed:</p>
130 <ul>
131 <li>IProblem.ParsingErrorNoSuggestion</li>
132 <li>IProblem.ParsingErrorOnKeyword</li>
133 <li>IProblem.ParsingErrorOnKeywordNoSuggestion</li>
134 <li>IProblem.UnmatchedBracket</li>
135 <li>IProblem.InvalidExpressionAsStatement</li>
136 </ul>
137<h2>Converting to the new API</h2>
138 TODO
139
140<hr><h1>Force reload of .classpath file</h1>
141 Last edit: 2003/06/12 (-&gt;M2)
142<h2>Problem description</h2>
143 TODO
144<h2>Problem resolution</h2>
145 Added API <code>IJavaProject#forceClasspathReload(IProgressMonitor)</code> to force reload of <code>.classpath</code> file
146 before next automatic update occurs.
147 <pre>
148/**
149 * Force the project to reload its <code>.classpath</code> file from disk and update the classpath accordingly.
150 * Usually, a change to the <code>.classpath</code> file is automatically noticed and reconciled at the next
151 * resource change notification event. If required to consider such a change prior to the next automatic
152 * refresh, then this functionnality should be used to trigger a refresh. In particular, if a change to the file is performed,
153 * during an operation where this change needs to be reflected before the operation ends, then an explicit refresh is
154 * necessary.
155 *
156 * @param monitor a progress monitor for reporting operation progress
157 * @exception JavaModelException if the classpath could not be updated. Reasons
158 * include:
159 * - This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
160 * - Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
161 * - A entry of kind <code>CPE_PROJECT</code> refers to this project (INVALID_PATH)
162 * - This Java element does not exist (ELEMENT_DOES_NOT_EXIST)
163 * - The output location path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
164 * - The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
165 * - The output location path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
166 * - The classpath is being modified during resource change event notification (CORE_EXCEPTION)
167 * @since 3.0
168 */
169 </pre>
170<h2>Converting to the new API</h2>
171 TODO
172
173<hr><h1>Allow empty path to be equivalent to no source attachment</h1>
174 Last edit: 2003/06/13 (-&gt;M2)
175<h2>Problem description</h2>
176 <code>JavaCore.newLibraryEntry(...)</code> used to not allow an empty source attachment (
177 <code>new Path("")</code>) to be equivalent to no source attachment (i.e. <code>null</code>).
178 This adjustment is made necessary for library entries generated from classpath variables which cannot be set to
179 <code>null</code>. Also see bug <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=38531">38531</a>.
180<h2>Problem resolution</h2>
181 <code>JavaCore.newLibraryEntry(...)</code> will now allow an empty source attachment (
182 <code>new Path("")</code>) to be equivalent to no source attachment (i.e. <code>null</code>).
183 <pre>
184* @param sourceAttachmentPath the absolute path of the corresponding source archive or folder,
185* or <code>null</code> if none. Note, since 3.0, an empty path is allowed to denote no source attachment.
186* and will be automatically converted to <code>null</code>.
187 </pre>
188<h2>Converting to the new API</h2>
189 TODO
190
191<hr><h1>Close the gap between compilation units and working copies</h1>
192 Last edit: 2003/06/27 (-&gt;M2)
193<h2>Problem description</h2>
194 TODO
195 <p>See also <a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=36888 ">bug 36888</a>.
196 </p>
197<h2>Problem resolution</h2>
198 The following new APIs are added to <code>ICompilationUnit</code>:
199 <ul>
200 <li><pre>
201/**
202 * Changes this compilation unit handle into a working copy. A new IBuffer is
203 * created using this compilation unit handle's owner. Uses the primary owner is none was
204 * specified when this compilation unit handle was created.
205 *
206 * When switching to working copy mode, problems are reported to given
207 * IProblemRequestor.
208 *
209 * Once in working copy mode, changes to this compilation unit or its children are done in memory.
210 * Only the new buffer is affected. Using commitWorkingCopy(boolean, IProgressMonitor)
211 * will bring the underlying resource in sync with this compilation unit.
212 *
213 * If this compilation unit was already in working copy mode, an internal counter is incremented and no
214 * other action is taken on this compilation unit. To bring this compilation unit back into the original mode
215 * (where it reflects the underlying resource), discardWorkingCopy must be call as many
216 * times as becomeWorkingCopy.
217 *
218 * @param problemRequestor a requestor which will get notified of problems detected during
219 * reconciling as they are discovered. The requestor can be set to null indicating
220 * that the client is not interested in problems.
221 * @param monitor a progress monitor used to report progress while opening this compilation unit
222 * or null if no progress should be reported
223 * @exception JavaModelException if this compilation unit could not become a working copy.
224 * @see discardWorkingCopy
225 * @since 3.0
226 */
227void becomeWorkingCopy(IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException;
228 </pre></li>
229 <li><pre>
230/**
231 * Commits the contents of this working copy to its underlying resource.
232 *
233 * It is possible that the contents of the original resource have changed
234 * since this working copy was created, in which case there is an update conflict.
Stephan Herrmann66cc2b62010-09-26 15:38:59 +0000[diff] [blame]235 * The value of the force parameter affects the resolution of
Stephan Herrmann7b7062f2010-04-01 19:56:59 +0000[diff] [blame]236 * such a conflict:
237 * - true - in this case the contents of this working copy are applied to
238 * the underlying resource even though this working copy was created
239 * before a subsequent change in the resource
240 * - false - in this case a JavaModelException is thrown
241 *
242 * Since 2.1, a working copy can be created on a not-yet existing compilation
243 * unit. In particular, such a working copy can then be committed in order to create
244 * the corresponding compilation unit.
245 *
246 * @param force a flag to handle the cases when the contents of the original resource have changed
247 * since this working copy was created
248 * @param monitor the given progress monitor
249 * @exception JavaModelException if this working copy could not commit. Reasons include:
250 * - A CoreException occurred while updating an underlying resource
251 * - This element is not a working copy (INVALID_ELEMENT_TYPES)
252 * - A update conflict (described above) (UPDATE_CONFLICT)
253 * @since 3.0
254 */
255void commitWorkingCopy(boolean force, IProgressMonitor monitor) throws JavaModelException;
256 </pre></li>
257 <li><pre>
258/**
259 * Changes this compilation unit in working copy mode back to its original mode.
260 *
261 * This has no effect if this compilation unit was not in working copy mode.
262 *
263 * If becomeWorkingCopy was called several times on this
264 * compilation unit, discardWorkingCopy must be called as
265 * many times before it switches back to the original mode.
266 *
267 * @see becomeWorkingCopy
268 * @exception JavaModelException if this working copy could not return in its original mode.
269 * @since 3.0
270 */
271void discardWorkingCopy() throws JavaModelException;
272 </pre></li>
273 <li><pre>
274/**
275 * Returns the working copy owner of this working copy.
276 * Returns null if it is not a working copy or if it has no owner.
277 *
278 * @return WorkingCopyOwner the owner of this working copy or null
279 * @since 3.0
280 */
281WorkingCopyOwner getOwner();
282 </pre></li>
283 <li><pre>
284/**
285 * Returns a new working copy of this element if this element is not
286 * a working copy, or this element if this element is already a working copy.
287 *
288 * Note: if intending to share a working copy amongst several clients, then
289 * getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)
290 * should be used instead.
291 *
292 * When the working copy instance is created, an ADDED IJavaElementDelta is
293 * reported on this working copy.
294 *
295 * Since 2.1, a working copy can be created on a not-yet existing compilation
296 * unit. In particular, such a working copy can then be committed in order to create
297 * the corresponding compilation unit.
298 *
299* @param monitor a progress monitor used to report progress while opening this compilation unit
300 * or null if no progress should be reported
301 * @exception JavaModelException if the contents of this element can
302 * not be determined.
303 * @return a new working copy of this element if this element is not
304 * a working copy, or this element if this element is already a working copy
305 * @since 3.0
306 */
307ICompilationUnit getWorkingCopy(IProgressMonitor monitor) throws JavaModelException;
308 </pre></li>
309 <li><pre>
310/**
311 * Returns a shared working copy on this element using the given working copy owner to create
312 * the buffer, or this element if this element is already a working copy.
313 * This API can only answer an already existing working copy if it is based on the same
314 * original compilation unit AND was using the same working copy owner (that is, as defined by Object.equals).
315 *
316 * The life time of a shared working copy is as follows:
317 * - The first call to getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)
318 * creates a new working copy for this element
319 * - Subsequent calls increment an internal counter.
320 * - A call to discardWorkingCopy() decrements the internal counter.
321 * - When this counter is 0, the working copy is discarded.
322 *
323 * So users of this method must discard exactly once the working copy.
324 *
325 * Note that the working copy owner will be used for the life time of this working copy, that is if the
326 * working copy is closed then reopened, this owner will be used.
327 * The buffer will be automatically initialized with the original's compilation unit content
328 * upon creation.
329 *
330 * When the shared working copy instance is created, an ADDED IJavaElementDelta is reported on this
331 * working copy.
332 *
333 * Since 2.1, a working copy can be created on a not-yet existing compilation
334 * unit. In particular, such a working copy can then be committed in order to create
335 * the corresponding compilation unit.
336 *
337 * @param owner the working copy owner that creates a buffer that is used to get the content
338 * of the working copy
339 * @param problemRequestor a requestor which will get notified of problems detected during
340 * reconciling as they are discovered. The requestor can be set to null indicating
341 * that the client is not interested in problems.
342 * @param monitor a progress monitor used to report progress while opening this compilation unit
343 * or null if no progress should be reported
344 * @exception JavaModelException if the contents of this element can
345 * not be determined.
346 * @return a new working copy of this element using the given factory to create
347 * the buffer, or this element if this element is already a working copy
348 * @since 3.0
349 */
350ICompilationUnit getWorkingCopy(WorkingCopyOwner owner, IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException;
351 </pre></li>
352 </ul>
353And the following abstract class replaces <code>IBufferFactory</code>:
354 <pre>
355/**
356 * The owner of an ICompilationUnit handle in working copy mode.
357 * An owner is used to identify a working copy and to create its buffer.
358 *
359 * @see ICompilationUnit#becomeWorkingCopy
360 * @see ICompilationUnit#discardWorkingCopy
361 * @since 3.0
362 */
363public abstract class WorkingCopyOwner {
364 /**
365 * Creates a buffer for the given working copy.
366 * The new buffer will be initialized with the contents of the underlying file
367 * if and only if it was not already initialized by the compilation owner (a buffer is
368 * uninitialized if its content is null).
369 *
370 * @param workingCopy the working copy of the buffer
371 * @return IBuffer the created buffer for the given working copy
372 * @see IBuffer
373 */
374 public IBuffer createBuffer(ICompilationUnit workingCopy) {
375 ...
376 }
377}
378 </pre>
379 To generalize the usage of a working copy owner (entire JavaModel is now aware of owned working copies), new
380 APIs were added. These new APIs are copies of existing APIs augmented with a <code>WorkingCopyOwner</code>
381 parameter, that defines the working copies to consider in the operation.
382 When specifying an owner parameter, all working copies belonging to this owner will implicitly take precedence over primary ones
383 (without requiring the owner to remember all its working copies, as in 2.1 era). Note that when no owned working copy is found, a primary
384 unit will be considered instead, and since primary units have a built-in working copy (see <code>ICompilationUnit.becomeWorkingCopy(...)</code>),
385 the primary unit may already be in working copy mode (very likely since an editor got opened on it). This means that an owner will already
386 transparently see unsaved editor contents for all units for which it has no better working copy to contribute.
387 The following new APIs were added:
388 <ul>
389 <li><code>AST.parseCompilationUnit(char[] source, String unitName, IJavaProject project, WorkingCopyOwner owner)</code></li>
390 <li><code>AST.parseCompilationUnit(IClassFile classFile, boolean resolveBindings, WorkingCopyOwner owner)</code></li>
391 <li><code>AST.parseCompilationUnit(ICompilationUnit unit, boolean resolveBindings, WorkingCopyOwner owner)</code></li>
392 <li><code>IEvaluationContext.codeComplete(String codeSnippet, int position, ICompletionRequestor requestor, WorkingCopyOwner owner)</code></li>
393 <li><code>IEvaluationContext.codeSelect(String codeSnippet, int offset, int length, WorkingCopyOwner owner)</code></li>
394 <li><code>IDOMCompilationUnit.getCompilationUnit(IPackageFragment parent, WorkingCopyOwner owner)</code></li>
395 <li><code>ICodeAssist.codeComplete(int offset, ICompletionRequestor requestor, WorkingCopyOwner owner)</code></li>
396 <li><code>ICodeAssist.codeSelect(int offset, int length, WorkingCopyOwner owner)</code></li>
397 <li><code>ICompilationUnit.reconcile(boolean forceProblemDetection, WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
398 <li><code>IJavaProject.findElement(IPath path, WorkingCopyOwner owner)</code></li>
399 <li><code>IJavaProject.findType(String packageName, String typeQualifiedName, WorkingCopyOwner owner)</code></li>
400 <li><code>IJavaProject.findType(String fullyQualifiedName, WorkingCopyOwner owner)</code></li>
401 <li><code>IJavaProject.newTypeHierarchy(IRegion region, WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
402 <li><code>IJavaProject.newTypeHierarchy(IType type, IRegion region, WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
403 <li><code>IPackageFragment.getCompilationUnit(String name, WorkingCopyOwner owner)</code></li>
404 <li><code>IPackageFragment.getCompilationUnits(WorkingCopyOwner owner)</code></li>
405 <li><code>IType.codeComplete(char[] snippet, int insertion, int position, char[][] localVariableTypeNames, char[][] localVariableNames, int[] localVariableModifiers, boolean isStatic, ICompletionRequestor requestor, WorkingCopyOwner owner)</code></li>
406 <li><code>IType.newSupertypeHierarchy(WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
407 <li><code>IType.newTypeHierarchy(IJavaProject project, WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
408 <li><code>IType.newTypeHierarchy(WorkingCopyOwner owner, IProgressMonitor monitor)</code></li>
409 <li><code>IType.resolveType(String typeName, WorkingCopyOwner owner)</code></li>
410 <li><code>JavaCore.create(IFile file, WorkingCopyOwner owner)</code></li>
411 <li><code>JavaCore.create(IResource resource, WorkingCopyOwner owner)</code></li>
412 <li><code>JavaCore.create(String handleIdentifier, WorkingCopyOwner owner)</code></li>
413 <li><code>JavaCore.createCompilationUnitFrom(IFile file, WorkingCopyOwner owner)</code></li>
414 <li><code>JavaCore.getWorkingCopies(WorkingCopyOwner owner)</code></li>
415 <li><code>SearchEngine.SearchEngine(WorkingCopyOwner workingCopyOwner)</code></li>
416 <li><code>SearchEngine.createHierarchyScope(IType type, WorkingCopyOwner owner)</code></li>
417 </ul>
418<h2>Converting to the new API</h2>
419 TODO
420
421<hr><h1>IJavaElement.getResource() returns a non null value for working copies</h1>
422 Last edit: 2003/06/18 (-&gt;M2)
423<h2>Problem description</h2>
424 <code>IJavaElement.getResource()</code> was specified to return <code>null</code> for working copies.
425 This didn't make sense as this is a handle-only operation and an <code>IResource</code> is also a handle.
426<h2>Problem resolution</h2>
427 This restriction was removed and <code>IJavaElement.getResource()</code> now returns a non-<code>null</code>
428 value for a working copy.
429<h2>Converting to the new API</h2>
430 TODO
431
432<hr><h1>Rename getOriginalElement() into getPrimaryElement()</h1>
433 Last edit: 2003/06/20 (-&gt;M2)
434<h2>Problem description</h2>
435 The 2.1 API <code>IWorkingCopy.getOriginalElement()</code> returns an <code>IJavaElement</code>. In practice
436 the original element for a working copy is always an <code>ICompilationUnit</code> whose owner is the primary owner.
437<h2>Problem resolution</h2>
438 <code>getPrimary()</code> was added on <code>ICompilationUnit</code> to return an <code>ICompilationUnit</code>.
439 This new API replaces <code>getOriginalElement()</code>.
440 <pre>
441/**
442 * Returns the primary compilation unit (whose owner is the primary owner)
443 * this working copy was created from, or this compilation unit if this a primary
444 * compilation unit.
445 * Note that the returned primary compilation unit can be in working copy mode.
446 *
447 * @return the primary compilation unit this working copy was created from,
448 * or this compilation unit if it is primary
449 * @since 3.0
450 */
451ICompilationUnit getPrimary();
452 </pre>
453 In the same manner, <code>IWorkingCopy.getOriginalElement(IJavaElement)</code> is replaced with
454 <code>IJavaElement.getPrimaryElement()</code>.
455 <pre>
456/**
457 * Returns the primary element (whose compilation unit is the primary compilation unit)
458 * this working copy element was created from, or this element if it is a descendant of a
459 * primary compilation unit or if it is not a descendant of a working copy (e.g. it is a
460 * binary member).
461 * The returned element may or may not exist.
462 *
463 * @return the primary element this working copy element was created from, or this
464 * element.
465 * @since 3.0
466 */
467IJavaElement getPrimaryElement();
468 </pre>
469
470<h2>Converting to the new API</h2>
471 TODO
472
473<hr><h1>JavaCore.newLibraryEntry(...) no longer accepts a relative source attachment path</h1>
474 Last edit: 2003/06/30 (-&gt;M2)
475<h2>Problem description</h2>
476 The API <code>JavaCore.newLibraryEntry(IPath path, IPath sourceAttachmentPath, IPath sourceAttachmentRootPath, boolean isExported)</code>
477 for creating a library classpath entry with a source attachment used to accept a relative source attachment path. It was spec'ed as such,
478 but its implementation was too permissive.
479<h2>Problem resolution</h2>
480 From 3.0 on, an <code>IllegalArgumentException</code> will be raised if a non-relative source attachment path is provided.
481 Note that the only exception to this rule is an empty path (answering <code>true</code> to <code>IPath.isEmpty()</code>) which is
482 now automatically translated into <code>null</code> denoting no source attachment.
483 In 3.0, a .classpath file will compact source attachments into project relative ones (as it does with other entry pathes already). During
484 this process, relative pathes are known to be meaning project relative (internally when reading/writing the .classpath file). Externally,
485 only absolute pathes are allowed to avoid confusion when reading/writing the .classpath file.
486 The tolerance for empty relative pathes comes from the fact that it is possible for variable classpath entries can be resolved to library entries
487 with no classpath. Then the variable source attachment needs to be positionned to a value meaning no source (<code>null</code>).
488 However, assigning a classpath variable to <code>null</code> is not allowed (nullification is used to remove variables),
489 thus an empty relative source path is tolerated to work around this limitation.
490<h2>Converting to the new API</h2>
491 TODO
492
493<hr><h1>Read <code>.classpath</code> file contents even if project has not the java nature yet</h1>
494 Last edit: 2003/09/01 (-&gt;M4)
495<h2>Problem description</h2>
496In 2.0 it was allowed to access IJavaProject.getOutputLocation/getRawClasspath on a project where the JavaNature was not set yet. Since 2.1 a
497JavaModelException is thrown if that happens.
498For example, the new Java project wizard does this if a .classpath file is found at the
499location where the project will be created.
500<h2>Problem resolution</h2>
501
502 Added API <code>IJavaProject#readRawClasspath()</code> to allow user to read the raw classpath from <code>.classpath</code> disk file
503 on a java project which java nature has not been set yet.
504 <pre>
505/**
506 * Returns the raw classpath for the project as defined by its <code>.classpath</code> file from disk, or <code>null</code>
507 * if unable to read the file.
508 *
509 * This classpath may differ from the in-memory classpath returned by <code>getRawClasspath</code>, in case the
510 * automatic reconciliation mechanism has not been performed yet. Usually, any change to the <code>.classpath</code> file
511 * is automatically noticed and reconciled at the next resource change notification event.
512 * However, if the file is modified within an operation, where this change needs to be taken into account before the
513 * operation ends, then the classpath from disk can be read using this method, and further assigned to the project
514 * using <code>setRawClasspath(...)</code>.
515 *
516 * A raw classpath may contain classpath variable and/or container entries. Classpath variable entries can be resolved
517 * individually (see <code>JavaCore#getClasspathVariable</code>), or the full classpath can be resolved at once using the
518 * helper method <code>getResolvedClasspath</code>.
519 * TODO (jim) please reformulate to include classpath containers in resolution aspects
520 *
521 * Note that no check is performed whether the project has the Java nature set, allowing an existing <code>.classpath</code>
522 * file to be considered independantly (unlike <code>getRawClasspath</code> which requires the Java nature to be associated
523 * with the project).
524 *
525 * @return the raw classpath from disk for the project, as a list of classpath entries
526 * @see #getRawClassPath
527 * @see IClasspathEntry
528 * @since 3.0
529 */
530 </pre>
531
532 Added API <code>IJavaProject#readOutputLocation()</code> to allow user to read the output location from <code>.classpath</code> disk file
533 on a java project which java nature has not been set yet.
534 <pre>
535/**
536 * Returns the default output location for the project as defined by its <code>.classpath</code> file from disk, or <code>null</code>
537 * if unable to read the file.
538 *
539 * This output location may differ from the in-memory one returned by <code>getOutputLocation</code>, in case the
540 * automatic reconciliation mechanism has not been performed yet. Usually, any change to the <code>.classpath</code> file
541 * is automatically noticed and reconciled at the next resource change notification event.
542 * However, if the file is modified within an operation, where this change needs to be taken into account before the
543 * operation ends, then the output location from disk can be read using this method, and further assigned to the project
544 * using <code>setRawClasspath(...)</code>.
545 *
546 * The default output location is where class files are ordinarily generated
547 * (and resource files, copied). Each source classpath entry can also
548 * specify an output location for the generated class files (and copied
549 * resource files) corresponding to compilation units under that source
550 * folder. This makes it possible to arrange generated class files for
551 * different source folders in different output folders, and not
552 * necessarily the default output folder. This means that the generated
553 * class files for the project may end up scattered across several folders,
554 * rather than all in the default output folder (which is more standard).
555 *
556 * @return the workspace-relative absolute path of the default output folder
557 * @see #getOutputLocation
558 * @since 3.0
559 */
560 </pre>
561<h2>Converting to the new API</h2>
562 TODO
563
564</body>
565</html>