Xtext M6 with more documentation and stable API

According to the project plan we have published the sixth milestone version of TMF Xtext this Tuesday. Please note, this is not a release candidate, yet. Nevertheless, it’s another huge step towards the Galileo release in June and tough guys may want to explore M6 as some early adopters already do.

We know about bugs and missing features but with good cause I want to draw your attention to this release. Apart from the constantly improved core documentation we are beginning with documents like “Getting Started” or ”Migration from oAW Xtext“. The latter is far from being finished and will summarize the lessons we have learned together with our customers that have be been using TMF Xtext since M5 and earlier.

Xtext users might be glad to hear that the API of Xtext is reliable. To accomplish this goal we leverage the annotation @java.lang.Deprecated for parts of the API that won’t be supported in future. But more interesting is the newly introduced annotation @org.eclipse.xtext.Stable. An interface tagged this way is not truly stable itself since we might introduce new methods in future but the annotation might help you anyway. It directs you to an abstract class that you should derive from. Whenever a new method will be introduced in future this class will complement your work with a null implementation your can override as necessary (does anyone know how this pattern is called?).

Interface with @stable and corresponding abstract class

Interface with @stable and corresponding abstract class

So, even if you won’t try out TMF Xtext at this stage this documentation material might give you a preview of what you can expect in June. Check out the New and Noteworthy Page for a general overview of this release.

Feedback is welcome through the news group and bugzillas.

Support my Work

Writing an article like the one you have just read takes me quite an amount of my personal time. Way too often, I invest this time in different interests and decide against another blog post. On the other hand, you can motivate me with your feedback, your thoughts and your ideas. Please leave a comment below or flattr this post if you think it's worth it.

Comments

  1. Gunnar says:

    Heiko, why didn’t you use API tooling but introduced yet another markup that people need to learn?

    I understand that annotations look stronger than JavaDoc tags. But Eclipse API tags are great for expressing what your @Stable annotation does. Plus, they integrate nicely with the Eclipse API tooling.

    Example:
    @noimplement This interface is not intended to be implemented by clients directly. They must subclass {@link SomeBaseClass} instead.

  2. Jens v.P. says:

    As fas as I understand these annotations, they are not Xtext related, are they? Would be nice to have something like that available for other projects, too.

    BTW: I figure the diagram was created with OmniGraffle, wasn’t it? Frankly, I create my diagrams with OmniGraffle, too. Isn’t that weird? Working with GEF everyday, I still use OmniGraffle if I want to produce nice diagrams… Hmm… we definitely have to improve these Eclipse graphical editor things.

  3. @Gunnar: We had this discussion, too. See http://dev.eclipse.org/mhonarc/lists/xtext-dev/msg00187.html as a starting point of this thread in the mailing list. Eventually, we settled with the annotation partly due to tooling capabilites (e.g. “Find References”). Also, the Eclipse API tooling has a resticting tone whereas the @stable annotation declares stable parts. Last not least we want to generate code against interfaces that are not marked as stable. Since Eclipse API tooling cannot distinguish between generated and manually written code this might cause false errors.

  4. @Jens Yes, the @stable annotation is Xtext specific. We decided to place it there and limit the possibilities of reuse. On the other hand, its implementation is not that complex

    @Target({ ElementType.TYPE})
    public @ interface Stable {
    String since();
    Class< ?> subClass() default Object.class;
    }

    and an Xtext specific annotation allows you to find every stable aspect of the API by a simple “Find References”.

  5. @Jens: And yes, OmniGraffle rocks!

  6. [...] case. Eventually, we realized that the omnipresent logo started with a lower-case “x” (convince yourself). So it was out own [...]

Leave a Reply