Introduction

IBM WebSphere Host Access Transformation Services is an easy-to-implement Web-to-host solution that delivers HTML to users' Web browsers, extending legacy applications to end users on the Web. HATS applications can run directly within WebSphere Portal as portlets. By integrating HATS with WebSphere Portal server, the data can flow freely between HATS, WebSphere Portal, and other portal applications.

This article provides step-by-step examples on how to implement Host Access Transformation Services V5.0 (HATS) portlet messaging. We will use the IBM Portal Toolkit for portlet development and use HATS business logic to create messaging between portlets on a Web page. Ultimately, HATS portlet messaging is an integration of HATS, WebSphere Portal, and the Portal Toolkit.

HATS takes advantage of all WebSphere Portal functions, but portlet messaging is covered exclusively in this article, which will demonstrate how to implement examples of HATS Business Logic, Global Variables, and Screen Customizations. Using HATS functions and the Portal Toolkit, we will outline the steps to develop the following application examples:

• MessageSender portlet
• MessageReceiver portlet
• Utility portlet.

Upon completion of these portlet applications, we will describe the deployment and testing steps on WebSphere Portal.

Prerequisites

This article assumes prior knowledge of WebSphere Portal and the IBM Portal Toolkit. To perform the instructions in this article, the following software must be installed and accessible in your environment:

• WebSphere Studio Application Developer Version 5.1
• Host Access Transformation Services Version 5.0
• IBM Portal Toolkit Version 5.0.2
• WebSphere Portal Version 5.0.2

The examples included here connect to a 5250 host, but a 3270 host is interchangeable.

Back to top

Create the MessageSender portlet

To create the MessageSender portlet in WebSphere Studio Application Developer (hereafter called Application Developer):

1. Create a HATS Portlet project by clicking the Create HATS Project wizard icon from the Application Developer toolbar and enter the requested information:
   1. On the Create a Project dialog (Figure 1), enter a project name in the Name field; for example, HATSMessageSender.
      Figure 1. Create a Project
      
      
   2. Check Create as a Portlet.
   3. Accept the default options as shown in Figure 1, then select Next to enter Connection information.
   4. On the next dialog, enter a Host name and the specific host information pertaining to your configuration, then select Next to select a Template.
   5. Select a Template for your HATS Portlet project, then select Finish .
2. Create business logic code that will broadcast a message to all listening portlets using the broadcastPortletMessage method (the sendPortletMessage method directs a message to a specific portlet):
   1. Right-click on the new HATS portlet project you just created and select New HATS => Business Logic (Figure 2).
      Figure 2. New Business Logic
      
      
   2. Enter a Class name for the Java™ file; for example, MessageSend in Figure 3.
      Figure 3. Create a Java Class
      
      
   3. Check Portlet Integration samples and uncheck the others, as shown in Figure 3. Click Finish to complete the Business Logic wizard.
   Note that the MessageSend file is located in the HATS Project view tree under the Project Name => Source folder.
3. Add example code in the execute method of MessageSend source file:
   1. In the MessageSend.java editor, add the following line of code to the execute method, as shown in Figure 4:
      
      

      broadcastPortletMessage(blInfo, "HATSMessageSender navigated to User Tasks Screen");

      
      
      Figure 4. Execute Method Code
      
      
   2. Save the MessageSend.java file.
