Handly/NewIn06

New & Noteworthy for Handly 0.6

The 0.6 release is an incremental improvement of the entirely new design introduced in Handly 0.5. This release nearly completes the serious API (re-)work started a year ago in 0.4 and is expected to provide a more stable base for adopters.

Due to the API rework involved, this release introduces a number of breaking changes. Please see the migration guide if you are a current adopter.

Here are the highlights of this release.

On the Way to Non-Breaking Evolution

Building an API that can evolve without breaking is not easy, but it is vital for the long-term health of a project. The 0.6 release should get us closer to this goal by introducing contexts and the model object as a means of facilitating future evolution of Handly.

Contexts (499220)

Fundamentally, a context supplies values (data objects or services) associated with keys. When used as a method parameter or return value, it enables a more loosely coupled functional interaction and therefore allows for more independent variability of the participants of the interaction (a caller and a callee).

Composite contexts can emulate a dynamic scope or dynamic binding available in some programming languages and used to a great effect in such extensible systems as EMACS.

The interface org.eclipse.handly.context.IContext allows such context-facilitated functional interactions to remain type-safe by supporting two kinds of keys: org.eclipse.handly.util.Property and java.lang.Class. The Property class has been moved from the org.eclipse.handly.model package (498749) and generalized to retain type information at runtime (498752) and to be able to provide a default value (498873).

As a first application of contexts in Handly, we have replaced the class org.eclipse.handly.model.ToStingStyle with a context (499540) and have also revised the signatures of a number of methods in the Element hierarchy, making them context-aware (500408). The new design should make it possible to evolve APIs in a non-breaking fashion by introducing new context properties or deprecating and replacing existing ones without changing the method signature, while making it easy to propagate context bindings across the call stack.

The Model Object (500653)

Contexts interplay with another new feature in Handly 0.6, the model object, which reifies the concept of the model as the owner of elements. The model object exposes a context (the model context), which can supply information and services pertaining to the model as a whole.

One example of such a model-scoped service in 0.6 is the notification manager (505777). The introduction of notification manager API has allowed us to provide a fully-functional implementation of hWorkingCopyModeChanged() and NotifyingReconcileOperation right in the SourceFile, which previously needed to be duplicated across specific models. The only thing that model implementations will have to do to use this generic facility is to register a notification manager in the model context.

The model object API also makes it possible to check the Handly API level supported by a model, which should enable future evolution of Handly without having to introduce "extension interfaces" such as IElement2, IElementImpl2, etc. to add new API methods. By checking the API level, generic code will be able to dynamically discover which API methods are supported by the model it is dealing with.

Last but not least, the new API makes it possible to navigate from an element to the owning model and also supports models that can have multiple element trees. By using the equals method to compare the model objects, clients can test whether two elements belong to the same model or whether an element belongs to a specific model.

Other API Enhancements

• Support for files external to the workspace has been implemented on top of the Eclipse File System (EFS) API (500893, 502000)
• The workspace-related functionality has been extracted from SourceFile to a new subclass, WorkspaceSourceFile (500676)
• Non-local file systems are now also supported (506453, 506717)
• The buffer and working copy APIs have been revised and streamlined (505714, 506332)

Full List of Issues Addressed in This Release

 0.6 - https://projects.eclipse.org/projects/technology.handly/releases/0.6/bugs