Level: Intermediate Murray Beaton (beatonm@ca.ibm.com), Advisory Software Developer, IBM
Jim Bonanno (bonanno@us.ibm.com), WebSphere Portal Development, IBM
Dorian Birsan (birsan@ca.ibm.com), Advisory Software Engineer, IBM
08 Nov 2005 Why spend your time struggling with the details of portlet APIs and best programming practices, when you can construct your portlets visually in Universal Modeling Language (UML)? This article extends Part 8 of the series, which explains how to use Enterprise Patterns to quickly build Java™ 2 Platform, Enterprise Edition (J2EE) applications using IBM Rational® Software Architect. Rational Software Architect now supports IBM State Oriented Portlet Patterns that help you rapidly architect and generate a complete portlet application for IBM WebSphere® Portal. Discover how to use these patterns and a model-driven approach to produce portlets in a fraction of the time.
Introduction
This article extends Part 8: Build J2EE applications with IBM Rational Software Architect of the series. In this article (Part 14 in the series), you use the newly released State Oriented Portlet Patterns to build and deploy portlets to front the application. You'll discover how State Oriented Portlet Patterns can help you rapidly build a portlet on WebSphere Portal Version 5.1. And you'll also find out how to configure click-to-action (C2A) capability between portlets using stereotypes defined in a profile.
Understanding State Oriented Portlet Patterns
The State Oriented Portlet Patterns are packaged as a reusable asset that can be imported and installed into Rational Software Architect. You can architect a complete portlet application, without venturing beyond the Unified Modeling Language (UML) modeling capabilities of Rational Software Architect, through visual construction of portlet state transitions using a UML state machine.
 | State Oriented Portlet Patterns The State Oriented Portlet Patterns Rational Software Architect Asset models portlet state transitions using a UML state machine. It includes patterns that capture portlet view and portlet transition data. It supports popular portal features such as portlet modes and click-to-action capability. Using this asset, a complete portal application can be generated. Users can add their own business logic at architected locations. The best practices encoded by this pattern are harvested from IBM Software Services engagement experiences. |
|
You can also refine portlet behavior and preferences using patterns. Although creating portlets visually is a new experience, portlet concepts such as model view controller (MVC) patterns, portlet modes, and C2A are upheld. Once the portlet architecture is defined, a complete portlet project can be generated in Rational Software Architect that can be deployed on WebSphere Portal V5.1. The State Oriented Portlet Patterns include:
- Portlet
- A Portlet Pattern acts as the main entry point to the State Oriented Portlet Patterns. It allows binding of a state machine for use with other state patterns. Since states are not available to bind directly to a pattern parameter, it also builds a <<States>> enumeration for consumption by other patterns.
- Portlet View
- The Portlet View Pattern is responsible for associating views and data to accompany a state as defined by a state machine. To bind a state, you should choose an enumeration literal from the states bound to a Portlet Pattern. The data bound to a Portlet View is used to define the view bean for the bound state. Additional parameters and transition data can also be associated with a Portlet View.
- Transition Data
- Transition Data is used to define data for the application that exceeds the lifetime of the request. The generated view bean is created from the Portlet View Pattern and defines the navigational state for the portlet state. The transition data is used to define data that can be persisted between requests and can include storing data in session or portlet data.
 |
