Primary tabs

Handly, a technology project at Eclipse, provides basic building blocks that help create handle-based models similar in design patterns and principles to the JDT Java model. The uniform API makes it possible to supply common IDE components dealing with Handly-based models. Integration with Xtext editor is provided along with support for other source editors.

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.

The workspace resource model is 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 with due consideration of possible licensing issues. The traditional process required much effort, was tedious and error-prone. 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 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.

In particular, the project defines a common interface and provides a skeletal implementation for the central notion of a handle 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 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.

Elements of a Handly-based model are expected to implement certain basic interfaces such as IHandle, ISourceElement and ISourceFile using the provided skeletal implementations. That being said, 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 project also defines common interfaces for model change notifications such as IHandleDelta and IElementChangeEvent and provides 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.

The project provides 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 established API makes 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 Handly. While providing a uniform handle-based API, the project imposes almost no restrictions on the shape of attainable models or on the languages modeled.

Besides API Javadocs, an architectural overview comprises the currently available documentation. The project provides a number of exemplary implementations including a basic Xtext-based example and a more advanced Java model example. There is also a comprehensive step-by-step guide (hosted on GitHub and made available under the EPL v1.0) to getting started with Handly. You might also be interested in project lead's blog posts on topics surrounding Handly.

If you have any questions or would like to provide feedback, consider using the project's forum or developer mailing list. Any input would be greatly appreciated.

Latest Releases: 

From June 25th, 2014 to June 22nd, 2016

0.4 New!2015-12-09Review
Contribution Activity: 
Commits on this project (last 12 months).