Handly 0.3 : API enhacements

by Vladimir Piskarev

Handly 0.3 includes a number of API enhancements; some of them are breaking changes. Here I would like to focus on the most important ones:

ISourceElement: remove hard dependency on ISourceFile (Bug 461262)

Source elements no longer have the getSourceFile() method. Such method, if necessary or desired for a specific model, can be provided by the model implementor, probably in model-specific terms.

The problem with this method was that it had been originally specified to return the source file containing the source element and could not return null, assuming, thus, that source elements are always contained in a source file in the workspace. It was realized that this assumption didn’t hold for models like the JDT Java model that support source attachment for “binary modules” such as class files. For example, in the Java model, both ICompilationUnit and IClassFile consist of pretty much the same elements: ITypes, IMethods and IFields, which all extend the ISourceReference interface (that roughly corresponds to ISourceElement in Handly).

Fortunately, this design flaw was fixed in Handly 0.3. Unfortunately, a few breaking changes had to be introduced to make it possible. As a rule, we try to preserve backward compatibility, but in this case it was not feasible, and it is hoped that future benefits should outweight present costs.

Here’s the complete list of breaking changes related to this redesign around source elements:

  • ISourceElement#getSourceFile() method got removed
  • ISourceElementInfo#getSnapshot() may now return null (if no source is available)
  • ISourceElementInfo#getFullRange() and #getIdentifyingRange() may now return null, but may no longer return a NULL_RANGE (see below)
  • TextRange#isNull() and #NULL_RANGE got removed. The special source range with a -1 offset and a 0 length was a JDT legacy that I did not readily identified as such. It would be very painful to deprecate it (JDT couldn’t): that’s why we had to do it as soon as possible. For a bit of history, see bug 130161.

Deprecate ISourceFileFactory (Bug 464588)

The interface ISourceFileFactory has been superseded, for all intents and purposes, by IElementForEditorInputFactory, and may be removed in a future release. The new interface is more generic and capable. There is little point in having an imperfect API except for backward compatibility: ISourceFileFactory was allowed (and intended) to be implemented by clients.

So, if you have previously implemented ISourceFileFactory (and, for Xtext languages, bound it in the Xtext UI module for the language, as was required by Handly/Xtext integration), please consider implementing (and binding it in the UI module, for Xtext languages) the new interface IElementForEditorInputFactory instead. A typical implementation might look like this.