2. Running the Examples

Now we will try to run the examples. The examples are contained in the /webapps dir and are ready to be deployed using /webapps/pushlet.war.

2.1. Server Requirements

You need to have a servlet engine that supports servlet API 2.1 or higher and possibly JSP 1.0+ (for examples only, pushlets themselves don't require JSP). Examples of servlet engines are Tomcat (jakarta.apache.org), Resin (www.caucho.com). Most servlet engines now support the J2EE standard. By using web.xml and .war files deployment is greatly facilitated.

See compatibility.html for a list of compatible servlet engines and browsers.

Some notes:

2.2. Deploying pushlet.war

With J2EE-compliant servers such as Apache Tomcat and JBoss, deployment of the examples will be as simple as dropping /webapps/pushlet.war into Tomcat's webapps directory. Using JBoss is really cool since it supports hot deploy, i.e. you don't have to restart the server for each deployment. The Ant script in /build.xml contains a target to deploy pushlet.war. You need to adapt the deployment directory in /build.properties to point to your local deployment directory (e.g. /webapps for Tomcat).

2.3. Verifying the Examples

Run your servlet engine with the deployed pushlet.war and browse to http://<your-host:port>/pushlet and verify that the examples are working.

2.4. Troubleshooting

Although Pushlets have been shown to work in most Java servlet engines, there may be some reasons why things don't work for you.

2.4.1. No events come through

If you didn't had the above issues (servlet not found, sources.properties issues) it may be that no events come through. A common cause may be that your server is buffering the events. Try waiting a very long time (minutes) and see if a burst comes through. Then it may very well be that your server buffers. This has been observed in particular with Apache. Other causes of buffering may be inbetween proxy servers.

You may try to force "pull" for all pushlet sessions mode using listen.force.pull.all=true in pushlet.properties.

2.4.2. No events come through - mod_jk or mod_proxy(_ajp)

When you use a setup with Apache HTTP server connected to Tomcat through mod_jk or mod_proxy/mod_proxy_ajp you may find that output is buffered when using Pushlet streaming mode. Events will come through after a long time (i.e. when buffer is filled). This issue is also general Comet issue in an Apache/Tomcat setup. The solution is to force the Apache-Tomcat internal connection to flush all packets.

mod_jk: see this blog post for a solution using"JkOptions +FlushPackets".

mod_proxy/mod_proxy_ajp: see this mail for a solution using e.g."ProxyPass ajp://localhost:8009/pushlet flushpackets=on".