Introduction

This article introduces the command bean framework of the User Interface Generator for IBM InfoSphere Master Data Management (MDM) Server. The User Interface Generator lets you generate role-based user interfaces from a UML user model. The UML user model describes the ways in which users will interact with the system.

The User Interface Generator provides tooling that allows a user model to be transformed into several components that make up a generated Web application. One of the generated components is the Java command bean stubs. Generated command bean stubs act as a link between the generated user interface layer and the back-end services connected to the user interface. The generated command bean stubs can be extended to provide a connection into any new or existing services available inside an organization. This connection allows data to be passed from the existing services into the generated user interface.

In this article, it is assumed that the User Interface Generator tooling is installed into Rational Software Architect (RSA), and that a valid user model has been constructed. You will learn how to use the tooling to generate the command beans, and about the artifacts that are generated. You will also learn how these artifacts can be used to connect the generated user interface to a back-end system.

Back to top

Sample model

This article refers to the sample model provided in the Downloads section. The sample model is one of several samples included with the User Interface Generator. This model is a small, simple model that provides enough information to understand the concepts you'll be working with. The model can be imported into your RSA workspace by importing the SampleModel.zip as a Project Interchange resource. Figure 1 shows the sample model.

In the model you can identify a number of components that we want to be available in the generated code. There is a <<user_task>> named UpdatePerson, and that task has three associated relationships:

• <<select>> PersonFilter
• <<view>> Person
• <<update>> Person

The model has two user objects:

• Person
• Car

The model also has one Filter:

• PersonFilter

The User Interface Generator will interrogate this model; capture all of the objects, properties, and associated relationships; and generate the commands beans required. For more information about constructing a user model, see Build a user model with Rational Software Architect and the User Interface Generator.

Back to top

Generating command beans

The User Interface Generator tooling includes a wizard that steps through the process of generating the artifacts required for the user interface. For this exercise, you will concentrate only on the command bean generation.

1. Make sure you are in the Modeling perspective in RSA.
2. From the menu, select Modeling -> User Interface Generator.

   The wizard should then appear.

3. On the first page select only Command Beans.

   The first time the wizard is executed you must generate the command beans and the Web application projects, due to a dependency that the generated command bean project has on the Web application. Once the web application projects exist, you only need to generate the command bean project.

4. In the User Models field, add a valid user model.
5. Click Next, as shown in Figure 2.

The next window requests information concerning the command beans that will be generated. As shown in Figure 3:

1. Enter an Organization name.
2. Enter a valid Java project name for the Command beans project.
3. Enter a valid Java package name for the generated Command beans package.
4. Do not check the box to Generate default command bean implementation code.
5. Click Next.
6. Enter names for the WAR and EAR projects.
7. Click Finish.

The wizard will now launch the transformation, and generate the command beans described in the user model into the project specified in the wizard.

Generate default implementations

You can generate some basic implementation code for the command beans automatically. The basic implementation code provides just enough code in the command beans for the generated user interface to function without any additional coding, letting you visualise how the model will look in the user interface. Data is persisted using a file store on the local file's system. This function is designed to only be used for demonstration and education purposes; it is not recommended that production systems use the default implementations.

Back to top

Generated components

After running the wizard, a new project will be created in your RSA workspace with the name that was specified. The files that were generated are shown in Figure 4.

Back to top

Command framework classes

Several classes are always generated by the User Interface Generator regardless of the contents of the supplied user model. These classes are for implementing the core framework provided by the User Interface Generator, and providing an entry point into the framework for developers.

Most classes relating to the command framework will be generated and placed into the com/ibm/mdm/parsimony/commands/ package. Advanced users of the User Interface Generator tooling are advised to become familiar with the code inside this package. However, in most instances there is no need to change any of the classes contained within it.

CommonCommand

The CommonCommand class is the super class of all the generated command beans. It extends and implements classes that are vital to the User Interface Generator command framework. All command beans must extend this class, or one of its children, to be considered a valid command bean.

This file contains any common methods that are available across all of the command beans. You may add additional code to this class if you think it should be available to all instances of the command beans.

KeywordCommand

KeywordCommand extends CommonCommand, and is the super class of any command beans that use one of the reserved keywords. (See the User Interface Generator User Guide for more details.) This abstract class provides an implementation of the execute() method, which takes care of getting the correct scope for the users attributes in the context.

Command beans

The User Interface Generator will generate command beans for each <command> node specified in the supplied user model.

