Lesson 1: Create a Model File (.jmm)

As already shown in the Code Generator Introduction, the code generator's transformation workflow looks like this:

One of the most important inputs in that workflow is the model file (.jmm file). Think of a model file as the definition of your Java/.NET integration problem. Technically speaking, a model file is a terp script whose evaluation results in a Java model instance (terp is Codemesh's proprietary scripting language).

Practically speaking, a model file is something that records all the changes and edits that you make to a model in the code generator GUI.

When you run the code generator GUI without arguments, you get an empty integration model that is initialized with default values. It might look something like this:

You can see a Navigation Pane that contains just the empty model root on the left side of the model window and a Model Properties Pane that contains all th default-initialized model properties. In particular, you can see the model's name, which was initialized to "JavaModel - 1". Let's change that value to a more meaningful name.

Step by Step Instructions

1. Verify That Code Generator Can Run

   For many users this will be the first time they try to run the code generator, so let's make sure it works!

   To start the code generator, open a console window, change into the installation's bin directory and run the batch (xmog.bat) or shell script file (xmog). Use the batch file on Windows systems and the shell script file on all other platforms. Your directories will likely be different but the following snippets should make clear what you need to do on your system.

   We will ask the code generator for its version number. This simple operation is implemented to execute some of the internal machinery and makes for a great smoke test to verify that the code generator is properly installed and that it can find everything it needs to run, at least in command line mode.

   cd C:\Program Files\junc++ion-4.8.429\bin
   xmog -version

   cd /opt/junc++ion-4.8.429/bin
   ./xmog -version

   You should see a version message in your console window.

   DEBUG

   Check That the CLI Version Works

   If the command line version of the code generator is not working as expected, it is probably due to one of a few possible reasons:

   On Unix-like systems you might have a permissions problem. Check the output of

   ls -la <codegen dir>/bin

   Make sure that you have executable privileges for the xmog shell script. You might have to ask your sysadmin for help if you don't.

   If you get an error related to Java, you might not have a compatible Java Development Kit installed or xmog cannot find it. In general, for the CLI version, any JDK version 7 or higher should work.

   The script will try to use a java interpreter from the PATH or it will look for one relative to the environment variable JAVA_HOME.

   Locate a compatible JDK and do the following:

   export PATH=$PATH:<jdkdir>/bin

   set PATH=%PATH%;<jdkdir>\bin

   Alternatively, define the JAVA_HOME environment variable:

   export JAVA_HOME=<jdkdir>

   set JAVA_HOME=<jdkdir>

   Call us if the problem persists.

   Please click the button on the right if you do not see the expected version message to help you with debugging the issue. Feel free to call us if the problem persists.
2. Start the Code Generator GUI

   To start the code generator, run xmog without the -version argument. Assuming you are still in the code generator's bin directory, simply type:

   xmog

   ./xmog

   You might be asked to agree to the evaluation license agreement if you have never run the code generator before. Please read and accept (you already accepted this license before you downloaded). The code generator might ask to download the runtime library. You will need your download credentials and write privileges for the code generator installation for the runtime installation to work. If you don't have both, just skip this step. Finally, a GUI window similar to the one shown in the above screenshot should display.

   DEBUG

   Check That the GUI Version Works

   If the GUI version of the code generator will not start up as expected, it is probably due to a third-party incompatibility. Please note that some warning messages during startup are acceptable and do not necessarily constitute a problem.

   Please check first that the commandline version of the code generator works as expected. The instructions to do so can be found further down. If the CLI version works as expected but the GUI version still does not, you are probably running into an incompatibility of a third-party component we use in the GUI and your version of Java.

   We have only encountered this issue on MacOS-X so far. On MacOS-X you have to run the code generator GUI with a JDK version 7 or 8. Later versions will not work. At the time of writing, an OpenJDK-compatible Java 8 JDK was available from Azul.

   Please consider installing an older version of Java and retry. Please note that this does not mean that you have to generate code for an old version of Java. The version of Java used to run the code generator is independent of the version of Java on which the proxy types are based.

   Contact us if you are blocked due to this issue.

   Check That the CLI Version Works

   Make sure the commandline version works by asking it to display its version information. Change into the code generator's bin directory and run:

   ./xmog -version

   xmog -version

   You should see the products version information. If not, your problem is likely due to one of the following causes.

   On Unix-like systems you might have a permissions problem. Check the output of

   ls -la <codegen dir>/bin

   Make sure that you have executable privileges for the xmog shell script. You might have to ask your sysadmin for help if you don't.

   If you get an error related to Java, you might not have a compatible Java Development Kit installed or xmog cannot find it. In general, for the CLI version, any JDK version 7 or higher should work.

   The script will try to use a java interpreter from the PATH or it will look for one relative to the environment variable JAVA_HOME.

   Locate a compatible JDK and do the following:

   export PATH=$PATH:<jdkdir>/bin

   set PATH=%PATH%;<jdkdir>\bin

   Alternatively, define the JAVA_HOME environment variable:

   export JAVA_HOME=<jdkdir>

   set JAVA_HOME=<jdkdir>

   Assuming this works, try starting the GUI now. If not, call us.

   If the expected window does not open in a reasonable amount of time please click the button on the right to help you debug the issue.
3. Change the Model's Name

   Click in the value for the "Model Name" model property to get a property editor. You should see a blinking cursor and can now type your desired model name. That name should be descriptive of the model's purpose. We'll keep it simple and type Lesson 1 and hit the Enter key.

   Once you hit the Enter key, the code generator recognizes that you made a change, so the "Save model" toolbar button (it has a floppy disk icon) is now enabled, as are the "File - Save Model" and "File - Save As" menu options.

4. Save the Model

   But before we do this, please note that the Model File property value is empty. This means that the code generator is aware that the model is newly created and not loaded from your file system.

   Now click the floppy disk icon in the toolbar or choose one of the File Save menuitems and select a directory to which you want to save it. Press Save.

   When you now look at the Model File property, you will see that it contains the file name you chose as a read-only value now.

5. Let's look at the saved model.

   Locate the saved file and open it in your favorite text editor. When I looked at the file on my system, it had the following contents:

   ^javamodel({id:'javamodel.12796327196.1'}).setmodelproperty('name', 'Lesson 1');
   ^javamodel({id:'javamodel.12796327196.1'})

   You can also click on the Model State tab (you always either look at the model properties or at the state) and compare the model state with the contents of your saved file. They should of course be identical.

   But what does it all mean? The contents of a model file are explained in greater detail in the Modelfile Reference but let's do quick run-through here.

   Every line starts with a ^javamodel({id:'javamodel.12796327196.1'}) expression. This is a terp expression that stands for: locate or create a model with the computer-generated unique identifier 'javamodel.12796327196.1'. The first time this expression is encountered, a new Java model with the desired unqiue identifier is created. The second time and every subsequent time this expression is encountered, the already created Java model instance with the given unique id is returned.

   In the first line we see the edit that we made to the model. We changed its name to "Lesson 1." This edit got persisted as a terp expression that invokes the setmodelproperty() command on the Java model instance.

   All model modifications that you make are recorded in this basic way. Again, please see the Modelfile Reference to learn more about model properties and commands.

   But why is there no change for the modelFile property? It changed when we saved the model to the file system. The modelFile property is special in that it always implicitly takes the value of the file from which the model was opened or to which it was saved. Therefore its value is not recorded as a change.

6. Now Change the Model's Name Again

   Make another edit to the model name. Let's be creative and call it "Lesson 2." After you hit Enter, take a look at the Model State again. You will find this:

   ^javamodel({id:'javamodel.12796327196.1'}).setmodelproperty('name', 'Lesson 1');
   ^javamodel({id:'javamodel.12796327196.1'}).setmodelproperty('name', 'Lesson 2');
   ^javamodel({id:'javamodel.12796327196.1'})

   Both changes have been recorded with the second name change overriding the first one because it is executed later.

   This is an important lesson: changes are cumulative and the sequence of changes can matter.

7. Close the Code Generator

   This concludes the first lesson and we want to start with a fresh code generator for the next lesson. Please do not save the changes to your model when you exit the code generator.

Take-Away Points

This was not a complicated lesson, but you should have learned some important facts about the code generator:

1. The code generator GUI is launched through script/batch files called xmog that are located in the product's bin directory.
2. There were some sick minds at work here. Who came up with the name xmog?

   When we created the original code generator two decades ago, we were inspired by "Calvin and Hobbes" transmogrifier gun. We decided to go easy on our users and use xmog instead of transmogrify.

3. A model file is a terp script that records all modifications made to an integration model in the code generator GUI.
4. A model file is a plain text file that can be created, viewed, and edited in a text editor.
5. There is an implicit model property called modelFile that always has the name of the file from which the model was loaded or to which you saved it as its value.
6. A model file does not contain all the property values that you see in the model view. It only records the changes that you made.