How to implement the reference streamer in Jboss

A note on caching

The streamer is written in java, which isn't known for speed under the best cases. I attempted to design it to be as fast as possible, and it is indeed fast. With that said, the streamer adds 200 to 500 ms overhead to each request. On a server under heavy load, it can (clearly) be more. As such, it is recommended that caching or load balancing be implemented on the front side of the streamer for high-bandwidth sites.

Step 0: Get the source.

If you downloaded the binary tarball then please feel free to skip to Step 1.

From a console, use CVS to get the latest streamer source. This can be done via the following two commands in a BASH shell:

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

Once you have checked out the streamer source code, you will want to build it. On a Gentoo Linux system with your java classpath configured this can be quite easy by simply emerging commons-httpclient and oro and then using java-config to configure your classpath. The ant build script uses the classpath to find the prerequsists, which are the Jakarta project oro (for regular expressions) and the Jakarta commons project HttpClient.

Step 1: The jar file.

Once the jar has been built, copy it to your server lib directory. On Gentoo linux this would be /var/lib/jboss/default/lib on a default configuration (or perhaps all or minimal if you have changed your jboss.conf). It will be system specific on other configurations, and if you are not familiar with where to find you jboss install perhaps you are getting ahead of yourself reading this document =).

Step 2: Connection Pool

To configure the reference connection pool deploy the streamer_jca.rar into your JBoss deploy directory. On Gentoo it would be /var/lib/jboss/default/deploy. This file only contains the jca deployment descriptor xml file (ra.xml).

Step 3: Deploy the streamer configuration file

The streamer operates on a series of rewrite rules listed inside of a configuration file. This file is in XML format and can be located anywhere you like (provided the user jboss is running under has permission to read the file). You specify the name and location of this file in the next section. By default, I recommend you place it in the server conf directory. On Gentoo, this would be /var/lib/jboss/default/conf. It is out of the scope of this document to describe how to go about creating rewrite rules. Please see the guide to rewriting for more information on that subject.

Step 4: Deploy the data source descriptor

Copy the pstream-ds.xml to your deploy directory. Again, as above, on Gentoo it would be /var/lib/jboss/default/deploy.

This will deploy your datasource. If you wish to alter the jndi name of your connection pool, or the properties of the streamer connection, you must do so in this file. The contents are displayed here for reference, but I believe most are self-explanatory. NOTE: The JCA connection pool in jboss will return null for a connection if any of these parameters are invalid (such as PortletName not existing in the config file, or the config file not existing where ConfigURL points or not being readable by the jboss user).

<connection-factories>

<no-tx-connection-factory>

<jndi-name>pstream_jca</jndi-name>

<adapter-display-name>PstreamJCA</adapter-display-name>

<config-property name="PortletName" type="java.lang.String">zope</config-property>

<config-property name="ConfigURL" type="java.lang.String">file:///var/lib/jboss/default/conf/pstream_config.xml</config-property>

<config-property name="Protocol" type="java.lang.String">http</config-property>

<config-property name="Host" type="java.lang.String">10.2.2.60</config-property>

<config-property name="Port" type="java.lang.Integer">8780</config-property>

</no-tx-connection-factory>

</connection-factories>

You can deploy as many datasources as you like, provided all of the jndi-name parameters differ. There probably isn't much point in configuring multiple datasources for the same configurations, so you probably also change the PortletName config property to point at a different configuration. There is no need to have multiple configuration files (although you can if you wish) because it will support multiple streamer configurations.

Step 5: Implementing the reference servlet.

The reference servlet is an abstract class. An implementing class needs to define the method getPoolName which returns the jndi name of the connection pool the implementing class should retrieve. To use the reference implementation, that is all that is required. See the API documentation if there is any custom overrides you wish to implement inside of your own servlet.

Step 6: The web application.

You can find the taglib definition for the reference jsp implementation inside of ./src/META-INF/pstream.tld in the source distribution. Place this taglib inside of your web application's WEB-INF directory. Deploy your servlet implementation either in WEB-INF/classes or in WEB-INF/lib (if it is in a jar file).

Step 7: Enjoy =) This is an early version of this document so I do not have a troubleshooting guide as yet. As time allows and promotion of the project expands I will be happy to provide one.