This page outlines language module development process. Steps overview:

1. Create domain model.
2. Generate model code. Optionally generate edit and editor code.
3. Add logic to the model to load data from sources.
4. Implement and register PackageProvider service.
5. Optionally implement and register ImageProvider service in the edit module.
6. Create render templates or renderers for model classes.
7. Create a manifest file with classpath entries for dependency libraries.
8. Create a build file and package the solution for distribution.

1. Download Eclipse for modeling from Eclipse download site and install it.
2. Create an empty EMF project.
3. Create an Ecore model and Ecore diagram associated with the model.
4. Load Hammurapi review model resource.
5. Model your domain. Have your domain classes extend LanguageElement interface from the Hammurapi review model. For example, if you create a model of JDBC metadata, you'd have Database root object which would contain (containment reference) Catalog class. Catalog in turn would contain Schema, etc.

1. Create EMF generator model from your model. Add references to Hammurapi, Config, and Party generator models.
2. Adjust the generator model - set the base package, change other attributes if necessary.
3. Generate model code.
4. Generate edit and editor code if you are going to edit or browse your domain models in Eclipse.

Implements model logic, in particular:

1. Loading. E.g. for the JDBC metadata model the root class implementation (DatabaseImpl) shall have a constructor from Connection to load metadata.
2. Root of the model shall implement Iterable or be convertible to Iterable.
3. If the root iterable returns TreeIterator, you can add @Fork annotation to certain domain classes for review parallelism.

You can add package provider service definition to you model. Take a look at Configurator sources to see how to do it.

If you generated .edit plugin, you can add ImageProvider service to it.

Create renderers or JXP templates for domain classes. Take a look at Configurator or Hammurapi Core sources for examples.

Create a manifest file with classpath entries for dependency libraries.

Create a build file and package the solution for distribution. Generate model documentation as part of the build process.

Below is the build file for the Party product. You can use it as a starting point for your build file.

buildRuntime.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project default="build">
    <target name="build">
    	<delete dir="lib" failonerror="false"/>
    	<mkdir dir="lib"/>
 
    	<delete dir="build" failonerror="false"/>
    	<mkdir dir="build"/>
 
		<copy toDir="lib">
			<fileset dir="../TechStack/EMF/lib" includes="org.eclipse.emf.common_2.5.0.v200906151043.jar, org.eclipse.emf.ecore_2.5.0.v200906151043.jar, org.eclipse.emf.ecore.xmi_2.5.0.v200906151043.jar"/>			
		</copy>
 
    	<javac 
    		source="1.5"
    		debug="on"
    		destdir="build">
 
    		<src path="src"/>
 
    		<classpath>
    			<fileset dir="lib" includes="*.jar"/>
    		</classpath>
    	</javac>
 
    	<jar destfile="lib/com.hammurapi.party.jar" manifest="MANIFEST.MF">
    		<fileset dir="build"/>
    		<fileset dir="src" excludes="**/*.java"/>
    	</jar>
 
    	<delete dir="doc/api" failonerror="false"/>
    	<mkdir dir="doc/api"/>
 
        <javadoc 
        	access="protected" 
        	additionalparam=" -linksource" 
        	author="true" 
        	destdir="doc/api" 
        	doctitle="Party model"
        	linksource="true"
        	nodeprecated="false" 
        	nodeprecatedlist="false" 
        	noindex="false" 
        	nonavbar="false" 
        	notree="false" 
        	packagenames="com.hammurapi.party.*" 
        	source="1.5" 
        	splitindex="true" 
        	use="true" 
        	version="true">
 
       		<fileset dir="src" includes="com/**"/>
 
	       	<classpath>
        		<fileset dir="lib" includes="*.jar"/>
        	</classpath>
 
        	<link 
        		href="http://java.sun.com/javase/6/docs/api/"
            	packagelistloc="C:\Apps\Java\jdk1.6.0_07\docs\api" 
            	offline="yes"
        	/>
        </javadoc>
 
    	<taskdef name="ecoredoc" classname="com.hammurapi.render.emf.EcoreDoc">
    		<classpath>
    			<fileset dir="..\ModelDocumenter\lib" includes="*.jar"/>
    		</classpath>
    	</taskdef>
 
    	<delete>
    		<fileset dir="doc/model" includes="ewim_*.html"/>
    	</delete>
 
    	<ecoredoc diagram="model/party.ecorediag" outputdir="doc/model"/>
 
    	<property name="releaseDir" value="..\..\release\party"/>
 
    	<delete dir="${releaseDir}" failonerror="false"/>
    	<mkdir dir="${releaseDir}/doc"/>
    	<mkdir dir="${releaseDir}/lib"/>
 
    	<zip destfile="${releaseDir}\com.hammurapi.party.zip" basedir="." includes="lib/**"/>
    	<zip destfile="${releaseDir}\com.hammurapi.party-src.zip" basedir="." excludes="bak/**, build/**, bin/**, wink/**, buildRuntime.xml, MANIFEST.MF"/>
    	<copy todir="${releaseDir}/doc">
    		<fileset dir="doc"/>
    	</copy>
 
    	<copy todir="${releaseDir}/lib">
    		<fileset dir="lib"/>
    	</copy>
    </target>
</project>

If you've generated edit and editor plugins, create a feature project and update site project.

One of most interesting applications of Hammurapi is inspection of quality of source files written in programming languages such as Java. In order to do it Hammurapi needs language modules for programming languages to present source files in a form convenient for inspection. While it is possible to model language constructs directly in UML, it is a tedious task because programming languages have many such constructs (e.g. Java has almost 150).

Programming languages grammars are usually defined using Backus-Naur Form (BNF) or a notation similar to BNF ¹⁾.

To simplify creation of language modules for programming languages there is a utility called Bnf2Emf. The utility takes BNF-like grammar definition as input and produces an Ecore model from the definition.

The syntax diagram below shows Bnf2Emf grammar rules.

• grammar is a collection of rule definitions.
• ruleDefinition consists of optional rule type (only interface is used), rule name and rule body. Interface rule type results in generation of a class with isAbstract and isInterface set to true and without a superclass.
• ruleBody contains zero or more fields.
• There are two types of fields:
  • Sub-rule. Sub-rules become sub-classes of rule class.
  • Attribute definition, which consists of:
    • Attribute type:
      • attribute is generated to class attribute if type is DataType and containment reference if type is Class.
      • list is an optional modifier. If it is present, then attribute/reference cardinality is set to 0..* instead of 0..1 otherwise.
    • Attribute name.
    • Optional attribute type. If type is omitted, then attribute name serves also as attribute type. Data types which are not defined in the grammar shall be defined in the seed model.
    • Optional opposite reference definition. Opposite shall be specified if reference between classes shall be bi-directional. The opposite class does not need to define a corresponding attribute/reference.

TypeDefinition {
	attribute Name : String;
	attribute list Fields : Field opposite reference EnclosingType;

	ClassOrInterfaceDefinition;
	EnumDefinition;
	AnnotationDefinition;
}

The rule above will result in generation of a class TypeDefinition with name attribute and a containment reference to Field class. The Field class will have a reference to TypeDefinition class named EnclosingType. ClassOrInterfaceDefinition, EnumDefinition and AnnotationDefinition will be subclasses of TypeDefinition. As no rule lists TypeDefinition as its sub-rule, TypeDefinition will extend the root language element class.

Note that the seed model shall contain definition of String data type.

ClassOrInterfaceDefinition {
	attribute list TypeParameters : TypeParameter;
	
	ClassDefinition;
	InterfaceDefinition;
}

ClassDefinition {
	reference SuperClass : ClassDefinition opposite reference list SubClasses;
	reference list ImplementedInterfaces : InterfaceDefinition opposite reference list Implementors; 
}

The rule above shows reference definition.

interface Statement {
	CompoundStatement;
	VariableDefinition;
	Expression;
	ClassDefinition;
	LabeledStatement;
	If;
	For;
	While;
	Do;
	LabelReference;
	Return;
	Switch;
	TryBlock;
	Throw;
	SynchronizedStatement;
	Assert;
	EmptyStatement;
}

The rule above shows definition of interface Statement. Statement rule doesn't define any attributes or references, just lists rule classes which implement Statement interface.

One of inputs to Bnf2Emf utility is a seed model. The seed model shall contain data types referenced from rules, the root language element class (which should extend LanguageElement interface from the Review model), and may contain other definitions. Bnf2Emf utility generates model classes, attributes and reference incrementally, i.e. it does not overwrite classes and structural features already defined in the model.

Bnf2Emf utility is available here:

• Binary distribution.
• Sources.
• JavaDoc.

Download the binary distribution and execute

java -jar com.hammurapi.bnf2emf.jar <bnf file> <root language element class name> <seed model> <output file>

in the lib folder. Arguments:

1. Bnf file - the grammar file.
2. Root language element class name - classes for rules without super-rules will extend this class. The class shall be present in the seed model.
3. Seed model.
4. Output file.