Grizzly Comet

The following sections describe how to use Grizzly Comet.

• The Grizzly Comet API

• The Hidden Frame Example

• Creating a Comet-Enabled Application

• Developing the Web Component

• Creating the Client Pages

• Creating the Deployment Descriptor

• Deploying and Running a Comet-Enabled Application

The Grizzly Comet API

Grizzly's support for Comet includes a small set of APIs that make it easy to add Comet functionality to your web applications. The Grizzly Comet APIs that developers will use most often are the following:

• CometContext: A Comet context, which is a shareable space to which applications subscribe in order to receive updates.

• CometEngine: The entry point to any component using Comet. Components can be servlets, JavaServer Pages^TM (JSP^TM), JavaServer Faces components, or pure Java classes.

• CometEvent: Contains the state of the CometContext object

• CometHandler: The interface an application implements to be part of one or more Comet contexts.

The way a developer would use this API in a web component is to perform the following tasks:

1. Register the context path of the application with the CometContext object:

   CometEngine cometEngine = 
   	CometEngine.getEngine();
   CometContext cometContext = 
   	cometEngine.register(contextPath) 

2. Register the CometHandler implementation with the CometContext object:

   cometContext.addCometHandler(handler)

3. Notify one or more CometHandler implementations when an event happens:

   cometContext.notify((Object)(handler))

The Hidden Frame Example

This rest of this tutorial uses the Hidden Frame example to explain how to develop Comet-enabled web applications. You can download the example from grizzly.dev.java.net at Hidden example download. From there, you can download a prebuilt WAR file as well as a JAR file containing the servlet code.

The Hidden Frame example is so called because it uses hidden IFrames. What the example does is it allows multiple clients to increment a counter on the server. When a client increments the counter, the server broadcasts the new count to the clients using the Comet technique.

The Hidden Frame example uses the long-polling technique, but you can easily modify it to use HTTP-streaming by removing two lines. See Notifying the Comet Handler of an Event and Creating the HTML Page That Updates and Displays the Content for more information on converting the example to use the HTTP-streaming technique.

The client side of the example uses hidden IFrames with embedded JavaScript tags to connect to the server and to asynchronously post content to and accept updates from the server.

The server side of the example consists of a single servlet that listens for updates from clients, updates the counter, and writes JavaScript code to the client that allows it to update the counter on its page.

See Deploying and Running a Comet-Enabled Application for instructions on how to deploy and run the example.

When you run the example, the following happens:

1. The index.html page opens.

2. The browser loads three frames: the first one accesses the servlet using an HTTP GET; the second one loads the count.html page, which displays the current count; and the third one loads the button.html page, which is used to send the POST request.

3. After clicking the button on the button.html page, the page submits a POST request to the servlet.

4. The doPost method calls the onEvent method of the Comet handler and redirects the incremented count along with some JavaScript to the count.html page on the client.

5. The updateCount JavaScript function on the count.html page updates the counter on the page.

6. Because this example uses long-polling, the JavaScript code on count.html calls doGet again to resume the connection after the servlet pushes the update.

Creating a Comet-Enabled Application

This section uses the Hidden Frame example application to demonstrate how to develop a Comet application. The main tasks for creating a simple Comet-enabled application are the following:

• Developing the Web Component, such as a servlet to support the Comet requests and a Comet handler to send updates to the client

• Creating the Client Pages, one or more HTML pages that include some client-side technology to open an asynchronous connection to the server and to receive updates from the web component

• Creating the Deployment Descriptor, which configures the web component

Developing the Web Component

This section shows you how to create a Comet-enabled web component by giving you instructions for creating the servlet in the Hidden Frame example.

Developing the web component involves performing the following steps:

1. Create a web component to support Comet requests.

2. Register the component with the Comet engine.

3. Define a Comet handler that sends updates to the client.

4. Add the Comet handler to the Comet context.

5. Notify the Comet handler of an event using the Comet context.

Creating a Web Component to Support Comet

1. Create an empty servlet class, like the following:

   import javax.servlet.*;
   
   public class HiddenCometServlet extends HttpServlet {
   	private static final long serialVersionUID = 1L;
   private String contextPath = null;
   	@Override
   	public void init(ServletConfig config) throws ServletException {}
   
   	@Override
   	protected void doGet(HttpServletRequest req, 
   	HttpServletResponse res) 
   	throws ServletException, IOException {}
   
   	@Override
   	protected void doPost(HttpServletRequest req, 
   	HttpServletResponse res)
   	throws ServletException, IOException {);
   }

2. Import the following Comet packages into the servlet class:

   import com.sun.grizzly.comet.CometContext;
   import com.sun.grizzly.comet.CometEngine;
   import com.sun.grizzly.comet.CometEvent;
   import com.sun.grizzly.comet.CometHandler;

