Setting up your environment

1. Make sure you've installed Java JDK version 5 (1.5.0_15 or higher). You can download one from the Sun download site .
   
   
2. Install Eclipse 3.5 SR1 (Galileo) for Java EE developers . You can download one from the Eclipse download site . If you've already installed Eclipse Galileo, you can check if it is the right version, by checking the About box from the menu: Help -> About Eclipse. Somewhat surprisingly you should see "Eclipse Java EE IDE for Web Developers."
   
   
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	- Xtext Antlr Support 0.7.2 - TMF XTEXT SDK (Incubation) 0.7.2 - M2T XPAND SDK (Incubation) 0.7.2	http://download.itemis.com/updates/releases
   Eclipse IAM (Integration for Apache Maven), formerly called Q4E	Select all features	http://q4e.googlecode.com/svn/trunk/updatesite-iam
   Mod4j Eclipse plug-in	Select all features	http://mod4j.org/updatesite/3.5

   
   
4. Take care of the following Workspace settings in Eclipse:
   - Set the Text file encoding in Eclipse to UTF-8 . For Linux users UTF-8 is usually the default platform encoding, and no change will be necessary.
   - Enable the option Refresh automatically . While working with the Mod4j editors a lot of the (re)sources will be generated or regenerated. To keep the compiler happy its convenient to refresh your workspace automatically.
   You can verify and set both settings by navigating to Window > Preferences... > General > Workspace .
   
   
5. Install Apache Maven 2.1.0 or higher. For download and install instructions see the Apache Maven site
   
   
6. Due to known issue MODFORJ-146 , all users should check if the path to their local Maven repository contains any spaces. If so, they should apply one of the provided workarounds as described in this issue.

Start modelling

If you've completed the installation steps above, you're ready for modeling...

You can create the following Mod4j models in your project:

BusinessDomain model
DataContract model
Service model
Presentation model -- NOT AVAILABLE YET

Before you start we want to bring our RecordShop example project to your attention. This project contains a example of each of the Mod4j models above. So if you want to learn the syntax and structure of the models, take a look at the RecordShop. The RecorodShop is an example project that we maintain during our development process. Features we implement in Mod4j are first tested in the RecordShop.
Here you can find the RecordShop sources and model files.

1. First of all you need to create a new Eclipse project for the Mod4j DSL models you are going to create.
   Choose: File, New, Other, Mod4j, Mod4j Project .
2. Enter the application name of the project. For instance: MyApplication
3. Enter the Root package. For instance: org.mycompany.myapplication
4. Uncheck the "Use default location" checkbox and choose a location where all model projects and modules for your application can be placed.
   While your project develops over time, this folder will contain the project modules you create: all generated project modules and the generated Maven parent-pom.
   We suggest (commonly used) you use the following folder structure:
   path-to-your-projects/MyApplication/modules
5. After finishing the wizard, a new project is created with the name MyApplication-dslModels and a directory structure like this:
   src/model/businessdomain/MyApplicaton.busmod (the model file containing the elements of your businessdomain model)
   src/model/datacontract/MyApplication.dtcmod (the model file containing the elements of your datacontract model)
   src/model/service/MyApplication.sermod (the model file containing the elements of your service model)
   src/model/mod4j.properties (the property file containing input parameters for code generation)
6. For modeling the business domain model of your application, open the file src/model/businessdomain/MyApplication.busmod with the BusinessDomain Model Editor .
7. Here you can add the classes, attributes, businessrules, associations etc. of your BusinessDomain model. Code-completion (ctrl + space) will help you a lot to find the right keywords and model elements to use. See the usermanual for more information about how to setup your BusinessDomain model.
8. You can setup your DataContract- and Service models in the same way.
9. After saving your models in Eclipse, the (re)sources for your application are automatically generated. See next section.

Generating source code

If you've completed and saved your model(s) as described in the previous section, the source code and resources for your application are automatically generated out of the model(s). Here below is described were you can find them and how to import them as projects into Eclipse. You can also find a overview and the location of the generated sources by opening the Mod4j "Generated Files" console. (Window > Show View > Other > Mod4j > Generated Files).

1. As you can see in the figure above, the Business Domain model generates (re)sources into two modules: the -data and -domain module. If these modules don't exist the modules will be automatically created. The -domain and -data modules are created in the application folder for all your modules, right beside the MyApplication.dslModels folder. See: ../MyApplication-domain and ../MyApplication-data
2. The generated sources and resources are placed in the generated-sources and generated-resources folders. Sources in MyApplication-domain/generated-sources and resources in MyApplication-data/generated-resources
   All Extension Points (see also next section) are initially generated into the src/main/.. folders.
3. Since the generated modules are fully Mavenized you can import the generated modules as Maven projects into Eclipse. But before ypu do that, it's a good practice to check if the generated modules can be build by Maven.
   Open a command console and navigate to location of the generated parent-pom (it's the pom.xml in the root of your application folder).
   type: mvn clean install
   If you run Maven for the first time, it could take a few minutes to complete for downloading the needed dependencies. After the build is finished and you've seen "BUILD SUCCESFULL", the parent-pom and submodules are locally installed and you can import the modules as Maven projects into Eclipse.
4. You can import all the generated Maven modules at once as follows:
   Choose: Import, Maven 2, Maven 2 Project
   and navigate to the application folder. Choose Ok .
5. By default all modules found with a pom are selected for the import. Make sure you do not import the the MyApplication-dslModels module by deselecting it. This module already exist as project in your Eclipse workspace.
6. Complete the import by clicking on Finish
7. In the previous step the IAM Maven plug-in not always recognizes the source folders correctly. If you encounter compilation failures, adjust the source folders manually. 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.

Extension Points

There are several reasons to mention why a developer needs to manually add (re)sources to the generated (re)sources by Mod4j.

• To implement business rules
• If the generated code does not fit the developers needs, and changing the model is not possible or does not lead to the right result.
• ...

For these reasons with Mod4j you can use Extension Points. Extension Points are extends to the generated (re)sources and provide a place where developers manually can make additions to- or change the behavior of the system. Initially Mod4j generates Extension Points once if they do not exist already. So Extension Points will not be overwritten by the generator.

Typically Extension Points are placed under the src folder of a module and needs to be added to the projects versioncontrol system.