4. Create a Screen Customization for the Host screen that will execute the broadcastPortletMessage code. The example screen used on the AS/400 is the User Tasks menu screen. When the user navigates to this screen, a broadcast message will be sent out to the receiving portlets stating that the user is positioned on the User Tasks menu screen:
   1. Right-click on the HATS Portlet project and select Open Host Terminal => main (Figure 5).
      Figure 5. Open the Host Terminal
      
      
   2. Logon to the host system with the applicable credentials.
   3. Navigate to the User Tasks screen via option 1. The User Tasks screen is shown in Figure 6.
      Figure 6. User Tasks screen
      
      
   4. Click the Create HATS Screen Customization icon from the Host Terminal toolbar.
   5. Enter a Name for the Screen Customization, or accept the default name, and select Next.
   6. Click Next on the Screen Recognition Criteria dialog.
   7. On the Select Actions dialog, select Prepopulated with host components in the Apply a transformation section, as shown in Figure 7.
      Figure 7. Select Actions
      
      
   8. Check Add advanced actions, then Next.
   9. On the Advanced Actions dialog (Figure 8), select Add Block Delimiter twice to create a prepresentation begin and end block for the execution of the business logic created in Step 2, above.
      Figure 8. Advanced Actions
      
      
   10. Next, click on the Add button to add an action to the list.
   11. On the next dialog, select the Execute business logic radio button, then Next.
   12. On the Define Action Properties dialog (Figure 9), either type in the class name (created in Step 2) or click the Browse button to display the Select Class dialog.
       Figure 9. Define Action Properties
       
       
   13. Select the MessageSend class by clicking on MessageSend and then OK to continue.
   14. Click Finish to complete the action properties shown in Figure 9.
   15. Finally, on the Advanced Actions dialog, under Action Type, click on Run a Java method and then the Up arrow button so the action is positioned after the Prepresentation Begin, but before the Prepresentation End, as shown in Figure 8.
   16. Click Finish to save the Advanced Actions.

The MessageSender portlet creation is complete. In the next section, we will create the MessageReceiver portlet.

Back to top

Create the MessageReceiver portlet

5. Create a new HATS Portlet project named, in our example, HATSMessageReceiver, replicating the steps above.
6. Create a Java class file and extend the EntryPortlet:
   1. From Application Developer, select File => New => Other .
   2. On the New Project dialog (Figure 10), select Java => Class, then Next.
      Figure 10. New Java Class
      
      
   3. On the Create a new Java class dialog (Figure 11), enter or select the name of the Source Folder for the new file, such as HATSMessageReceiver/Java Source.
      Figure 11. Create a new Java class
      
      
   4. In the Name field, enter a name for the class file, such as MessageReceive. The MessageReceiver portlet must extend com.ibm.hats.runtime.EntryPortlet, so enter com.ibm.hats.runtime.EntryPortlet in the Superclass field, and then Finish to save the file.
   5. In the MessageReceive java editor, right-click and select Source => Override/Implement Methods. The Override/Implement Methods dialog will display. Be sure that only the methods marked as selected in Figure 12 are checked, then OK.
      Figure 12. Override/Implement Methods
      
      
7. Implement the MessageListener with the ReceiveMessage code:
   1. From the MessageReceiver.java editor, add the implements MessageListener code, shown in Figure 13.
      Figure 13. Add MessageListener code
      
      
   2. Add the following import statements as shown circled in red in Figure 13:
      
      

      import org.apache.jetspeed.portlet.event.MessageEvent; import org.apache.jetspeed.portlet.event.MessageListener;

      
      
8. Create the messageReceived method. The sample method retrieves the message information and stores it in a shared global variable that is accessible in HATS, for example, for use with screen recognition criteria.
   1. From the MessageReceive.java editor, add the following import statements, as shown in Figure 14:
      
      

      import org.apache.jetspeed.portlet.DefaultPortletMessage; import java.util.Hashtable; import com.ibm.hats.common.GlobalVariable; import com.ibm.hats.common.IGlobalVariable; import com.ibm.hats.runtime.ClientContainer; import com.ibm.hats.runtime.ClientSpecificInfo;

      
      
      Figure 14. Add import statements
      
      
   2. Now add the following method code in the MessageReceive.java editor, as shown in Figure 15:
      
      

      public void messageReceived(MessageEvent event) throws PortletException { PortletRequest request = event.getRequest(); PortletSession session = request.getPortletSession(); DefaultPortletMessage message = (DefaultPortletMessage)event.getMessage(); ClientSpecificInfo csi = ClientContainer.getInstance().accessClient(session.getId()); String asiID = (String) session.getAttribute(EntryPortlet.SESSION_ATTR_ASI_ID); if(csi==null) { System.out.println("Unable to access csi."); return;} Hashtable gvs = csi.getGlobalVariables(); IGlobalVariable gv = new GlobalVariable("messageQueue",message.getMessage()); gvs.put("messageQueue",gv); System.out.println("Message received: "+message.getMessage()); }

      
      
      Figure 15. Add method code
      
      
