Difference between revisions of "Handly/NewIn06"

Revision as of 10:50, 14 November 2016

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 be a more stable base for early 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 (bug 499220) and the model object (bug 500653) as a means of facilitating future evolution of Handly.

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 (bug 498749) and generalized to retain type information at runtime (bug 498752) and to be able to provide a default value (bug 498873).

As a first application of contexts in Handly, we have replaced the class org.eclipse.handly.model.ToStingStyle with a context (bug 499540) and have also revised the signatures of a number of methods in the Element hierarchy, making them context-aware (bug 500408). The new design should make it possible to evolve context-aware 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.

Contexts also interplay with another new feature in Handly 0.6, the model object (bug 500653), 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 (bug 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 (bug 500893, bug 502000)
• The workspace-related functionality has been extracted from SourceFile to a new subclass, WorkspaceSourceFile (bug 500676)
• Non-local file systems are now also supported (bug 506453, bug 506717)
• The buffer and working copy APIs have been revised and streamlined (bug 505714, bug 506332)

Full list of issues addressed in this release

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