Command beans will be generated and placed into a location equal to <user_supplied_package>/commands/, where <user_supplied_package> is equal to the path specified in the wizard.

Command beans allow an implementer to provide their own code to interact with the application's back-end services. The generated command beans provide stub implementation code to help you in your implementation. Central to this implementation is the context.

Context

The context, available from the CommonCommand’s super class ContextAwareImpl, is a shared container that's used to set and get attributes to/from. The context is shared across a user’s session. Any data that is set into the context during the user's session will be available from another command bean within the same session, unless it has been explicitly removed or overwritten.

In most instances, the primary job of the command beans will be to retrieve an object from the context, manipulate it in some way, then set it back to the context, allowing the generated user interface to display this information to the user.

User objects

User objects provide a representation of the <<user_object>> and <<user_datatype>> stereotyped classes on the supplied user model. The User Interface Generator uses the Eclipse Modeling Framework (EMF) to generate a series of interfaces and implementations of these user objects. The objects can then be used by the command beans to get and set data to them, and pass them through the context into the user interface. The structure of the user objects is taken directly from the user model, so it's unlikely there will be a need to customize the code within these objects directly. For this reason, the user objects are generated into the src/internal directory of the command bean project.

Each property, as defined in the class diagram for a user object, will be represented in the generated code as a property of that user object and will have related accessor methods. These accessor methods should be used by the command bean code that the implementer will be providing.

Filters

Filters refer to objects that have the <<user_object_Filter>> stereotype applied to them. Filters can be applied to a user object, and they provide a subset of the user object's properties to the user interface. For more information see Part 1.

Like user objects, filters are also generated using EMF. They are generated as super classes to the associated user object, allowing them to only deal with a subset of properties associated with the child user object.

Each property, as defined in the class diagram for a filter, will be represented in the generated code as a property of that filter and will have related accessor methods. These accessor methods should be used by the command bean code that the implementer will be providing. It is unlikely that the generated code within the filter will need to be changed, as it describes the <user_attributes> specified in the supplied user model.

User attributes

Each user object can have properties associated with it. These properties are known as user attributes. Each user attribute must have the stereotype <user_attribute> assigned to it, which ensures that the User Interface Generator will see these properties as valid user attributes that should be included in the generated code.

Simple user attributes

User attributes can be either simple or complex. Simple user attributes have a primitive type assigned to them. The example below shows that the Person user object has four simple attributes, all of primitive type String.

To ensure that the transformation knows that these user attributes are required in the generated code, each of the attributes has the <user_attribute> stereotype applied to them.

Complex user attributes

Complex user attributes are similar to simple user attributes in that they are still considered properties of the parent user object. However, their type is not primitive. In the example in Figure 6, the Person user object has several complex user attributes and the original simple user attributes in the previous section.

In the example in Figure 6, Person has the following complex user attributes:

• Car of type Car
• Child of type Person
• Parent of type Person

The user object Car also has the following attributes:

• Complex user attribute named owner of type Person
• Simple user attribute named cc of type Integer
• Simple user attribute named model of type String
• Simple user attribute named make of type String

Complex user attributes also require that the <user_attribute> stereotype be applied to them. The stereotype should be applied to the role name of the user attribute and not the object to which it is referring. In the example below, the <user_attribute> stereotype would be applied to the parent, child, owner, and car roles.

Dynamic enumerations

User attributes can also have a <dynamic_enum> stereotype applied. Making a user attribute a dynamic enum allows the user attribute to be supplied a list of values that, when executed in the UI, will display a list of values for the user to select one or more options from. User attributes that have the <dynamic_enum> applied to them require additional code to be generated. The additional code will be placed in a location equal to:

<user_supplied_package>/commands/enums

Where <user_supplied_package> is equal to the path specified in the wizard.

The code supplied into the dynamic enum command bean will be executed on load of the page to retrieve a list of values from a back-end system.

Role names

The role name on the relationships between user objects is given default values by the modeling tools. At generation time, the role names are used to form the names of the properties within the user objects. It is therefore advisable to change these default role names to something more meaningful so the names of the user objects properties are descriptive. User objects cannot have more than one role with the same name.

Resources directory

The resources directory contains several supplementary files required by the User Interface Generator. The files are generated and, in some instances, allow customization of the command framework and generated user interface. The files are described below.

commands.properties

Contains the mappings between the name of the command bean on the user model and the name and location of its associated Java file. In an instance where a command implementer wishes to create their own command beans in addition to those generated, an associated mapping must be added to this file.

