Introduction

Creating your own domain-specific textual languages in Xtext is really easy, and the authors in Northern Germany are doing a good job to make it even easier. Once you have a language, you want to process it and this means usually to transform your model into another representation. The facility responsible for this transformation is called generator and consists of a bunch of transformation templates (e.G. XPand) and some code executing them. On some event, the model is read in and the transformations are applied to produce code. Currently, there are two ways of triggering the transformation: you can put the calling infrastructure in a Modeling Workflow Engine file, which is a kind of batch script or you can write a build-participant, which react on the changes in the model. In this article I want to describe my experiences with the builder approach.

Examining initial builder

The base idea behind the builder approach is the fact, that Xtext provides an project builder, which watches for all Xtext resource changes (Xtext-based DSL models) and notifies the so-called XtextBuilderParticipants. These are registered using Eclipse extension point org.eclipse.xtext.builder.participant and implement the IXtextBuilderParticipant interface:

...
public interface IXtextBuilderParticipant {
    void build(IBuildContext context, IProgressMonitor monitor) throws CoreException;
}

public interface IBuildContext {
    IProject getBuiltProject();
    List<IResourceDescription.Delta> getDeltas();
    ResourceSet getResourceSet();
    void needRebuild();
}

In order not to start completely from scratch, let us examine the builder provided in the Domain-Model-Example, delivered with Xtext. In the build method the example builder processes as follows:

• checks that the project is a Java project
• finds the generation folder
• creates an Output
• creates an Outlet and registers it in the Output
• registers a post-processor managing Java imports on the outlet
• creates the Xpand execution context
• registers the Java Beans version of the metamodel
• processes the changes and analyses if the files have to be deleted or not prior re-generation
• for all changed model elements re-generates

Quite a lot of tasks, so there is a good reason, why MWE scripts are used for generation.

Using Project natures

The first improvement I created for the builder is the ability to distinguish DSLs. The problem of triggering all XtextBuildParticipants on the change of any Xtext-based resource is that the entire Workspace gets re-generated. In my scenario, we used three DSLs and a random change caused three builders to run, even if the change has been made in another project of workspace. In order to solve this problem I used the standard Eclipse way to distinguish projects: Project Natures.

The nature I created is used as a marker for the builder and is emtpy:

public class UiNature implements IProjectNature {
	public static final String NATURE_ID = "de.techjava.dsl.uiNature";
	private IProject project;

	public void configure() throws CoreException {
        }

	public void deconfigure() throws CoreException {
	}
	public IProject getProject() {
		return project;
	}
	public void setProject(IProject project) {
		this.project = project;
	}
}

Don’t forget to register it in the plugin.xml:

   <extension point="org.eclipse.core.resources.natures"
         id="de.techjava.dsl.uiNature"
         name="User Interface DSL Project Nature">
      <runtime>
         <run class="de.techjava.dsl.userinterface.builder.UiNature" />
      </runtime>
   </extension>

As the first line in my builder I check the presence of the nature in the current project and stop building if the nature is not present:

if (!context.getBuiltProject().hasNature(UiNature.NATURE_ID)) {
	// skip projects without UI DSL nature
	return;
}

Now, what is missing is the ability to add and remove the nature to/from the project. I liked the way how Xpand/Xtend Natures are configured (using toggle action in configure menu of the project pop-up menu). What you need is a ToggleAction that can be switched on, if the nature is not present and switched off, if the nature is installed.

public class ToggleNatureAction implements IObjectActionDelegate {
	private ISelection selection;
	@SuppressWarnings("unchecked")
	public void run(IAction action) {
		if (selection instanceof IStructuredSelection) {
			for (Iterator it = ((IStructuredSelection) selection).iterator(); it.hasNext();) {
				Object element = it.next();
				IProject project = null;
				if (element instanceof IProject) {
					project = (IProject) element;
				} else if (element instanceof IAdaptable) {
					project = (IProject) ((IAdaptable) element).getAdapter(IProject.class);
				}
				if (project != null) {
					toggleNature(project);
				}
			}
		}
	}

