IBM Portlet for Google Gadgets: Using the inter portlet communication feature
This article explains the inter portlet communication (IPC) feature of IBM Portlet for Google Gadgets and shows how to write a source portlet on IBM WebSphere Portal V6.0. On a WebSphere Portal page with one or more instances of IBM Portlet for Google Gadgets deployed, the IPC feature enables the other portlets on the page to interact with the selected gadgets in IBM Portlet for Google Gadgets; that is, the gadgets react in response to the events triggered in the other portlets.This article is intended for everyone who is interested in mashups and inter portlet communication. As background for this article, you should have a general understanding of inter portlet communication and of Google Gadget Syndication Services.
Inter portlet communication
Inter portlet communication refers to the capability of portlets on a page to interact with each other by sharing information. One or more cooperative portlets (portlets that have implemented inter portlet communication) on a portal page can automatically react to changes from a source portlet, triggered by an action or an event in the source portlet. This capability provides coordinated and consistent behavior among the portlets on the page, and it enhances the overall user experience.
Cooperation between source and target portlets is facilitated by a WebSphere Portal runtime entity called the property broker. Portlets on a page can cooperate using the property broker even if they were developed independently without the programmer's awareness of the existence of other cooperative portlets. This approach is in contrast to tightly coupled communication paradigms, such as portlet messaging, in which portlet cooperation and information exchange are specifically encoded to the portlet instances.
IPC is a loosely coupled model for information exchange among portlets. Each portlet is associated with a set of typed data items, called properties, which the portlet can generate or receive. Each portlet can also be associated with a set of actions, which are capable of generating or receiving property values at runtime. Property broker facilitates the exchange of property values at runtime. There are two ways to achieve this functionality: click-to-action and wiring. (Refer to the Resources section to find more information about these concepts.) IBM Portlet for Google Gadgets achieves this functionality using wiring.
Writing a source portlet for a gadget
Assume you have a portlet that displays a list of people; when a person is selected, the portlet displays the address of the selected person. Wouldn't it be great if you could easily obtain additional contextual information about that person, displayed automatically on the same portal page, and also show the person's address on a map? With the new IBM Portlet for Google Gadgets, you can achieve this easily. You can use an instance of the IBM Portlet for Google Gadgets configured to a Google map to show not only the address of the person but also the location on the map or even the satellite image. This can be achieved by using the wiring feature, also known as the IBM WebSphere Portal Collaborative Portlet feature.
Let’s see how to write a source portlet taking the Google Map gadget as an example.
Every gadget has input parameters that govern its display. For example, the Google Map gadget (as shown in figure 1) needs four parameters to display the map of a location:
- Loc. Address of the location whose map is to be shown.
- View. View type; choices are Map, Satellite, and Hybrid.
- Locname. Address Name.
- Zoom. Street, Main Street, City, Metro, Nation, and so on.
Figure 1. HTML view of gadget parameters in portlet
To get the parameters list for the selected gadget, click the "I want to get this gadget's parameter names" link enclosed in a red rectangle as shown in figure 1. This opens an XML file in a new browser window that corresponds to the selected gadget and specifies the gadget parameters as shown in listing 1 (we display only a portion of the XML file to show only the gadget parameters).
Listing 1. XML view of gadget parameters
<UserPref name="locname" display_name="Address Name" default_value="Google" /> <UserPref name="loc" display_name="Address or Zip" default_value="1600 Amphitheatre Parkway, Mountain View, CA" datatype="location" required="true" /> - <UserPref name="zoom" display_name="Zoom" default_value="Street" datatype="enum"> <EnumValue value="Address" /> <EnumValue value="Street" /> <EnumValue value="Main Street" /> <EnumValue value="City" /> <EnumValue value="Metro" /> <EnumValue value="Region" /> <EnumValue value="Nation" /> </UserPref> - <UserPref name="view" display_name="View Type" default_value="Map" datatype="enum"> <EnumValue value="Map" /> <EnumValue value="Satellite" /> <EnumValue value="Hybrid" /> </UserPref> |
All the gadget parameters are defined by the UserPref tag. The name attribute of this tag represents the gadget parameter name. If a UserPref tag has child elements, such as the EnumValue tag, the selected gadget parameter can have only values defined by the EnumValue tag. For example, the view parameter in this XML view can have only one of the three values: Map, Satellite, and Hybrid.
The Google Map gadget requires the values of these parameters to show a location's map. The source portlet needs to pass the parameter values for a location in order to display a particular map in the gadget.
Configuring IBM Portlet for Google Gadgets
Now, you must configure IBM Portlet for Google Gadgets to enable it for IPC. To configure this portlet, open the /config/gadget_param_mapping.xml file and add the parameter mapping for the selected gadget as shown in listing 2.
Listing 2. Defining mapping for gadget parameters in gadget_param_mapping.xml
<!-- parameter mapping Google Map Gadget -->
<gadget:parameters
xmlns:gadget="http://ralph.feedback.googlepages.com/googlemap.xml">
<!-- multiple inputs values specified in the sourceKeys attribute should be
processed and transformed to one output string. filtered map will be passed
to mapper. -->
<parameter name="loc" sourceKeys="street city state"
mapper="com.test.mapper.MyLocationMapper" />
<!-- when only sourceKeys is defined, the value of sourceKeys in passed map
would be used for this parameter. -->
<parameter name="view" sourceKeys="viewkey" />
<!-- ommitting the sourceKeys attribute means the value specified for 'name'
should be used to look up the value in the map -->
<parameter name="zoom" />
<!-- ommitting the sourceKeys attribute if a mapper is defined means that
source map will be passed to the mapper without filtering -->
<parameter name="locname" mapper="com.test.mapper.UnFilteredMapper" />
</gadget:parameters>
|
Parameter mapping for a gadget is identified using the gadget URL as the namespace. For example, in listing 2, the Google map gadget's parameter mapping is namespaced using http://ralph.feedback.googlepages.com/googlemap.xml. You can determine the URL for a gadget by clicking the "I want to get this gadget's parameter names" link as shown in figure 1. Every gadget's parameter mapping must be namespaced using the gadget's URL.
For every gadget parameter, you need to define three attributes in the mapping file:
- Name. Actual gadget parameter name (only one value for this attribute is allowed).
- sourceKeys. This attribute contains keys, whose values are used to prepare this gadget parameter value. This attribute can have more than one value, separated by a space.
If more than one value is given for this attribute, the mapper attribute must be defined for this gadget parameter.
- Mapper. This attribute represents a Java class, which is invoked by IBM Portlet for Google Gadgets. The Java class must implement the GadgetValueMapper interface and should be a Java bean. Only one value is allowed, and this value must be the fully qualified Java class name.
IBM Portlet for Google Gadgets expects the parameter values to be passed in the java.util.Map Object, where keys are sourceKeys in the XML file (as defined previously) and where values are the values for sourceKeys.
The sourceKeys and mapper attributes for a gadget parameter are optional. If these two attributes are not defined, IBM Portlet for Google Gadgets uses the name attribute to retrieve the value for the gadget parameter from the map object passed from the source portlet.
When only name and sourceKeys attributes are defined and the mapper attribute is not defined, the sourceKeys attribute can have only one value. The value of this attribute is used to retrieve the value for the gadget parameter. If more than one value is defined for the sourceKeys attribute, then an exception is thrown.
When all three attributes are defined, IBM Portlet for Google Gadgets prepares a filtered map (from the map received from the source portlet) and invokes the mapper's getMappedValue method passing this filtered map. The filtered map contains only those keys that are defined for the sourceKeys attribute, for example,
<parameter name="loc" sourceKeys="street city state"
mapper="com.test.mapper.MyLocationMapper" />
|
In this case, the filtered map contains three keys, street, city, and state, and their values. Now it's the mapper's responsibility to transform this input into a string value for the gadget parameter.
When only the name and mapper attributes are defined, the whole map object is passed to the mapper's getMappedValue method.
The JAR file containing mapper classes must be in the classpath of the portlet application. This can be achieved either by putting the JAR file directly into the /WEB-INF/lib directory or by creating a shared library (using the admin console of IBM WebSphere Application Server) and placing the JAR file in the shared library.
While placing the JAR file in the shared library, mapperIfc.jar must be moved to this shared library.
Authoring the WSDL file for the source portlet
Listing 3 show a WSDL file for the source portlet that interacts with IBM Portlet for Google Gadgets.
Listing 3. WSDL file
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="Source"
targetNamespace="http://www.ibm.com/wps/wiring/source"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:portlet="http://www.ibm.com/wps/wiring"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.ibm.com/wps/wiring/source"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<types>
<xsd:schema
targetNamespace="http://www.ibm.com/wps/wiring/source">
<xsd:complexType name="GADGET_PARAMS">
<xsd:all>
<xsd:element name="part1" type="xsd:string"/>
<xsd:element name="part2" type="xsd:string"/>
<xsd:element name="part3" type="xsd:string"/>
</xsd:all>
</xsd:complexType>
</xsd:schema>
</types>
<message name="SetGadgetParamRequest">
<part name="GADGET_PARAMS" type="tns:GADGET_PARAMS" />
</message>
<portType name="Source">
<operation name="set_GadgetParams">
<output message="tns:SetGadgetParamRequest" />
</operation>
</portType>
<binding name="GadgetsBinding" type="tns:Source">
<portlet:binding />
<operation name="set_GadgetParams">
<portlet:action name="setGadgetParams" type="standard"
caption="show.gadget.with.this.params"
description="show.gadget.with.this.params"
actionNameParameter="ACTION_NAME" />
<output>
<portlet:param name="GADGET_PARAMS"
class="java.util.HashMap" partname="GADGET_PARAMS"
boundTo="request-attribute" caption="gadget.params" />
</output>
</operation>
</binding>
</definitions>
|
Because IBM Portlet for Google Gadgets expects a java.util.Map Object, the complexType GADGET_PARAMS represents a map object, and boundTo="request-attribute" indicates that this object is found as a request attribute.
Populating the map object in the source portlet
When a user interacts with the source portlet, for example by clicking a link or submitting a form, using the processAction method, the source portlet populates the java.util.Map Object and sets this object as the request attribute. Listing 4 shows how this can be done.
Listing 4. Populating the java.util.Map Object in processAction
public void processAction(ActionRequest request, ActionResponse response)
throws PortletException, java.io.IOException
{
String actionName = request.getParameter(“ACTION_NAME”);
if (actionName != null && actionName.equalsIgnoreCase(“setGadgetParams”))
{
Map gadgetPrefs = new HashMap();
gadgetPrefs.put("viewkey", "Map");
gadgetPrefs.put("zoom", "Street");
gadgetPrefs.put("street", "Durham");
gadgetPrefs.put("city", "NC");
gadgetPrefs.put("state", "USA");
request.setAttribute(“GADGET_PARAMS”, gadgetPrefs);
}
}
|
Writing the mapper class
Listing 5 shows an example of the mapper class.
Listing 5. Sample mapper class
package com.test.mapper;
import java.util.Map;
import com.ibm.wps.portlets.gadget.ipc.GadgetValueMapper;
/**
*Created on Sep 14, 2007
*@author Shailesh K Mishra (shailekm@in.ibm.com)
*
*/
public class MyLocationMapper implements GadgetValueMapper {
/* (non-Javadoc)
* @see com.ibm.wps.portlets.gadget.ipc.GadgetValueMapper#getMappedValue(java.util.Map)
*/
public String getMappedValue(Map sourceValuesMap) {
System.out.println("*********"+sourceValuesMap+"*************");
String address = "";
String street = (String)sourceValuesMap.get("street");
String city = (String)sourceValuesMap.get("city");
String state = (String)sourceValuesMap.get("state");
address = street+", "+city+", "+state;
System.out.println("*********"+address+"*************");
return address;
}
}
|
This class implements the GadgetValueMapper interface and provides implementation of the getMappedValue method. As shown in figure 2, this mapper is defined with three source keys, so it receives a filtered map, which contains three key-value pairs where the keys are street, city, and state. This sample mapper simply appends the key values to form an address.
Figure 2 displays the results of this integration.
Figure 2. Sample integration
------------------------------------------------------------------------------------------------
Courtesy:- Shailesh K Mishra For this article
No comments:
Post a Comment