In the first of our three-part series, published in November 2004, we introduced the composite application model and how WebSphere Portal supports it. Composite applications are a class of application whose fundamental construction model is the composition of parts or components. They are formed by choosing components or services from a catalog or palette and interconnecting the components to create the behavior desired.

The foundation of the composition model is the portal infrastructure, which provides access to user profile information and remote content, the ability to communicate and trigger other portlets and to participate in windows and action events, store persistent data, and look up credentials.

Composite applications within WebSphere Portal are built from portlets. WebSphere supports this model by allowing portlets to be composed into composite applications through the same tooling used to design portal pages. Portlets can be considered to be the components in the composition model since they are each self-contained applications that support multiple states and view modes.

While simply exposing business data and operations through a portlet offers a lot of value, even greater value can be obtained when portlets work together. To create a composite application the portlets must be able to pass data to each other, react to changes in their data, trigger events, and respond to events from other components.

Communication and interaction with other composite application components take place through defined interfaces such as messaging, event handling, or services. Each portlet can be removed or added from the model or page without impacting other portlets.

What are Co-operative Portlets?
Composite applications in WebSphere Portals are built on co-operative portlets, which support the trigger/workflow model. Co-operative portlets pass information to each other using the WebSphere Portal property broker, which enables portlets to publish their typed data , or properties, and to declare actions (services) that they are willing to execute based on the data values published by other portlets.

The portlet that provides a property is called the "source portlet," while the properties that the source portlet publishes are called "output properties." The portlet that receives a property is called the "target portlet" and the properties that are received by the target are called "input properties." With cooperative portlets, the target portlet can provide an action based on the property or data it receives.

Each value passed has meta-information associated with it-specifically the type, namespace, and direction. The type specifies the semantics of the property, the namespace provides a unique name to prevent collision, and direction specifies whether it is an input property or an output property.

A co-operative portlet can register its properties programmatically or through the use of WSDL file. If a WSDL file is used, the property broker will parse it and register the actions and properties.

There are two modes of interaction between co-operative portlets: click-to-action (C2A) and wired. C2A allows end-users to trigger data transfers from the source portlet to the target portlets using pop-up menus that appear next to the data being transferred. The menus are created dynamically by the portlet property broker. Wired co-operative portlets entail the implementation of persistent connections between portlets. A data change in the source portlet automatically triggers a change on the target portlets without requiring the intervention of the user.

If the target action was specified in the wire, the Property Broker delivers the property values through the actionPerformed method. However, if the target property is specified in the wire, the property value is delivered through the setProperties method.

Creating Composite Applications with Co-operative Portlets
Creating and enhancing composite applications with co-operative portlets is not difficult! There are two methods-either using the Portlet Wiring Tool, or doing it through programming. We will first show you how to do it the hard way, since that is the way most geeks (like us) like doing it.

Our examples will be based first showing how IBM Workplace for Business Control Reporting (IWBCR) exploits the composite application model through the use of co-operative portlets. IBM Workplace for Business Control Reporting is a WebSphere Portal Application written and marketed by IBM. (IWBCR was created in response to the Sarbanes-Oxley Act of 2002. The act is intended to help protect stockholders of companies with shares trading on U.S. exchanges and to place more accountability on the decision makers within those companies. IBM Workplace for Business Controls and Reporting is a solution designed to help companies manage and assess their business controls. The offering provides corporations with the ability to document, monitor, and test internal controls that can help manage financial reporting processes in a cost effective and sustainable manner. It allows organizations to help drive down the cost of control with features to help manage organizational change, simplify testing and auditing and help improve performance through an update option that ensures different departments have the most current data at their fingertips.)

WBCR portlets take the advantage of co-operative portlets to synchronize the data displayed in multiple portlets when re-acting to user actions on one portlet. IWBCR uses programmable co-operative portlets extensively to enable an action in one portlet to trigger an event in another portlet.

Figure 1 shows two portlets on the same page and how they interact. When the user clicks on a tree node (Test Control Feb 1) in the Evaluation Navigator portlet, it triggers a co-operative portlet event. The Evaluation Detail portlet receives this event, and displays the details of the item clicked on the tree. If a user clicks on an item on the table in the Evaluation Navigator (Test Procedure Feb 1), it triggers a cooperative portlet event, the Evaluation Detail portlet on the left hand side receives the event, and sets the tree selection on the tree node (Test Procedure Feb 1).

To make this work, you must make sure that the pbportlet.jar (which contains the PortletWrapper class) is in the WEB-INF/lib directory of the war file. Then the co-operative portlets must be wrapped by a special portlet, PortletWrapper. In the web.xml file within the WAR file, you need to define the main servlet class, c2a-application-portlet-class, specify it again through a special <init-param> as follows:

     <servlet-class>com.ibm.wps.pb.wrapper.
       PortletWrapper</servlet-class>
 		 <init-param>
       <param-name>c2a-application-portlet-class
         </param-name> 
       <param-value>com.ibm.lwp.bcr.portlet.
         BCRPortlet</param-value>

