Mod4j Developer Guide

This Developer Guide helps developers of the Mod4j project to get started with coding and modeling. If you are an user of Mod4j you should follow the Getting Started from the user docs. See menu > User Docs > Getting Started.

Getting started

  1. Make sure you've installed Java JDK version 5 or 6. You can download one from the Sun download site .

  2. Install Eclipse Helios SR2 for Java EE developers . You can download one from the Eclipse download site . If you've already installed Eclipse, you can check if it is the right version, by checking the About box from the menu: Help -> About Eclipse. You should see "Eclipse Java EE IDE for Web Developers. Version: Helios Service Release 2."

  3. Install, using the Update Manager in Eclipse, at least the following plug-ins into Eclipse:
    Eclise plug-in Features to select when installing Update site
    Eclipse Xtext and Xpand plug-ins - TMF XTEXT SDK (Incubation) 0.7.2
    - M2T XPAND SDK (Incubation) 0.7.2
    - MWE SDK (Incubation) 0.7.2    		 http://download.eclipse.org/releases/galileo
    Eclipse Xtext Antlr plug-ins - Xtext Antlr Support 0.7.2 http://download.itemis.com/updates/releases
    Eclipse Maven plug-in: m2eclipse - Maven Integration for Eclipse 0.12.1 or higher http://m2eclipse.sonatype.org/sites/m2e
    Ecore Tools. (For graphical modeling of our meta-models) Choose Modeling and then Ecore Tools SDK Helios - http://download.eclipse.org/releases/helios
    Subclipse, plug-in for integration with Subversion Select all features http://subclipse.tigris.org/update_1.6.x

  4. Make sure the text file encoding in Eclipse is set to 'UTF-8'. You can verify and set this in the field 'Text file encoding' by navigating to 'Window -> Preferences... -> General -> Workspace'. For Linux users UTF-8 is usually the platform encoding, and no change will be necessary.

  5. Set XML editor preferences. Navigate to 'Window -> Preferences -> XML -> XML Files -> XML Editor' and
    • Set Line width: to 128
    • Enable Indent using spaces, with a Indentation size of 4

  6. Import our Eclipse code formatter for Java. You can download and save the configuration file smartjava_eclipse_formatter.xml here .
    In Eclipse navigate to Window -> Preferences -> Java -> Code Style -> Formatter and choose Import . Select the file smartjava_eclipse_formatter.xml .

  7. Install Apache Maven 2.1.0 or higher. For download and install instructions see the Apache Maven site

Checking out, import into Eclipse, generating the DSL-editors

While the metamodel and its associated syntax is still under development, you should be prepared to generate the model editors yourself from the metamodel and the syntax definitions, before you can start modeling:

Hybrids
Important to know is, that the Mod4j modules that you are going to checkout from the repository, do have a hybrid nature. Some of the modules are Eclipse plug-ins and some are Maven modules. But the most modules are both: Eclipse plug-in and configured as a Maven module (yes, you can recognize them by the pom.xml file).
This last category, the hybrids, must be treated with extra care. It mainly implies that you as a developer must know that dependencies must be manually managed in two places within the module. In the manifest (Eclipse plug-in) and in the pom.xml file (Maven) of the module. Also, in an equal manner, the versions of the module must be maintained manually twice.
At the moment we do not have a suitable solution for automating this process, maybe in the future we will extend our mod4j-maven-plugin with this functionality or see if the maven-eclipse-plugin can help us out.

  1. Check out the source code of the mod4j project from the Subversion URL https://svn.codehaus.org/mod4j/trunk into a directory on your file system. See the link Project information for information on how to do this.
  2. Choose Import > Existing Project into Workspace and Browse to the ../modules/Crossx folder. After choosing Ok and Finish the following modules are imported in your workspace:
    org.mod4j.crossx.mm
    org.mod4j.crossx.broker
  3. Even so do this with:
    modules/org.mod4j.common and
    modules/org.mod4j.updatesite and
    modules/Eclipse/org.mod4j.eclipse
  4. Choose Import > Existing Project into Workspace and Browse to the ../modules/BusinessDomainDsl folder. After choosing Ok and Finish the following modules are imported in your workspace:
    org.mod4j.dsl.businessdomain.generator
    org.mod4j.dsl.businessdomain.mm
    org.mod4j.dsl.businessdomain.validation
    org.mod4j.dsl.businessdomain.xtext
    org.mod4j.dsl.businessdomain.xtext.ui
  5. If you need to (re)generate the modelcode from a meta model, for instance the BusinessDomani meta model: Open org.mod4j.dsl.businessdomain.mm/model/BusinessDomainDsl.genmodel in the EMF Generator editor.
  6. Right-click on BusinessDomainDsl in the editor pane, and choose Generate Model Code
    Normally you wouldn't need to add generated sources to the version control system (Subverson), but due to not being able for us to perform this step outside Eclipse we've decided -for now- to add the generated code (src-gen folder) to Subversion. So the continuous integration build can build it and other modules can depend on it.
  7. You need to generate the code for Xtext and Xtext.ui projects: Right-click the file org.mod4j.dsl.businessdomain.xtext/src/org.mod4j.dsl.businessdomain.xtext/GenerateBusinessdomain.mwe, and choose
    Run As -> MWE Workflow from the context-menu.
  8. Repeat the previous steps you took for importing the BusinessDomainDsl projects for:
    ../modules/DataContractDsl and
    ../modules/ServiceDsl
  9. Now import as Maven Project :
    Choose Import > Maven2 Project > Next and Browse to the modules/org.mod4j.runtime.common folder. Then choose Ok and Finish .
    Do the same with:
    modules/org.mod4j.mavenplugin