3. Import these additional classes that you need for incrementing a counter and writing output to the clients:

   import java.io.IOException;
   import java.io.PrintWriter;
   import java.util.concurrent.atomic.AtomicInteger;

4. Add a private variable for the counter:

   private final AtomicInteger counter = new AtomicInteger();

Registering the Servlet with the Comet Engine

1. In the servlet's init method, add the following code to get the component's context path:

   ServletContext context = config.getServletContext();
   contextPath = context.getContextPath() + "/hidden_comet";

2. Get an instance of the Comet engine by adding this line after the lines from step 1:

    CometEngine engine = CometEngine.getEngine();

3. Register the component with the Comet engine by adding the following lines after those from step 2:

   CometContext cometContext = engine.register(contextPath);
   cometContext.setExpirationDelay(30 * 1000);

Defining a Comet Handler to Send Updates to the Client

1. Create a private class that implements CometHandler and add it to the servlet class:

   private class CounterHandler 
   	implements CometHandler<HttpServletResponse> {
   	private HttpServletResponse response;
   }

2. Add the following methods to the class:

   public void onInitialize(CometEvent event) 
   	throws IOException {}
   
   	public void onInterrupt(CometEvent event) 
   		throws IOException {
   		removeThisFromContext();
   	}
   	
   	public void onTerminate(CometEvent event) 
   		throws IOException {
   		removeThisFromContext();
   	}
   
   	public void attach(HttpServletResponse attachment) {
               this.response = attachment;
   	}
   
   	private void removeThisFromContext() throws IOException {
   		response.getWriter().close();
   		CometContext context = 
   			CometEngine.getEngine().getCometContext(contextPath);
   		context.removeCometHandler(this);
   	}

   You need to provide implementations of these methods when implementing CometHandler. The onInterrupt and onTerminate methods execute when certain changes occur in the status of the underlying TCP communication. The onInterrupt method executes when communication is resumed. The onTerminate method executes when communication is closed. Both methods call removeThisFromContext, which removes the CometHandler object from the CometContext object.

Adding the Comet Handler to the Comet Context

1. Get an instance of the Comet handler and attach the response to it by adding the following lines to the doGet method:

   CounterHandler handler = new CounterHandler();
   handler.attach(res);

2. Get the Comet context by adding the following lines to doGet:

   CometEngine engine = CometEngine.getEngine();
   CometContext context = engine.getCometContext(contextPath);

3. Add the Comet handler to the Comet context by adding this line to doGet:

   context.addCometHandler(handler);

Notifying the Comet Handler of an Event

1. Add an onEvent method to the CometHandler class to define what happens when an event occurs:

   public void onEvent(CometEvent event) 
   	throws IOException {
   	if (CometEvent.NOTIFY == event.getType()) {
   		int count = counter.get();
   		PrintWriter writer = response.getWriter();
   		writer.write("<script type='text/javascript'>" + 
   			"parent.counter.updateCount('" + count + "')" +
   			"</script>\n");
   		writer.flush();
   		event.getCometContext().resumeCometHandler(this);
   	}
   }

   This method first checks if the event type is NOTIFY, which means that the web component is notifying the CometHandler object that a client has incremented the count. If the event type is NOTIFY, the onEvent method gets the updated count, and writes out JavaScript to the client. The JavaScript includes a call to the updateCount function, which will update the count on the clients' pages.

   The last line resumes the Comet request and removes it from the list of active CometHandler objects. By this line, you can tell that this application uses the long-polling technique. If you were to delete this line, the application would use the HTTP-Streaming technique.

   • For HTTP-Streaming:

     Add the same code as for long-polling, except do not include the following line:

     event.getCometContext().resumeCometHandler(this);

   You don't include this line because you do not want to resume the request. Instead, you want the connection to remain open.

2. Increment the counter and forward the response by adding the following lines to the doPost method:

   counter.incrementAndGet();
   CometEngine engine = CometEngine.getEngine();
   CometContext<?> context = 
   	engine.getCometContext(contextPath);
   context.notify(null);
   req.getRequestDispatcher("count.html").forward(req, res);

   When a user clicks the button, the doPost method is called. The doPost method increments the counter. It then obtains the current CometContext object and calls its notify method. By calling context.notify, the doPost method triggers the onEvent method you created in the previous step. After onEvent executes, doPost forwards the response to the clients.

Creating the Client Pages

Developing the HTML pages for the client involves performing these steps:

1. Create a welcome HTML page, called index.html, that contains: one hidden frame for connecting to the servlet through an HTTP GET; one IFrame that embeds the count.html page, which contains the updated content; and one IFrame that embeds the button.html page, which is used for posting updates using HTTP POST.

2. Create the count.html page that contains an HTML element that displays the current count and the JavaScript for updating the HTML element with the new count.

3. Create the button.html page that contains a button for the users to submit updates.

Creating a Welcome HTML Page That Contains IFrames for Receiving and Sending Updates

1. Create an HTML page called index.html.

