JDT Core 3.0 Porting Guide

Last modified January 30, 2004

These entries for the porting guide cover Debug-related items.

Required changes for 3.0

None.

Recommended changes for 3.0

[JDT only] Improved support for working copies (package org.eclipse.jdt.core)

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.

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.

The Java model API changes in 2 ways to add this improved support:

(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.

(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.

These changes do not break binary compatibility.

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.

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).

Because the changes involving IWorkingCopy and IBufferFactory are interwined, we recommend dealing with both at the same time. The detail

[JDT only] Java search participants (package org.eclipse.jdt.core.search)

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:

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).

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).

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).

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.

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.