userdirectory.properties

Is used by the default implementation of the user interfaces authentication mechanism to store user credentials. Also contains the name of the authentication implementation class.

For information on how to extend the default authentication mechanism, see the User Interface Generator User Guide.

ui.properties

Contains important configuration settings for the user interface, such as default field size and location of field labels.

For information on how to change this file, see the User Interface Generator User Guide.

organization.orgmodel

Is an EMF representation of the supplied user model. The User Interface Generator uses the information in this file at run time to understand the relationships between the various components of the UML model.

This file can be viewed using the orgmodel editor. You can add tasks, roles, and goals to this file and the changes will be reflected in the user interface. The changes will be lost, however, the next time the transformation is executed. It's recommended that you make such changes directly to the source UML model.

Back to top

Implementing the command beans

In this section you learn more about the generated command beans, and create an implementation that will connect into the back-end services. Topics include:

• The generated command beans
• Extending the command beans
• @generated
• Command beans for filters

Reviewing the generated command beans

Although the code for each of our generated command beans will differ slightly, most experienced Java programmers will understand the differences when compared to the example below. This example uses the CreatePerson command bean.

The class definition extends KeywordCommand, ensuring that this is a valid command bean and that you have all common methods and fields available to you. It also handles the order in which the methods in this class are executed.

public class CreatePerson extends KeywordCommand {

You then define a List of Person objects. This has been defined, as you can see in Figure 1, because <<view>> Person has a relationship to a Person object. You create a list to store these Person objects. Often, the list might contain only one Person, but to allow for multiplicity we use a list. The example implementation must create Person objects and add them to this list.

private List<Person> personList;

The doExecute() method should be used to provide the custom command bean implementation. The User Interface Generator provides a mechanism that requires just this method to be updated to call into back-end services. It is in here that the implementer will add code to create instances of Person and add them to the personList.

/**
 * Provide your implementation here.
 * 
 * @generated
 */	
private String doExecute() {
	//Provide your implementation here	
	return getGuard();
}

The doIntialize() method handles the calls to retrieve the personList from the context if it has been set there from a previously executed command bean. If a personList is found in the context, it returns that personList for manipulation by the user in the doExecute() method. If no personList is found, then a new ArrayList is created and passed back.

protected void doInitialize() {
	ContextScope contextScope = getContextScope();
	personList = null;
	Object objectInContext = contextScope.getObjectFromContext(
		getContext(), getKey());
	if (objectInContext instanceof List) {
		personList = (List) objectInContext;
	}
	if (personList == null) {
		personList = new ArrayList();
	}
}

It is the job of the doFinalize() to set the personList back to the context after it has been manipulated in the doExecute() method. It does this by getting the existing context and setting the personList to it.

protected void doFinalize() {
	ContextScope contextScope = getContextScope();
	contextScope.setObjectToContext(
		getContext(), getKey(), personList);
}

Each command bean has a getKey() method, which returns the name of the current class. This is then used as the key in the context for getting and setting the instance of this command bean.

protected String getKey() {
	return Person.class.getName();
}
            

Extending the command beans

The generated command beans have been designed to ensure that connecting to existing back-end services is as easy and flexible as possible. These services can be called from the doExecute() method, and the returned data put into the List from context, with very few lines of code.

The example uses the SelectPersonFilter command bean that has been generated from the SampleModel example. You are going to extend the doExecute() method to call a fictional set of back-end services that are available inside our organization. The services that will be called are available in the Samples.jar file that accompanies this article.

1. Run the User Interface Generator transformation on the Sample Model and generate the command beans and Web Application.
2. Import the Samples.jar into the generated EAR file.
3. Add a dependency from the generated command bean project to the Samples.jar by ensuring it is checked in the J2EE module dependencies properties dialog, as shown below.
   
   Figure 7. J2EE dependency properties
   
   
   

To update the doExecute() method to call the services that exist in the samples.jar:

1. Open the generated SelectPersonFilter command bean.
2. Add an import statement for the package of the CustomerRecordRetriever class.

   import org.example.services.*;

   
   

3. Provide an implementation for the doExecute() method. The implementation should call the getAllCustomerRecords() method of the CustomerRecordRetriever. It should then iterate through all the returned records and create instances of PersonFilter. The instances can be added to the list. The command bean framework will take care of passing this data into the generated user interface.

