Overriding HATS portlet connection parameters using the WebSphere Portal V6 Advanced URL generation API

Empower users to select their preferred system at run time

IBM® WebSphere®Host Access Transformation Services (HATS) developers can use portlets to provide graphical user interfaces for character-based 3270 and 5250 host applications. They can specify defaults for required connection parameters; however, sometimes their users need to modify the connection parameters at run time. This article shows HATS developers how to use the advanced URL generation API capabilities in WebSphere Portal Version 6 to enable their users to override connection parameters in a HATS portlet application. To get the most out of this article, you should have basic HATS skills and be familiar with portal technology and portlet development.

Share:

Hung Lam (hungvlam@us.ibm.com), Software Engineer, IBM

Hung Lam photoHung Lam is a software engineer at IBM in Research Triangle Park, North Carolina. He joined IBM in 1999 and works on the WebSphere Host Access Transformation Services development team. His main areas of focus are HATS toolkit and portlet components.



14 November 2007

Introduction

In this article, you learn how to leverage the advanced URL generation API that are provided by WebSphere Portal V6.0. Specifically, you see how to implement connection parameter overrides in a IBM WebSphere Host Access Transformation Services (HATS) portlet application.

HATS enables you to build Web applications, including portlets, that provide an easy-to-use graphical user interface for your character-based 3270 and 5250 host applications. You can use a single HATS portlet to transform different host applications or to provide a different look-and-feel for the same application through the use of connection parameter overrides. For more information on HATS, see the IBM WebSphere Host Access Transformation Services V7 Information Center.

You might need to use using connection parameter overrides for a variety of reasons, such as enabling your users to override the LUName. The developer configures and assigns each LUName with specific printers. For example: LU00001 is associated with a printer in an office in Research Triangle Park, and the LU00002 is associated with a printer in an office in New York City. Depending on the office location, the user can sign in to the application with the correct LUName so that print jobs go to the correct printer.

This article describes the steps to create a portlet solution to transform different host applications based on the user’s selections. The solution involves these tasks:

  • Create two portlets: a HATS portlet that transforms the host applications and a JSR 168 non-HATS portlet that displays a list of host applications. When the user selects a host application from the JSR 168 portlet, the selection is sent to the HATS portlet to process.
  • Deploy the portlets on WebSphere Portal, and configure custom unique names for the portal page and for the HATS portlet.

If you work through the exercise, you produce a portal page that contains the JSR 168 portlet shown in Figure 1 and another portal page that contains the HATS portlet. Clicking a host application link on the JSR 168 portlet page invokes the HATS portlet which connects to the selected host application.

Figure 1. JSR 168 portlet page that contains 2 host application links
Figure 1. JSR 168 portlet page that contains 2 host application links

Software prerequisites

If you want to play through the exercise, you must have the following software installed and running on your system:

  • IBM Rational® Application Developer V7.0 or higher with Portal Toolkit.
  • IBM WebSphere Portal V6.0 or higher.
  • IBM WebSphere Host Access Transformation Services (HATS) V7.0 or higher.

Although this article describes the solution for connection parameter overrides, you can use the same method to provide global variable or other request parameter overrides. For example, a developer implements a portlet application that provides different look-and-feel themes that are based on the selected profile. When the user signs in to the application, he or she is prompted with a list of optional profiles. When the user makes a selection, the selected profile is stored in a global variable and then passed to the HATS portlet to override the default profile.


About the download

The download contains URLGenDemo.war, which is a JSR 168 portlet application. It contains a portlet class that uses the Portal URL Generation service to generate a direct link to a HATS portlet application. It also contains a JSP file that uses the link generated by the portlet to create two links to different host systems.


Create the portlets

Two portlets are involved with this solution: a HATS portlet and a JSR 168 portlet. The HATS portlet enables clients to override connection parameters. The JSR 168 portlet uses the WebSphere Portal URL Generation APIs to generate links to the HATS portlet using different connection parameters.

Create and configure a HATS portlet

First, create a HATS portlet using the HATS Toolkit and enable the connection parameter override setting.

  1. Create a HATS portlet by clicking Create HATS Project on the HATS toolbar. P
  2. Provide a default host name (or IP address), and connection type. These are the default connection parameters that will be overridden.
  3. Open the Project Settings editor and click the Other tab.
  4. Select Connection Parameter Overrides, and then select Allow all default connection parameters to be overridden by client requests (see Figure 2).
  5. Save the settings.
Figure 2. Enable connection parameter override setting
Figure 2. Enable connection parameter override setting

Create and configure JSR 168 portlet

Next, you create a JSR 168 portlet using the Portal Toolkit. You use URL Generation APIs to generate links to invoke the HATS portlet.

  1. Create a JSR 168 portlet by selecting File => New => Project => Portal => Portlet Project.
  2. Ensure the following settings are selected (Figure 3).
    • Target Runtime: WebSphere Portal v6.0
    • Portlet API: JSR 168 Portlet
    • Portlet type: Empty Portlet
    Figure 3. Create a new JSR 168 portlet project
    Figure 3. Create a new JSR 168 portlet project

