Primary tabs

Handly, a technology project at Eclipse, provides basic building blocks that help create handle-based models similar in quality 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.

Handle-based models employ a variation of the handle/body idiom, where clients have direct access only to handles that act like a key to a model element and have the following principal characteristics:

  • immutable, equal by value
  • can define behavior of the element, but don't keep any element state beyond the key information. The element state beyond the key information is stored separately in an internal body
  • can refer to non-existing elements

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.

Why Handly?

Traditionally, language-specific handle-based 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 quality and basic design patterns and principles to the JDT Java model. This reduces programming effort, fosters software reuse and provides opportunities for interoperability.

What's in the Box?

  • Common interfaces and skeletal implementations for handle-based model elements, including code-centric ones such as source files and source elements
  • Common interfaces and default implementations for change notifications in a Handly-based model
  • Infrastructure interfaces and implementations for buffer and cache management
  • Comprehensive working copy support, including integration with the Xtext editor and support for integrating other source editors
  • Common UI components such as an outline framework, quick outline, and working set support that work with Handly-based models
  • Exemplary implementations, including a basic Xtext-based example and a more advanced Java model example

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 imposes almost no restrictions on the shape of attainable models or on the languages modeled.

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 established API makes it possible to develop generic IDE components dealing in a uniform way with Handly-based models. Although we provide some common UI components that leverage Handly, it is not in the current scope of the project to provide a full range of those. Currently, our primary goal is to come up with a really nice design of the core API.

Success Stories

Despite its currently unassuming version number, Handly is successfully used in large-scale commercial products, as demonstrated in success stories related by our adopters. Get inspired by seeing how others use Handly in real products and projects. If you are an adopter, tell the world about your usage.

Getting Started with Handly

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).