Primary tabs

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

Handle-based models are an important ingredient in an Eclipse IDE, if only because the workspace resource model is handle based. The handle-based Java model of JDT provides a good example of a language model that defines a code-centric view on the workspace and supports navigation down to structural elements inside source files. It is this class of code-centric handle-based models (code models for short) that is the main area of this project.

Because the rest of the IDE usually depends on the code model, the quality of the design and implementation of that model is of the utmost importance. Traditionally, such models were built either entirely from scratch or by forking and modifying preexisting models. 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, although the models did seem to have certain traits in common.

The Handly project begs to differ with the traditional approach. In particular, it attempts to distill core abstractions of a code model into a uniform API and supply a set of flexible building blocks for construction of such models. It borrows heavily from some of the design patterns and principles underlying the Java model, but aims for a generalized (albeit partial) implementation.

Thus, the project provides a uniform API and a partial implementation for the central notion of a handle that acts like a key to a model element and has the following principal characteristics:

  • a value object -- immutable, equality isn't based on identity
  • can define the behavior of an element, but doesn't keep any element state (beyond the key information) -- lightweight, never stale, references can be kept for a long time
  • can refer to non-existing elements -- existence can be tested with exists()

A handle-based design gives a lot of freedom when resolving handles to find the corresponding element state (the body). For instance, an implementation can maintain a (not strictly) bounded LRU cache of element bodies. The handle acts like a key into the cache. The model swaps out bodies to make room for other elements (unsaved changes can never be swapped out). Bodies store the cached structure and attributes for a particular element and are computed on demand. The basic building blocks for such an implementation are supplied by the project.

Also, the project supports the notion of a working copy (of a source file), its editing and reconciling. A layer of integration with Xtext is provided for editing and reconciling a working copy connected to Xtext editor. Handly can also support other editors. In particular, it provides integration with TextFileBuffer-based text editors.

The uniform 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 tries to impose as minimal restrictions as possible on the shape or the underlying language(s) of attainable models.

Besides extensive Javadocs, an architectural overview comprises the currently available documentation. Don't miss out on the provided exemplary implementations (Handly Examples) including a basic Xtext-based example and a more advanced Java model example. There is also a 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. Thank you!

Latest Releases: 

From to December 11th, 2015

0.3 New!2015-06-24Review
Contribution Activity: 
Commits on this project (last 12 months).