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 Ganymede 3.4 SR1 for Java EE Developers. You can download one from the Eclipse download site.
   
3. Install, using the Update Manager, at least the following plug-ins into Eclipse:
   • OpenArchitectureWare Eclipse 4.3.0 (4.3.0.20080508-1430PRD). Update site: http://www.openarchitectureware.org/updatesite/milestone/4.3.0/
   • QforEclipse 0.8.1 Eclipse plugin for Maven2 projects. Update site: http://q4e.googlecode.com/svn/trunk/updatesite
4. Make sure you start Eclipse with the right jdk, e.g on a linux system: /path-to-eclipse-mod4j/Eclipse-europa/eclipse -vm /path-to-jdk1.5.0_15/jre/bin/java
5. Take care of the following Workspace settings in Elipse:
   - Make sure the 'Text file encoding' in Eclipse is set 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'.
6. Install Apache Maven 2.1.0 or higher. For download and install instructions see the Apache Maven site
7. Install the Mod4j DSL Eclipse plug-in as described in the next section.

Installing the Mod4j DSL Eclipse plug-in

The Mod4j DSL Eclipse plug-in can be installed from the Mod4j update site:

Mod4j update site: http://mod4j.org/updatesite

1. In Eclipse navigate to: Help, Software Updates, Find and Install...
2. Choose the option "Search for new features to install" and click on "Next".
3. To create a new remote site for Mod4j, click on "New Remote Site".
4. Enter a Name: "Mod4j update site"
5. Enter the URL: http://mod4j.org/updatesite and click on "OK"
6. Next you can select the Mod4j features of your choice. Complete the wizard to install the chosen features.

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 imnport by clicking on Finish
7. In the previous step the Q4E 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.

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.