antonywilkins

Xtext Spring Demo - Part 5

2009-08-06T17:43:00.001-07:00

Serialisation of model to text form

What about if you already have instances of the Java model classes - and want to save them in text form - using your new language.

This is also very simple.

Coming soon...

Previous Start

Xtext Spring Demo - Part 4

2009-08-06T17:41:00.003-07:00

Export Spring XML from model

In the previous parts we saw how to integrate our Spring model at runtime.

But suppose we want to actually generate something from our model during development or build?

Xtext models can be used in combination with another language - Xpand - to generate code or other text.

As an example of this, we will write a simple code generator for our Spring model - one that can export our model as valid Spring XML.

The generator project has an example code generator - open the existing file src/templates/Template.xpt, and replace it's example text with the following:


«IMPORT spring»

«EXTENSION templates::Extensions»

«DEFINE main FOR SpringModel-»
«FILE "spring-confg.xml"-»
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
                  "http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
«EXPAND bean FOREACH beans.sortBy(e|e.name)-»
</beans>
«ENDFILE-»
«ENDDEFINE»


«DEFINE bean FOR Bean-»
    <bean id="«name»" class="«type»"«IF properties.size > 0»>
«ELSE-»/>
«ENDIF-»
«EXPAND property FOREACH properties.sortBy(e|e.name)-»
«IF properties.size > 0 »    </bean>
«ENDIF»
«ENDDEFINE»

«DEFINE property FOR Property-»
        <property name="«name»" «IF value!=null-»value="«value»"«ENDIF-»«IF ref!=null-»ref="«ref.name»"«ENDIF-» />
«ENDDEFINE»

Now right click on src/workflow/SpringGenerator.mwe and Run As->MWE Workflow. The console should show successful looking logging text, and the code generator will have created a file from our model. Open src-gen/spring-config.xml to see the results:

Previous Next

Xtext Spring Demo - Part 3

2009-08-06T17:41:00.001-07:00

Read a Spring model to load a BeanFactory

As a hint on how you could extend Spring to create a new BeanFactory loader, this example shows how to populate a BeanFactory from the model files.

This is very similar to how the Spring implementation will populate a BeanFactory while parsing in, for example, ClassPathXmlApplicationContext.

The example only covers the basics, but Spring spend a lot more code doing even the equivalent slice of functionality in their BeanFactory loading code.

In order to actually load a bean factory from the example file - we need to create the two example Java classes. Their implementation is obvious and trivial, but for convenience you should download them and copy them into the generator project "src" folder from this location.

Create a new Java class like this example - within the generator project - org.xtext.example.dsl.spring.generator:
src/org/xtext/example/dsl/spring/integration/SpringIntegrationTest.java


package org.xtext.example.dsl.spring.integration;

import org.eclipse.emf.common.util.URI;
import org.eclipse.emf.ecore.resource.Resource;
import org.eclipse.emf.ecore.resource.ResourceSet;
import org.eclipse.emf.ecore.resource.impl.ResourceSetImpl;
import org.springframework.beans.MutablePropertyValues;
import org.springframework.beans.factory.config.BeanDefinitionHolder;
import org.springframework.beans.factory.config.RuntimeBeanReference;
import org.springframework.beans.factory.config.TypedStringValue;
import org.springframework.beans.factory.support.BeanDefinitionReaderUtils;
import org.springframework.beans.factory.support.DefaultListableBeanFactory;
import org.springframework.beans.factory.support.GenericBeanDefinition;
import org.xtext.example.dsl.spring.SpringStandaloneSetup;
import org.xtext.example.dsl.spring.spring.Bean;
import org.xtext.example.dsl.spring.spring.Property;
import org.xtext.example.dsl.spring.spring.SpringModel;

public class SpringIntegrationTest {

 static {
  SpringStandaloneSetup.doSetup();
 }

 /**
  * @param args
  */
 public static void main(String[] args) {
  SpringModel model = readSpringModel("src/model/MyModel.spring");

  // Load a bean factory from the model
  DefaultListableBeanFactory registry = new DefaultListableBeanFactory();
  for (Bean bean : model.getBeans()) {
   GenericBeanDefinition beanDef = new GenericBeanDefinition();
   beanDef.setBeanClassName(bean.getType());
   MutablePropertyValues propertyValues = new MutablePropertyValues();
   for (Property property : bean.getProperties()) {
    Object propertyValue = getPropertyValue(property);
    propertyValues.addPropertyValue(property.getName(),
      propertyValue);
   }
   beanDef.setPropertyValues(propertyValues);
   BeanDefinitionHolder beanHolder = new BeanDefinitionHolder(beanDef, bean.getName());
   BeanDefinitionReaderUtils.registerBeanDefinition(beanHolder, registry);
  }

  Object bean = registry.getBean("myObject");
  System.out.println(bean.getClass());
  System.out.println(bean);
 }

 private static Object getPropertyValue(Property property) {
  Bean referencedBean = property.getRef();
  if (referencedBean != null) {
   return new RuntimeBeanReference(referencedBean.getName());
  }
  return new TypedStringValue(property.getValue());
 }

