Tutorial: Embedded Java With Xtext

Jbase is a customization of Xbase to handle pure Java expressions and to adhere to the stricter Java type system.

Jbase main implementation aspects are:

  • redefines many of the Xbase grammar rules so that they can handle Java expressions (including array access expressions with
    [])
  • customizes the Xbase compiler to handle additional Java expressions
  • customizes the Xbase type system to adhere to the stricter Java type system

As shown in this blog post, the programmers already familiar with Xbase will only have to perform a few steps to use Jbase in their DSL.

In this blog post I’d like to show how to get started using Jbase. Of course, you need to be already familiar with Xbase concepts, in particular with the JvmModelInferrer. In the end, you will get all the benefits of Xbase, but with the syntax of Java expressions.

Why would I want that? Well, first of all, I’d like to stress that I really love Xbase, not to mention its main incarnation: Xtend. I’m using Xtend whenever I can, even for non Xtext projects, since its Xbase-based syntax is really a better Java without noise. I started to develop Jbase because in some projects I really need to embed real Java expressions, even if I lose the clean Xbase syntax. In particular, one year ago I implemented Java–, a simpler version of Java aiming to teach programming (e.g., just functions, no classes, no inheritance), that’s when I had to customize Xbase to get Java expressions. Jbase is basically the factoring out of the reusable parts of Java–.

NOTE: Jbase is currently based on Xtext/Xbase 2.8.4, so it will not work with the newer version of Xtext 2.9.0. The porting to Xtext 2.9.0 will start soon.

The source code of Jbase can be found at https://github.com/LorenzoBettini/jbase

and the update site at http://sourceforge.net/projects/xtext-jbase/files/updates/releases

First Tutorial

Create an Xtext project, you can leave the defaults for names, e.g., org.xtext.example.mydsl.

Open the MANIFEST.MF of the main project and

  • add a dependency to the bundle jbase and re-export that dependency;
  • add a dependency to the bundle jbase.mwe2 and make it optional;

Save the file.

Change the Xtext grammar, MyDsl.xtext, making the grammar inherit from jbase.Jbase:

Open the MWE2 workflow, GenerateMyDsl.mwe2 and

  • in the StandaloneSetup part, add the references to the JbasePackage and to Jbase.gnemodel, the modified part should look like this
  • search for the XbaseGeneratorFragment reference, and replace it with JbaseGeneratorFragment:
Run the GenerateMyDsl.mwe2 just to make sure that the Xtext artifacts are correctly generated and that Jbase dependencies are added to the ui project.

Implement the Jvm model inferrer as follows:

Thus, for each Hello element, we create a Java class with the name of the element (in the package “my.company”) with a public method with name “hello” + the name of the Hello element, and associate the block expression to the body of the method. Note that the return type of the method will be inferred automatically from the contents of the block expression.

If you want to manually test your DSL, run another Eclipse instance (Xtext should have generated a launch configuration in your projects, if you started with an empty workspace); in the new instance, create a Plug-in project, and add a dependency to the bundle org.eclipse.xtext.xbase.lib. In the src folder create a new file with extension .mydsl, e.g., example.mydsl; when the dialog pop-ups, accept to add the Xtext nature to the project.

Try and add some contents to the file; remember that in the codeblock you must use Java syntax, NOT Xbase syntax:

Note that variable declarations are like in Java, and that you have array access expressions.

The Domainmodel with Jbase

We now see how to turn an existing Xbase-DSL to use Jbase. We will use the well-known Xtext/Xbase Domainmodel example.

First of all, import this example into the workspace: File => New => Example… then navigate to the “Xtext Examples” category and choose “Xtext Domain-Model Example”, this will materialize into your workspace the standard Xtext Domainmodel example’s three projects.

First of all, open org.eclipse.xtext.example.domainmodel‘s MANIFEST.MF file and

  • add a dependency to the bundle jbase and re-export that dependency;
  • add a dependency to the bundle jbase.mwe2 and make it optional;

Save the file.

