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

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:anonymous@pushlets.cvs.sourceforge.net:/cvsroot/pushlets login

cvs -z3 -d:pserver:anonymous@pushlets.cvs.sourceforge.net:/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).

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:

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

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