9. Create a Screen Customization for the Host screen which will display the received messages (see Step 4). Our example uses the AS/400 Main Menu screen. When the user navigates to the User Tasks screen via the MessageSender portlet, a message stating "HATSMessageSender navigated to User Tasks Screen" is displayed on this Screen Customization.
   1. Right-click on the HATSMessageReceive project and open the Host Terminal.
   2. Logon to the host system with the applicable credentials. The OS/400 Main Menu screen is displayed after the logon completes, as shown in Figure 16.
      Figure 16. OS/400 Main Menu screen
      
      
   3. Click the Create HATS Screen Customization icon from the Host Terminal toolbar.
   4. Enter a Name for the Screen Customization (or accept the default name) and click Next.
   5. Click Next on the Screen Recognition Criteria panel.
   6. On the Select Actions dialog, select Prepopulated with host components in the "Apply a transformation" section, then Finish to complete the screen customization.
10. Add example code to the Transformation JavaServer Page™ (JSP™) that will display the messageQueue output. The OS_400MainMenu.jsp source file is used for our example.
    1. In the OS_400MainMenu.jsp editor, add the following lines of code to the <HATS:Form> tag section, as shown in Figure 17:
       
       

       <br>Message Queue: <%= ((TransformInfo)request.getAttribute (CommonConstants.REQ_TRANSFORMINFO)).getSharedGlobalVariable("messageQueue", true).getString() %>

       
       
       Figure 17. Add Display messageQueue Code
       
       
    2. Save the OS_400MainMenu.jsp file.
11. Modify the Web deployment descriptor to add the MessageReceive class:
    1. In the Navigator view, expand the contents of the project, HATSMessageReceiver => Web Content => WEB-INF as shown in Figure 18.
       Figure 18. WEB-INF Contents in Navigator view
       
       
    2. Double-click on the web.xml file to open the Web Deployment Descriptor.
    3. Click on the Servlets tab and select the EntryPortlet in the "Servlets and JSPs" section of the dialog, shown in Figure 19.
       Figure 19. Web Deployment Descriptor
       
       
    4. Update the Servlet class by selecting the Browse button. Enter MessageReceive in the Choose a servlet field and click OK.
    5. Save the descriptor file.

The MessageReceiver portlet creation is complete.

Back to top

Create the Utility portlet

So far, we have created two messaging portlets to run on WebSphere Portal:

• The MessageSender portlet sends a message when the user navigates to a certain host screen.
• The MessageReceiver portlet will receive the message sent by the MessageSender portlet and display that message.

We will now create a Utility portlet that will show an additional method for sending and receiving messages. This new portlet demonstrates the same functionality as the MessageSender and MessageReceiver portlets, but it uses functionality provided with the IBM Portal Toolkit.

12. To create the IBM Portal Toolkit sample Utility portlet that enables testing of portlet messaging:
    1. In Application Developer, select File => New => Project.
    2. In the New Project dialog, select Portlet Development => Portlet Application Project (Figure 20), then Next.
       Figure 20. New Portlet Application Project
       
       
    3. Enter a Project name in the input field, such as MessagingUtility (Figure 21). Make sure Create basic portlet and Configure advanced options are both selected.
       Figure 21. Define Portlet Project
       
       
    4. Click Next until the Event Handling dialog displays (Figure 22).
       Figure 22. Event Handling
       
       
    5. In the Event Handling dialog, check the following:
       • Under Portlet message event: Add message listener and Add message sender portlet sample
       • Under Event log viewer: Add event log viewer and Add edit panel to change maximum event count.
    6. Click Finish to complete the Utility portlet.
13. If Application Developer asks to switch to the Portlet perspective, select OK, since that will be used in the next section.

The Utility portlet creation is complete. Next we will deploy and test the MessageSender, MessageReceiver, and Utility portlet on WebSphere Portal.

Back to top

Deploy and test on WebSphere Portal

14. Using either the Navigator view inside the HATS perspective or the Project Navigator view in the Portlet perspective, export the three portlets just created to the file system:
    1. Right-click on the project and select Export..., as shown in Figure 23.
       Figure 23. Exporting the project
       
       
    2. Select WAR file and click Next.
    3. Enter or select the Destination for the Web project, confirming the .war file extension, and then click Finish.
    4. Repeat these export steps for the remaining two portlets.