Now you edit the Java source file of the new JSR 168 portlet and add the following code.

  1. Declare a PortalURLGenerationService object to access the URL Generation APIs, and declare the name of the request attribute in which the URL to the HATS portlet is stored.
    Listing 1. Declare the portlet service and request attribute
    import com.ibm.portal.portlet.service.url.PortalURLGenerationService;
    
    // The URL Generation portlet service
    private PortalURLGenerationService portalURLGenerationService;
    	
    // The request attribute that contains the URL to HATS portlet
    public static final String REQ_ATTR_BASE_URL = "REQ_ATTR_BASE_URL";
  2. Access the PortalURLGenerationService using the Java Naming and Directory Interface (JNDI) lookup in the init() method of the portlet.
    Listing 2. Implementation of the init() method
    import com.ibm.portal.portlet.service.PortletServiceHome;
    import javax.naming.NamingException;
    	
    
    public void init() throws PortletException
      {
        super.init();
    				
        try
         {			
           final javax.naming.Context ctx = new javax.naming.InitialContext();
           final PortletServiceHome psh = 
            (PortletServiceHome) ctx.lookup
             ("portletservice/com.ibm.portal.portlet.service.url.PortalURLGenerationService");
           portalURLGenerationService = 
            (PortalURLGenerationService) psh.
             getPortletService(PortalURLGenerationService.class);
          }
          
         catch ( NamingException exception )
          {
    	throw new PortletException(exception);
          }
    }
  3. Use the URL Generation APIs to generate a URL that invokes the HATS portlet in the doView() method of the portlet.

    In this example:

    • writePortletRenderURL method is used to generate a URL to a portal page where the HATS portlet resides.
    • com.ibm.hats.demo.DemoPage is the custom unique name of the portal page.
    • com.ibm.hats.demo.HatsDemoPortlet is the custom unique name of the HATS portlet.

    These names are used later in this article when you configure the HATS portlet and portal page on WebSphere Portal.

    Listing 3. Implementation of the doView() method
    import com.ibm.portal.portlet.service.url.PortalURLWriter;
           
     public void doView(RenderRequest request, RenderResponse response) 
      throws PortletException, IOException
      {
       // Set the MIME type for the render response.
       response.setContentType(request.getResponseContentType());
            
       // Generate the URL using Portal API.
       PortalURLWriter portalURLWriter = 
          portalURLGenerationService.getPortalURLWriter(request, response);
       StringWriter mywriter = new StringWriter();
       portalURLWriter.writePortletRenderURL(mywriter, 
          "com.ibm.hats.demo.DemoPage", "com.ibm.hats.demo.HatsDemoPortlet");                
       String baseUrl = mywriter.toString();
            
       // Save the URL in the request attribute.
       request.setAttribute(REQ_ATTR_BASE_URL,baseUrl);
            
       // Forward the request to index.jsp.
       PortletRequestDispatcher rd = 
          getPortletContext().getRequestDispatcher("/index.jsp");
       rd.include(request,response);        
    }
  4. Create a new index.jsp file in the WebContent directory.
  5. Add the following code to the source of index.jsp to display two host connections as HTML links. Replace urlgendemo.URLGenDemoPortlet with the fully-qualified class name of your portlet. In this example, zserveros and iseriesd are IBM 3270 and 5250 hosts used for demonstration.
Listing 4. Create HTML links to different hosts
<%@taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<portlet:defineObjects />

<%
   String baseURL = 
     (String) renderRequest.getAttribute(urlgendemo.URLGenDemoPortlet.REQ_ATTR_BASE_URL);
%>

Demo systems:
<p><a href="<%=baseURL%>?host=zserveros.dfw.ibm.com&sessionType=1" 
   target="_blank">zserveros (3270)</a>
<p><a href="<%=baseURL%>?host=iseriesd.dfw.ibm.com&sessionType=2"  
   target="_blank">iseriesd (5250)</a>

Deploy and configure the portlets and portal page

To prepare to test your portlets, you deploy them on WebSphere Portal and configure the custom unique names for the portal page and the HATS portlet.

To export and deploy the portlets:

  1. In Rational Application Development, export as WAR files both of the portlets that you developed.
  2. Start WebSphere Portal (if it is not already running).
  3. In WebSphere Portal Administration, install the WAR files and add the portlets to different portal pages.

To configure unique names for the portal page and HATS portlet:

  1. In WebSphere Portal Administration, select Portal Settings => Custom Unique Names.
  2. To assign the unique name for the portal page:
    1. Select Pages from the available resource types.
    2. Search for the page that contains the HATS portlet.
    3. Click the Edit unique name for Page icon to assign a custom unique name for your page as shown in Figure 4.
    4. Enter com.ibm.hats.demo.DemoPage for the new custom unique name of your portal page. The name must be the same as the one you defined in the doView() method when you created the JSR 168 portlet earlier.
    5. Click OK to save the changes.
      Figure 4. Edit custom unique name for HATS portlet page
      Figure 4. Edit custom unique name for HATS portlet page
    6. To assign the unique name for the HATS portlet:
  3. Select Portlets from the available resource types.
  4. Search for the HATS portlet and click the Edit unique name for Portlet icon.
  5. Enter com.ibm.hats.demo.HatsDemoPortlet for the new custom unique name of your HATS portlet. The name must be the same as in the doView() method when you created the JSR 168 portlet earlier.
  6. Click OK to save the changes.

Test the portlets

To test the portlets:

  1. Launch the page that contains the JSR 168 portlet. Your page looks similar to Figure 1.
  2. Click on either of the links to start the HATS portlet and use the connection parameter overrides to connect to the selected host application.
  3. Because the connection parameter overrides are only applied at startup time, you must disconnect the existing HATS portlet from the host application in order to restart it and connect to a different host application. The HATS portlet might transform the host screens differently for different host applications.

Conclusion

Now you know how to apply the WebSphere Portal V6 URL Generation APIs to enable connection parameter overrides in HATS portlets. You can use the same APIs to implement global variable and other request parameter overrides.


Download

DescriptionNameSize
Code sampleURLGenDemo.war7 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Rational
ArticleID=269093
ArticleTitle=Overriding HATS portlet connection parameters using the WebSphere Portal V6 Advanced URL generation API
publish-date=11142007