Leveraging Reverse AJAX in IBM WebSphere Portal 7.0 using Dojo CometD and Web messaging service

Introduction

The Reverse Asynchronous Java^TM and XML (AJAX) technology enables dynamic content to be delivered to the browser, thus improving application performance by eliminating the need for constant polling. This technology can be used in many scenarios to deliver an excellent user experience.

For example, a news portal can push the news to a user's browser when it becomes available, without needing user action and without needing to keep refreshing or re-rendering the whole page. Another scenario is to display an up-to-date task list to which the server pushes the new task once it is created, so that the task owner doesn't need to keep pulling the updates.

In this article we go through all the steps needed to leverage Reverse AJAX in portlets using Dojo CometD implementation. We develop a Task List portlet that displays a set of tasks assigned to the logged-in user and to which the server keeps pushing any new tasks, using reverse AJAX.

To get the most from this article, you should have basic knowledge of AJAX and Dojo, prior experience in developing portlets, and basic IBM® WebSphere® Portal development and administration skills.

Understanding Reverse AJAX and Web messaging service

AJAX technology enables HTTP requests to be made to a dynamic Web resource from the client browser, without the need to refresh or submit the Web page. This is usually used to deliver better user experience and to use the network more efficiently by transferring only the needed data between client and server.

Reverse AJAX is the concept of sending data from server to client browser in the form of event notifications. This means that the client doesn't need to keep pulling the data; instead, it just subscribes to a specific topic and is notified once a related event occurs.

To implement Reverse AJAX in an application, you usually leverage a set of technologies and concepts including Comet, the Bayeux protocol, Dojo CometD, and Web messaging service, which are defined as follows:

Comet. A Web application model in which a long-held HTTP request allows a Web server to push data to a browser, without the browser explicitly requesting it. Comet is a term that combines many known technologies in a specific model to achieve this goal.

Bayeux protocol by the Dojo Foundation. Defines a higher-level protocol for communication between browser and server, with the aim of allowing re-use of client-side JavaScript code with multiple Comet servers, and allowing the same Comet server to communicate with multiple client-side JavaScript implementations. Bayeux is based on the publish/subscribe mechanism, so this must be supported by the server to be able to leverage this model.

Dojo CometD. A project by the Dojo Foundation to produce a specification for Bayeux, and a set of implementations of that specification.

Web messaging service. A publish and subscribe implementation that connects the browser to the IBM WebSphere Application Server service integration bus for server-side event push. Client/server communication is achieved through the Bayeux protocol. Any JavaScript library or HTTP client that implements the Bayeux protocol support can communicate with the Web messaging service.

Preparing for the example

To implement Reverse AJAX in WebSphere Portal, we must enable the Web messaging service, as it is disabled by default, following these steps:

1. Log in to the administration console of WebSphere_Portal profile and navigate to Servers --- Application servers --- WebSphere_Portal.
2. Expand Web Container Settings and select Web container transport chains.
3. Select WCInboundDefault --- Web container inbound channel --- Custom Properties.
4. Click New to enter a new property, and enter “webmsgenabled” for the name and “true” for the value (see figure 1).

Figure 1. webmsgenabled property


Next, we need to create a Bus and Topic connection factory for the example. Follow these steps to create the Bus:

1. Log in to the administration console and navigate to Service Integration --- Buses.
2. Click New, enter ReverseAjaxBus for the name, and clear the Bus Security check box.
3. Click Next and then Finish, to create the Bus; save the changes to the master configuration.
4. Click ReverseAjaxBus to enter its configuration page and click Bus members under the Topology detail page.
5. Click Add, and select WebSphere_Portal server to add it to the Bus members.
6. Accept the other defaults, click Next and then Finish, and save the changes to the master configuration.
7. Restart WebSphere Portal.

Follow these steps to create the Topic connection factory:

1. Log in to the administration console and navigate to Resources –- JMS --- Topic connection factories, making sure to select WebSphere_Portal in the server scope.
2. Click New, select Default Messaging Provider, and click OK.
3. Enter ReverseAjaxTopic for the name, and jms/reverseajax for the JNDI name.
4. Select ReverseAjaxBus from the Bus Name menu.
5. Click OK and then save the changes to the master configuration.

Example: Real-time task list portlet using Reverse AJAX

In this section we go through the implementation details of the example (see the attached RealtimeTaskList.zip file), in which we implement two portlets: The task list portlet, which will be used to render the task list to the logged-in user, and an administration portlet to simulate creating new tasks.

The task administration portlet simulates adding a new task and then pushing a notification, using Reverse Ajax, to the task list portlet to update the displayed list. We use IBM Rational® Software Architect to implement the Portlet Project; however, any Integrated Development Environment (IDE) that has access to the needed libraries and supports portlet development can be used for implementation.

Creating and configuring the Project

1. Create a new Portlet Project using the wizard and enter RealtimeTaskList as project name.
2. Select WebSphere Portal 7.0 (stub) as the target runtime for the project.
3. Clear the Create a portlet check box and then click Finish.
4. Right-click the created project, select properties, and then open the Project Facets section (see figure 2).
5. Select “JSR Portlets on WebSphere Portal (v 7.0)”.
6. Expand the Web 2.0 section, select “Dojo Toolkit on WebSphere Portal” and “Server-side Technologies”, and then click OK to save the properties.

Figure 2. Project Facets window



7. Open project properties again and add WebSphere Application Server 7.0 runtime to the project by selecting Java Build Path --- Libraries --- Add Library --- Server Runtime --- WebSphere Application Server 7.0.

8. Add the web messaging service APIs JAR file to the project Web app library (copy webmsg_applib.jar) to WEB-INF/lib directory of the project. This JAR file is under WebSphere Application Server feature pack for Web 2.0 (AppServer\web2fep\optionalLibraries\MessagingService).

Developing the task list portlet

In this section we will go through the steps of developing and configuring the Task List portlet; specifically, we discuss the steps to enable the portlet to use Web messaging service. Note, however, we do not discuss the details behind the steps; for more information on this you can refer to the Web Messaging Service overview topic in the WebSphere Application Server documentation.

Create the portlet:

1. Right-click the project and select New --- Portlet.
2. Enter TaskListPortlet as the portlet name, making sure that JSR 286 is the selected API, and select Basic Portlet for the type.
3. Click Finish, to create the portlet resources.

Configure Web messaging service in deployment descriptor:

1. Open web.xml and insert the code snippet in listing 1 into the web-app tag. (This configures the Web messaging service servlet and publisher servlet, and adds references to the JMS topic factory that will be used for communications.)

Listing 1. Code to insert into web-app tag


1. Open the ibm-web-bnd.xml file to add binding to the JMS resource we referenced in web.xml, and add the following line of code inside the web-bnd tag:

<resource-ref name="jms/reverseajax" binding-name="jms/reverseajax" />

Create Web messaging service configuration file:

1. As described in the Web Messaging Service overview documentation, we need a JavaScript Object Notation (JSON) configuration file to define some properties needed by the service. Navigate to the WEB-INF directory of the project, right-click it, and select New --- File.
2. Name the file webmsg.json, and copy the code in listing 2 to the newly created file.

Listing 2. Code to copy to webmsg.json

Developing the Portlet JavaServer Pages (JSP):

1. Open the JSP file TaskListPortletView.jsp (this should have been created for you when you create the basic portlet).
2. We assume that the Dojo library has already been referenced from the Portal theme; if you are using a custom theme, you will need to add the references to Dojo manually. If you are using the default Portal theme, then no need to load the library in your JSP.
3. In this page we use Dojo CometD APIs to subscribe to a specific topic and handle any notifications coming through that channel. The code is described as follows:

Listing 3. Code to initialize cometd configuration

Listing 4. publishHandler function