Installing State Oriented Portlet Patterns
State Oriented Portlet Patterns require Rational Software Architect V6.0.0.1 or V6.0.1, including the Portal Tools optional component. To install the State Oriented Portlet Patterns, launch the New Repository Connection wizard from the RAS (Reusable Assets) Perspective, and select DeveloperWorks Repository, as shown in Figure 1.
Figure 1. DeveloperWorks Repository Connection
After successful connection, the State Oriented Portlet Patterns is visible in the design_j2ee folder. Select Import, as shown in Figure 2.
Figure 2. Importing State Oriented Portlet Patterns Asset
The State Oriented Portlet Patterns will appear in the Pattern Explorer, as shown Figure 3.
Figure 3. Viewing State Oriented Portlet Patterns in Pattern Explorer
Understanding Enterprise Patterns and the ODFinance scenario
In Part 8, we use the Enterprise Patterns to create the Session Facade, Business Delegate, Entity beans, and Message Facade code. Together, they provide the function on the service provider side.
In this article, you learn to:
- Extend the underlying schema (from Part 8) to generate a portlet application to perform create, retrieve, update, and delete (CRUD) requests using WebSphere Portal.
- Build state machines using the stereotypes supplied in the State Oriented Portlet Patterns profile.
- Leverage the State Oriented Portlet Patterns to configure the properties and behavior of the state machine.
We'll also build a second portlet application to illustrate how the State Oriented Portlet Patterns support advanced features, such as C2A.
Implementing a CRUD access portlet with the existing application can be done several ways. Accessing the entity beans with a Business Delegate is one possibility and may be desirable for remote applications. In this example, we facilitate CRUD access by providing simplistic data classes to represent the tables in the schema.
Building the CRUD state machine
As mentioned, state machines lets you capture portlet transitions in a visual manner. In this example, we will build two portlets -- CustomerApp and CustomerDetails. The CustomerApp portlet will capture the flow of a typical CRUD portlet, and CustomerDetails will be a simplistic display portlet for showing customer details.
To build the customer portlet, you can start by creating a new UML model (for example, CustomerApp) and applying the State Oriented Portlet Profile. The State Oriented Portlet Profile provides several stereotypes for annotating UML classes and state diagrams. To apply the profile, simply select Profiles in the model properties and click Add Profile. Select State Oriented Portlet Profile, as shown in Figure 4.
Figure 4. Adding State Oriented Portlet Profile
Next you need to add a UML package (com.ibm.customer.app, for example) to capture future artifacts. Select the model and choose Add UML > Package, as shown Figure 5.
Figure 5. Creating a package
Now you're ready to build a state machine to capture the flow of the CustomerApp CRUD application. Begin by adding a new state machine UML element by selecting Add UML > state machine. In the resulting state machine diagram, use the palette to create an initial (pseudostate) node. Also create three basic states: main, update, and delete. Using the Transition type from the palette, connect the states as shown in Figure 6. This figure also shows the completed CRUD state machine portlet.
Figure 6. CustomerApp state machine
After completion of the transitions, proceed to annotate the state diagram using the State Oriented Portlet Profile. For example, to annotate the transition from the initial pseudostate to main state, first highlight the transition object in the diagram. In the Properties view, select Stereotypes > Add Stereotype. Proceed to add initial, as shown in Figure 7.
Figure 7. Transition Stereotypes
A number of stereotypes have been applied to the previous state machine, indicated by the <<>> brackets. For example, we annotated our initial pseudostate as <<view>> mode. Alternatively, we could have chosen Edit, Help, or Configure. We also leveraged various transition stereotypes. For example, <<initial>> is used to annotate transitions from an initial pseudostate, and <<link>> is used to annotate transitions that appear as links in the final portlet page. For detailed explanations of all available stereotypes in the State Oriented Portlet Profile, see the pattern documentation.
With our state transition flow defined in our state machine diagram, we can now apply some State Oriented Portlet patterns.
Applying the Portlet Pattern
To apply the portlet pattern, select the Portlet Pattern from the Pattern Explorer, and drop it into a freeform diagram. For example, a main freeform diagram is created during model creation unless you select otherwise. Note that you cannot drag patterns into state diagrams. However, to achieve a consolidated view of your artifacts, you can drag state machines into freeform diagrams.
Bind the CustomerApp state machine to the Portlet [1]parameter in the Portlet Pattern, as shown in Figure 8, then enter CustomerAppStates for the States [1] parameter.
Figure 8. Portlet pattern
Applying the Portlet View Patterns
The next step is to define the views associated with the portlet states using the Portlet View pattern. In our example, four views are configured. The Delete and Update states require one view each of kind Delete and Update respectively, and the Main state requires two -- one for displaying the current customers and another for inserting new customers. To construct a portlet view, select the Portlet View pattern from the Pattern Explorer and drop it into your diagram. Repeat this step three times to construct the remaining views required. Figure 9 shows the completed application.
Figure 9. Completed CustomerApp model
See a larger version of this figure.
As shown, four Portlet Views are defined for the portlet. Binding of states to Portlet View Patterns is accomplished through the State [1] parameter. The Kind [1] parameter captures the view kind, which is restricted to Insert, Update, Delete, or Display. Portlet views of kind Display transform to HTML tables, whereas Insert, Update, and Delete transform to HTML forms. For a detailed description of the Portlet View Pattern or any other pattern (or its parameters), see the documentation available from the Pattern Explorer.
For Main state, two Portlet View Patterns are defined: one to capture displaying of customers and another to facilitate inserting new customers. Notice both patterns work from the same data class Customer, but the isMultiple value varies. The Display Portlet view is responsible for rendering all customers; therefore the isMultiple value is true. Insert, however, deals with a single customer object, so its isMultiple value is false. The same applies to the Portlet views defined for the update and delete states. The customer data class in the top left is a UML representation of the underlying customer table schema.
Applying the Transition Data Pattern
Transition Data is used to define data for the application that exceeds the lifetime of the request. The generated view bean is created from the Portlet View Pattern and defines the navigational state for the portlet state. The transition data is used to define data that can be persisted between requests, which can include storing data in session or portlet data. In our example, the Transition Data Pattern is completed, as shown in Figure 10. This transition data is bound to all of the Portlet Views configured earlier in Figure 9.
Figure 10. Transition Data Pattern
The CRUD application is complete at this point. Next we'll link to another portlet using C2A.
Collaborating with a CustomerDetails portlet using C2A
Now that our CRUD CustomerApp portlet is complete, we can build a new portlet to show customer details to be linked using C2A. The CustomerApp portlet, in this scenario, is considered to be the source portlet. Enabling C2A on a source portlet requires annotating a field on the data class with the <<click-to-action>> stereotype found in the State Oriented Portlet Patterns Profile.
The <<click-to-action>> stereotype has a property called c2atype, which is the name of the type used for matching portlets that can receive C2A messages. The namespace for the C2A matching is specified during transformation time. C2A tags leverage the namespace and the type to create the visuals during runtime. If no matches are found, the C2A icon will not appear when the portlet is rendered. Figure 11 shows the updated data class and the properties associated with the <<click-to-action>> stereotype.
Figure 11. C2A configuration on source portlet
Once our source portlet is C2A enabled, we can build a target portlet, CustomerDetails, to display the details of an individual customer. The customer details shown in the CustomerDetails portlet depend on the customer selected in the CustomerApp.
Because we are building a new portlet, a new state machine is required to capture states and transitions just as before. It is recommended that the new state machine, and its related artifacts, reside in a new model.
You can enable a portlet to receive broadcasted C2A messages by annotating a transition from an entry point with the <<c2a>> stereotype, also contained in the State Oriented Portlet Profile. Entry points serve as anchor points for <<c2a>> transitions and as visual cues for C2A configurations. The <<c2a>> stereotype has several properties that must be set to ensure notification from a source portlet. In this scenario, we are interested in the customerNumber field from the CustomerApp portlet data class; as a result, we should specify consumesType as customerNumber. The C2A namespace, as before, is specified during transformation and must match that of the CustomerApp portlet. Figure 12 shows the completed state machine diagram and the properties for <<c2a>>.
Figure 12. CustomerDetails state machine diagram
Having completed our state machine diagram to capture our state transition flow, we proceed to apply some State Oriented Portlet patterns as in the CustomerApp portlet.
The Portlet and Portlet View Patterns are leveraged in the same fashion as before. We first bind the state machine to the Portlet pattern and define its corresponding states enumeration. Then, using the Portlet View Pattern, we define two portlet views, MainShow and DisplayCustomerDetails. Figure 13 shows the completed CustomerDetails portlet.
Figure 13. Completed CustomerDetails portlet
The application is now complete and ready for transformation to source.
Running UML-to-portlet transformation
The UML to portlet transform is included in the State Oriented Portlet Patterns asset. You can use this transform to generate a complete Portlet Project for Rational Software Architect. Since we have built two portlets, we will invoke the transform twice, each time specifying a different portal project. From the Modeling perspective, highlight the CustomerApp model, and select Transform > Run Transformation > UML to Portlet to invoke the transform, as shown in Figure 14.
Figure 14. Invoking UML to Portlet on CustomerApp model
In the resulting wizard, choose to Create a Target Container. Enter CustomerApp as the project name, and unselect the Create a portlet checkbox if necessary, as shown in Figure 15.
Figure 15. Portlet Project creation
Select the Messaging tab from the transformation wizard and select Enable Click-to-Action, as shown in Figure 16. You can accept the default for the namespace or choose another.
Figure 16. Enabling click-to-action
Select the CustomerApp project in the transformation wizard, as shown in Figure 17. Select Run.
Figure 17. Project selection
Repeat the steps above for the CustomerDetails model, using a new Portlet project called CustomerDetails. Be sure the value for the Click-To-Action Namespace under the messaging tab matches the previous invocation for the CustomerApp portlet.
Most of the generated portlet code is complete, but you need to implement the application business logic in the controller/access class located in the portlet package. For this scenario, this means implementing CustomerAppAccess and CustomerDetailsAccess. Listing 1 shows the implementation for one of the CustomerAppAccess methods. Select the download icon to obtain complete working implementations for your reference.
Listing 1.CustomerAppAccess.java
/**
* @generated UML to Portlet (com.ibm.xtools.transform.uml2.portlet.transformation)
*
* Performs the business logic required
*
* @param Customers customerAttribute
* @param Customer customer
*
* @exception MainInsert_CreateCustomer_Success_Exception
*/
public void doMainInsert_CreateCustomer(Configuration configBean, Customers[]
in_customerAttribute, Customer in_customer) throws MainInsert_CreateCustomer
_Success_Exception {
try {
MainViewBean out_ViewBean = new customer.app.view.MainViewBean();
Customers[] out_CustomersName = new customer.app.Customers[0];
Customers[] out_CustomersName = createCustomer(in_customerAttribute,
in_customer);
out_ViewBean.setCustomers(out_CustomersName);
throw new MainInsert_CreateCustomer_Success_Exception(out_ViewBean, out_CustomersName);
} finally {
}
}
|
Figure 18 shows the portlets deployed to WebSphere Portal 5.1
Figure 18. Deployed portlets
Summary
In this article, you used the recently released Rational Software Architect State Oriented Portlet Patterns to help you rapidly build a portlet application on WebSphere Portal V5.1. You also discovered how to build CRUD support around existing schemata; for example, the schema in Part 8. As more and more reusable patterns are captured in Rational Software Architect, more of the best practices can be automatically generated, reducing the development time and improving overall quality.
Download
Resources Learn
Get products and technologies
About the authors | 
| | Murray Beaton is an Advisory Software Developer for the On Demand Software Development team. Murray's previous role was as a Technical Team Lead with WebSphere Studio Application Developer. Contact Murray at beatonm@ca.ibm.com.
|
| 
| | Jim Bonanno is a Senior Programmer at IBM currently working for the On Demand Software Development team. Jim was previously responsible for integrating the Jakarta Struts framework into the WebSphere Portal product. |
| 
| | Dorian Birsan currently works with the IBM On Demand Software Development team, where he is focused on architecting and developing assets around various service-oriented architecture (SOA) technologies. He has also played an active role in the Eclipse Platform since its inception and led various projects on application development tools at the IBM Toronto Lab. Contact Dorian at birsan@ca.ibm.com. |
Rate this page
| 
