Pushlets - Installation
Author: Just van den Broecke
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.
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.
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:email@example.com:/cvsroot/pushlets login cvs -z3 -d:pserver:firstname.lastname@example.org:/cvsroot/pushlets co pushlets
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).
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.
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.
The servlet engine must be able to find /webapps/pushlet/WEB-INF/lib/pushlet.jar. Either it must be in the CLASSPATH or automatically deployed using J2EE configuration files.
Pushlet properties like protocol parameters are configured in /webapps/pushlet/WEB-INF/classes/pushlet.properties. When the web application initializes these properties are read from the CLASSPATH
Event sources for the examples are configured in /webapps/pushlet/WEB-INF/classes/sources.properties. When the web application initializes the event sources are automatically instantiated when enabled in pushlet.properties.
/webapps/WEB-INF/web.xml specifies the servlets (currently only the Pushlet servlet) and their mappings.
The Pushlet servlet is required for the pushlet protcol. (postlet and pullet servlets are no longer required/supported). Pushlet.init() is used for framework initialization.
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).
Run your servlet engine with the deployed pushlet.war and browse to http://<your-host:port>/pushlet and verify that the examples are working.
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.
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".