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. Eclipse development tools such as JDT and CDT make use of their own handle-based models that define a code-centric view on the workspace and support 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, taking into account license 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, 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-centric handle-based 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, a model 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; that's why the cache is not strictly bounded). 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 a set of building blocks for 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 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.1 New!2015-10-02
Contribution Activity: 
Commits on this project (last 12 months).