OptimalJ tutorial for dummies

In this blog I’ll explain how easy it is to create an application with OptimalJ. For those people who want to learn more about MDA and other MDA tools, read my first blog https://technology.amis.nl/blog/?p=1178 or take a look at http://www.omg.org/mda/ 

This article discovers the most basis elements of a simple application and it gives a good introduction in OptimalJ and the Model Driven Architecture. The following subjects are covered in this article.

  • Install OptimalJ
  • Create a new project
  • Create a Platform Independent Model (PIM)
  • Create a Platform Specific Model (PSM)
  • Connect to a database
  • Generate and compile the code
  • Create the database tables
  • The first run
  • Create your own template
  • Create your own webpages
  • Implement some validation
  • Implement a search method
  • Add a static list
  • Run your OptimalJ application!



Install OptimalJ

You can download a free trial version of OptimalJ from Compuware’s site http://www.compuware.com/. There are two downloads available; the Professional version based on NetBeans and the Professional version based on Eclipse. The user interface is almost the same of these two versions, however I prefer the NetBeans version because this version was used to write this article. Besides OptimalJ you need to have JDK 5.0 installed on your computer.
(I used OptimalJ version 4.1 for this tutorial).


Create a new project

Start OptimalJ and choose File –> New OptimalJ Project and give up the name AMISLibrary and click on Next. In the step Specify Project Type choose for New Model and select a directory where the models must be placed, you can keep the defaults if you want.


Create a Platform Independent Model (PIM)

After creating a new project you can begin with modeling your PIM. Open the Domain Model until class is visible, right click on it and choose for Show Domain Class Diagram. 

Show Domain Class Diagram

The PIM worksheet is visible where you can draw the classes. Create the following classes with their attributes.

isbn : String
logo : Image

publishWeek : int

title : String
publishYear : int

name : String
website : String
country : String

When the creation of the classes are finished it is time to make some relations between them. Click on the icon Association on the toolbar and then click on the class Publisher, drop the relation on Medium. Choose for exactly one by Multiplicity for Publisher and choose for zero or more by Multiplicity for Medium. Accept the defaults and click on Finish.

Click on the Generalization icon on the toolbar and then click on the class Book. Drop the relation onclass Medium, accept the defaults and click on Finish. Repeat this step for the class Magazine.

Your PIM should like this.

Finished PIM



Create a Platform Specific Model (PSM)

Choose in the Model menu for the option Update All Models. This option takes care of the creation of the PSM models. Take a look at the Application Model to see what OptimalJ generated for you.



Connect to a database

By default OptimalJ uses a Solid database in the test environment. You can use this database if you want, but for this article I used a Oracle database. Before you can use a Oracle database with OptimalJ some settings must be made. First copy the file classes12.jar to your_optimalj_installation_dir\lib\ext and also copy the file to your_optimalj_installation_dir\libDeploy. Restart OptimalJ to make the changes effective.
Choose in the menu Tools for Options and then for OptimalJ Configuration –> Code Generation. Right click on Databases en choose for New –>
 Oracle. Put Oracle in the name field and click on Finish. Click on the just created database and change the settings where necessary, for example:
Database Driver oracle.jdbc.driver.OracleDriver
Database Mapping Oracle9i (you can use a Oracle10 database with this setting)
Database URL jdbc:oracle:thin:@localhost:1521:demodb
Generate SQL Scripts on
Support Schema on
Use Schema off
User Name rob
User Password secret

Choose for testing in the window Options. You can find this option under OptimalJ Configuration. Go to menu Testing en change the Deployment Database from Solid into Oracle (you can find this option under Database Configuration).

Finally change the schema name of the database PSM. Go to the Application Model en click on dbms and change the RelationalDataSchema in your own preferred schema name (for example rob).



Generate and compile the code

Go to the Model menu and choose for Generate All –> Code. The only thing left is to compile the code, go to the Project menu and choose for Compile Poject.


Create the databas tables

The statements for the creation of the needed tables can be generated by OptimalJ too. Go to the Code Model and look for ..\AMISLibraryDbmsModuleCode, click on it to make Oracle MetaAMISLibraryDbms.sqm visible. Right click on it and choose the option SQL Workbrench in context. Connect to your database and load the SQL create statements with the option Create. Execute all the statements with Exec Batch. Take a look at the log to verify if your tables were created, it should be like this:

