Handly 0.3 : Example model for Java

by Vladimir Piskarev

A highlight of the upcoming Handly 0.3 release (just a few days away) is a Java model example (org.eclipse.handly.examples.javamodel*), which demonstrates a Handly-based model for the Java language along the lines of the JDT Java model.

Back in Handly 0.1, a basic exemplary implementation was provided: a complete Handly-based model for a simple Xtext-based language, with the outline page and navigator view implemented atop the model. Intentionally contrived to be simple so as not to explain a lot of stuff that isn’t Handly-related, but at the same time sufficient for demonstrating many design and implementation aspects, this example provided the basis for a later multi-part tutorial, which has received some acclaim from early adopters.

It was obvious, though, that a more advanced example was really needed. Such an example would be called for to demonstrate how to implement some of the more advanced features with Handly and, ideally, spur further Handly adoption.

In particular, the following requirements for this example had been gathered via the project’s forum:

  • “Real-world”;
  • Demonstrate how to deal with a classpath-like concept (e.g. source folders);
  • Exemplify model integration with a custom text editor (i.e. non-Xtext).

After a discussion with early adopters, it was decided that an example model for Java would fit the bill. It could exemplify all the features mentioned above and would be sufficiently real-world (despite the inevitable simplifications vs. the full-fledged JDT implementation). Besides, adopters already know Java (and probably JDT internals too), so it sounded like a useful common ground. Also, JDT provides some important services (like parsing) that could be reused by the example code.

So, I set to work on the Java model example. The outcome of this work for Handly 0.3 is the core model and a bunch of tests. There is no corresponding UI yet. As one whould expect from an example, the model is somewhat contrived. In particular:

  • Only classpath entries of kind CPE_SOURCE, with paths of length 1 are considered (i.e. only source folders that are direct children of the project resource);
  • Inclusion/exclusion filters are ignored — everything is included;
  • Only default output location is supported, with path of length 1;
  • Initializers and local/anonymous types are not represented in the model.

Some of these constraints may be relaxed in the future (especially based on community feedback).

The following UI parts are expected to appear in a subsequent release:

  • Example Java editor, with Handly-based reconciling and outline;
  • Example Java navigator view.

It is hoped that this example will be useful to Handly adopters. In particular, I tried to craft the series of commits carefully to show how one can grow the model organically. For instance, it can be seen that at one point there was no effective model cache/delta processor, only a bare model structure that, however, was fully functional and testable. Only after the model structure was fully fleshed out, the model cache/delta processor were implemented. This is the way I would recommend for developing a Handly-based model.

Feedback is most welcome and can be directed to the project’s forum or right to the developer mailing list (the list requires subscription).