Gitiles
Code Review Sign In
git.eclipse.org / objectteams / org.eclipse.objectteams / 7698613f7c36563430f70040457a7601e3bc9955 / . / org.eclipse.jdt.core / notes / porting_guide.html
blob: 1121f75e2098b8c7a0352a31434fd83cacfa7ce6 [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
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<title>JDT Core Porting Guide</title>
7<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
8<meta name="ProgId" content="FrontPage.Editor.Document">
9 <link rel="stylesheet" href="../jdt_core_style.css" charset="iso-8859-1" type="text/css">
10</head>
11
12<body>
13
14<h1>JDT Core 3.0 Porting Guide</h1>
15<p>Last modified January 30, 2004</p>
16<p>These entries for the porting guide cover Debug-related items.</p>
17<h2>Required changes for 3.0</h2>
18<p>None.</p>
19<h2>Recommended changes for 3.0</h2>
20<p><b class="title1">
21[JDT only] Improved support for working copies (package org.eclipse.jdt.core)
22</b></p>
23<p>The Java model working copy facility has been reworked in 3.0 to provide
24greatly increased functionality. Prior to 3.0, the Java model allowed creation
25of individual working copies of compilation units. Changes could be made to the
26working copy and later committed. There was support for limited analysis of a
27working copy in the context of the rest of the Java model. However, there was no
28way these these analyses could ever take into account more than one of the
29working copies at a time.</p>
30<p>The changes in 3.0 make it possible to create and manage sets of working
31copies of compilation units, and to perform analyses in the presence of all
32working copies in a set. For example, it is now possible for a client like JDT
33refactoring to create working copies for one or more compilation units that it
34is considering modifying and then to resolve type references between the working
35copies. Formerly this was only possible after the changes to the compilation
36unit working copies had been committed.</p>
37<p>The Java model API changes in 2 ways to add this improved support:</p>
38<p>(1) The functionality formerly found on IWorkingCopy and inherited by
39ICompilationUnit has been consolidated into ICompilationUnit. The IWorkingCopy
40interface was only used in this one place, and was gratuitously more general
41that in needed to be. This change simplifies the API. IWorkingCopy has been
42deprecated. Other places in the API where IWorkingCopy is used as a parameter or
43result type have been deprecated as well; the replacement API methods mention
44ICompilationUnit instead of IWorkingCopy.</p>
45<p>(2) The interface IBufferFactory has been replaced by WorkingCopyOwner. The
46improved support for working copies requires that there be an object to own the
47working copies. Although IBufferFactory is in the right place, the name does not
48adequately convey how the new working copy mechanism works. WorkingCopyOwner is
49much more suggestive. In addition, WorkingCopyOwner is declared as an abstract
50class, rather than as an interface, to allow the notion of working copy owner to
51evolve in the future. The one method on IBufferFactory moves to WorkingCopyOwner
52unaffected. WorkingCopyOwner does not implement IBufferFactory to make it clear
53that IBufferFactory is a thing of the past. IBufferFactory has been deprecated.
54Other places in the API where IBufferFactory&nbsp; appears as a parameter or
55result type have been deprecated as well; the replacement API methods mention
56WorkingCopyOwner instead of IBufferFactory.</p>
57<p>These changes do not break binary compatibility.</p>
58<p>When migrating, all references to the type IWorkingCopy should instead
59reference ICompilationUnit. The sole implementation of IWorkingCopy implements
60ICompilationUnit as well, meaning objects of type IWorkingCopy can be safely
61cast to ICompilationUnit.</p>
62<p>A class that implements IBufferFactory will need to replaced by a subclass of
63WorkingCopyOwner. Although WorkingCopyOwner does not implement IBufferFactory
64itself, it would be possible to declare the subclass of WorkingCopyOwner that
65implements IBufferFactory thereby creating a bridge between old and new (IBufferFactory
66declares createBuffer(IOpenable) whereas WorkingCopyOwner declares
67createBuffer(ICompilationUnit); ICompilationUnit extends IOpenable).</p>
68<p>Because the changes involving IWorkingCopy and IBufferFactory are interwined,
69we recommend dealing with both at the same time. The detail</p>
70<ul>
71 <li>IWorkingCopy (package org.eclipse.jdt.core)
72 <ul>
73 <li>public void commit(boolean, IProgressMonitor) has been deprecated.
74 <ul>
75 <li>The equivalent functionality is now provided on ICompilationUnit
76 directly:
77 <ul>
78 <li>public void commitWorkingCopy(boolean, IProgressMonitor)</li>
79 </ul>
80 </li>
81 <li>Replace wc.commit(b,monitor) with ((ICompilationUnit)
82 wc).commitWorkingCopy(b,monitor)</li>
83 </ul>
84 </li>
85 <li>public void destroy() has been deprecated.
86 <ul>
87 <li>The equivalent functionality is now provided on ICompilationUnit
88 directly:
89 <ul>
90 <li>public void discardWorkingCopy(boolean, IProgressMonitor)</li>
91 </ul>
92 </li>
93 <li>Replace wc.destroy() with ((ICompilationUnit)
94 wc).discardWorkingCopy()</li>
95 </ul>
96 </li>
97 <li>public IJavaElement findSharedWorkingCopy(IBufferFactory) has been
98 deprecated.
99 <ul>
100 <li>The equivalent functionality is now provided on ICompilationUnit
101 directly:
102 <ul>
103 <li>public ICompilationUnit findWorkingCopy(WorkingCopyOwner)</li>
104 </ul>
105 </li>
106 </ul>
107 </li>
108 <li>public IJavaElement getOriginal(IJavaElement) has been deprecated.
109 <ul>
110 <li>The equivalent functionality is now provided on IJavaElement:
111 <ul>
112 <li>public IJavaElement getPrimaryElement()</li>
113 </ul>
114 </li>
115 </ul>
116 <ul>
117 <li>Replace wc.getOriginal(elt) with elt.getPrimaryElement()</li>
118 <li>Note: Unlike IWorkingCopy.getOriginal,
119 IJavaElement.getPrimaryElement does not return <code>null</code> if
120 the receiver is not a working copy.</li>
121 </ul>
122 </li>
123 <li>public IJavaElement getOriginalElement() has been deprecated.
124 <ul>
125 <li>The equivalent functionality is now provided on ICompilationUnit
126 directly:
127 <ul>
128 <li>public ICompilationUnit getPrimary()</li>
129 </ul>
130 </li>
131 <li>Replace wc.getOriginalElement() with ((ICompilationUnit)
132 wc).getPrimary()</li>
133 <li>Note: Unlike IWorkingCopy.getOriginalElement,
134 IWorkingCopy.getPrimary does not return <code>null</code> if the
135 receiver is not a working copy.</li>
136 </ul>
137 </li>
138 <li>public IJavaElement[] findElements(IJavaElement) has been deprecated.
139 <ul>
140 <li>The method is now declared on ICompilationUnit directly.</li>
141 <li>Replace wc.findElements(elts) with ((ICompilationUnit)
142 wc).findElements(elts)</li>
143 </ul>
144 </li>
145 <li>public IType findPrimaryType() has been deprecated.
146 <ul>
147 <li>The method is now declared on ICompilationUnit directly.</li>
148 <li>Replace wc.findPrimaryType() with ((ICompilationUnit)
149 wc).findPrimaryType()</li>
150 </ul>
151 </li>
152 <li>public IJavaElement getSharedWorkingCopy(IProgressMonitor,
153 IBufferFactory, IProblemRequestor) has been deprecated.
154 <ul>
155 <li>The equivalent functionality is now provided on ICompilationUnit
156 directly:
157 <ul>
158 <li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
159 IProblemRequestor, IProgressMonitor)</li>
160 </ul>
161 </li>
162 <li>[parameter order scrambling]</li>
163 </ul>
164 </li>
165 <li>public IJavaElement getWorkingCopy() has been deprecated.
166 <ul>
167 <li>The equivalent functionality is now provided on ICompilationUnit
168 directly:
169 <ul>
170 <li>public ICompilationUnit getWorkingCopy(IProgressMonitor)</li>
171 </ul>
172 </li>
173 <li>Replace wc.getWorkingCopy() with ((ICompilationUnit)
174 wc).getWorkingCopy(null)</li>
175 </ul>
176 </li>
177 <li>public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory,
178 IProblemRequestor) has been deprecated.
179 <ul>
180 <li>The equivalent functionality is now provided on ICompilationUnit
181 directly:
182 <ul>
183 <li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
184 IProblemRequestor, IProgressMonitor)</li>
185 </ul>
186 </li>
187 <li>[parameter order scrambling]</li>
188 </ul>
189 </li>
190 <li>public boolean isBasedOn(IResource) has been deprecated.
191 <ul>
192 <li>The equivalent functionality is now provided on ICompilationUnit
193 directly:
194 <ul>
195 <li>public boolean hasResourceChanged()</li>
196 </ul>
197 </li>
198 <li>Replace wc.isBasesOn(res) with ((ICompilationUnit)
199 wc).hasResourceChanged()</li>
200 </ul>
201 </li>
202 <li>public boolean isWorkingCopy() has been deprecated.
203 <ul>
204 <li>The method is now declared on ICompilationUnit directly.</li>
205 <li>Replace wc.isWorkingCopy() with ((ICompilationUnit)
206 wc).isWorkingCopy()</li>
207 </ul>
208 </li>
209 <li>public IMarker[]&nbsp; reconcile() has been deprecated.
210 <ul>
211 <li>The equivalent functionality is now provided on ICompilationUnit
212 directly:
213 <ul>
214 <li>public void reconcile(boolean,boolean,WorkingCopyOwner,IProgressMonitor)</li>
215 </ul>
216 </li>
217 <li>Replace wc.reconcile() with ((ICompilationUnit)
218 wc).reconcile(false,false,null,null)</li>
219 <li>Note: The former method always returned null; the replacement
220 method does not return a result.</li>
221 </ul>
222 </li>
223 <li>public void reconcile(boolean, IProgressMonitor) has been deprecated.
224 <ul>
225 <li>The method is now declared on ICompilationUnit directly.</li>
226 <li>Replace wc.reconcile(b,monitor) with ((ICompilationUnit)
227 wc).reconcile(false,b,null,monitor)</li>
228 </ul>
229 </li>
230 <li>public void restore() has been deprecated.
231 <ul>
232 <li>The method is now declared on ICompilationUnit directly.</li>
233 <li>Replace wc.restore() with ((ICompilationUnit) wc).restore()</li>
234 </ul>
235 </li>
236 </ul>
237 </li>
238 <li>IType (package org.eclipse.jdt.core)
239 <ul>
240 <li>public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[],
241 IProgressMonitor) has been deprecated.
242 <ul>
243 <li>The replacement method is provided on the same class:
244 <ul>
245 <li>public ITypeHierarchy newSupertypeHierarchy(ICompilationUnit[],
246 IProgressMonitor)</li>
247 </ul>
248 </li>
249 </ul>
250 </li>
251 <li>public ITypeHierarchy newTypeHierarchy(IWorkingCopy[],
252 IProgressMonitor) has been deprecated.
253 <ul>
254 <li>The replacement method is provided on the same class:
255 <ul>
256 <li>public ITypeHierarchy newTypeHierarchy(ICompilationUnit[],
257 IProgressMonitor)</li>
258 </ul>
259 </li>
260 </ul>
261 </li>
262 </ul>
263 </li>
264 <li>IClassFile (package org.eclipse.jdt.core)
265 <ul>
266 <li>public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory)
267 has been deprecated.
268 <ul>
269 <li>The replacement method is provided on the same class:
270 <ul>
271 <li>public ICompilationUnit getWorkingCopy(WorkingCopyOwner,
272 IProgressMonitor)</li>
273 </ul>
274 </li>
275 <li>[parameter order scrambling]</li>
276 </ul>
277 </li>
278 </ul>
279 </li>
280 <li>JavaCore (package org.eclipse.jdt.core)
281 <ul>
282 <li>public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory) has been
283 deprecated.
284 <ul>
285 <li>The replacement method is provided on the same class:
286 <ul>
287 <li>public ICompilationUnit[] getWorkingCopies(WorkingCopyOwner)</li>
288 </ul>
289 </li>
290 </ul>
291 </li>
292 </ul>
293 </li>
294 <li>SearchEngine (package org.eclipse.jdt.core.search)
295 <ul>
296 <li>public SearchEngine(IWorkingCopy[]) has been deprecated.
297 <ul>
298 <li>The replacement constructor is provided on the same class:
299 <ul>
300 <li>public SearchEngine(ICompilationUnit[])</li>
301 </ul>
302 </li>
303 </ul>
304 </li>
305 </ul>
306 </li>
307</ul>
308
309<p><b class="title1">
310[JDT only] Java search participants (package org.eclipse.jdt.core.search)
311</b></p>
312<p>Languages close to Java (such as JSP, SQLJ, JWS, etc.) should be able to participate in Java searching.
313In particular implementors of such languages should be able to:</p>
314<ul>
315<li>index their source by converting it into Java equivalent, and feeding it to the Java indexer</li>
316<li>index their source by parsing it themselves, but record Java index entries</li>
317<li>locate matches in their source by converting it into Java equivalent, and feeding it to the Java match locator</li>
318<li>locate matches in their source by matching themselves, and return Java matches</li>
319</ul>
320<p>Such an implementor is called a search participant. It extends the SearchParticipant
321class. Search participants are passed to search queries
322(see SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope, SearchRequestor, IProgressMonitor).</p>
323<p>For either indexing or locating matches, a search participant needs to define a subclass of
324SearchDocument that can retrieve the contents of a document by overriding either
325getByteContents() or getCharContents(). An instance of such class is
326returned in SearchParticipant.getDocument(IFile) or getDocument(String).</p>
327<p>A search participant whishing to index some document will use
328SearchParticipant.scheduleDocumentIndexing(SearchDocument, IPath) to schedule the indexing
329of the given document in the given index. Once the document is ready to be indexed, the underlying framework
330calls SearchParticipant.indexDocument(SearchDocument, IPath). The search participant is then
331supposed to get the document's content, parse it and add index entries using
332SearchParticipant.addIndexEntry(char[], char[], SearchDocument).</p>
333<p>Once indexing is done, one can then query the indexes and locate matches using
334SearchEngine.search(SearchPattern, SearchParticipant[], IJavaSearchScope, SearchRequestor, IProgressMonitor).
335This first asks each search participant for the indexes needed by this query using
336SearchParticipant.selectIndexes(SearchPattern, IJavaSearchScope). For each index entry that matches
337the given pattern, a search document is created by asking the search participant (see getDocument(String)).
338All these documents are passed to the search participant so that it can locate matches using
339locateMatches(SearchDocument[], SearchPattern, IJavaSearchScope, SearchRequestor, IProgressMonitor).
340The search participant notifies the SearchRequestor of search matches using acceptSearchMatch(SearchMatch)
341and passing an instance of a subclass of SearchMatch.</p>
342<p>A search participant can delegate part of its work to the default Java search participant. An instance of
343this default participant is obtained using SearchEngine.getDefaultSearchParticipant(). For example when asked to
344locate matches, an SQLJ participant can create documents .java documents from its .sqlj documents and
345delegate the work to the default participant passing it the .java documents.</p>
346
347</body>
348
349</html>