<%@page session="false" contentType="text/html" pageEncoding="ISO-8859-1"

	 import="java.util.*,javax.portlet.*,com.ibm.realtimetasklist.*" %>

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet"%>        

<%@taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.1/portlet-client-model" prefix="portlet-client-model" %>        

<portlet:defineObjects/>

<portlet-client-model:init>

      <portlet-client-model:require module="ibm.portal.xml.*"/>

      <portlet-client-model:require module="ibm.portal.portlet.*"/>   

</portlet-client-model:init>

<style type="text/css">

    body,  html { font-family:helvetica,arial,sans-serif; font-size:90%; }

</style>

<script type="text/javascript">

    dojo.require("dojo.io.script");

    dojo.require("dojox.cometd");

    dojo.require("dojox.cometd.callbackPollTransport");

    < portlet:namespace/>cometdConfig = function() {

    	//if not connected, connect to web messaging service servlet

    	if(dojox.cometd.state() == "unconnected"){

       dojox.cometd.init("<%= renderRequest.getContextPath()+"/webmsgServlet" %>");

      }

      //subscribe to private topic

      dojox.cometd.subscribe("/taskList/<%= renderRequest.getRemoteUser() %>",

		 "<portlet:namespace/>publishHandler");

       //subscribe to public topic

      dojox.cometd.subscribe("/taskList", "<portlet:namespace/>publishHandler");

    }

    dojo.addOnLoad(<portlet:namespace/>cometdConfig);

    commonHandler = function(message){alert(message);}

    < portlet:namespace/>publishHandler = function (message) {

        console.log("<portlet:namespace/>received", message);

        dojo.byId("<portlet:namespace/>taskList").

        appendChild(document.createElement("div")).

		appendChild(document.createTextNode(message.data));

    }

</script>

<div>

<h2>Real-Time Task List for user <%= renderRequest.getRemoteUser() %></h2>

</div>

<div id="<portlet:namespace/>taskList">

    <strong>

        Tasks:

    </strong>

</div>

	<%@page session="false" contentType="text/html" pageEncoding="ISO-8859-1" 

 		import="java.util.*,javax.portlet.*,com.ibm.realtimetasklist.*" %>

	<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet"%>        

	<%@taglib uri="http://www.ibm.com/xmlns/prod/websphere/portal/v6.1/portlet-client-model" prefix="portlet-client-model" %>        

	<portlet:defineObjects/>

	<portlet-client-model:init>

      	<portlet-client-model:require module="ibm.portal.xml.*"/>

      	<portlet-client-model:require module="ibm.portal.portlet.*"/>   

	</portlet-client-model:init> 

	<div>

 		<form action="<portlet:actionURL/>">

 			<input type="text" name="TaskString">

 			<select name="TaskOwner">

 				<option value="taskcommon">Common</option>

 				<option value="taskuser1" >User 1</option>

 				<option value="taskuser2" >User 2</option>

 				<option value="taskuser3" >User 3</option>

 			</select>

 			<input type="submit" name="Submit">

 		</form>

	</div>

 	public void processAction(ActionRequest request, 

		 ActionResponse response) 

 		throws PortletException, java.io.IOException {

 		String taskString = request.getParameter("TaskString");

 		String taskOwner = request.getParameter("TaskOwner");

 		//Here comes the code that will create the task 

		//in database or process engine or whatever

 		//Now we will push a notification to owner's topic

		Publisher publisher = (Publisher) getPortletContext().getAttribute(

 		        JmsPublisherServlet.PUBLISHER_SERVLET_CONTEXT_KEY);

 		try {

 			if("taskcommon".equals(taskOwner)){//public task

				publisher.publish(

					new BayeuxJmsTextMsg("/taskList", taskString));

 			}else{//private task

				publisher.publish(

				new BayeuxJmsTextMsg("/taskList/"+taskOwner, taskString));

			}

 		} catch (PublisherException e) {

			e.printStackTrace();

		}

	}