	public void selectionChanged(IAction action, ISelection selection) {
		this.selection = selection;
	}

	public void setActivePart(IAction action, IWorkbenchPart targetPart) {
	}

	/**
	 * Toggles sample nature on a project
	 * @param project to have sample nature added or removed
	 */
	private void toggleNature(IProject project) {
	// implemetation of toggle nature ...
	}
}

In order to make an action to a toggle-action the Eclipse Command Framework, Object Contributions and the Command Core Expressions are needed. The idea is to register two actions as object contributions on the IProject using the org.eclipse.ui.popupMenus extension point and define visibility of those to be complement to each other (if one is visible the other is not) based on the object state, which is the presence of a project nature. The actions used point to the same implementation class but have different labels. The menu path to pop-up menu Project > Configure is org.eclipse.ui.projectConfigure/additions. The visibility is defined based on the objectState:

  <extension point="org.eclipse.ui.popupMenus">
      <objectContribution adaptable="true"
            id="de.techjava.dsl.userinterface.ui.addNature"
            objectClass="org.eclipse.core.resources.IProject">
         <action
               class="de.techjava.dsl.userinterface.ui.action.ToggleNatureAction"
               id="de.techjava.dsl.userinterface.ui.AddNatureAction"
               label="Add User Interface DSL Nature"
               menubarPath="org.eclipse.ui.projectConfigure/additions">
         </action>
         <visibility>
            <not><objectState name="nature" value="de.techjava.dsl.uiNature" /></not>
         </visibility>
      </objectContribution>
      <objectContribution adaptable="true"
            id="de.techjava.dsl.userinterface.ui.removeNature"
            objectClass="org.eclipse.core.resources.IProject">
         <action
               class="de.techjava.dsl.userinterface.ui.action.ToggleNatureAction"
               id="de.techjava.dsl.userinterface.ui.AddNatureAction"
               label="Remove User Interface DSL Nature"
               menubarPath="org.eclipse.ui.projectConfigure/additions">
         </action>
         <visibility>
            <objectState name="nature" value="de.techjava.dsl.uiNature" />
         </visibility>
      </objectContribution>
   </extension>

Please note, that the nature is implemented and registered inside of the generator project and the toggle action is implemented in the UI project. Finally, the code of the toggleNature method, which is the standard code for the project nature installation and removal:

...
	IProjectDescription description = project.getDescription();
	String[] natures = description.getNatureIds();

	// remove the nature
	for (int i = 0; i < natures.length; ++i) {
		// if nature exists
		if (NATURE_ID.equals(natures[i])) {
			// Remove the nature
			String[] newNatures = new String[natures.length - 1];
			System.arraycopy(natures, 0, newNatures, 0, i);
			System.arraycopy(natures, i + 1, newNatures, i, natures.length - i - 1);
			description.setNatureIds(newNatures);
			project.setDescription(description, null);
			return;
		}
	}

	// Add the nature
	String[] newNatures = new String[natures.length + 1];
	System.arraycopy(natures, 0, newNatures, 0, natures.length);
	newNatures[natures.length] = NATURE_ID;
	description.setNatureIds(newNatures);
	project.setDescription(description, null);
...

That’s it, run and right-click on the Project and then go to the Configure Menu (pretty low in the pop-up) and you will see the result:

Parameterizing generator

Domain-specific languages should cover only the real requirements and incorporate the specific decision made in the project. So far the theory, but in fact it is a trade-off and a compromise, what is a part of the language and what is too specific to be covered. The same holds for the generator: on the one hand you want the generator to solve exactly your problem, on the other hand you want to make it generic enough to cover a class of similar problems.

I faced the problem of using the generator for two teams in a big project, where the langage could be reused, but the generation infrastructure need to be slightly modified. For example, the information about the generation target folder, package prefix and the fact which artifact should be generated differred between the teams. In the same time the teams were able to agree on the same language. In order not to develop two generators, I decided to parameterize the generator and the templates.

The Xpand2/Xtend developers provided a way of parameterization of the templates using the so-called Global Variables, using the GLOBALVAR keyword. My favorite way of using it is to create a cached extension for reading the variable:

/*
 * Retrieves the boolean value of the global variable set from outside of the template
 */
cached Boolean generateService() :
    GLOBALVAR generateService == "true"
;

In order to set global variables from the build participant the XPand execution context constructor takes a Map<String, Variable> argument. The nice story about the global variables, that you can provide any objects as values. So the advantage over the usage of MWE workflow with property files read-in during processing is the big flexibility in providing the object-graphs or even statefull objects as global variable values. A good example of usage of global variable is provided in Domain-Example with Java Import Tool:

JavaImportsTool importsTool = new JavaImportsTool();
...
ctx = new XpandExecutionContextImpl(output, null,
    Collections.singletonMap(JavaImportsTool.VAR_NAME,
    new Variable(JavaImportsTool.VAR_NAME,importsTool)),
    null, null);
...

In the same time it is important to be able to load simple properties from file in the generation project. For example you could implement your own ModelProperties container, which reads properties from the file located in the generation project. For example:

public class ModelProperties extends Properties {
	/**
	 * Indicates that no timestamp is available
	 */
	private static final long NO_TIMESTAMP = -1;

	private long lastModified = NO_TIMESTAMP;
	private final IFile propertyFile;
	private final HashMap<String, Variable> globalVars;

	/**
	 * Creates a valid model properties instance
	 *
	 * @param aProject reference to the current project
	 * @param name of the property file
	 * @throws CoreException on errors
	 */
	public ModelProperties(final IProject aProject, String filename) throws CoreException {
		if (aProject == null) {
			ErrorHelper.throwCoreException("project must be not null");
		}
		if (filename == null) {
			ErrorHelper.throwCoreException("filename must be not null");
		}
		this.globalVars = new HashMap<String, Variable>();
		this.propertyFile = (IFile) aProject.findMember(filename);
	}

	public IFile getPropertyFile() {
		return propertyFile;
	}

	/**
	 * Returns the global variables.
	 * @return global variables.
	 */
	public Map<String, Variable> getGlobalVars() {
		updateProperties();
		return globalVars;
	}

	@Override
	public String getProperty(String key) {
		updateProperties();
		return super.getProperty(key);
	}

	/**
	 * Updates the properties and the global variables if the property file has
	 * been modified.
	 */
	public void updateProperties() {
		if (this.propertyFile != null && lastModified != this.propertyFile.getModificationStamp()) {
			loadProperties();
			globalVars.clear();
			for (Map.Entry<Object, Object> entry : entrySet()) {
				final String propertyName = (String) entry.getKey();
				globalVars.put(propertyName, new Variable(propertyName, entry.getValue()));
			}
		}
	}

	/**
	 * Loads the properties from the model file
	 */
	private void loadProperties() {

		try {
			if (propertyFile != null && propertyFile.exists()) {
				super.load(propertyFile.getContents());
				this.lastModified = propertyFile.getModificationStamp();
				handleSpecialProperties();
			}
		} catch (CoreException e) {
			// no model property file isn't a problem but clear the properties:
			super.clear();
			this.lastModified = NO_TIMESTAMP;
		} catch (IOException e) {
			super.clear();
			this.lastModified = NO_TIMESTAMP;
		}
	}

	protected void handleSpecialProperties() {

	}
}

Using this class you can simple initialize the XPandExecutionContext with properties read from the file system. So in build-Method of your Generator put something like:

         ModelProperties structureProperties = new ModelProperties(context.getBuiltProject(), "structure.properties");
         XpandExecutionContextImpl ctx = new XpandExecutionContextImpl(output, null, structureProperties null, null);

Now you can resolve the values from the property files directly from the Templates and Extensions using the built-in GLOBAL VAR feature.

Galileo, or the JDT (Java Development Tools) to be more precisely, does not surprise with a load of stunning new features, instead, its a solid continuation of improvements. Concerning the JDT part, it has lost its pace of former days. But Eclipse JDT still is the reliable friend at your side, helping you code. This is a good thing, since Eclipse has been the IDE of choice for many, many Java programmers for a lot of years now and has grown to something like a “standard”. Its usability and reliability are well known and especially the first part has been constantly improved.

