Skip to main content



The Handly project is a proposed open source project under the Technology Top-Level Project.

This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process) and is written to declare its intent and scope. We solicit additional participation and input from the Eclipse community. Please send all feedback to the Eclipse Proposals Forum.


The Handly project aims to provide a foundation for construction of language-oriented handle-based models not unlike the JDT Java Model in their essential qualities. It borrows from core design patterns and principles used in the Java Model, but aims for a generalized albeit partial basic implementation, on top of which complete handle-based models for languages of diverse kinds could be built with relative ease. The project includes a layer of integration with Xtext.


It is well known that the Java Model is one of the pillars of Eclipse Java development tools (JDT). To a great extent, it is the Java Model that makes possible seamless tool integration and unified user experience in JDT. The Java Model is designed to be a lightweight, fault-tolerant model with elements to which a reference can be kept; the model that is well suited for presenting in views. It meets those design goals with a handle-based, lazily-populated model that keeps no resolved information and wrappers the workspace resource model. Meanwhile, models with similar design properties might play an equally important role in Eclipse-based development tools for other languages.

It seems that core design patterns and principles used in the Java Model can be just as relevant to handle-based models for other languages. But as the Java Model shows, implementation of those patterns and principles might be a nontrivial undertaking. Doing it from scratch, over and over again for each language does not appear to be an attractive proposition, especially when dealing with languages on a large scale (e.g. DSL engineering). Can those patterns and principles be (at least partially) implemented in a framework of general usefulness? That is the question that seems worthwhile to investigate.


The project is going to encompass the following areas of work:
  • Core framework. The main proposition of the project is a framework that attempts to distill the core abstractions of a handle-based model into a uniform API and aims to provide the raw materials deemed generally useful for implementing such models.
  • Common UI components. The API provided by the core framework can potentially enable construction of reusable UI components. This might be an area for future work.
  • Integration with other Eclipse projects. A layer of integration with the Xtext project is provided initially. Other integration layers may be devised in the future, when and if appropriate.
  • Exemplary implementations. To encourage adoption of the framework, comprehensive examples of its use must be provided. These examples would be most fruitful if they could also serve as practical tools.


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 will attempt to distill the 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 used in the Java Model, but aims for a generalized albeit partial implementation.

Thus, the project will provide 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 will be supplied by the project.

Furthermore, the project will support the notion of a working copy (of a source file), its editing and reconciling. A layer of integration with Xtext will be provided for editing and reconciling a working copy connected to an Xtext editor.

While providing a uniform handle-based API, the project will try to impose as minimal restrictions as possible on the shape or the underlying language(s) of attainable models.

Relationship with other Eclipse projects

The project rests upon the Eclipse Platform and includes a layer of integration with Xtext; integration with other Eclipse projects is possible in the future.

There are existing efforts at Eclipse that might be viewed as related to the project in a way:

  • The IDE Meta-tooling Platform (IMP) has a much wider scope than this project, and a different emphasis. Among other things, it provides a 'universal' language-oriented handle-based model, with limited extensibility. The current implementation doesn't support elements inside compilation units, the notion of a reconcilable working copy, or a handle/body design with a bounded LRU cache of bodies, all of which we'll have already covered in the initial contribution. More important, our approach is fundamentally different. Instead of providing a single complete handle-based model supposed to be a universal fit for all languages, we intend to provide an abstract API and a partial implementation for constructing any number of specific language-oriented handle-based models, with few restrictions on the shape of the model. Update: the IMP project has recently been archived (January 2014).
  • Dynamic Languages Toolkit (DLTK) provides (among other things) an extensible handle-based model intended for dynamic languages. The design and implementation are largely influenced by the Java Model. The DLTK model does support elements inside source modules and is otherwise similar to the Java Model in all essential qualities. However, it is predefined to contain elements pertaining to (a subset of) dynamic languages (e.g. a source module may contain types, fields and methods; a type may contain fields, methods and inner types). We aim to support implementation of custom handle-based models of almost arbitrary shapes, for languages of diverse kinds (including domain-specific languages).
  • Xtext is a wonderful tool for language engineering. It covers many important components of an Eclipse-based IDE in a generic and extensible way, but does not explicitly address handle-based models. As part of the initial contribution we'll provide an integration layer to support editing and reconciling of a working copy connected to an Xtext editor. We regard both projects as complementary and hope to collaborate with the Xtext team on further facilitating construction of handle-based models for Xtext-based languages. That said it's our explicit goal to keep the core framework completely neutral of any specific language implementation technology and encapsulate such dependencies strictly within corresponding integration layers.

Why Eclipse?

We believe the nature of this project makes Eclipse the right home for it. As stated above, handle-based models can play an important role in an Eclipse-based IDE. This supports our hope that the area of work to be developed by the project might be interesting and useful to the Eclipse community. At the same time, such project should definitely benefit from the wider exposure with the Eclipse community. We do welcome and hope for open participation and contributions from the community; diversity is really important for this project to succeed. The project would also benefit from the commendable Eclipse development process and IP management.

Initial Contribution

The initial code base will be contributed by 1C LLC and includes the core framework and a layer of integration with Xtext.

Although the code is pretty stable and has been used internally with promising results, we regard it only as a starting point. The intent is to come up with a really nice design in this problem area through an open and transparent development process informed by community feedback.

Some parts of the initial design and implementation were adapted from Eclipse JDT and Xtext projects. The code makes direct references to the following third-party libraries, already present in the Eclipse Orbit repository:

  • 3.0.0 - Apache License, Version 2.0
  • 10.0.1 - Apache License, Version 2.0
  • org.apache.log4j 1.2.15 - Apache License, Version 2.0

Legal Issues

There are no known legal issues.


The following individuals are proposed as initial committers to the project:

Vladimir Piskarev, 1C (lead)
Vladimir is the main developer of the existing framework
George Suaridze, 1C (co-lead)
George is an early adopter of the existing framework

We welcome additional committers and contributions.


The following Architecture Council members will mentor this project:

  • Doug Schaefer
  • Marcel Bruch

Interested Parties

The following individuals, organisations, companies and projects have expressed interest in this project:

  • itemis AG

Project Scheduling

The initial contribution is to be expected shortly after creation of the project and approval of the Eclipse IP Team. The first milestone build based on the initial code base should follow soon after that. Although no exact dates are given, we intend to make the initial contribution available to the community as soon as technically and legally possible.

Changes to this Document

Date Change
10-Jan-2014 Document created

Back to the top