Now you have imported and generated the necessary modules. The DSL editors are ready to use. There for you need to activate the newly created editor in a second Eclipse instance. See next section "Modeling".

Modeling

  1. Be sure you start a second Eclipse instance with the right memory settings. Add the following arguments in the Arguments tab, see Run > Run Configurations...
    Add to Vm arguments: -Xms512m -Xmx512m -XX:PermSize=512m -XX:MaxPermSize=512m
    Add to Program Arguments: -Dcom.sun.management.jmxremote
  2. To start the second Eclipse instance: Right-click the module org.mod4j.dsl.businessdomain.xtext.ui and choose Run As -> Eclipse Application from the context menu.
  3. Choose Import > Existing Project into Workspace and Browse to the ../modules/Examples/RecordShop-ExampleProject/RecordShop-dslModels folder. After choosing Ok and Finish the following modules are imported in your workspace:
    RecordShop-dslModels
  4. Now import as Maven Project :
    Choose Import > Maven2 Project > Next and Browse to the ../modules/Examples/RecordShop-ExampleProject folder. Then choose Ok
    Uncheck the RecordShop-dslModels module (you already imported this one in the previous step) and klick Finish .
    After choosing Ok and Finish the following modules are imported in your workspace:
    RecordShop-domain
    RecordShop-data
    RecordShop-business
    RecordShop-service
  5. In the previous step the IAM Maven plug-in not always recognizes the source folders correctly. Adjust the source folders manually if you encounter compilation failures. Right-click on the project to adjust the "Build Path" configuration. Add src/main/java, src/test/java, src/main/resources, generated-sources and generated-resources to it.
  6. In the new Eclipse session you should be able to edit the .busmod, .sermod and .dtcmod model files in the RecordShop-dslModels project.
    Open the file RecordShop-dslModels/src/model/businessDomain/businessDomain/model.busmod change this file as needed and save the file.
  7. The previous step generated two new modules into the RecordShop-ExampleProject folder. See: ../RecordShop-ExampleProject/RecordShop-domain and ../RecordShop-ExampleProject/RecordShop-data
    The modules are generated as a mulitmodule Maven project. To test and install the maven modules:
    Open a command console and navigate to location of the parent-POM (../RecordShop-ExampleProject/pom.xml)
    Give the command: mvn clean install

First day procedure for Mod4j developers

As a new developer of Mod4j you will need to follow the next steps

  1. Subscribe yourself to the developer mailinglist (dev@mod4j.codehaus.org) and post a short message to introduce your self to the other developers. So all developers know who you are and that there is a new developer active.
  2. Add yourself as notifier to the notifiers list of the ciManagement section in the parent-pom. So you will be notified by Continuum of build status changes.
  3. Make sure you're familiar with the different Maven profiles in the parent-pom. Its important to know which modules are effected when you're building with Maven.