UX-To-Web Transformation v1.1.1

Copyright @2005-2006 IBM. All Rights Reserved.

This transformation plug-in demonstrates the ability to generate a runnable Web application from a UML model using IBM^® Rational^® Software Architect (RSA). The transformation implements a limited subset of features commonly found in Web applications. It is not intended to generate fully operational applications but it is intended to illustrate a Model-Driven Development approach: business logic is captured in UML models and implementation technologies are encapsulated in the transformation itself. This means in particular that you can adopt new implementation technologies without having to modify the business logic.

Starting with version 1.1.0, the plug-in uses JSF for the presentation layer and Hibernate for the persistence layer. Version 1.0.3 of the plug-in supported both JSF and Struts, but the latter has been abandoned due to lack of time. Version 1.1.1 corrects a problem in the initialization of the Hibernate mappings that precluded - in some cases - the succesful execution of the generated application.

Overview
Known Limitations
Running the Transformation
Using the UXModeling2 Profile
Using the DataModeling Profile
How It Works (in a nutshell)

Overview

The UX-To-Web Transformation is a prototype whose goal is to demonstrate the MDD/MDA features of RSA to build a transformation that generates a complete set of files from a UML model to which appropriate profiles have been applied. The complete set of files consists of .java, .xml, .jsp and .css files that form a runnable Web application. JSF is used for the presentation layer, Hibernate for the persistence layer.

The transformation generates the executable application from a User-Experience (UX) model, i.e. a model that describes the screens of the target application and the navigation between these screens. A UXModeling profile was developed accordingly. A DataModeling profile was developed for the persistence aspect.

Here is a typical scenario:

The user logs on.
The application displays a list of items retrieved from a database.
The user clicks on a colum-link of one of the rows to see the details of the item..
The user updates the selected item and submits the changes.
The changes are committed to the database.

The following is a summary of the major capabilities covered by the UX-To-Web Transformation:

MDD/MDA.
UML2 profiles.
JET (Java Emitter Templates) Technology: Template-based code generation.
JMerge Technology: business logic manually added is preserved from one generation to the next.

This tranformation is not intended to generate fully operational applications. See limitations.

Known Limitations

This tranformation cannot be used "as is" with IBM Rational Software Modeler (RSM) as it uses Dynamic Web Projects provided by IBM Rational Application Developer (RAD).
The UXModeling2 profile offers a limited number of constructs (like screens, input forms, static text fields, input text fields, radio buttons, user actions, links). For instance, checkboxes are not implemented. In version 1.1.x, listboxes are not fully operational. The screen layout is not customizable.
The profiles (UXModeling2 and DataModeling) have not been released.
If modifications in the model affect the location of the generated Java classes, the transformation does not remove the classes previously generated.You will need to manually clean up the target project.
The transformation works correctly with the provided UML examples but has not been tested extensively outside the scope of these examples.

Running the Transformation

