Pushlets - Installation

Author: Just van den Broecke
Organization: Just Objects B.V.
Email: just[AT]justobjects.nl

FileID: $Id: installation.xml,v 1.5 2009/04/16 10:48:42 justb Exp $
Date: $Date: 2009/04/16 10:48:42 $

This document describes the installation and deployment of the pushlet distribution. It applies to version 2.0.4.


1. Installation

1.1. Unpack Distribution

Unzip pushlet-x.y.z.zip or tar xzvf pushlet-x.y.z-tar.gz.

1.2. Directories

The unpacked distribution should contain the following directories:

                    /client additional (non-J2SE) clients
                    /src all Java sources
                    /webapps pushlet.war file with the examples; also unpacked in the pushlet subdir
                    /doc all documentation
                    /lib the pushlet.jar and pushletclient.jar libraries
                    /thirdparty external libraries
                

From here on file names starting with "/" are referred from the top of the install dir.

1.3. Getting from CVS

If you want to check out the current version from CVS, follow the instructions on http://sourceforge.net/cvs/?group_id=62939. Anonynmous CVS checkout can be done as follows:

                    cvs -d:pserver:anonymous@pushlets.cvs.sourceforge.net:/cvsroot/pushlets login

                    cvs -z3 -d:pserver:anonymous@pushlets.cvs.sourceforge.net:/cvsroot/pushlets co pushlets
                

1.4. Rebuilding

Assuming you have Ant installed, you can rebuild the .jars and .war in this distribution by typing ant in the toplevel directory. /build.xml is the Ant build file for all jars and wars.

If you want to rebuild an entire distribution from CVS which includes documentation, you need to use the build file/build-dist.xml. Pass this build file to ant as follows:ant -f build-dist.xml. If you don't care about building the documentation you may as well use /build.xml with the CVS version.

There is one nasty issue which makes the XBook documentation generation fail (NullPointerException or ArrayOutOfBoundsException) in some cases when building the distribution (using /build-dist.xml) from CVS. This has to do with xalan.jar in your CLASSPATH, either in the Ant lib dir or in J2SE 1.4 runtime. xalan.jar is also present in xbookaux.jar but must be in the same classloader as xbook.jar. I resolved this by putting both xbook jars (under /thirdparty/justobjects/xbook) in the Ant lib dir (and removing xalan.jar).

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".