vladimir piskarev's blog

Musings on the Eclipse Handly project and software development in general

Eclipse Handly 1.1 Released

We are pleased to announce the availability of Eclipse Handly 1.1 release.

For some time, the project was concentrating on the Core framework and, with the 1.0 release this June, has reached stability for the Core API. The 1.1 release is focused on the UI side of things. To that end, it polishes existing UI components and provides new ones, such as integration with Search View and an initial support for Call Hierarchy View.

You do not necessarily have to implement the API for handle-based models provided by the Handly Core to be able to use Handly UI components; much of the code is fairly generic and can be reused in other contexts. Of course, if you do implement the handle-based API, the UI components will take full advantage of that.

Please note, however, that the UI API is still not as mature as the Core API and might need further polishing. The UI bundles in this release have version 0.10 to indicate a slim chance that their API may still change in a breaking way. Particularly, the initial API for Call Hierarchy should be considered provisional and subject to change.

Having said that, we would like to invite potential adopters to take a look and leave feedback; as always, it would be much easier to fix any discovered API deficiencies early on.

New and Noteworthy
Migration Guide

The Handly Team


Eclipse Handly 1.0 Released

We are very pleased to announce the availability of Eclipse Handly 1.0 release. Simultaneously, Handly has graduated from incubation and is now considered a mature project at the Eclipse Foundation. Thanks to everyone involved with the project, especially to our early adopters, who have been successfully using Handly in their products for quite a long time! And thanks to everyone interested in the project; perhaps now it is a good time to put Handly to use for you!

New and Noteworthy
Migration Guide

The Handly Team

Eclipse Handly 0.8 Released

We are pleased to announce the availability of Eclipse Handly 0.8 release, which attempts to finalize the key parts of the Core API. To that end, it contains many API enhancements to elements, element deltas, the model, and working copy management. It also introduces new naming convention for model *Impl* interface methods and a separate package for model implementation support. Also, some optimizations have been made in skeletal implementations to allow Handly-based models scale even better than before.

New and Noteworthy
Migration Guide

Despite its incubation status, the project is known to be successfully used by early adopters in their large-scale commercial products. Recently, we created an experimental fork of Eclipse Java development tools (JDT) on GitHub as an experiment in adopting Handly within a non-trivial existing model implementation (the Java model), which can also serve as an exemplary implementation in addition to the exemplary implementations that are shipped as part of the project. All of the nearly 8 000 JUnit tests for the Java model, including performance tests, run successfully in the Handly-based fork, with none of the existing public JDT APIs having been affected in any way. The JDT fork and the other exemplary implementations as well as the project’s getting started tutorial and architectural overview have been updated to illustrate enhancements in Handly 0.8.

Broader community feedback and participation would be most welcome.

The Handly Team

Announcing Handly 0.7

We are pleased to announce the availability of Eclipse Handly 0.7 release, which contains a number of enhancements in Core API.

New and Noteworthy
Migration Guide

The 0.7 release has been informed in a large part by trying to adopt Handly in a specially created experimental fork of Eclipse Java development tools (JDT) to test the core framework in the context of a non-trivial, well-known existing model implementation, the Java model. The JDT Core component has a comprehensive suite of JUnit tests, including nearly 8 000 tests specifically for the Java model. All of the Java model tests, including performance tests, run successfully in the Handly-based fork now. None of the existing public JDT APIs have been affected in any way. Notably, most of the internal JDT (non-)APIs have also been kept intact. We humbly hope that it can serve as a real-world example of what Handly is capable of now and help encourage further adoption. Broader community feedback and participation would be most welcome.

Eclipse Handly 0.6 Released

We are pleased to announce the availability of Eclipse Handly 0.6 release. This release is an incremental improvement of the entirely new design introduced in Handly 0.5, with special emphasis on facilities for non-breaking API evolution and support for non-local file systems and files external to the Eclipse workspace.  Besides quite a few revisions through the whole spectrum of the core API, new features include a context API (499220), an API for the model object (500653), and a notification manager API (505777).

New and Noteworthy
Migration Guide

If you are new to Handly or just wish a succinct refresher, here is a bunch of slides about the project’s background, goals, and current status:


You can also take a look at the project’s getting started guide, which has been updated for the new Handly release:


The Handly Team

Announcing Handly 0.5

I am very pleased to announce the availability of the Handly 0.5 release, a true “2.0” version in spirit. This release introduces an entirely new design that gives the implementor of a Handly-based model complete control over the model API. Among other things, this should make it possible to use Handly for (re-)implementing handle-based models where the model API is a given, just as in the case of a preexisting model API that needs to be preserved for backward compatibility. Many of the core APIs have been revised in this release to make Handly even more flexible and robust.

New and Noteworthy
Migration Guide

Any feedback would be greatly appreciated.

Many thanks to all who contributed to this release:

  • Ondrej Ilcik, head of IDE Team at Codasip, has kindly contributed a navigator view for the Java model example, which made its way into this release. This is the first significant (~ 4K LOC) contribution to the project by a non-committer. Codasip Studio is one of the earliest adopters of Handly, and it is really great to see that a major adopter becomes a significant contributor. Also, Ondrej has been so kind as to share a great success story of Codasip Studio and Handly, which is all the more valuable as the first success story published by a Handly adopter.
  • Vlad Dumitrescu, the project lead of erlide, has been actively participating in discussions on the project’s mailing list. His earlier feedback helped inspire the new design introduced in this release, and he has also contributed great ideas about restructuring the project’s web page to make it more readable.
  • Peter Gribanov, 1C, has contributed a success story describing how 1C:Enterprise Development Tools, the earliest adopter of the project, is using Handly.