In the portlet.xml file, we specified the location of the WSDL file;

    <config-param>
    	  <param-name>c2a-action-descriptor
            </param-name>
      	  <param-value>/wsdl/CatTree.wsdl
            </param-value>
    </config-param>

The portlets register their intent to publish property values and/or receive notification of property changes by implementing methods of the interfaces EventPhaseListener.

public class BCRPortlet extends AbstractPortlet implements ActionListener,
PortletTitleListener, EventPhaseListener

We won't describe the methods for registering properties. They are described in the WebSphere Portal Infocenter. http://publib.boulder.ibm.com/pvc/wp/510/ent/en/InfoCenter/index.html.

However, we will illustrate the methods used to actually publish the values and value changes for registered properties.

Portlets wishing to publish a property value do so by calling methods of the property broker service built into the portal. (In addition to directly calling methods from the property broker, portlet writers may also use the C2A tag libraries in order to publish property changes.) When the Evaluation Navigator portlet process a portlet action (like the user selecting a node in the navigation tree) which should trigger a cooperative portlet event, the action handler will call the following code:

public void publishProperty(PortletRequest request,
String stringToPassThruTheWire,
String type, String name) {

    PortletSettings settings = request.
     getPortletSettings();
    Property p = null;
	PropertyValue[] pva = new PropertyValue[1];

	try {
	  PropertyBrokerService pBroker =
     (PropertyBrokerService) getPortletConfig().
     getContext().getService(PropertyBrokerService.
     class);
	  if (pBroker != null) {
		p = PropertyFactory.createProperty(settings);
		p.setName( name );
		p.setDirection(Property.OUT);
		p.setType( type );
		p.setNamespace(NAMESPACE);
		pva[0] = PropertyFactory.createPropertyValue
		(p, stringToPassThruTheWire);

		pBroker.changedProperties(request,
          portletConfig, pva);
	  }
	}
	catch (PropertyBrokerServiceException pbse) {
	  CatLogger.debug("PropertyBrokerServiceException:
      nested exception is: " + pbse.getMessage());
	  return;
	}
  }

Any portlets on the same page that are registered with actions on the same property types (through wsdl files) will receive a regular portlet action, with the action name defined in the wsdl file.

Adding a Third-Party Portlet
So how does a normal person exploit the composite application framework without doing complex coding? This is easily accomplished by using the Portlet Wiring Tool, which is downloadable in WP 5.0 and included with WP 5.1. The Portlet Wiring tool enables to view, add, or delete the current set of wires on a page.

In order to access the Portlet Wiring Tool, click on Edit Page and then click on the Wires Tab. The wires for the page will then be displayed. You can then select the source portlet and output property, the target portlet and input property, and then create a wire.

So now let's go to a IWBCR page and add a third-party portlet.

In Figure 2, we have the Documentation Navigator and the Documentation Detail portlets as delivered by the base product. These portlets are pre-configured (through an XMLAccess script that is executed by the application installer) to "co-operate" with each other through the Cooperative Portlets service.

Again, these portlets use the "programmatic" way of defining and processing the user actions, not the traditional C2A user menu-driven method. When the user clicks on a node in the tree control, the portlet on the right hand side will load the data for the item selected in the tree. Conversely, when the user clicks on an item from the table on the right hand side, the tree will expand to a node that represents that data item.

We can add a third-party portlet (or even multiple portlets ) to be deployed on a same portal page with the IWBCR portlets that can 'cooperate' with the other portlets on the page. The third-party portlet that we will be adding is called the "the C2 Sample Portlet." It has been designed to display a simple message based on the property values emitted by the Documentation Navigator or Documentation Details portlet.

Figure 3 shows the Portlet Wiring Tool screen with the "C2A Sample Portlet," deployed on a portal page with the pre-existing, pre-configured WBCR portlets. This sample portlet reacts to user actions when clicking on the tree nodes, or the items in the table on the right hand side.

As a result of some user action, the IWBCR portlets publish a pre-formatted string message that contains information such as the item type, and most importantly, the item ID for the item selected. Hence, the third-party portlet can use that information to process what it wants to accomplish, in the case of our sample, it simply displays the message. In this fashion, the third-party portlet can work with the WBCR portlets seamlessly. (The third-party portlet can also publish the message to the IWBCR portlets, although we haven't shown that capability in this example.)

Integrating the Sample Portlet
In order to integrate the sample portlet, we first have to make it a co-operative portlet. When using co-operative portlets, the main servlet class for the portlet is replaced by an IBM specified "wrapper" class. This wrapper class, in turn, takes the original portlet class as a parameter. The wrapper pre-processes many of the co-operative portlet methods and events, then delegates most of its behavior to the original portlet. We define the main servlet class and specify the c2a-application-portlet-class in the web.xml file as follows:

   	<servlet-class>com.ibm.wps.pb.wrapper.
          PortletWrapper</servlet-class>
 		 <init-param>
       <param-name>c2a-application-portlet-class
          </param-name> 
       <param-value>com.ibm.lwp.c2a.portlet.
          C2ASamplePortlet</param-value>
		 </init-param>

Then we provide a wsdl file and specify it in the portlet.xml file.

    <config-param>
    	  <param-name>c2a-action-descriptor
            </param-name>
      	  <param-value>/wsdl/C2ASample.wsdl
            </param-value>
    </config-param>

In the WSDL file that should be packaged with the Sample portlet, the <types> definition has to have a simpleType defined as: "SOXNodeWire." (Note that this sample does not need to implement EventPhaseListener because the actions are delivered directly to the "actionPerformed" method.)

This matches up with the same type that the WBCR portlets are using so that they can find each other. You can know what types to define for your portlet by inspecting the WSDL files of other portlets. In fact, you can easily change the type names of any portlet simply by editing the WSDL file of that portlet. In this way, an installation could adapt the type names produced and consumed by all of their portlets to be types meaningful to the particular enterprise.

The type definition for SOXNodeWire looks like this:

<types>
 <xsd:simpleType name="SOXNodeWire">
  <xsd:restriction base="xsd:string">
  </xsd:restriction>
 </xsd:simpleType>
</types>

In your WSDL file you will also define the names of actions that your portlet is willing to perform on the data type you just defined. In our example, the snippet below maps a portlet action name to a WSDL operation on a particular data type.

...
<operation name="C2AInAction">
 <portlet:action name="C2AInAction" type="simple"
    caption="any string" 
	description="Display an action name"/>
 <input>
   <portlet:param name="C2AInActionMessage"
      partname="Message" caption="message"/>
 </input>
</operation>
...

The heavy lifting is in the method: actionPerformed() in the C2AsamplePortlet.java. This is where and how the Sample portlet processes the wired message from the WBCR portlets. Remember, the action name and the message parameter are defined in the C2Asample.wsdl file as shown above.

public void actionPerformed(ActionEvent event) { 
	PortletRequest request = event.getRequest();
	PortletSession psession = request.getPortletSession( false );
	try {
	  String actionName = event.getActionString();
	  System.out.println("C2ASamplePortlet: 
    actionPerformed: actionName = " +actionName );
	  Enumeration requestParams = request.
     getParameterNames();
  	  while (requestParams.hasMoreElements()) {
		String param = (String) requestParams.
         nextElement();
		String val = (String) request.
         getParameter(param);
		System.out.println(" --param = " + param +
         ", value = " + val);
  }
	  // cooperative actions are defined in the WSDL
      file, including the action name
	  // and its parameter name. See: C2ASample.wsdl
	  if ( actionName != null && (actionName.equalsIgn
      oreCase("C2AInAction") ) ) {
		String wireMessage = request.getParameter
         ("wireParamIn");
		//save the wire message so that it can be
          displayed in the view JSP
	if ( wireMessage != null )
		  psession.setAttribute("WireMessage",
           wireMessage );
	  }

Once the Sample portlet is installed and deployed on a WBCR portal page, one needs to use the Portlet Wiring tool to "wire" the portlets together. Figure 3 indicates what those wires are. Note that the first two wires are the pre-defined when installing IWBCR application. The last two are the two additional wires to indicate how the Sample portlet re-acts to the IWBCR actions.

The coding above is done by engineers skilled in writing portlets. However, the wiring of a co-operative portlet into a page, and thus into an composite application, is something that can be done by any end-user. The user is not aware of any of the implementation details of properties or actions, but instead simply sees the names of properties and actions that can be interconnected using the portlet wiring tool. This is a small step up from the simple administration required to place a portlet on a page. The task of writing co-operative portlets is also made easier by tooling provided by Rational Application Developer release 6.

This is Only the Beginning
In this article, we showed how to make composite programs with co-operative portlets, both programmatically and with the Portlet Wiring Tool. We showed how easy it was to add a third-party portlet onto a composite portlet. We also showed how IBM was committed to this technology.

But there is only so much you can say in a short article. As we mentioned, we've chosen to show you the more difficult (and more flexible) of the mechanisms for creating composite applications with cooperative portlets, portlet wiring. We did not show you how Click-to-Action portlets can just as easily be integrated as wired cooperative portlets. So if you want to find out more about cooperative portlets, we suggest you read IBM Developerworks; Using Cooperative Portlets in WebSphere Portal V5 by Amber Roy-Chowdry.

In the last article of our-three part series, we will focus on advanced topics for composite applications. In any programming model, there are a set of patterns that recur repeatedly. For composite applications these include performing portal navigation from components, using labels, using portlets as pop-up windows or "dialogs," enabling "Solo Mode," and forming URL commands to open new windows. We will also look at how to use co-operative portlets to create mapping filters between differing data types. Finally, one of the most exciting capabilities of the composite application programming model is the ability to create associations and user navigational linkages between objects in one business domain and those in another.

The authors wish to thank Joseph Lu, Theresa Smit, and Binh Q Nguyen for their assistance with this article.

• Figure 1
• Figure 2
• Figure 3