| 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 |
|
| 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> </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 (->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 (->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 (->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 (->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 (->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 |
*/ |
| 227 |
void 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. |
| 235 |
* The value of the force parameter affects the resolution of |
| 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 |
*/ |
| 255 |
void 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 |
*/ |
| 271 |
void 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 |
*/ |
| 281 |
WorkingCopyOwner 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 |
*/ |
| 307 |
ICompilationUnit 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 |
*/ |
| 350 |
ICompilationUnit getWorkingCopy(WorkingCopyOwner owner, IProblemRequestor problemRequestor, IProgressMonitor monitor) throws JavaModelException; |
| 351 |
</pre></li> |
| 352 |
</ul> |
| 353 |
And 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 |
*/ |
| 363 |
public 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 (->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 (->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 |
*/ |
| 451 |
ICompilationUnit 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 |
*/ |
| 467 |
IJavaElement 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 (->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 (->M4) |
| 495 |
<h2>Problem description</h2> |
| 496 |
In 2.0 it was allowed to access IJavaProject.getOutputLocation/getRawClasspath on a project where the JavaNature was not set yet. Since 2.1 a |
| 497 |
JavaModelException is thrown if that happens. |
| 498 |
For example, the new Java project wizard does this if a .classpath file is found at the |
| 499 |
location 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> |