UX-To-Web Transformation v2.0.U

Copyright @2005-2007 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) V7. 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.

This version of the plug-in uses JSF for the presentation layer and Hibernate for the persistence layer. Changes since the 1.3.0 version are:

• Migration to the new MDD functionalities in RSA V7 (a full model-to-text transformation is the combination of a model-to-model (M2M) mapping transformation and an EMFT JET model-to-text (M2T) transformation).
• The UXModeling profile has been renamed WebModeling and has icons for several of the stereotypes.
• New class stereotype <<settings>> (replaces <<global>>): the target project is now named based on the name of the <<settings>> class. A dependency from the <<settings>> class to a <<screen>> class will result in the creation of an index.jsp file. This means you can start your project by right-clicking the project itself instead of the specific jsp.
• Support for searches: A <<useraction>> operation starting with 'find' is interpreted as a search function and will generate the appropriate code. The fields to use for the search are specifiied using an <<input>> class. Only string fields are supported: compilation errors will appear in the generated code if non-string fields are used. A <<link>> operation starting with 'list' is interpreted as a "list all" action.More details in the Using the WebModeling Profile section
• <<useraction>> and <<link>> list... operations require a <<bean>> class to be identified. In previous versions this was modeled using dependencies to the <<bean>> classes. In addition, the target bean was required to have an operation with the same name as the <<useraction>> operation. The latter is no longer required. In addition the dependency can be replaced with the following naming convention for the operations: <keyword><bean name><optional text>. Examples: findCd, findCdByArtist, listCd will all result in the bean Cd being identified (there must be a matching <<bean>> Cd).
• Mscellaneous bugs.

Table of contents

Overview
Limitations
Running the Transformation
Using the WebModeling Profile
Using the DataModeling Profile

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 running Web application from a UML model to which appropriate profiles have been applied. The application consists of a RSA Dynamic Web Project and the matching Enterprise Application Project. The integrality of the two projects is generated from the plug-in. 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 WebModeling profile was developed accordingly. A DataModeling profile was developed for the persistence aspect.

Here is a typical scenario:

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

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

1. MDD.
2. UML2 profiles.
3. JET Technology: Template-based code generation.

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

back to top

Limitations

1. This transformation can be used only with IBM Rational Software Architect (RSA) V7 and above.
2. 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). IBM Rational Software Architect is therefore required.
3. The WebModeling 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 2.0.x, listboxes are not fully operational. The screen layout is not customizable.
4. 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.
5. The transformation works correctly with the provided UML example but has not been tested extensively outside the scope of this example.
6. The server must be restarted after each application of the transformation.
7. Searches must be limited to string fields.
8. Only single primary keys are supported. You cannot have a table using for instance LASTNAME and FIRSTNAME as a composite key. In this case, you should use a unique identifier.
9. I had some unaccounted for siutations where the generated code will not compile properly. This seems to be related to the JSF settings but I do not know exactly what settings. The symptom is that the Java compiler will report errors on the last generated class of the type "The type java.lang.Object cannot be resolved. It is indirectly referenced from required .class files". If you have this problem, please contact me.

back to top

Running the Transformation

1. 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_front_end plug-in (the complete path is something like C:\Program Files\IBM\SDP70\plugins\com.ibm.jps.uxtoweb.frontend_2..0.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).

   
   

   • 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:
   1. In the .zip file you used to install the plug-in, you will find a file called UXToWeb_CDSTORE.zip. Extract the contents of this file in a location of your choice, say C:\Documents and Settings\user\My Documents\Databases. A CDSTORE directory is created. (CDSTORE is a CloudScape database. You should be able to use any other database, but this has not been tested in UXToWeb 2.0.x. See also step c below.).
   2. Select the <<database>>CDShop component in the model.
   3. In the Properties view of CDShop, select the Stereotypes tab. The DB connection parameters are listed as properties of the stereotype <<database>>. If CDSTORE is located in C:\Documents and Settings\user\My Documents\Databases, change the connectionUrl property to jdbc:db2j:C:\Documents and Settings\user\My Documents\Databases\CDSTORE.. A copy of the db2j driver is included in C:\Program Files\IBM\SDP70\plugins\com.ibm.jps.uxtoweb.codegen_2.0.x.jar. If you want to use another database, you should update the other parameters, in particular connectionDriverClass.
2. Configure a transformation:
   • In the Modeling perspective, configure the transformation (Modeling > Transform > Configure Transformations ....):
   1. Name the new configuration (e.g. CDShop), select the UX To Web transformation (in the Custom UML Transformations category), and define the configuration file destination (/TestUML below). The click Next..
      
      
      
      
   2. In the Source and Target page, select CDShop both as the source and target models. Make sure to select the model, not the .emx file. Click Finish.

   
   
   

3. • Run the transformation
     • Close the CDShop.tc file.
     • Right-click CDShop.tc in the Project Explorer and run the transformation (as illustrated below). Currently markers are not correctly displayed. This means that errors detected during the model validation performed by the transformation will not be visible. The only way to get around this problem is to run the transformation by importing the Project Interchange version of the transformation and testing the transformation using the run-time workbench: errors are logged in the console of the host workbench.

   
   
   

   • Run the CDShop Web application.
     • If everything goes well, the transformation will have generated e CDShopApp project and a CDShopAppEAR project.
     • If you have a <<settings>> class pointing to your main entry <<screen>>, right-click > CDShopApp > Run > Run On Server...
     • Otherwise right-click > CDShopApp::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 complete the CDShop model to implement the ManageUsers functionality...
   • You can modify the model and re-run the transformation. See Using the WebModeling 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.
     

back to top

Using the WebModeling 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.. 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 at least one <<inputtext>> or <<radiobutton>> field. Relationships: Dependencies must be drawn to the <<bean>> class holding the attributes matching the input fields. See <<inputtext>> for more details. Attributes: None.
<<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.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. If the user action starts with find, the transformation will generate code to retrieve the database records based on the fields available in the associated <<input>> class. For the special keywords mentioned above, you must indicate a target bean (the bean for which we want to provide the corresponding functionality). You can do this with the following naming convention for the operation: <keyword><bean name><optional text>. Examples: findCd, findCdByArtist, listCd will all result in the bean Cd being identified. The class <<bean>> Cd must exist. An alternative is to indicate the targeted bean with a dependency from the <<screen>> class owning the operation to the <<bean>>. The naming convention takes precedence. 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. If the <<bean>> class is not found, an error is added to the Problems view. See also naming convention alternative above. Attributes: label: The text used for display on the screen (button label). Defaults based on the operation name. 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	This stereotype can be used with an attribute or an operation. Typical use with an attribute: with <<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). If the operation starts with 'list', the transformation will generate code to retrieve all records from the corresponding bean. The latter is identified in the same manner as the target bean for a <<useraction>>. 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 specified as enumeration literals 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 None.
<<settings>>	Class	Defines global settings : Project name: the name of the <<settings>> class is used to name the targeted projects. For instance, is the class is called 'MyWebApp', the projects MyWebApp and MyWebAppEAR are created. If the <<settings>> class does not exist, the name of the model is used instead. Main entry point: use a dependency to the main <<screen>> class. This will allow you to run the application by clicking directly on the created Web project rather than directly on the jsp file. Application name and logo: see attributes below. Relationships: (Optional) Use a dependency to the main <<screen>> class. This will allow you to run the application by clicking directly on the created Web project rather than directly on the jsp file. 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-in-pixels: Optional height in pixels. Default = 80. logowidth-in-pixels: Optional width in pixels. Default = 200.

back to top

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.

back to top