Thank you for contributing!

Handle-based models with Handly

Handle-based models are all around us in the Eclipse IDE: on top of the programming language agnostic Platform resource model, language-specific code-centric models of the underlying workspace form a basis for Eclipse Java Development Tools (JDT), C/C++ Development Tooling (CDT), and other Eclipse-based development tools. Traditionally, such models were built either entirely from scratch or by forking and modifying preexisting models. Handly, an incubating technology project at Eclipse, begs to differ with the traditional approach. At its core, it can be described as a class library for handle-based models, with special emphasis on code-centric models of the Eclipse workspace. This article, intended as a short introduction to the problem area, is hoped to raise awareness of the project within the wider Eclipse community. The article is supplemented with a slide deck.

By Vladimir Piskarev (1C), Project Lead, Handly
December 9, 2015

It goes without saying that handle-based models play an important role in the Eclipse IDE, with the workspace resource model being the foremost example.

A handle, in this context, is an object that acts like a key to a model element and has the following principal characteristics:

  • immutable, equals by value
  • can define behavior of the element, but doesn’t keep any element state beyond the key information
  • can refer to non-existing elements

Handle-based models employ a variation of the handle/body idiom, where clients have direct access only to handles to model elements, while the element state beyond the key information is stored separately in an internal body. Such design has a number of important properties:

  • handles are stable, you can freely keep references to them
  • handles are lightweight but can be rich in behavior
  • bodies can be computed on demand and virtualized

This makes handle-based models highly scalable and perfectly suited to presenting in Eclipse views such as Project Explorer, Search, Outline, etc.

The workspace resource model is, of course, programming language agnostic, so Eclipse development tools such as JDT (Java Development Tools) and CDT (C/C++ Development Tooling) are based on language-specific handle-based models that define a code-centric view on the underlying workspace and support navigation down to structural elements inside source files.

Traditionally, such models were built either entirely from scratch or by forking and modifying preexisting models. The process was tedious and error-prone, and the resulting models were effectively silos with a completely isolated API, which prevented a possibility of developing reusable IDE components around those models, although the models did seem to have certain traits in common.

The Handly project (eclipse.org/handly) begs to differ with the traditional approach. Basically, it provides a unified architecture and a set of flexible building blocks that help create handle-based models similar in design patterns and principles to the JDT Java model. This reduces programming effort, fosters software reuse and provides opportunities for interoperability.

When designing the new API, we attempted to distill the truly fundamental abstractions and aimed at a deeper introspection on what a common language infrastructure should include for ‘the model part’, and what would be better left to the model implementor. The framework imposes almost no restrictions on the shape of attainable models or on the languages modeled. At the same time, the API is rich enough to enable such features as comprehensive working copy support, including out-of-the-box integration of the working copy facility with the Xtext editor and support for integrating other source editors.

The core framework defines common protocols for elements of handle-based models, with special emphasis on code-centric models of the Eclipse workspace. It expects model elements to implement certain basic interfaces such as IHandle, ISourceElement and ISourceFile and provides skeletal implementations of these basic interfaces to minimize the effort required to implement the model. Naturally, the model implementor is free to define model specific interfaces such as IFooProject, IFooFile and IFooFunction and make model elements implement those interfaces in addition to the basic interfaces.

The provided implementation gives a lot of freedom when resolving handles to find the corresponding body. For example, using supplied building blocks a model can maintain an LRU cache of element bodies to set a cap on its memory footprint.

The core framework also defines common interfaces for change notifications in a handle-based model such as IHandleDelta and IElementChangeEvent and provides complete implementations of these interfaces that can be used as they stand or extended as circumstances warrant. It also includes infrastructure interfaces and implementations that provide essential support for the model such as buffer and cache management.

Of course, the devil is in the detail, and there’s more to it than that, but in a nutshell that’s it. Please refer to the System Overview (written in early 2014, but still relevant) for a more detailed discussion of the core framework.

The common protocols established by the core framework make it possible to develop generic IDE components dealing with Handly-based models. Some common UI components such as an outline framework, quick outline and working set support are already supplied by the project both as a proof of concept and as a way to deliver more value to our adopters.

Handly has been about two years in development at Eclipse. The 0.4 version has just been released, with many API improvements, model adaptation facility, and other significant enhancements. Handly is successfully used in two commercial products, with quite positive feedback from the early adopters. We have provided a comprehensive getting started guide and a number of exemplary implementations including a Java model example.

In the 0.5 release, tentatively scheduled to coincide with Eclipse Neon, we’ll try to stabilize the core API, in preparation for a later 1.0 release. The problem is that we’re lacking broader community feedback and participation, which would be required in order to truly finalize the API and graduate from the Incubation Phase.

Involving the Eclipse IDE community seems to be a tough question, if history is any guide… Development Tools Factorization is apparently a long-standing problem in Eclipse. There are, of course, pragmatic reasons for that. A lack of resources along with backward compatibility concerns immediately come to mind, among other things.

The situation is quite unfortunate, however. The factorization problem is important and will become increasingly important as more *DT projects are created: Eclipse is not just a Java IDE. This puzzle can only be solved together, and I believe that Handly might serve as a first piece, in some way or another. The project’s success crucially depends on more significant community involvement and suitable joining of forces.

I hope that this short introduction will raise awareness of the project within the wider Eclipse community. Any help or feedback would be greatly appreciated. Thank you very much for your attention!

Watch the slides