   protected String doExecute() { //Call our service to get all customer Records ArrayList<CustomerRecord> customerRecords = (ArrayList)CustomerRecordRetriever.getAllCustomerRecords(); /* *Loop though them, create personFilters with the values from *each customerRecord that has been found in the back end. Add *the new objects to the list on context */ for (CustomerRecord customerRecord : customerRecords) { PersonFilter personFilter = SampleFactory.eINSTANCE.createPerson(); personFilter.setForenames(customerRecord.getFirstName()); personFilter.setSurname(customerRecord.getLastName()); personFilterList.add(personFilter); } return getGuard(); }

   
   

4. Update the javadoc comment for the doExecute() method to read @generated NOT
5. Save the command bean.
6. Open the generated PersonTitleEnum command bean in the .enums package. This enum command bean has been generated as the Title <user_attribute> in the model, and had the <dynamic_enum> stereotype applied.

   By adding values to the list in this class, they will display in the user interface as an option in a drop-down box.

7. Update the doExecute() method so that the enumList is being populated with values.

   protected void doExecute(Person owningUserDatatypeInstance) { enumList.clear(); enumList.add("Mr"); enumList.add("Mrs"); enumList.add("Miss"); }

   
   

8. Update the javadoc comment for the doExecute() method to read @generated NOT
9. Save and close the command bean.
10. Start your server and run the Update Person task. The first step in the task will show the records returned from the call to the CustomerRecordRetriever service, as seen in Figure 8.
    
    Figure 8. The generated user interface
    
    
    

This example showed how a command bean of type select can be implemented to call existing back-end services. The same principles can be applied in other types of command beans, where services are used to either add or remove objects from the lists in context.

@generated

Typically, command beans are regenerated several times during a development iteration. For this reason, the User Interface Generator uses EMF’s @generated tag notation. All methods that are generated by the User Interface Generator will contain an @generated tag in the javadoc comment. The @generated tag informs the User Interface Generator that this method has previously been generated.

When a method is modified, such as the doExecute() method, it is important that the tag is updated to read @generated NOT. This tells the User Interface Generator that changes have been made to this method, and it should no longer be overwritten by the User Interface Generator code generation. Failure to update the javadoc comment will result in the method being overridden the next time the transformation is executed.

Command beans for filters

You can generate command beans that work with a <user_object_filter> rather than a <user_object>. You can see an example of this with the sample model where there is a relationship from the Update Person Task to the PersonFilter, as shown below.

In this case, the generated command bean works with instances of the filter rather than instances of the underlying user object. These instances are set back into the context with the doFinalize() method as previously stated, but using the key of the underlying user object. If these filter instances are retrieved from the context by another command bean, then they can be pulled from the list as instances of the underlying <user_object>. This is possible because of the Java inheritance that's being enforced in the structure of the generated user objects and filters.

Back to top

Summary

This article outlined the artifacts that are generated by the User Interface Generator. You explored the uses of these generated components, and the design behind the command framework API. You learned how the generated command beans can be extended to use existing services to connect the generated application to back-end data.

The User Interface Generator's command framework offers vast flexibility for you to connect your generated user interface into existing services. It provides a mechanism that lets you focus on working with the services instead of being concerned with passing that data into the user interface.

Back to top

Downloads

Information about download methods

Resources

Learn

• Learn more about user modeling concepts from the User modelling demystified series (on developerWorks).
  
  
• The User Interface Generator is a component of the MDM Workbench, which is available as part of IBM InfoSphere Master Data Management Server.
  
  
• The MDM developerWorks space contains articles and forums with useful information for users of the MDM Workbench and the User Interface Generator.
  
  

Get products and technologies

• Download a trial version of Rational Software Architect.
  
  
• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Jay Limburn, MBCS CITP, has worked for IBM since 2000. He is an IBM Senior Inventor, and is currently a senior software engineer in the software group Information Management division in Hursley UK. As the technical lead on the User Interface Generator, Jay guides the technical direction of the User Interface Generator and leads the team in fulfilling delivery commitments. Previously, Jay worked in a technical client-facing capacity in various software group services, predominantly within the Lotus brand, where he was a leading technical consultant on WebSphere Portal Server. His areas of expertise include model driven development, solution delivery and design, Eclipse, and J2EE technologys. Jay has produced a number of publications on these topics, and has filed six patents.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Sample model
• Generating command beans
• Generated components
• Command framework classes
• Implementing the command beans
• Summary
• Downloads
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers