_ css deactivated
_ javascript deactivated

Online Tutorial - M2Flex

Design and generate Flex application 

Posted November 16, 2009

 

I. Overview

The goal of this tutorial is to demonstrate how simple it is to generate Flex applications with M2Flex. The sample application that will be built is a JavaEE application that manage customers and employees. A set of frameworks are implemented in this application such as Cairngorm, BlazeDS, Spring, Hibernate...

This tutorial is split into several parts:

  • UML model creation: UML diagrams and notations used to specify the business functionalities.
  • UI Configuration: user interfaces design that will be used to generate the flash client, data binding based on the designed model.
  • Source code generation and execution: step-by-step process to generate the source code of the Flex application.
  • Resources: Source and target resources including UML models, generation projects (workspace to import in M2Flex).

When you want to create an application in M2Flex, you need first to create a project with M2Flex nature using the wizard. The project contains a default transformation workflow: "m2flex.workflow", which you can edit in your workbench for the generation default configuration.

M2Flex projects contain also directories for UML model and UI mock-ups. Export the designed diagrams within MagicDraw UML modeling tool into the "model" directory. The user interfaces are designed and bound to the model using  Adobe Flex Builder. These UIs are used to generate the server side implementation and the client communication channel including the data binding (Cairngorm and BlazeDS implementation). M2Flex generates and build then the final flash application.

You can use other Flex editors to create and bind the user interfaces (mxml files) and then add these files to the M2Flex generation project. M2Flex core engine can validate and transform these UIs to generate, on the Adobe Flex SDK, a client based flash application.


II. Getting started

In this tutorial we will use MagicDraw UML 16.6 modeling tool to design the business functionalities of the target demo application. We will also use Adobe Flex Builder 3 to design and bind data to the created model. Then, we will generate the demo application source code using M2Flex.

MagicDraw product is bundled with M2Flex and automatically installed by the installation program, including project creation templates, specific wizards and validators.

M2Flex product is based on Eclipse and provides a set of Eclipse plug-ins to generate the application source code. Thus, M2Flex and Adobe Flex Builder can be used in the same workbench to achieve a generation project. By changing the Eclipse perspectives, user can have access to each product features (tools, views and editors). M2Flex generated Web project is configured with Flex project nature. If you are new to Eclipse and want to learn more, please see the Eclipse "Getting Started" resources.

This tutorial is not intended to demonstrate all the M2Flex and Adobe Flex builder full features. However, it showcases off the use of these products and basic configuration used to generate the demo application. More information, tutorials, user guides and trial download of Adobe Flex Builder are available at: http://www.adobe.com/products/flex/.

M2Flex free 30-day trial is available with the installation guide at: http://www.model2code.com.

You will also need to install a database server (among the following list: Oracle 9i or 10g, MSSQL Server 2000 or 2005, PostgreSQL, DB2-UDB or MySQL). In this tutorial, we used PostgreSQL database (http://www.postgresql.org/download/). You will need to create a new database and user before starting this tutorial. You will also need a deployment server; Tomcat server is used in this tutorial (http://tomcat.apache.org/).


III. Generation project setting up

We will start with showing you how to set up the generation project. We will provide an overview of M2Flex and Adobe Flex Builder, how they can be used together and then build a demo application to have the Flex client talks to database-back-end application.

We will start with launching M2Flex environment and creating the M2Flex project. The typical sequence is as follows:

  1. Launch the M2Flex product from the start menu: "Programs > M2Flex" and select the M2Flex perspective.
  2. Create a new M2Flex project by using the wizard form: "File > New > M2Flex project".
  3. Set the project name: "DemoApp" and then click "Next".
  4. Select the database server than you already have in your environment, and put your specific information about the database, username and password. Then, click "Next".
  5. Configure the Flex SDK and Java SDK paths as installed in your environment. See the Flex Builder and Java installation directories. And then, click "Finish".

Here we are creating a new M2Flex project named "DemoApp" that contains a mockup folder, model folder and a transformation workflow used to generate the application source code.

Let's remind that in Flex 3, you write code in MXML and ActionScript files and compile them into a SWF file, which runs in the Flash player. This SWF is referenced by an HTML file, so that when you load the HTML file, it plays the Flash movie (prompting the user to download Flash 9 if it’s not present). The SWF contained in the web page can interact with the server it was sent from. The server side implementation, the communication channel setup and implementation, the compilation and packaging are done automatically by M2Flex.

For the demo application, we will provide the MXML files that we can find in the resources section, and create the UML model from scratch to generate the projects source code.

Bellow a screen cast demonstrating how to set up the generation project in more details (click on the image to launch the flash screencast)


IV. Tutorial part1: Create and generate authentication features for the demo application


A. UML model creation

Now, we will create the UML model that manages the authentication (Login/Logout features) in the demo application.


Figure 1: Login user interface

To get started, follow the instructions bellow:

  1. Launch the MagicDraw UML modeling tool from the start menu: "Programs > M2Flex > MagicDraw UML"
  2. Create a new project by using the wizard from: "File > New Project".
  3. Select "Project from Template" and the M2Flex Template. This template will automatically load the M2Flex UML profiles used to annotate the diagrams and UML elements by using stereotypes and tagged values. Set the project name: "DemoApp" and the project location. Then, click "Ok" to create the project.
  4. Now, create the project packages and subpackages with the related stereotypes as shown in Figure 2 bellow.
  5. Next, create in the "DemoApp" package a new use case diagram with the application roles access as described in the Figure 3.
  6. Then, create the application entities and business objects in a class diagram. From this diagram, M2Flex will automatically generate the persistence implementation in the "Entities" project. See the Figure 4 for the entities and attributes description. The entities will be annotated with "Entity" stereotype and the attributes types with the M2Flex profile data types.
  7. Create a new class diagrams with the application Business Objects (BO) that inherit from the created entities. BO will define the business view of the persisted entities including operation constraints.
  8. Use now the M2Flex wizard integrated to MagicDraw to create the application activity diagrams and execution services:
    1. Select the wizard: "M2Flex > Wizards > Screen Creation Wizard" to create the activity diagrams that will detail the execution of the demo application case study. Set the Screen name to: "Login" and click "Next". The wizard will automatically select the created use case. Then click "Finish". A new activity diagram will be created and opened.
    2. Select the wizard: "M2Flex > Wizards > Service Creation Wizard" to create the execution services and operations. Set the service name to: "AppUser" and select "AppUser" in the "Entity's name" selection box. then, click "Next"'. Many services types can be created using this wizard, select the "FindAll" option, and then click on "Finish".
  9. Add the created operation to the generated activity diagram, by a drag and drop, on the "Server" swim line. Then, create a "Control Flow" to navigate through the activity actions (call operations and call behavior actions) as shown on the Figure 5, named "AppUserFindAll". The "Control Flow" names will be used to handle the event from the user interface and execute the designed operations.


Figure 2: UML project packages and sub-packages


Figure 3: Demo application use case


Figure 4: Demo application entities class diagram


Figure 5: Demo Application activity diagram for the authentication process

Bellow a screen cast demonstrating a step-by-step UML model creation, from the MagicDraw project setup to the model export (click on the image to launch the flash screencast)

When you finish the UML model creation, export the designed diagrams to "EMF UML (V2.x) XMI" format using MagicDraw from: "File > Export To" menu. Then, select the model directory created on the previous section to copy the extracted files.


B. UI configuration

To create the Flex application user interfaces you can use the Adobe Flex Builder product. This Eclipse-based product provides tools and editors to create MXML files with a design view. Switch to the "Flex Development Perspective" to edit MXML and ActionScript files.

To customize the Flex user interfaces, you need to add Flex components and ActionScript that handles the user events. Bellow a sample code from the demo application "Login" user interface.


Figure 6: Action Script sample source code


Figure 7: MXML sample source code

M2Flex can generate MXML blank files to customize by adding Flex components. These files can be generated as designed in the model's activity diagram. To do so, you need to configure the transformation workflow:

  1. Open the M2Flex transformation workflow "m2flex.workflow" using the "Workflow Model Editor".
  2. Select the BSP: "com.netfective.bluage.bsp.j2ee.flex" from the edited file, and right click to select: "Show Properties View".
  3. Set the GenerateMxml property to: "new", to create blank MXML files from the UML model.
    1. Set the GenerateMxml property to: "save", to generate the application source code from the customized MXML in the Web project.
    2. Set the GenerateMxml property to: "copy", to generate the application source code from the MXML files in the generation project mockup folder. In this case, M2Flex will overwrite existing files in the generated Web project.


C. Source code generation

Now, we will generate and execute the demo application from the model that you can find in the resources section, copy and extract this file into M2Flex project "model" folder. Copy and extract also the mockup file in the project "mock-up" folder.

To be sure that the created model is correct, you can validate the model exported from MagicDraw.  In the M2Flex perspective, right click the UML exported file on the "model" folder, then select "M2Flex Model Validation". The "Problems" view will display all the validation errors messages and their locations (paths) on the model.

The M2Flex project is now completely configured to generate the application source code. Run the generation process by executing the transformation workflow. To do so, right click the: "m2flex.workflow" and select: "Run as > M2Flex Launch Generation". This will execute the source code generation process. You can follow this process execution on the "console" until the final compilation and packaging of the application. The final result must be displayed in the "console" as: "BUILD SUCCESSFUL". Otherwise, you need to validate the project inputs (model or Flex MXML files).

You can now start the Flex application by deploying the Web project on the server instance, and point your browser to: http://localhost:8080/DemoApp-web/DemoApp.html.

Bellow a screen cast demonstrating the source code generation process and the demo application execution.  A quick highlight tour of the generated source code is also shown (click on the image to launch the flash screencast).


D. Tool tip and quick highlight

  • M2Flex allows you to generate the application source code and final package (ear, war archives).  In order to execute correctly the various automatic tasks, you should >disable all Eclipse validators to avoid conflict and errors. On "widow > Preferences" view, select the "validation" preferences and set "Suspend all validators".
  • To automatically creates the database structure from the UML model, you have to change the "m2flex.workflow" and select on the BSP "com.netfective.bluage.bsp.j2ee.hibernate.spring" the "Property hibernateHbm2DDLAuto". Set the value of this property to "update". By default, this option  value is "none".
  • Before you Log in to the application, create the initialization data from the script available in the resources section. This script will create the username, password and roles of the application users needed to execute the demo application.
  • M2Flex generates all the application source code from the projects inputs, including the UML model and mock-up. The mock-up includes only the MXML and related ActionScript. The modelLocator used in the MXML files, VO (Value Object that contains data to display), controllers... are generated by M2Flex. To configure the MXML files you need to generate first these implementation files (for Cairngorm framework), before binding the data and actions from the ModelLocator in the MXML files.
  • Adobe Flex Builder 3 offers many features for creating and customizing MXML files. Open MXML files from the generated Web projects and click on the "Design" view to customize the UIs, you add components from the existing palette and modify the tags options from the "Flex Properties" view. The generated Web projects are created with "Flex Project Nature". Click the "Source" view and from an MXML tag select "Ctrl+Space" to have access to the Flex tool tips and auto-completion features. These features are also available for the modelLocator and referenced data.
  • To launch the application exection, you can also select the "Flex development" perspective, right click the generated Web project and select "Run As > Flex Application".


E. Tutorial part 1 resources

- UML model to be edited with the MagicDraw modeling tool DemoApp_01.mdzip
- UML model exported in EMF UML (v2.x) XM (extract and copy the content on the generation project "model" folder) DemoApp_01.zip
- UI mock-up (MXML files) (extract and copy the content on the generation project "mockup" folder) DemoApp_Mockup_01.zip
- Database initialization data script (insert script) SqlInsertScript_01.zip



IV. Tutorial part 2: Create and generate the customer management (CRUD services)


A. UML model creation

Now, we will add new functionalities for the demo application. We will create the UML model that manages the customers.

At this point, we create a UML model for the authentication features and we will add the customers' features. We will start by adding the class entities diagram to the existing model, and then create the activities and services to manage customers. Open the created UML model in the MagicDraw UML modeling tool and create the diagrams as follows:

  1. Add a new class diagram with the "Customer", "Address" and "Employee" entities as shown in the Figure 8.
  2. Create a new class diagram for the entities related Business Objects.
  3. Use the M2Flex wizards to create the activities description and related services:
    1. Create the "Customers", "AddCustomer" and "UpdateCustomer" activities using the "Screen Creation Wizard".
    2. Create the "Customer" and "Address" CRUD services using the "Operation Creation Wizard".
  4. Customize and enhance the CRUD services by adding advanced description. This feature is detailed later in this section.
  5. Drag and drop created operations to the activity diagrams and design the "Control flow" relationships as shown in the Figure 10.
  6. Export the UML model using the MagicDraw Export to EMF UML (V2.x) XMI option.

Application services are created in the UML model in the "Services" package and defined as UML interfaces. Each service is annotated with a stereotype to specify its execution. These stereotypes are available from the UML profile: (Create, Update, Delete, CreateAll, UpdateAll, DeleteAll, FindById, FindByProperties, FindAll). To customize the services execution, you can model in an activity process diagram the step-by-step execution workflow. In this diagram, you can add a decision or condition nodes, expansion region to iterate on a list of Business Objects...

In this demo application, we will add advanced services illustrating the process diagram design, hql_operation description and specific Java source code integration:

  • Create a new service namaed "customerCreateWithAddress"as UML interface in the "Services" package with "process" stereotype. Create an activity diagram with the same name. Add an activity initial and final node to this diagram, and design the execution workflow through the call operation and decision nodes as shown in the Figure 9. Use the activity Central Buffer nodes to define the business Objects instance used and shared by the created operations.
  • Customize the "CustomerFindAll" operation, created by the M2Flex Wizard, by adding a HQL request execution. Assign the "hql_operation" stereotype to this service and add the following request "from CustomerBO c left join fetch c.address" as a tag value in the operation specification and set bo option to "CustomerBO".
  • Add a specific implementation in Java source code as constraint for the "AddressBO". Create an operation related to this BO named "setIdToNull()" with the "formula" stereotype. Add the source code "id=null;" to "binary_java" option, in the operation tagged value: "formula".


Figure 8: Demo application class diagram (Part 2)


Figure 9: Activity process diagram for service execution


Figure 10: Demo Application activity diagram for customers' management

Bellow is a screen cast demonstrating a step-by-step operation to add the demo application new features (customer management) (click on the image to launch the flash screencast)


B. Tool tip and quick highlight

  • M2Flex product is not limited to creating CRUD application (services). M2Flex provides a set of stereotypes and tagged values to create complex enterprise applications. This UML profile offers many features to design complex business needs, requirements, logics and rules. You can specify complex services execution by using the activity process diagram. You can also simply create Web Services from the operations created in the UML model by adding related stereotypes. You can also design a workflow service's execution and generate the BPEL and WSDL implementation...
  • M2Flex allows you to simply add specific implementation of services, operations, classes by adding the source code to the transformation workflow. This source code or jar files will be added to the source code during the M2Flex generation process. Simply configure the "source path" and "target path" in the "Resource Model" from the "m2flex.workflow" file.


C. Tutorial part 2 resources

To generate and execute the application source code, follow the "Source code generation" section on this tutorial part 1.

- UML model to be edited with the MagicDraw modeling tool DemoApp_02.mdzip
- UML model exported in EMF UML (v2.x) XM (extract and copy the content on the generation project "model" folder) DemoApp_02.zip
- UI mock-up (MXML files) (extract and copy the content on the generation project "mockup" folder) DemoApp_Mockup_02.zip

M2Flex Getting Started Tutorials was posted November 16, 2009.