2. Add the following content to the page:

   <html>
   	<head>
   		<title>Comet Example: Counter with Hidden Frame</title>
   	</head>
   	<body>
     </body>
   </html>

3. Add IFrames for connecting to the server and receiving and sending updates to index.html in between the body tags:

   <frameset>
   	<iframe name="hidden" src="hidden_comet" 
   		frameborder="0" height="0" width="100%"></iframe>
   	<iframe name="counter" src="count.html" 
   		frameborder="0" height="100%" width="100%"></iframe>
   <iframe name="button" src="button.html" frameborder="0" height="30%" widget="100%"></iframe>
   </frameset>

   The first frame, which is hidden, points to the servlet by referencing its context path. The second frame displays the content from count.html, which displays the current count. The second frame displays the content from button.html, which contains the submit button for incrementing the counter.

Creating the HTML Page That Updates and Displays the Content

1. Create an HTML page called count.html and add the following content to it:

   <html>
   	<head>
   	</head>
   		<body>
   			<center>
   				<h3>Comet Example: Counter with Hidden Frame</h3>
   				<p>
   				<b id="count">&nbsp;</b>
   				<p>
   			</center>
   		</body>
   </html>

   This page displays the current count.

2. Add JavaScript code that updates the count in the page . Add the following lines in between the head tags of count.html:

   <script type='text/javascript'>
   	function updateCount(c) {
   		document.getElementById('count').innerHTML = c;
   		parent.hidden.location.href = "hidden_comet";
   	};
   </script>

   The JavaScript takes the updated count it receives from the servlet and updates the count element in the page. The last line in the updateCount function invokes the servlet's doGet method again to reestablish the connection.

   • For HTTP-Streaming:

     Add the same code as for long-polling, except for the following line:

     parent.hidden.location.href = “hidden_comet”

     This line invokes the doGet method of CometServlet again, which would reestablish the connection. In the case of HTTP-Streaming, you want the connection to remain open. Therefore, you don't include this line of code.

Creating the HTML Page That Allows Submitting Updates

1. Create an HTML page called button.html and add the following content to it:

   <html>
   	<head>
   	</head>
   		<body>
   			<center>
   				<form method="post" action="hidden_comet">
   					<input type="submit" value="Click">
   				</form>
   			</center>
   		</body>
   </html>

   This page displays a form with a button that allows a user to update the count on the server. The servlet will then broadcast the updated count to all clients.

Creating the Deployment Descriptor

This section describes how to create a deployment descriptor to specify how your Comet-enabled web application should be deployed.

Creating the Deployment Descriptor

1. Create a file called web.xml and put the following contents in it:

   <?xml version="1.0" encoding="UTF-8"?>
   	<web-app version="2.5"
   		xmlns="http://java.sun.com/xml/ns/javaee"
   		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   		xsi:schemaLocation=
   			"http://java.sun.com/xml/ns/javaee 
   			http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd ">
   			
   		<servlet>
   			<servlet-name>HiddenCometServlet</servlet-name>
   			<servlet-class>
   				com.sun.grizzly.samples.comet.HiddenCometServlet
   			</servlet-class>
   			<load-on-startup>0</load-on-startup>
   		</servlet>
   		<servlet-mapping>
   			<servlet-name>HiddenCometServlet</servlet-name>
   			<url-pattern>/hidden_comet</url-pattern>
   		</servlet-mapping>
   	</web-app>

   This deployment descriptor contains a servlet declaration and mapping for HiddenCometServlet. The load-on-startup attribute must be set to 0 so that the Comet-enabled servlet will not load until the client makes a request to it.

Deploying and Running a Comet-Enabled Application

Before running a Comet-enabled application in the Enterprise Server, you need to enable Comet in the server. Then you can deploy the application just as you would any other web application.

When running the application, you need to connect to it from at least two different browsers to experience the effect of the servlet updating all clients in response to one client posting an update to the server.

Enabling Comet in the Enterprise Server

Before running a Comet-enabled application, you need to enable Comet in your application server by adding a special property to the http-listener element of the domain.xml file.

The following steps tell you how to add this property.

1. Open domain-dir/config/domain.xml in a text editor.

2. Add the following property in between the http-listener start and end tags:

   <property name="cometSupport" value="true"/>

3. Save domain.xml and restart the server.

Deploying the Example

These instructions tell you how to deploy the Hidden Frame example.

1. Download grizzly-comet-hidden-1.7.3.1.war.

2. Run the following command to deploy the example:

   as-install/bin/asadmin deploy grizzly-comet-hidden-1.7.3.1.war

Running the Example

These instructions tell you how to run the Hidden Frame example.

1. Open two web browsers, preferably two different brands of web browser.

2. Enter the following URL in both browsers:

   http://localhost:8080/grizzly-comet-hidden/index.html

3. When the first page loads in both browsers, click the button in one of the browsers and watch the count change in the other browser window.