Galileo now draws its innovative power from the huge amount of different projects which were developed for it. The amount of tools for modeling is impressive. However it is not surprising, since modeling has become a sport in the past month. Consequently, it is bare logic to improve the tooling capabilities and quality. Galileo is following this path, not only because of Eclipse, but with what is available for it.

Code is poetry!

[wscompile] wscompile ...\env\java\1.4.2_03\jre\bin\classpath-classpath D:\workspaces\general\lib\bla.bo-0.0.1.jar; ... D:\workspaces\general\lib\... jar.0.5.5

In this line, the classpath of wscompile is printed.

The build script uses configured Apache Ant in version 1.6.5. I tried to start it with Java in versions 1.4.2 und 1.6.0.10. Both works in Europa (Eclipse 3.3.x) but don’t work in Ganymede (Eclipse 3.4.x), except for the first run. It seems that Ganymede provides a different handling for Ant scripts. Every first start of an Ant build script produces new “External Tool Configuration” (if not already there). If this configuration already exists, wscompile task doesn’t work!

This means my build script with wscompile task works only once, every first time after deleting the “External Tool Configuration”. I could live with that if I wouldn’t need that configuration. But I need that configuration to use different java version that is the workspace default.

Do anyone know how to fix that?
Here is my task definiton.

<taskdef name="wscompile"
		classname="com.sun.xml.rpc.tools.ant.Wscompile"
		classpathref="class.path.jwsdp"
		/>

and also task usage in the script

<wscompile fork="true" import="true" base="java/class" sourceBase="java/generated" verbose="true" features="documentliteral, wsi, searchschema, serializeinterfaces, explicitcontext" mapping="java/generated/META-INF/jaxrpc-mapping.xml" config="metadata/wsdl-config.xml" xSerializable="true">
	<classpath>
		<path refid="class.path.local" />
		<path refid="class.path.ant" />
		<pathelement path="${java.class.path}" />
	</classpath>
</wscompile>

Comments are welcome.

This session will be interactive / openspace like. He will walk through the new EJB 3.1 APIs and explain some interesting stuff as well. It is the logical conduction of the first JUG HH session in May 2008.

Location: Lehmanns Fachbuchhandlung (Hamburg Hauptbahnhof), Kurze Mühren 6, 20095 Hamburg

Date and Time: 16.09.2008, 20:00
Topic: Productive Java EE 6 – Rethinking Best Practices And Bashing On Patterns, Cluster One

Abstract: Java EE 6 is great, but many questions like:

• Are DAOs dead?
• Do JSF really suck?
• Are anemic JPA-entities a best practice?
• Are XML deployment descriptors legacy?
• Are EJBs lightweight?
• How to test EJBs?
• Is layering an antipattern?
• Do we need factories?
• How to integrate with RESTFul services?
• Is it possible to deploy EJBs into a …WAR?
• Are “plain old web containers” dead?
• Services or Objects – what is the way to go?

still remain open. These and many other questions will be discussed interactively with …code.

Speaker: Adam Bien

About the speaker: Java Champion Adam Bien is a self-employed consultant, lecturer, software architect, developer, and author in the enterprise Java sector in Germany who implements Java technology on a large scale. He is also the author of several books and articles on Java and J2EE technology, as well as distributed Java programming. His books include J2EE Patterns, J2EE HotSpots, Java EE 5 Architectures, Enterprise Architectures, Enterprise Java Frameworks, SOA Expert Knowledge, and Struts, all published in German.

As BEA technical director, Bien is also a member of the NetBeans Dream Team; an Expert Group member of the Java Community Process for EJB 3.1, JPA 2.0, and Java EE 6; and involved in embedded Java, Grid, and P2P technology. He currently works as an architect and developer in several J2EE-Java EE Model-Driven Architecture (MDA) and EAI component architecture projects for the Java EE platform and .NET.

Maven 2 is often compared with Apache Ant. Sometimes it is seen as an extension to Ant. This is wrong. So, what’s the difference? Ant is a build tool, meaning you can build your projects with it. Maven is a “project management and comprehension tool”. Project management is actually focussing the technical part, is does not include Gantt diagrams or things like that. What is does include is a description of the technical part of your project, including a source repository, dependencies, documentation, developers and so on. What is the advantage of this?

• Project setup is easier now. No searching for required libs, setting build paths, dealing with other weird stuff
• Project comprehension is easier. The information about the project, the Project Object Model (POM) is human readable. That’s for a reason. Especially in larger projects this seems to be useful to me.
• Changes in projects are tracked easier. Someone includes a new library? All the colleagues’ builds are broken. You have to communicate somehow to your team mates that they have to use that lib. With maven, just check in the new pom file, which includes the new dependency. All your colleagues will get it automatically from the repository you have in your company (hopefully).
• Release management and integration in CI systems comes out-of-the-box. You have all you need to do that. Simply.

Granted, you can do a lot of those with Ant if you are good at it. But with Maven 2 it is a lot easier. As Maven 2 brings a standard project layout, projects not only look similar in their structure every time but they can build in support for a lot of things this way. The pom files are very short compared to Ant build scripts doing the same and more readable. Granted again, you can make your own Ant script containing standard targets you use in every project. You split your Ant files in project specific and general parts. Your project specific part is very short then. Then you did just what the creators of Maven did. Congratulations, you are a smart guy.

I am not saying that all your problems are solved by using it. Maven 2 has some weaknesses as far as I can tell from my limited experience with it. I heard from a participant that the automatic dependency resolving does not work all the time. Normally, Maven would resolve all transitive dependencies from all libs. If lib A is dependent on lib B and you include A in your project, the description of A includes the dependency. Maven will include B, too. I don’t know if that is a failure of maven or the guy who told me about it. AFAIK it needs time to get into it, I often encountered behaviour I didn’t expect. But that was because of my lack of understanding of Maven 2, not because of Maven 2 itself. So, the disadvantage is the same as with every new tool. You need time to learn doing stuff with it, and unfortunately you need to fail sometimes to learn from your mistakes.

BTW, Maven 2 is open source. Everyone who misses something or wants something to get better is welcomed to get into the dev team of Maven 2. One of  those points would be the beloved documentation which has great potential for improvement.

Hope this helps integrating Maven 2 into your understanding of the software development world.

The evening started with an interesting preview of Xtext 2.0 by Sven Efftinge (also itemis). Xtext 2.0 is rewritten from scratch and provides better performance than its predecessor. The current plan for release is about October 2008. The talk was followed by a presentation given by Matthias Lübken (akquinet it-agile) who demostrated how to use the google web toolkit (GWT) in conjunction with serverside Equinox framework. Matthias talked about some of the tweaks which are necessary in order to get the two working together and also showed a little live demo. He was followed by Stefan Reichert of Lufthansa Systems who introduced his ‘wicked shell’ for Eclipse. This handy tool started as tech-demo how to bind an external process to a SWT widget. Finally, it turned into a command line, shell, bash… integration for Eclipse – featuring code completion and history. Reginald Stadlbauer (CEO froglogic) showed how to automize GUI testing of GWT and other Java based GUIs using froglogics Squish. Squish offers scripting languages like Perl, Python or JavaScript to the user to automatize application gui testing. The tool, not an Eclipse application itself, is currently rewritten and will feature full Eclipse integration sometime soon. Finally, Frank Zimmermann (Prof. at the Nordakademie) and two of his students Stefan Tanck and Henning Banneitz showed how model-driven software development (MDSD) using oAWs XText can be used to generate adapters for SAP SI in order to transform EDIFACT messages to XML and back. Unfortunately, a talk about Spring dynamic modules with OSGi was not held, the presenter Gerd Wütherich (independant consulting) was ill.

Apart from the interesting talks, it was nice to see many familiar faces, which attended the Eclipse Demo Camp in Hamburg at the end of 2007. The Eclipse Demo Camp seems to build a community. Thanks to the organizers for enabling this great event.

The http://www.techjava.de/ will be filled with information soon.