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:

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/libon 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).

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.tldin the source distribution. Place this
taglib inside of your web application's WEB-INF directory. Deploy
your servlet implementation either inWEB-INF/classesor inWEB-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.