 private static SpringModel readSpringModel(String filename) {
  Resource resource = loadModelResource(filename);
  SpringModel model = (SpringModel) resource.getContents().get(0);
  return model;
 }

 /*
  * this method, and the static initialiser call to
  * SpringStandaloneSetup.doSetup() are all that are needed to load a model
  * file
  */
 private static Resource loadModelResource(String modelFile) {
  ResourceSet resourceSet = new ResourceSetImpl();
  URI uri = URI.createFileURI(modelFile);
  Resource resource = resourceSet.getResource(uri, true);
  return resource;
 }

}

Right-click on the new class and Run As->Java Application.
You should see the System.out.println calls output a bean retrieved from the BeanFactory into the console:

Previous Next

Xtext Spring Demo - Part 2

2009-08-06T17:40:00.002-07:00

Test our new language - standalone

The generated language Java implementation includes a parser and a set of Java model classes.

The parser reads the model file text, and transforms into instances of the Java model classes.

It's very simple to access these APIs.

Create a new Java class like this example - within the generator project - org.xtext.example.dsl.spring.generator:

src/org/xtext/example/dsl/spring/integration/ReadSpringModelTest.java


package org.xtext.example.dsl.spring.integration;

import org.eclipse.emf.common.util.URI;
import org.eclipse.emf.ecore.resource.Resource;
import org.eclipse.emf.ecore.resource.ResourceSet;
import org.eclipse.emf.ecore.resource.impl.ResourceSetImpl;
import org.xtext.example.dsl.spring.SpringStandaloneSetup;
import org.xtext.example.dsl.spring.spring.Bean;
import org.xtext.example.dsl.spring.spring.Property;
import org.xtext.example.dsl.spring.spring.SpringModel;

public class ReadSpringModelTest {

 static {
  SpringStandaloneSetup.doSetup();
 }

 /**
  * @param args
  */
 public static void main(String[] args) {
  // integration with generated language within loadModelResource
  Resource resource = loadModelResource("src/model/MyModel.spring");

  // extract the SpringModel from the resource - in our case there will be only one
  SpringModel model = (SpringModel) resource.getContents().get(0);

  // example usage - walk the model, printing the values
  for (Bean bean : model.getBeans()) {
   System.out.println("\n\nBean: " + bean.getName());
   for (Property property : bean.getProperties()) {
    System.out.println("\t" + property.getName() + ": "
      + toValueString(property));
   }
  }
 }

 /*
  * this method, and the static initialiser call to
  * SpringStandaloneSetup.doSetup() are all that are needed to load a model
  * file
  */
 private static Resource loadModelResource(String modelFile) {
  ResourceSet resourceSet = new ResourceSetImpl();
  URI uri = URI.createFileURI(modelFile);
  Resource resource = resourceSet.getResource(uri, true);
  return resource;
 }

 private static String toValueString(Property property) {
  Bean referencedBean = property.getRef();
  if (referencedBean != null) {
   return " => " + referencedBean.getName();
  }
  String value = property.getValue();
  if (value == null) {
   return "«null»";
  }
  return "\"" + value + "\"";
 }

}

Right-click on the new class and Run As->Java Application. You should see the System.out.println calls output into the console:

Previous Next

Xtext Spring Demo - Part 1

2009-08-06T17:40:00.001-07:00

Create a new language to define Spring Beans

Let's start by downloading and installing Xtext.

Xtext is a set of plugins for Eclipse and can be obtained here in a variety of formats.

I recommend downloading the full distribution, because it includes links to the update site, and the integrated ANTLR parser bindings. This can be found here

Once installed - start the Xtext Eclipse installation in a new workspace - and we can start creating our new parser.

For this demonstration, I chose to create an alternative to the Spring XML bean definition language.

This isn't because I think the end result is particularly useful - but it does offer a great test case for a simple language and a variety of integration scenarios.

The demonstration stops some way short of being a fully-fledged replacement for Spring XML - it lacks support for most of Spring's features.

It does hint at how to go this far, though - it would be interesting to see how little code is required to replace Spring's XML bean definition loader :)

Create a new Xtext project

Create a new Xtext project by selecting the File menu, then New->Project... and choose "Xtext Project":

Give the project a name - use these examples:


Main project name: org.xtext.example.dsl.spring
Language name: org.xtext.example.dsl.spring.Spring
DSL-File extension: spring
Create generator project: yes

A set of projects are created - find the Spring.xtext file as shown and open it:

As you see - a new Xtext project starts with an example language - an entity description language.
(The Xtext language description language is actually very closely related to EBNF.)

The example is no use to us now, so let's replace that text with our Spring Bean definition language definition.

Leave the grammar and generate statements as they are, but replace the rest with:


SpringModel:
 (beans+=Bean)*;

Bean:
 'bean' name=ID type=STRING
   (properties+=Property)* ';';

Property:
 name=ID '=' (ref=[Bean]|value=STRING);

Now - we generate the Java implementation code for our language - run the GenerateSpring.mwe file - right-click on it and Run As->MWE Workflow:

The generator should run and you should see some successful looking output in the console:

Great! Let's test our new language :):

