It can be said that 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 further evidence. The Java Model also shows that the (programming-language agnostic) resource model is often not enough: a language or a group of languages may need its own handle-based model that defines a code-centric view on resources and supports navigation down to structural elements inside a source file (which requires parsing the contents of the file). It is this class of language-oriented handle-based models that is the main interest of this project.
The project aims to investigate technology needed to deal with such handle-based models on a large scale. In particular, the project attempts to distill core abstractions of a handle-based model into a uniform API and supply basic 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 implementation are supplied by the project.
Furthermore, 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 an Xtext editor.
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 the API Javadocs, an architectural overview comprises the currently available project documentation. You might also have a look at the provided exemplary implementations (Handly Examples). There is a work in progress hosted on GitHub and made available under the EPL v1.0 on a step-by-step guide to getting started with Handly. If you have any questions or would like to provide feedback, consider using the project's forum.