Well, the content itself is ok, but it could use some nice formatting so that the important information is highlighted. I did a quick rewrite (that could use some editing), mainly adding a few headlines and a "what you get" chapter (it could be merged with the 'rationale'). The implementation overview will probably have to be reworded in light of that.
**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.**
# Background
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.
# Handly rationale
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.
# What you get with Handly
* a handle-based model that can be used by generic UI components (navigator, outline, *list all!*)
* default implementations for
* model change handling (like IHandleDelta, IElementChangeEvent)
* buffer and cache management
* working copy support
* an outline framework, with quick outline
* working set support
* integration with Xtext editors
* almost no restrictions on the shape of attainable models or on the languages modeled
Although we provide some UI components that leverage Handly, it is not in the current scope of the project to provide a full range of those. We would like to get a stable API before considering that.
# Implementation overview
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 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 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.
