Web messaging service quick start

The Web messaging service consists of a run time JavaTM archive (JAR) file that gets placed in the WebSphere® Application Server installation directory and a library designed to be inserted into a new or existing Web module as a utility JAR file. This section provides brief instructions on enabling the Web messaging service and developing a Web messaging enabled application. Including in this section are links to more detailed sections. .


Step 1. Install the Web messaging service.

The Web messaging service must be installed to run a Web messaging enabled application. Refer to the IBM® WebSphere Application Server Feature Pack for Web 2.0 and Mobile installation instructions for more information.

Step 2: Locate the utility library.

Locate the Web messaging service utility library that was provided with this documentation. 

Step 3. Enable the Web messaging service

You must enable the Web messaging service for a Web messaging enabled application to run. Refer to the Web messaging service enablement instructions for more information.

  1. Log into the administrative console of WebSphere Application Server.
  2. Navigate to Servers->Application Servers
  3. Select current application server.
  4. Expand Web Container Settings and select Web container transport chains.
  5. Select WCInboundDefault transport chain or select transport chain that corresponds to the Virtual Host you will select during application install.
  6. Select Web Container Inbound Channel (WCC 2).
  7. Select Custom Properties.
  8. Click New.
  9. Enter webmsgenabled for the name property and true for the value.
  10. Click Apply.
  11. Click Save to save the repository information.
  12. You can restart the application server now or wait until after the Configure Service Integration Bus step.

Step 4. Configure a service integration bus.

A Web messaging application must have a configured service integration bus with a defined topic space to run. At a minimum, the bus name must be provided in a Web messaging configuration file for a Web messaging application to function.

Step 5. Insert the Dojo Toolkit into the Web module.

The Dojo Toolkit provides client support for the Web messaging service. The easiest way is to include the Dojo Tookit in a Web module. If the Dojo toolkit is not included in a Web module (statically served through web server for example), the Uniform Resource Identifier (URI) location of the dojo.js file must be known to load the Dojo Toolkit in any Web module presentation files.

Step 6. Embed the Web messaging utility library in the Web module.

The best place to insert the Web messaging utility library is in a Web module's WEB-INF/lib directory as a utility library. Copy the webmsg_applib.jar file file located in step 1 into the Web module's WEB-INF/lib directory. You can use the Web messaging utility library in the same Web module as the Dojo Toolkit, or in a different Web module. The key interaction point is the Bayeux protocol communication URI. See the installation steps for further information.

Step 7. Determine the Web messaging service communication URI and map the Web messaging servlet to that URI.

The "/webmsgServlet" servlet-mapping parameter defines the communication URI between the Dojo bayeux client and the Web messaging service. On the server side, a servlet mapping must be created that matches the dojox.cometd.init initialization parameter. The servlet mapping maps to the servlet class com.ibm.websphere.webmsg.servlet.WebMsgServlet. This servlet is provided in the Web messaging utility library. A web.xml file example is shown below. Refer to the Developing a Web messaging enabled application for more information.
	
  <servlet>
    <description/>
    <display-name>
       WebMsgServlet
    </display-name>
    <servlet-name>WebMsgServlet</servlet-name>
    <servlet-class>
	com.ibm.websphere.webmsg.servlet.WebMsgServlet
    </servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>WebMsgServlet</servlet-name>
    <url-pattern>/webmsgServlet</url-pattern>
  </servlet-mapping>
 

      
In step 9, the URI defined above is used by the Dojo Toolkit cometd client for initialization purposes. A simple initialization statement in a presentation file is used in the step 9 and an example and is shown here for comparison:  dojox.cometd.init( "webmsgServlet");

Step 8. Create a Web messaging configuration file.

The Web messaging service reads configuration parameters from a configuration file to handle incoming Web messaging requests. Create a Web messaging configuration file, webmsg.json, in the WEB-INF directory (same directory as the web.xml file) similar to the following example. The webmsg.json file is specified as a JSON Object(map) with each key matching an existing servlet name mapped to the Web messaging servlet. The Configuration overview section provides info on all possible configuration options.

{
   "WebMsgServlet": 
      {  
         "busName": "thebus", 
         "destination": "Default.Topic.Space", 
         "clientCanPublish": true,
         "longPollTimeout": 30
      }
}
      

Step 9. Create the client application.

All server side setup is now complete except for installing the application. The remaining task is to create the client side logic using the Dojo Toolkit functions. A simple test example is provided here. Note how the initialization URI parameter matches the Web messaging servlet mapping.

<html>
  <head>
    <title>cometd client/server test page</title>

    <script type="text/javascript" src="dojo/dojo.js" 
        djConfig="isDebug: true, parseOnLoad: true, debugAtAllCosts: false"></script>
    <script type="text/javascript">
       dojo.require("dojox.cometd");
       dojo.addOnLoad(function(){
          dojox.cometd.init("webmsgServlet")
          dojox.cometd.subscribe("/testtopic", window, "display");
         }
       );
       function display(msg) {
           alert("Message " + msg.data.test);
       }
    </script>
    <div align="left">
      <button Id="publishButton" onclick="dojox.cometd.publish('/testtopic', {test: 'Data'});">
         <span style="font-size:small">PUBLISH</span>
      </button>
    </div>
   </head>
   <body></body>
</html>
      

Step 10. Install and run the application.

Assemble, install, and test the application using standard Web application assemble, installation, and test procedures.



Terms of Use | Feedback