15. Install the three portlet projects on the file system into WebSphere Portal:
    1. Open a Web browser to WebSphere Portal and select the Log in link in the upper-right corner.
    2. Log in to the server.
    3. Select the Administration link in the upper-right corner, as indicated in Figure 24.
       Figure 24. Log in to WebSphere Portal Server
       
       
    4. Select Portlets => Install from the left column, enter the portlet project WAR file name, then click Next.
    5. Click the Install button to confirm installation of the portlet selection. A successful portlet installation is shown in Figure 25.
       Figure 25. Portlet install successful
       
       
    6. Repeat these installation steps for the remaining two portlets.
16. Create a portal page and add the three installed portlets to the page configuration:
    1. Select Portal User Interface => Manage Pages from the left column, as shown in Figure 26.
       Figure 26. Manage Pages
       
       
    2. Select the My Portal link from the Title list.
    3. Since you will be testing the portlets under the Welcome page, Select Welcome, as shown in Figure 27.
       Figure 27. My Portal
       
       
    4. Click the New page button (Figure 28).
       Figure 28. Welcome
       
       
    5. Enter a Title for the new page and expand Advanced options (Figure 29).
       Figure 29. New Page creation
       
       
    6. Click the single box frame radio button indicating page properties (Figure 29) and click OK. Click OK again on the confirmation screen.
    7. Click the Edit Page Layout icon, indicated in Figure 30.
       Figure 30. Edit Page Layout
       
       
    8. Click the Add portlets button.
    9. Navigate and select the checkboxes to add portlets to the portal page, as shown in Figure 31, then select OK.
       Figure 31. Select portlets to add
       
       
    10. Confirm the portlet additions and alignment. Use the Up and Down arrowhead icons to rearrange the ordering, then select Done when finished.
17. Test the portlets' messaging capabilities:
    1. Select My Portal in the upper-right corner.
    2. Select the HATS Messaging Portlets link, shown in Figure 32.
       Figure 32. Select the Messaging Portlets
       
       
    3. The four portlets are displayed on one page in the browser window. Refer to Figures 33 through 35 for sample screens of each portlet.
       Figure 33. MessagingUtility Portlet
       
       
       Figure 34. MessageReceiver Portlet
       
       
       Figure 35. MessagingSender Portlet
       
       
    4. Logon to the HATSMessageSender portlet (Figure 35) and navigate to the screen customized to send the broadcast message. The HATSMessageSender portlet was customized to broadcast a message on the User Tasks menu screen. When the User Tasks menu screen is displayed (Figure 36), a broadcast message is sent to the MessagingUtility portlet and the HATSMessageReceiver portlet.
       Figure 36. MessagingSender Portlet navigates to User Tasks screen
       
       Refer to the MessagingUtility sample screen (Figure 37) to see the list of recent events.
       Figure 37. MessagingUtility Portlet displays events from MessagingSender Portlet
       
       To see the broadcast message with the HATSMessageReceiver portlet, logon to the HATSMessageReceiver portlet and navigate to the OS/400 Main menu, which is where the HATSMessageReceiver portlet was customized to display the message. The broadcast message can be seen in Figure 38.
       Figure 38. MessagingReceiver Portlet displays events from MessagingSender Portlet
       
       
    5. A broadcast message can also be sent using the MessagingUtility portlet (Figure 33) by entering a message in the Enter message input field and then selecting Submit (Figure 39).
       Figure 39. MessagingUtility Portlet broadcasts message to receiving portlets
       
       The HATSMessageReceiver portlet receives the broadcast message and displays it, as shown in Figure 40.
       Figure 40. MessagingReceiver Portlet displays events from MessagingUtility Portlet
       
       

Back to top

Conclusion

We have completed the steps for implementing portlet messaging while integrating HATS and the IBM Portal Toolkit. The information in this article, while based on a simple scenario, provides the framework for using HATS Business Logic, Global Variables, and Screen Customizations, and should be helpful for implementing similar messaging functionality in your own portal applications.

Resources

• Browse for books on these and other technical topics.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Create the MessageSender portlet
• Create the MessageReceiver portlet
• Create the Utility portlet
• Deploy and test on WebSphere Portal
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Host Access Transformation Services Toolkit
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: Host Access Transformation Services Toolkit

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers