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
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>JDT Core Porting Guide</title>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<link rel="stylesheet" href="../jdt_core_style.css" charset="iso-8859-1" type="text/css">
</head>
<body>
<h1>JDT Core 3.0 Porting Guide</h1>
<p>Last modified January 30, 2004</p>
<p>These entries for the porting guide cover Debug-related items.</p>
<h2>Required changes for 3.0</h2>
<p>None.</p>
<h2>Recommended changes for 3.0</h2>
<p><b class="title1">
[JDT only] Improved support for working copies (package org.eclipse.jdt.core)
</b></p>
<p>The Java model working copy facility has been reworked in 3.0 to provide
greatly increased functionality. Prior to 3.0, the Java model allowed creation
of individual working copies of compilation units. Changes could be made to the
working copy and later committed. There was support for limited analysis of a
working copy in the context of the rest of the Java model. However, there was no
way these these analyses could ever take into account more than one of the
working copies at a time.</p>
<p>The changes in 3.0 make it possible to create and manage sets of working
copies of compilation units, and to perform analyses in the presence of all
working copies in a set. For example, it is now possible for a client like JDT
refactoring to create working copies for one or more compilation units that it
is considering modifying and then to resolve type references between the working
copies. Formerly this was only possible after the changes to the compilation
unit working copies had been committed.</p>
<p>The Java model API changes in 2 ways to add this improved support:</p>
<p>(1) The functionality formerly found on IWorkingCopy and inherited by
ICompilationUnit has been consolidated into ICompilationUnit. The IWorkingCopy
interface was only used in this one place, and was gratuitously more general
that in needed to be. This change simplifies the API. IWorkingCopy has been
deprecated. Other places in the API where IWorkingCopy is used as a parameter or
result type have been deprecated as well; the replacement API methods mention
ICompilationUnit instead of IWorkingCopy.</p>
<p>(2) The interface IBufferFactory has been replaced by WorkingCopyOwner. The
improved support for working copies requires that there be an object to own the
working copies. Although IBufferFactory is in the right place, the name does not
adequately convey how the new working copy mechanism works. WorkingCopyOwner is
much more suggestive. In addition, WorkingCopyOwner is declared as an abstract
class, rather than as an interface, to allow the notion of working copy owner to
evolve in the future. The one method on IBufferFactory moves to WorkingCopyOwner
unaffected. WorkingCopyOwner does not implement IBufferFactory to make it clear
that IBufferFactory is a thing of the past. IBufferFactory has been deprecated.
Other places in the API where IBufferFactory appears as a parameter or
result type have been deprecated as well; the replacement API methods mention
WorkingCopyOwner instead of IBufferFactory.</p>
<p>These changes do not break binary compatibility.</p>
<p>When migrating, all references to the type IWorkingCopy should instead
reference ICompilationUnit. The sole implementation of IWorkingCopy implements
ICompilationUnit as well, meaning objects of type IWorkingCopy can be safely
cast to ICompilationUnit.</p>
<p>A class that implements IBufferFactory will need to replaced by a subclass of
WorkingCopyOwner. Although WorkingCopyOwner does not implement IBufferFactory
itself, it would be possible to declare the subclass of WorkingCopyOwner that
implements IBufferFactory thereby creating a bridge between old and new (IBufferFactory
declares createBuffer(IOpenable) whereas WorkingCopyOwner declares
createBuffer(ICompilationUnit); ICompilationUnit extends IOpenable).</p>
<p>Because the changes involving IWorkingCopy and IBufferFactory are interwined,
we recommend dealing with both at the same time. The detail</p>
<ul>
<li>IWorkingCopy (package org.eclipse.jdt.core)
<ul>
<li>public void commit(boolean, IProgressMonitor) has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public void commitWorkingCopy(boolean, IProgressMonitor)</li>
</ul>
</li>
<li>Replace wc.commit(b,monitor) with ((ICompilationUnit)
wc).commitWorkingCopy(b,monitor)</li>
</ul>
</li>
<li>public void destroy() has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public void discardWorkingCopy(boolean, IProgressMonitor)</li>
</ul>
</li>
<li>Replace wc.destroy() with ((ICompilationUnit)
wc).discardWorkingCopy()</li>
</ul>
</li>
<li>public IJavaElement findSharedWorkingCopy(IBufferFactory) has been
deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public ICompilationUnit findWorkingCopy(WorkingCopyOwner)</li>
</ul>
</li>
</ul>
</li>
<li>public IJavaElement getOriginal(IJavaElement) has been deprecated.
<ul>
<li>The equivalent functionality is now provided on IJavaElement:
<ul>
<li>public IJavaElement getPrimaryElement()</li>
</ul>
</li>
</ul>
<ul>
<li>Replace wc.getOriginal(elt) with elt.getPrimaryElement()</li>
<li>Note: Unlike IWorkingCopy.getOriginal,
IJavaElement.getPrimaryElement does not return <code>null</code> if
the receiver is not a working copy.</li>
</ul>
</li>
<li>public IJavaElement getOriginalElement() has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public ICompilationUnit getPrimary()</li>
</ul>
</li>
<li>Replace wc.getOriginalElement() with ((ICompilationUnit)
wc).getPrimary()</li>
<li>Note: Unlike IWorkingCopy.getOriginalElement,
IWorkingCopy.getPrimary does not return <code>null</code> if the
receiver is not a working copy.</li>
</ul>
</li>
<li>public IJavaElement[] findElements(IJavaElement) has been deprecated.
<ul>
<li>The method is now declared on ICompilationUnit directly.</li>
<li>Replace wc.findElements(elts) with ((ICompilationUnit)
wc).findElements(elts)</li>
</ul>
</li>
<li>public IType findPrimaryType() has been deprecated.
<ul>
<li>The method is now declared on ICompilationUnit directly.</li>
<li>Replace wc.findPrimaryType() with ((ICompilationUnit)
wc).findPrimaryType()</li>
</ul>
</li>
<li>public IJavaElement getSharedWorkingCopy(IProgressMonitor,
IBufferFactory, IProblemRequestor) has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)</li>
</ul>
</li>
<li>[parameter order scrambling]</li>
</ul>
</li>
<li>public IJavaElement getWorkingCopy() has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public ICompilationUnit getWorkingCopy(IProgressMonitor)</li>
</ul>
</li>
<li>Replace wc.getWorkingCopy() with ((ICompilationUnit)
wc).getWorkingCopy(null)</li>
</ul>
</li>
<li>public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory,
IProblemRequestor) has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProblemRequestor, IProgressMonitor)</li>
</ul>
</li>
<li>[parameter order scrambling]</li>
</ul>
</li>
<li>public boolean isBasedOn(IResource) has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public boolean hasResourceChanged()</li>
</ul>
</li>
<li>Replace wc.isBasesOn(res) with ((ICompilationUnit)
wc).hasResourceChanged()</li>
</ul>
</li>
<li>public boolean isWorkingCopy() has been deprecated.
<ul>
<li>The method is now declared on ICompilationUnit directly.</li>
<li>Replace wc.isWorkingCopy() with ((ICompilationUnit)
wc).isWorkingCopy()</li>
</ul>
</li>
<li>public IMarker[] reconcile() has been deprecated.
<ul>
<li>The equivalent functionality is now provided on ICompilationUnit
directly:
<ul>
<li>public void reconcile(boolean,boolean,WorkingCopyOwner,IProgressMonitor)</li>
</ul>
</li>
<li>Replace wc.reconcile() with ((ICompilationUnit)
wc).reconcile(false,false,null,null)</li>
<li>Note: The former method always returned null; the replacement
method does not return a result.</li>
</ul>
</li>
<li>public void reconcile(boolean, IProgressMonitor) has been deprecated.
<ul>
<li>The method is now declared on ICompilationUnit directly.</li>
<li>Replace wc.reconcile(b,monitor) with ((ICompilationUnit)
wc).reconcile(false,b,null,monitor)</li>
</ul>
</li>
<li>public void restore() has been deprecated.
<ul>
<li>The method is now declared on ICompilationUnit directly.</li>
<li>Replace wc.restore() with ((ICompilationUnit) wc).restore()</li>
</ul>
</li>
</ul>
</li>
<li>IType (package org.eclipse.jdt.core)
<ul>
<li>public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[],
IProgressMonitor) has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li>public ITypeHierarchy newSupertypeHierarchy(ICompilationUnit[],
IProgressMonitor)</li>
</ul>
</li>
</ul>
</li>
<li>public ITypeHierarchy newTypeHierarchy(IWorkingCopy[],
IProgressMonitor) has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li>public ITypeHierarchy newTypeHierarchy(ICompilationUnit[],
IProgressMonitor)</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>IClassFile (package org.eclipse.jdt.core)
<ul>
<li>public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory)
has been deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
IProgressMonitor)</li>
</ul>
</li>
<li>[parameter order scrambling]</li>
</ul>
</li>
</ul>
</li>
<li>JavaCore (package org.eclipse.jdt.core)
<ul>
<li>public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory) has been
deprecated.
<ul>
<li>The replacement method is provided on the same class:
<ul>
<li>public ICompilationUnit[] getWorkingCopies(WorkingCopyOwner)</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>SearchEngine (package org.eclipse.jdt.core.search)
<ul>
<li>public SearchEngine(IWorkingCopy[]) has been deprecated.
<ul>
<li>The replacement constructor is provided on the same class:
<ul>
<li>public SearchEngine(ICompilationUnit[])</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<p><b class="title1">
[JDT only] Java search participants (package org.eclipse.jdt.core.search)
</b></p>
<p>Languages close to Java (such as JSP, SQLJ, JWS, etc.) should be able to participate in Java searching.
In particular implementors of such languages should be able to:</p>
<ul>
<li>index their source by converting it into Java equivalent, and feeding it to the Java indexer</li>
<li>index their source by parsing it themselves, but record Java index entries</li>
<li>locate matches in their source by converting it into Java equivalent, and feeding it to the Java match locator</li>
<li>locate matches in their source by matching themselves, and return Java matches</li>
</ul>
<p>Such an implementor is called a search participant. It extends the SearchParticipant
class. Search participants are passed to search queries
(see SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope, SearchRequestor, IProgressMonitor).</p>
<p>For either indexing or locating matches, a search participant needs to define a subclass of
SearchDocument that can retrieve the contents of a document by overriding either
getByteContents() or getCharContents(). An instance of such class is
returned in SearchParticipant.getDocument(IFile) or getDocument(String).</p>
<p>A search participant whishing to index some document will use
SearchParticipant.scheduleDocumentIndexing(SearchDocument, IPath) to schedule the indexing
of the given document in the given index. Once the document is ready to be indexed, the underlying framework
calls SearchParticipant.indexDocument(SearchDocument, IPath). The search participant is then
supposed to get the document's content, parse it and add index entries using
SearchParticipant.addIndexEntry(char[], char[], SearchDocument).</p>
<p>Once indexing is done, one can then query the indexes and locate matches using
SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope, SearchRequestor, IProgressMonitor).
This first asks each search participant for the indexes needed by this query using
SearchParticipant.selectIndexes(SearchPattern, IJavaSearchScope). For each index entry that matches
the given pattern, a search document is created by asking the search participant (see getDocument(String)).
All these documents are passed to the search participant so that it can locate matches using
locateMatches(SearchDocument[], SearchPattern, IJavaSearchScope, SearchRequestor, IProgressMonitor).
The search participant notifies the SearchRequestor of search matches using acceptSearchMatch(SearchMatch)
and passing an instance of a subclass of SearchMatch.</p>
<p>A search participant can delegate part of its work to the default Java search participant. An instance of
this default participant is obtained using SearchEngine.getDefaultSearchParticipant(). For example when asked to
locate matches, an SQLJ participant can create documents .java documents from its .sqlj documents and
delegate the work to the default participant passing it the .java documents.</p>
</body>
</html>
|