RESULT [1]: 0 record/s updated
RESULT [2]: 0 record/s updated
RESULT [3]: 0 record/s updated
RESULT [4]: 0 record/s updated
RESULT [5]: 0 record/s updated
=== END of BATCH ===


The first run

Now you can run the application for the first time. Choose for Start Application Server under menu Test. So great, you haven’t code anything and there you have a complete generated J2EE application.


Create your own template

As you see the layout can be better, let’s make some modifications. In this step you’ll create your own WebTemplate. If you haven’t much time left you can skip this step… but if you want a nice looking demo…
At the end of this article you can download logoAMIS.gif, logoAMISklein.gif and AMISModern.css. Copy the two images to your_project_dir\AMISLibraryWebModuleCode\images and copy the stylesheet to your_project_dir\AMISLibraryWebModuleCode\css.
Restart OptimalJ (else the images won’t be visible while creating the WebTemplate).

Navigate to the Application Model and goto the properties of AMISLibraryWeb (under presentation). Change the default stylesheet from css/Business.css to css/AMISModern.css. Be careful! there are two stylesheets so change the correct one.

Navigate to the Application Model again and right click on presentation. Choose for New Child –> WebTemplate. Enter a name for it, like CustomizedTemplate. After you created the WebTemplate double click on it, this will open the Web User Interface Designer.
Add 6 Panels and 1 TilePanel. Make sure you put 3 Panels above and 3 Panels beneath the TilePanel.
Click right on the most upper Panel and choose for Layout Manager –> Table. After you’ve done this you’ll make some adjustments to all the panels. Change the styleClass for each panel, from up to down:
1. webheaderpanel
2. webheadermenu
3. webfillerpanel
4. webpanel
5. webfillerpanel
6. webfooterpanel
7. webbannerpanel
Al the syleclasses given refer to the AMISModern stylesheet.

Add a WebLabel to the second column of the first panel en put some text on it like Model Driven Architecture. And also change the styleClass of the WebLabel to webheaderlabel.
Add another WebLabel to the the sixth panel and put here some text like Generated by OptimalJ. Set webfooterlabel as styleClass for this WebLabel. Finally add the last WebLabel to the second panel and put   in it.
Put a WebCustomHTML in the third, fifth and seventh Panel and set the HTML property to <BR> for each WebCustomHTML.

Add a WebImage to the most upper panel in the left column and make it refer to images/logoAMIS.gif. Put another WebImage on the latest panel and make it refer to images/logoAMISKlein.gif. Be aware that the properties are case sensitive…

Your template should like this if you did everything correctly.

Result template


Create your own webpages

In the presentation tier each WebComponent represents a webpage. To create a new webpage you must create a new WebComponent. Right click on presentation and choose for New Child –> WebComponent.


Enter Book as name and make sure the option HTML User-defined is enabled also make sure that the option connected (to businessfacade serving attribute) is enabled. In step 2 select the class Book under booksvc. Accept the defaults in step 3, 4 and 5. Create a WebDataSchema in step 6 by clicking on the button. Select in step 7 An Empty WebFlow to get an better impression how OptimalJ works. Accept the defaults in step 8. When you reached step 9 you’ve to create some web actions. Click on Add and select Retrieve by Type. Accept the defaults en deselect the option retrieveByStrings in step 3 before you click on finish.
Add the web actions Select, Update, Store, New and Delete. Make sure that bookSvc.book is selected for each web action under Used WEBDataClass.
After you’ve added the web actions you can continue with the creation of the WebComponent. Add two WebPages in step 9 named bookList and bookForm. Make sure you select list by bookList and form by bookForm. For both pages use booksvc.book as Used WEBDataClass. Add the PageEvents exit, edit, new and delete to bookList. Change the EventType of edit and delete to Reference. Add the PageEvents exit and save to bookForm and enable the option Submit and Val. for the pageEvent save. Finally click on Next and on Finish!

Go to the just created WebComponent and double click on the BookFlow to define the flow. This is a typical MDA thing, because the user can define the flow with a diagram.
If you did everything correctly you should see the start and finish node in the workbrench. Add all WebActionNodes and the two webpages.
Connect all elements to each other until it looks like the following picture. Pay attention on the PageEvents, e.g. make sure the PageEvent delete is connected to the DeleteActionNode.

Result webpage

Now let’s create the desired webpages. Double click on the WebPageNode booklist. Select Create initial layout. If you have made your own template select it else OptimalJ will use the default template. Be sure you select the right WebPage Type (List or Form).
Do the same thing for bookForm.

Create webpage

Add functionality to the bookForm page so you can select the right Publisher in this page. Open the page and right click on the latest row of the table and choose for the option Table Row –> insert row (after). Add an WebDropDownList and choose for Edit Binding. Select book.Publisher and click on Finish. Give the WebLabel a name like Publisher.
To access the data of the class Publisher in the bookForm page you need to add the class to the page. Go to the WEBComponent Book and look for bookSvc. Add PublisherSvc.publisherSvc to the property usedServingAttribute. usedServingAttribute is a property of bookSvc.

The get an impression of the webpages, take the following steps;
1. Update All Models
2. Generate All Code
3. Compile Project
4. Start Application Server

Own made webpages begins with Show in the name and automatic generated webpages begins with Maintenance.

If you add or edit a book you see a unique id instead of a name or something like that. You can easily fix this by right click on the WEBComponent Book and choose for the option Open Generated Files –> Code –> BookAction.java. Search for // copy label attribute. Add the following code on the place where the first item is found in the white code block.

keyvalue.set(“label”, publisherUO.getName());

If you take a look at the blue code block (protected block) you see that the uniqueId is used by OptimalJ. By adding the code line the uniqueId isn’t used anymore.
The nice thing about adding your own custom lines in the white blocks is that these lines stay preserved after regenerating the code. While the blue code blocks can change.

Save and close BookAction.java, compile the project and run the project again. And you should see the name of the publisher instead of the unique id.


Implement some validation

In this step you’ll create validation for the attribute website. Navigate to the Domain Model–> Publisher, right click on it and choose for New Child –> DomainAttributeConstraint. Give it the name WebsiteValidator. Click Next until step 4 (Expressions based on Regular Expressions). Add a regular expression and give also the name WebsiteValidator to this object. Add the following code to the body:


After you added the code line click on Finish. Now add the WebsiteValidator to the attribute Website of the class Publisher by adding the WebsiteValidator to the constraint attribute of the website attribute.

I didn’t like the default error message of OpimalJ so I changed it. Navigate to the Code Model–> WEB-INF/classes –> domain –> local –> AMISLibrary –> application –> presentation. Open the file AMISLibraryWebResources.properties (the latest or one of the latest files). Search for error.prefix and error.suffix. Change the prefix from <li> to <font color=’red’> and change the suffix from </li> to </font>. It’s up to you to change more of the options given in this properties file.


Implement a search method

Click open the Application Model –> business –> logic. Right click on Publisher and choose for New Child –> FinderMethod. Add a Finder, add a parameter name and put findByName as name for the FinderMethod.
Click on Finish and choose for Update All Models (this option can be found in the menu Model).

Search method


Add a static list

Navigate to the Domain Model., right click on class –> New Child –> Domain Enum Type. Put Country as name and String as type. Add in the latest step your desired countries, e.g.;
Name: Netherlands Value: NL
Name: Belgium Value: BE
Name: France Value: FR
Name: England Value: UK

Change the attribute type of the attribute Country (class Publisher) to Country. So the user can select the countries you just added to the Country attribute.


Run your OptimalJ application!

Test the validation, search method an the static list by adding a new webpage. Create a new WEBComponent called Publisher. Be sure that the option HTML User-defined is checked and that the component is connected. Select publishersvc.Publisher as DataClass. Create a new Query WEBDataClass by pressing the button. If you like you can give up your CustomizedTemplate in step 7. Don’t choose for an empty webflow like before just click on Finish.

Update All Models, Generate Code, and Compile the project to make the changes effective.

Run you the application to test the demo application!

Now you can test the validation method, static list and the search method. Use % as wildcard in the search method and _ for one single character wildcard.

Screenshot result


New nice features of OptimalJ

OptimalJ version 4.2 (expected on 22 novmeber 2006) comes with support for Hibernate. I was told by my contact at Compuware that support for JSF was also planned for version 4.2 but is delayed, I don’t know the reason.

Needed files (images en stylesheet)

Download files



I hope you enjoyed this tutorial. If you have any comments, suggestions please add a comment. Of course you can send an e-mail to me (rob.v.d.krogt@amis.nl).