We don't need to write any Java to start with - we can test our parser with the free IDE editor generated in the last step.

Normally one would export the generated plugins and restart a copy of eclipse with these plugins loaded, but to quickly test our language - we can just launch a test instance of eclipse to do that:

Import the "generator" project (org.xtext.example.dsl.spring.generator if you used the example names) into the test workspace, and open src/model/MyModel.spring.

As before - this file is pre-populated with an example model (a valid example of the original Entity language we blew away, but invalid for our new language).

Therefore - the editor quite correctly highlights an error:

So - paste this valid Spring bean model into the file - replacing all the current text:


/*
 * This is an example model
 */
bean myObject "org.xtext.example.dsl.spring.generator.test.MyType"
 intAttribute = "5"
 stringAttribute = "xtext is easy..."
 otherAttribute = otherObject;

bean otherObject "org.xtext.example.dsl.spring.generator.test.OtherType"
 someOtherAttribute = "...when you know how";

You should see the syntax highlighting in effect immediately, and notice that Java-like comments are supported:

Content assist proposals are given on Ctrl-Space - for syntax and for references and property values.
These can be customised.
Later we will see how to add Java class names proposals to the Bean "type" property...

Hit Ctrl+Shift+F.

Okay - sorry! It puts all the text on to one unreadable line.

That part isn't free - to get pretty printing we have to do a little Java coding.

We'll get to that later so hit Ctrl-Z for now and we'll write a test harness to demonstrate how you'd integrate the generated parser into your code.

Previous Next

Why Not XML?

2009-08-06T17:37:00.000-07:00

What's wrong with XML?

...and why is it so popular?

Is it popular? It's certainly not in short supply. It does seem like you can't open any Java project without encountering XML files, and regardless of how cutting-edge the technology used there - it always seems to bring on some new XML file format.

It does seem popular with framework providers.

But it doesn't seem popular with application builders using the frameworks - if you listen to the rhetoric. Until they have to write a custom config file or interchange file, of course. Then it seems like just the thing. If you listen to the users who have to read and write these config files, though...

In short - XML is a free (crap) parser and serializer/formatter. Which is slightly better for a programmer than no free parser/formatter at all. Programmatic access to XML is very well supported these days and a new config file format can often be supported in minutes by an experienced SAX/DOM/JAXB/whatever programmer.

Which is all bad for the end user because whenever a new file format is needed XML is automatically chosen as the base format.

But writing custom languages without XML is hard, right? I mean - there's ANTLR, but that's complex to learn and hard to get tool support for. Writing a new language in raw antlr is not a task to be done in minutes by a SAX/DOM/JAXB programmer.

See this article for easy to use alternatives.

Xtext Spring Demo

2009-08-06T17:34:00.000-07:00

Xtext Spring Demo

A powerful alternative to XML

XML is, of course, very familiar to programmers. It's used everywhere to configure and pass data between programs.

In my opinion - it's often not the best choice. See this article on why not.

But - if you want to skip that - basically I think it's because it's hard on the users of the XML languages (the readers and writers of XML files to whatever schema).

Why is it used so often if it's to hard to read and write?

I think it's mostly because XML gives you a lot of free parsing and formatting support.

Think of the effort required to create an XML parser that creates or configures your application objects.

You'd take an off-the-shelf package to help with most of the work - a SAX, DOM, or Object (JAXB) parser can be used to quickly integrate a new XML format into your application.

That's great on one hand - the programming job is done quickly and reliably. But the end users suffer.

They'd be much happier with a less verbose (less angle-bracket-y) language, with syntax and grammar tailored to their domain.

Traditionally this has been hard. There are well known tools to help create languages (ANTLR for example) - but they're not easy or quick to use.

Well - actually - writing custom languages is easy.

We've sort of been doing it for years.

Well read software engineers will be used to reading descriptions of languages written in BNF or EBNF

Some clever folk at itemis and openArchitectureWare have recently contributed their (already open source) project Xtext (as well as others) to the eclipse.org community.
They recently became a part of the Galileo release for eclipse modeling.

With a few tweaks, EBNF itself can be used as a general purpose language to define new textual languages.
Given just a little extra information, an EBNF-like language can be used as input to a generator that creates a parser, a formatter, a Java model to parse and format, as well as
a sophisticated Eclipse based editor with JDT-like features such as syntax highlighting, code completion and hyperlinking.

This article will demonstrate how Xtext can make the job of creating a parser for any arbitrary language as easy (if not easier than) XML.

It will also show how to go a lot further - for little or no extra effort.

The demo is broken down into parts:

Spring Demo - Part 1 - Create a new language to define Spring Beans : Shows how to create a simple Xtext language and sample model file

Spring Demo - Part 2 - Test our new language - standalone : Load the sample model file and read it from standalone Java

Spring Demo - Part 3 - Read a Spring model to load a BeanFactory : Integration with Spring - loading a BeanFactory from the model file

Spring Demo - Part 4 - Export Spring XML from model : Transformation of the model into standard Spring bean definition XML

Spring Demo - Part 5 - Serialisation of model to text form : Takes a programatically created model and exports it to the new Xtext Spring language

All code and these documents can be downloaded from SVN