Import the provided model(s):
- Open the Modeling perspective.
- Import CDShop (a simple UML model of a website for accessing CDs online): File > Import ... > File System and select the examples directory in the com.ibm.jps.uxtoweb plug-in (the complete path is something like C:\Program Files\IBM\Rational\SDP\6.0\rsa\eclipse\plugins\com.ibm.jps.uxtoweb_1.1.x\examples). Make sure to select banner.jpg as well as CDShop.emx. You can import the files into any project of your choice (TestUML below). (he complete path
- Open the model.
- If this is the first time you are using the UX-To-Web transformation with this model, you will need to update the settings for the CDSTORE database:
Configure a transformation:
- Define the target of the transformation by creating a Dynamic Web Project (File > New > Project ... > Dynamic Web Project):

Click Finish after entering the name of the project. Then in the explorer, right-click the project, select Properties, then in the Properties dialog, select Web Project Features in the left pane, then check the Add Faces Base Components feature. Then press OK.

In the Modeling perspective, configure the transformation (Modeling > Transform > Configure Transformations ...):

Click New to instantiate the transformation.
Choose an appropriate name (it is a good idea to name it after the target project).
Select the target project. You will notice that you still get an invalid source error. This is OK for now.
Click Apply, then Close.

Run the transformation
- Right-click the model in the Model Explorer and run the transformation (as illustrated below). If there are errors during the model validation performed by the transformation, these errors are reported in the Problems view and code generation does not take place. You should correct the errors and re-run the transformation. Note: A .JETEmitters project is automatically created (by default it is filtered out). If you have used JET templates before, you might already have such a project. If you are experiencing any difficulties generating the project files, you might want to delete .JETEmitters and restart the transformation..

Switch to the Web perspective.
- Right click on WebContent::logon.jsp > Run > Run On Server....
- Use the integrated test server.
- When the logon page is displayed, you can use 'user' (password 'user') or 'jules' (password 'alea'). You can also modify the CDSTORE database to add your own users: you can do this using CView (the interface for graphically creating, examining, and managing Cloudscape databases) but you can also complete the CDShop model to implement the ManageUsers functionality...
You can modify the model and re-run the transformation. See Using the UXModeling2 Profile and Using the DataModeling Profile. Here are some simple changes you can easily make in the model:
- For any item displayed on the screen, you can change its label. For instance, select the username input field in the <<input>> LogonForm and change the stereotype property label to any value of your choice. You might also experiment with the max and min properties for this input field.
- If you click on the Manage User Accounts link in the Home page, you will see that the page is not complete. It only has a Back link. You can add a logoff hyperlink: add an operation <<link>> logoff to the class <<screen>> ManageUsers and draw a directed association from ManageUsers to class <<screen>> Logon. Name the association logoff. (By the way, if you forget the association, an error will be generated. You might want to try it too.)
- A more elaborate change is to add a <<list>> to ManageUsers in order to be able to add/modify user accounts.
You can modify the stylesheet.css in the WebContent/theme folder to modify the appearance of components in the pages.
Because the JET templates are compiled "on-line", you can modify those templates to obtain a different look and/or behavior. You need to understand the underlying metamodel (see How It Works). But here is a simple case to try: let's say that you want to add a copyright line after the horizontal ruler on each page. Here is how:
- Open the file jsp.javajet located in C:\Program Files\IBM\Rational\SDP\6.0\rsa\eclipse\plugins\com.ibm.jps.uxtoweb_1.1.x\templates\jsf\jsp. (In RSA, you can use the command File > Open External File...)
- At the very end of the file, insert the text <H6>Copyright (...)</H6> as highlighted below, then save the file, close the Web Browser (if the application is running), re-apply the transformation to the model and re-run the application. You can also try adding <$= jsp.getTitle()$> in front of the word Copyright. This will display the "title" of the JSP. (The title defaults to the class name but you can change it in the model by changing the property label associated with the stereotype screen for each <<screen>> class...)

Using the UXModeling2 Profile

The following stereotypes are provided. All stereotype attributes have default values.

:

Stereotype	UML Element	Description
<<screen>>	Class	Describes a screen. A screen is transformed into a JSP. Relationships: Directed associations indicate navigation to other screens. The association should be named after the action that triggers the navigation (see <<useraction>> and <<link>>). The name may be followed by a condition within square brackets (e.g. success or failure). If only the condition is shown, it applies to all useractions and links not identified by a named association. If several actions point to the same screen, use a comma-separated list to name the relationship. Compositions indicate the existence of an input form (see <<input>>) or a list (see <<list>>).. Attributes: label: The name of the JSP. Defaults to the class name with the first letter in lower case.. path: Not used.JSPs are generated in the WebContent folder. heading: Optional JSP title. headingLevel: From 1 to 6.
<<input>>	Class	Describes an input form. An input form is intended for use with a <<screen>> class and should contain one or more inputtext fields. Relationships: Dependencies must be drawn to the <<bean>> class holding the attributes matching the input fields. See <<inputtext>> for more details. Attributes: path: Not used.
<<list>>	Class	Describes a list of items. A list is intended for use with a <<screen>> class and should contain one or more display fields. Relationships: A dependency must be drawn to the <<bean>> class holding the attributes matching the list items (see <<display>>). All elements in the list must correspond to the same <<bean>>. In the example above, the <<display>> elements of the CDList are the title, artist and price of a Cd object. Because all list items must point to the same bean, there should be only one dependency. If the list items point to more than one bean, a warning is added to the Problems view. If the <<bean>> is mapped to a database table, the transformation automatically connects to the database and retrieve the records to display. See Using the DataModeling Profile for more info about database access. Attributes: hasHeader: if set to true (default), the transformation will generate a header for the list as in the example above.
<<display>>	Attribute	Describes a display field. Used in a <<screen>> or in a <<list>> class. The attribute type is ignored. A display field must have a match with an attribute in a <<bean>> class. Relationships: Dependency from the owning <<screen>> or <<list>> class to the <<bean>> class with the matching attribute. If the <<bean>> class is not found, an error is added to the Problems view. Attributes: label: The text used for display on the screen.
<<options>>	Attribute	Provides additional information about the targeted element. Currently the only availabe "option" is sortable. Attributes: sortable: Used in lists to indicate that thecorresponding field-column is sortable. Currently only possible to sort String fields (warning generated otherwise) and only in ascending order.
<<useraction>>	Operation	Describes a user action, rendered as button or link (see attribute kind).Used in a <<screen>> class. A user action must have a match with an operation in a <<bean>> class (if not an error is generated). The transformation will provide some default processing based on the name of the action: If the user action starts with logon, the transformation will add code to read the database record matching the input primary key if appropriate. In addition, if the form/record includes a "password" field, the transformation will add code to check that the password matches the user-defined password and generate the appropriate error message. If the user action starts with add or create, the transformation will add code to a new record in the database if applicable. If the user action starts with update, the transformation will add code to save the data to the database if applicable. Relationships: Directed association(s) from the owning <<screen>> class to the target screen(s). See <<screen>> stereotype. Dependency from the owning <<screen>> class to the <<bean>> class with the matching operation. If the <<bean>> class is not found, an error is added to the Problems view. Attributes: label: The text used for display on the screen (button label). Defaults based on the operation name. path: Used in the Struts version. Defines the package where the matching action class will be stored. Defaults to the package of the owning <<screen>> class. kind: Indicates how to render the user action. Possible values: button (default), link. visibleOnAction: If empty, the component rendering the user action is always visible. Otherwise, it is visible only if the triggering action is included in the comma-separated list of possible actions. Example:
<<link>>	Attribute Operation	When used with an attribute, equivalent to a link-kind user action. Typical use: with a <<display>> field in a <<list>> as in the following example: Use with an operation to create an HTML link. A link must have an associated target <<screen>> class (error generated otherwise). Relationships: Directed association from the owning <<screen>> class to the target screen. See <<screen>> stereotype. Attributes: label: The text used for the link on the screen. Defaults based on the operation name. description: Optional text. If present, it is displayed to the right of the link name. Ignored when stereotype used with an attribute.
<<inputtext>> <<listbox>> <<radiobutton>>	Attribute	Describes an input field. Should only appear in an <<input>> class. Should have a matching attribute in a <<bean>> class. Currently the implementation of <<listbox>> is not complete. Values for <<radiobutton>> fields can be sepcified as enumerations in the UML model as shown below: Relationships: Dependency from the owning <<screen>> class to the <<bean>> class with the matching attribute. If the <<bean>> class is not found, an error is added to the Problems view. Attributes for <<inputtext>>: label: The text used for display on the screen. max: The maximum number of characters allowed. min: The minimum number of characters allowed. password: If true, the field is treated as a "secret" field. required: If true, the user must specify a value. Attributes for <<listbox>>: label: The text used for display on the screen. Attributes for <<radiobutton>>: label: The text used for display on the screen.
<<bean>>	Class	Describes a bean. Typically contain attributes and operations referenced by <<screen>>, <<input>> and <<list>> elements. See example above. Derived attributes: a bean may contain derived attributes. For instance <<bean>> User contains a firstname and a lastname attribute. These attributes may map to database entries as this is the case in the provided sample model CDShop. But you might want to display the full name of the user. In order to do this, you simply add a fullname attribute and select the Derived qualifier in the General tab of the Properties view of this attribute. You can specify in the Documentation field of the attribute the actual code, for instance: 'return getFirstname() + " " + getLastname();'. The transformation will automatically generate the correct getter. Attributes: path: Defines the package where the matching bean class will be stored. Defaults to the class package.
<<global>>	Class	Defines global settings. Attributes: appname: Optional application name. Will appear on every page. logofile: Optional logo file (.gif, .jpg, etc.). Should be a relative name in the project containing the model. logoheight: Optional height in pixels. Default = 80. logowidth: Optional width in pixels. Default = 200.

Using the DataModeling Profile

The following stereotypes are provided.

:

Stereotype	UML Element	Description
<<database>>	Component	Describes a database. Used to provide connection parameters for database access. Relationships: Dependencies to included tables. These dependencies are used only for documentation purposes. Attributes: connectionDriverClass: The application has only been tested with the driver shown below.. connectionPassword connectionUrl: The application has only been tested with a Cloudscape database. connectionUserName.
<<table>>	Class	Describes a database table. Used to perform the mapping between a <<bean>> class and a database table. The existence of the mapping will cause the transformation to automatically generate the access code. To create the mapping in UML, display the structure compartment (see below), populate this compartment with the class attributes (drag and drop from the Attribute compartment) and draw dependencies to the table "columns". Relationships: Dependencies from the attributes of the <<bean>> class to the corresponding attributes of the <<table>> class. Attributes: None
<<pk>>	Attribute	Defines a primary key. Currently only single attributes can be used to form a primary key. Attributes: generateKey: If true, the transformation will automatically generate a key (time in milliseconds since ...). Currently generateKey is always considered to be true. Therefore the keys in your tables should be VARCHAR with at least 10 (?) characters.

How It Works In A Nutshell

The transformation executes in two steps:

The collection of data from the input model. The collected data are stored in an internal metamodel. This step is independent of the technology used for the Web application.
The generation of code from the metamodel. This is performed based on JET Templates. There is one set of JET templates for Struts, and one set for JSF.

The transformation metamodel (not up-to-date!)

The code generation

All generated files are based on JET templates. JET templates are compiled automatically by the JET compiler as Java classes with a generate operation. In fact the templates are compiled on-line at run-time! The transformation invokes this operation that produces a String that IS the file contents. The generate operation takes one argument of type Object. This argument is a Java object corresponding to an object from the metamodel. For instance, for a JSP file generation, the generate operation will be passed an object of type Jsp. A JET template actually looks like a JSP file itself, mixing Java statements and statements corresponding to the targeted output. The example below was extracted from the template used for the generation of the faces-config.xml file. .

if (jsps != null) {
   for (Iterator i = jsps.iterator(); i.hasNext(); ) {
      Jsp jsp = (Jsp) i.next();$>
   <managed-bean>
      <managed-bean-name>pc_<$= JavaUtil.firstCharToUpperCase(jsp.getName())$></managed-bean-name>
      <managed-bean-class>pagecode.<$= JavaUtil.firstCharToUpperCase(jsp.getName())$></managed-bean-class>
      <managed-bean-scope>request</managed-bean-scope>
   </managed-bean><$
   }
}

back to top