JDT Core Porting Guide

# 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

- IWorkingCopy (package org.eclipse.jdt.core)
  - public void commit(boolean, IProgressMonitor) has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public void commitWorkingCopy(boolean, IProgressMonitor)
    - Replace wc.commit(b,monitor) with ((ICompilationUnit) wc).commitWorkingCopy(b,monitor)
  - public void destroy() has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public void discardWorkingCopy(boolean, IProgressMonitor)
    - Replace wc.destroy() with ((ICompilationUnit) wc).discardWorkingCopy()
  - public IJavaElement findSharedWorkingCopy(IBufferFactory) has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public ICompilationUnit findWorkingCopy(WorkingCopyOwner)
  - public IJavaElement getOriginal(IJavaElement) has been deprecated.
    - The equivalent functionality is now provided on IJavaElement:
      - public IJavaElement getPrimaryElement()
    - Replace wc.getOriginal(elt) with elt.getPrimaryElement()
    - Note: Unlike IWorkingCopy.getOriginal, IJavaElement.getPrimaryElement does not return `null` if the receiver is not a working copy.
  - public IJavaElement getOriginalElement() has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public ICompilationUnit getPrimary()
    - Replace wc.getOriginalElement() with ((ICompilationUnit) wc).getPrimary()
    - Note: Unlike IWorkingCopy.getOriginalElement, IWorkingCopy.getPrimary does not return `null` if the receiver is not a working copy.
  - public IJavaElement[] findElements(IJavaElement) has been deprecated.
    - The method is now declared on ICompilationUnit directly.
    - Replace wc.findElements(elts) with ((ICompilationUnit) wc).findElements(elts)
  - public IType findPrimaryType() has been deprecated.
    - The method is now declared on ICompilationUnit directly.
    - Replace wc.findPrimaryType() with ((ICompilationUnit) wc).findPrimaryType()
  - public IJavaElement getSharedWorkingCopy(IProgressMonitor, IBufferFactory, IProblemRequestor) has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)
    - [parameter order scrambling]
  - public IJavaElement getWorkingCopy() has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public ICompilationUnit getWorkingCopy(IProgressMonitor)
    - Replace wc.getWorkingCopy() with ((ICompilationUnit) wc).getWorkingCopy(null)
  - public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory, IProblemRequestor) has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProblemRequestor, IProgressMonitor)
    - [parameter order scrambling]
  - public boolean isBasedOn(IResource) has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public boolean hasResourceChanged()
    - Replace wc.isBasesOn(res) with ((ICompilationUnit) wc).hasResourceChanged()
  - public boolean isWorkingCopy() has been deprecated.
    - The method is now declared on ICompilationUnit directly.
    - Replace wc.isWorkingCopy() with ((ICompilationUnit) wc).isWorkingCopy()
  - public IMarker[] reconcile() has been deprecated.
    - The equivalent functionality is now provided on ICompilationUnit directly:
      - public void reconcile(boolean,boolean,WorkingCopyOwner,IProgressMonitor)
    - Replace wc.reconcile() with ((ICompilationUnit) wc).reconcile(false,false,null,null)
    - Note: The former method always returned null; the replacement method does not return a result.
  - public void reconcile(boolean, IProgressMonitor) has been deprecated.
    - The method is now declared on ICompilationUnit directly.
    - Replace wc.reconcile(b,monitor) with ((ICompilationUnit) wc).reconcile(false,b,null,monitor)
  - public void restore() has been deprecated.
    - The method is now declared on ICompilationUnit directly.
    - Replace wc.restore() with ((ICompilationUnit) wc).restore()
- IType (package org.eclipse.jdt.core)
  - public ITypeHierarchy newSupertypeHierarchy(IWorkingCopy[], IProgressMonitor) has been deprecated.
    - The replacement method is provided on the same class:
      - public ITypeHierarchy newSupertypeHierarchy(ICompilationUnit[], IProgressMonitor)
  - public ITypeHierarchy newTypeHierarchy(IWorkingCopy[], IProgressMonitor) has been deprecated.
    - The replacement method is provided on the same class:
      - public ITypeHierarchy newTypeHierarchy(ICompilationUnit[], IProgressMonitor)
- IClassFile (package org.eclipse.jdt.core)
  - public IJavaElement getWorkingCopy(IProgressMonitor, IBufferFactory) has been deprecated.
    - The replacement method is provided on the same class:
      - public ICompilationUnit getWorkingCopy(WorkingCopyOwner, IProgressMonitor)
    - [parameter order scrambling]
- JavaCore (package org.eclipse.jdt.core)
  - public IWorkingCopy[] getSharedWorkingCopies(IBufferFactory) has been deprecated.
    - The replacement method is provided on the same class:
      - public ICompilationUnit[] getWorkingCopies(WorkingCopyOwner)
- SearchEngine (package org.eclipse.jdt.core.search)
  - public SearchEngine(IWorkingCopy[]) has been deprecated.
    - The replacement constructor is provided on the same class:
      - public SearchEngine(ICompilationUnit[])

[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:

- index their source by converting it into Java equivalent, and feeding it to the Java indexer
- index their source by parsing it themselves, but record Java index entries
- locate matches in their source by converting it into Java equivalent, and feeding it to the Java match locator
- locate matches in their source by matching themselves, and return Java matches

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.