Modify the GenerateDomainmodelLanguage.mwe2 as shown in the First Tutorial

  • in the StandaloneSetup part, add the references to the JbasePackage and to Jbase.gnemodel, the modified part should look like this
  • search for the XbaseGeneratorFragment reference, and replace it with JbaseGeneratorFragment:
Make the Domainmodel.xtext grammar inherit from jbase.Jbase: Now run the mwe2 workflow, to re-generate Xtext artefacts.

The DomainmodelJavaValidator should be modified so that it extends JbaseValidator instead of XbaseValidator, so that it will use our Jbase custom Xbase validator.

There is no need to change the model inferrer, since the runtime model of Jbase is also a valid runtime model of Xbase.

If you want to manually test these modifications to the Domainmodel, run another Eclipse instance (Xtext should have generated a launch configuration in your projects, if you started with an empty workspace); in the new instance, create a Plug-in project, and add a dependency to the bundle org.eclipse.xtext.xbase.lib. In the src folder create a new file with extension .dmodel, e.g., example.dmodel; when the dialog pop-ups, accept to add the Xtext nature to the project.

Here’s an example of what you can write with the Domainmodel example that uses Jbase instead of Xbase. Note the Java variable syntax, array access syntax and formal parameters, which are, as in Java, non-final by default (so they can be assigned):

You may also want to modify the DomainmodelFormatter.xtend so that it extends JbaseFormatter instead of XbaseFormatter, so that automatic formatting will work for our Java expressions.

If you want to run the Domainmodel Junit test suite, you first need to update the inputs that are used in those tests, so that they respect the Java syntax: imports and statements must be terminated with a semicolon, method invocations must have parenthesis, etc. Moreover, the original test XbaseIntegrationTest will not work (since it relies on Xbase syntax). Finally, some tests should be removed completely, since they use features/mechanisms of Xbase that are not supported in Jbase, such as, e.g., static extension methods. (The modified domainmodel example can be found in the Git repository of Jbase).

 

By | 2016-11-30T08:34:08+00:00 January 24th, 2016|Eclipse, Tutorial, Xtext|6 Comments

Share This Article

About the Author:

Lorenzo is an Associate Professor in Computer Science at Dipartimento di Statistica, Informatica e Applicazioni, Università di Firenze. His main research topic is theory, design and implementation of programming languages. He is the author of the book "Implementing Domain-Specific Languages with Xtext and Xtend".

6 Comments

  1. DIdos June 15, 2016 at 19:32 - Reply

    is it planned to integrate Jbase as an alternative to Xtext official release?

    • Lorenzo Bettini June 16, 2016 at 08:13 - Reply

      Hi, what do you mean by “integrate Jbase as an alternative to Xtext”? Jbase is meant as a reusable Xtext DSL, like Xbase. It’s not an alternative to Xtext 🙂

  2. Akira Tanaka February 27, 2017 at 07:10 - Reply

    Hello

    I followed your domainmodel example with the latest Xtext (2.11). When I created test.dmodel with your sample code starting with “import java.util.List;”, I got the following error.

    “java.lang.UnsupportedOperationException: Coudn’t find a compilation strategy for expressions of type jbase.jbase.impl.XJSemicolonStatementImpl.”

    Could you give me a suggestion on where to look at, to make it work? Thank you in advance.

    Akira

    • Lorenzo Bettini February 27, 2017 at 10:52 - Reply

      Hi Akira

      I don’t get such an error with the modified domainmodel example that ships with Jbase (New -> Example -> Jbase Examples -> Jbase Domain Model example).

      Please keep in mind that in Xtext 2.11, the domain model example switched to the mwe2 new generator. So you should follow the instructions for the new mwe2 generator for Jbase.

      In any case, you might want to open a github issue https://github.com/LorenzoBettini/jbase/issues and we’ll continue the discussion there.

  3. Kaushal Patel June 29, 2017 at 00:46 - Reply

    What is the connection between Xtext/Xtend and Yang langauage?

    • Lorenzo Bettini June 29, 2017 at 08:08 - Reply

      This is not strictly connected to this article… however, from what I know, Yang is a modeling language for specifying network data, while Xtend is a general purpose language.

Leave A Comment