From 13a654d347e97e0c1a0b71250e11614453d1121a Mon Sep 17 00:00:00 2001
From: Bruce Robbins <robbins@everychoose-lm.(none)>
Date: Wed, 23 Feb 2011 09:38:54 -0800
Subject: [PATCH] Update client usage document to include Java example

---
 source/manual/client_usage.rst    | 80 +++++++++++++++++++++++++++++--
 source/manual/joining_streams.rst |  2 +-
 2 files changed, 78 insertions(+), 4 deletions(-)

diff --git a/source/manual/client_usage.rst b/source/manual/client_usage.rst
index d89251f..14756a6 100644
--- a/source/manual/client_usage.rst
+++ b/source/manual/client_usage.rst
@@ -17,15 +17,37 @@ Clone the repository:
   cd ${SOURCE_BASE}
   git clone git://github.com/s4/driver.git
 
+Alternatively, you can download the source as an archive file:
+
+1. Browse to https://github.com/s4/driver
+2. Click on Downloads button
+3. Select "Download .tar.gz"
+4. Download to your ``${SOURCE_BASE}`` directory
+5. ``tar xzf driver s4-driver-*.tar.gz``
+6. rename the directory to the expected name: ``find . -name "s4-driver*" | grep -v tar | xargs -J % mv % driver``
+
+To run the examples, you need a usable S4 image that contains the Speech02 sample application. See :ref:`here <building_and_running_speech02>`. Note: When creating your S4 image, follow those instructions for building S4 from latest source.
+
 Set environment variables.
 
+===============  =======================================================================================================================================================
+variable name    value
+===============  =======================================================================================================================================================
+``IMAGE_BASE``   the base directory of your runnable image (this would be :file:`${HOME}/s4image` if you followed the steps in :doc:`/tutorials/getting_started`)
+``PERLLIB``      ${SOURCE_BASE}/driver/perl/src
+``PYTHONPATH``   ${SOURCE_BASE}/driver/python
+``JAVA_HOME``    the base directory of your Java installation. You need to set this variable if you plan to run the Java example.
+===============  =======================================================================================================================================================
+
+For example:
+
 .. code-block:: bash
 
-  export PERLLIB=${SOURCE_BASE}/driver/perl/src
   export PYTHONPATH=${SOURCE_BASE}/driver/python
+  export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
 
-Injecting Events
-----------------
+Injecting Events with a Perl Client
+-----------------------------------
 
 We will use the ``speech02`` application.
 
@@ -68,6 +90,58 @@ As before, create an image. Let us call the image folder ``$IMAGE_BASE``.
 4. As in the ``speech02`` tutorial, observe that messages are printed by the
    event catcher PE.
 
+Injecting Events with a Java Client
+-----------------------------------
+
+Again, we will use the ``speech02`` application.
+
+Packages:
+
+- ``s4_core-0.3.0.0``
+- ``speech01-0.0.0.1``
+- ``speech02-0.0.0.2``
+
+1. Build the driver
+
+   1. ``cd ${SOURCE_BASE}/driver/java``
+   2. ``mvn install``
+
+  
+2. Build the sample client
+
+   1. ``cd ../examples/inject_java``
+   2. ``mvn assembly:assembly``
+
+  
+3. Start the S4 cluster, specifying the name of the client adapter cluster
+   (``-r``)
+
+   .. code-block:: bash
+
+     cd $IMAGE_BASE
+     ./bin/s4_start.sh -r client-adapter redbutton &
+
+4. Start the client adapter
+
+   .. code-block:: bash
+
+     ./bin/run_client_adapter.sh -s client-adapter -g s4 \
+     -x -d s4_core/conf/redbutton/client_stub_conf.xml &
+
+5. Inject events
+
+   .. code-block:: bash
+
+     cd ${SOURCE_BASE}/driver/examples/inject_java/target/inject_java-*.dir/bin
+
+     ./inject.sh localhost 2334 RawSpeech io.s4.example.speech01.Speech < \
+         ${SOURCE_BASE}/examples/testinput/speech.in
+
+     ./inject.sh localhost 2334 RawSentence io.s4.example.speech01.Sentence < \
+	     ${SOURCE_BASE}/examples/testinput/sentence.in
+
+6. As in the ``speech02`` tutorial, observe that messages are printed by the
+   event catcher PE.
 
 Receiving Events
 ----------------
diff --git a/source/manual/joining_streams.rst b/source/manual/joining_streams.rst
index 183f261..ac39e91 100644
--- a/source/manual/joining_streams.rst
+++ b/source/manual/joining_streams.rst
@@ -268,7 +268,7 @@ Because the PE is key-less, there is at most one instance per S4 node:
 
 .. image:: /../_static/joinPEc.png
 
-
+.. _building_and_running_speech02:
 
 Building and running the *speech02* example
 -------------------------------------------