QPID-5374: [Documentation] Added JMS pub/sub example.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1554404 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 311 insertions, 177 deletions

diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
index 6a3b335299..9042854f56 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Appendix-Maven.xml
@@ -29,8 +29,8 @@
 <appendix id="JMS-Client-0-8-Appendix-Maven">
   <title>Minimal Maven POM</title>
   <para> The following is a minimal Maven POM required to use the Qpid Client. It is suitable for
-    use with the <link linkend="JMS-Client-0-8-Hello-World-Example">examples</link> included in this
-    book</para>
+    use with the <link linkend="JMS-Client-0-8-Examples">examples</link> included in this
+    book.</para>
 
   <example>
     <title>Minimal Maven POM </title>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
index 13a93522cb..c433d459b5 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml
@@ -26,7 +26,7 @@
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Introduction.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Document-Scope-And-Intended-Audience.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Getting-And-Dependencies.xml"/>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Hello-World-Example.xml"/>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Examples.xml"/>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Understanding.xml"/>
     <!-- TODO:
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
index caa2dec37e..13b30b0e05 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Document-Scope-And-Intended-Audience.xml
@@ -40,7 +40,7 @@
   <para>
     The document covers some specific implementation details of JMS connections, sessions, consumers and producers
     in <xref linkend="JMS-Client-0-8-Client-Understanding"/>. It also demonstrates how to write a simple
-    <emphasis>Hello World</emphasis> application using Qpid JMS Client in <xref linkend="JMS-Client-0-8-Hello-World-Example"/>. 
+    point to point and simple publish/subscribe application using Qpid JMS Client in <xref linkend="JMS-Client-0-8-Examples"/>. 
   </para>
 
   <para>The Qpid JMS Client supports various configuration options which can be set via JVM system
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
new file mode 100644
index 0000000000..5ab40a006a
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Examples.xml
@@ -0,0 +1,297 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<chapter id="JMS-Client-0-8-Examples">
+	<title>Examples</title>
+
+	<para>The following programs shows how to send and receive messages using the Qpid JMS client.
+		The first program illustrates a <emphasis>point to point</emphasis> example, the second, a
+		pubish/subscribe example. </para>
+	<para>Both examples show the use JNDI to obtain connection factory and destination objects which
+		the application needs. In this way the configuration is kept separate from the application
+		code itself.</para>
+	<para>The example code will be straightforward for anyone familiar with Java JMS. Readers in
+		need of an introduction are directed towards <ulink url="&oracleJmsTutorial;">Oracle's JMS
+			tutorial</ulink>.</para>
+	<section id="JMS-Client-0-8-Examples-PTP">
+		<title>Point to point example</title>
+		<para>In this example, we illustrate point to point messaging. We create a JNDI context
+			using a properties file, use the context to lookup a connection factory, create and
+			start a connection, create a session, and lookup a destination (a queue) from the JNDI
+			context. Then we create a producer and a consumer, send a message with the producer and
+			receive it with the consumer.</para>
+
+		<example id="JMS-Client-0-8-Examples-PTP-Java">
+			<title>JMS Example - Point to Point Messaging</title>
+			<programlisting lang="java">
+import javax.jms.*;
+import javax.naming.Context;
+import javax.naming.InitialContext;
+import java.util.Properties;
+
+public class Hello {
+
+    public Hello() {
+    }
+
+    public static void main(String[] args) throws Exception {
+        Hello hello = new Hello();
+        hello.runTest();
+    }
+
+    private void runTest() throws Exception {
+      Properties properties = new Properties();
+      properties.load(this.getClass().getResourceAsStream("helloworld.properties"));  <co id="ptp-java-properties" linkends="callout-ptp-properties"/>
+      Context context = new InitialContext(properties);   <co id="ptp-java-context" linkends="callout-ptp-context"/>
+
+      ConnectionFactory connectionFactory
+          = (ConnectionFactory) context.lookup("qpidConnectionFactory"); <co id="ptp-java-connection-factory" linkends="callout-ptp-connection-factory"/>
+      Connection connection = connectionFactory.createConnection();  <co id="ptp-java-connection" linkends="callout-ptp-connection"/>
+      connection.start();  <co id="ptp-java-start" linkends="callout-ptp-start"/>
+
+      Session session = connection.createSession(true, Session.SESSION_TRANSACTED);<co id="ptp-java-session" linkends="callout-ptp-session"/>
+      Queue queue = (Queue) context.lookup("myqueue");  <co id="ptp-java-destination" linkends="callout-ptp-destination"/>
+
+      MessageConsumer messageConsumer = session.createConsumer(queue);  <co id="ptp-java-consumer" linkends="callout-ptp-consumer"/>
+      MessageProducer messageProducer = session.createProducer(queue);  <co id="ptp-java-producer" linkends="callout-ptp-producer"/>
+
+      TextMessage message = session.createTextMessage("Hello world!");        <co id="ptp-java-send" linkends="callout-ptp-send"/>
+      messageProducer.send(message);
+      session.commit();
+
+      message = (TextMessage)messageConsumer.receive();    <co id="ptp-java-receive" linkends="callout-ptp-receive"/>
+      session.commit();
+      System.out.println(message.getText());
+
+      connection.close();  <co id="ptp-java-close" linkends="callout-ptp-close"/>
+      context.close();   <co id="ptp-java-jndi-close" linkends="callout-ptp-jndi-close"/>
+    }
+}
+	</programlisting>
+		</example>
+
+		<calloutlist>
+			<callout id="callout-ptp-properties" arearefs="ptp-java-properties">
+				<para>Loads the JNDI properties file, which specifies the connection factory, queues
+					and topics. See <xref linkend="JMS-Client-0-8-JNDI-Properties-Format"/> for
+					details.</para>
+			</callout>
+			<callout id="callout-ptp-context" arearefs="ptp-java-context">
+				<para>Creates the JNDI initial context.</para>
+			</callout>
+			<callout id="callout-ptp-connection-factory" arearefs="ptp-java-connection-factory">
+				<para>Looks up a JMS connection factory for Qpid.</para>
+			</callout>
+			<callout id="callout-ptp-connection" arearefs="ptp-java-connection">
+				<para>Creates a JMS connection. Creating the JMS connections establishes the
+					connection to the Broker.</para>
+			</callout>
+			<callout id="callout-ptp-start" arearefs="ptp-java-start">
+				<para>Starts the connection, required for the consumption of messages.</para>
+			</callout>
+			<callout id="callout-ptp-session" arearefs="ptp-java-session">
+				<para>Creates a transactional session.</para>
+			</callout>
+			<callout id="callout-ptp-destination" arearefs="ptp-java-destination">
+				<para>Looks up a destination for the queue with JNDI name myqueue.</para>
+			</callout>
+			<callout id="callout-ptp-consumer" arearefs="ptp-java-consumer">
+				<para>Creates a consumer that reads messages from the queue<footnote>
+						<para>Creating consumer will automatically create the queue on the Broker
+							and bind it to an exchange. Specifically, in this case as the
+								<literal>queue.</literal> form is used in the JNDI properties the
+							effect will be to create a queue called <literal>queue1</literal> on the
+							Broker, and create a binding between the <literal>amq.direct</literal>
+							exchange and this queue using the queue's name. This process is
+							described in detail in <xref
+								linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-ConsumerSideEffect"
+							/></para>
+					</footnote>.</para>
+			</callout>
+			<callout id="callout-ptp-producer" arearefs="ptp-java-producer">
+				<para>Creates a producer that sends messages to the queue.</para>
+			</callout>
+			<callout id="callout-ptp-send" arearefs="ptp-java-send">
+				<para>Creates a new TextMessages, publishes the messages and commits the
+					session.</para>
+			</callout>
+			<callout id="callout-ptp-receive" arearefs="ptp-java-receive">
+				<para>Reads the next available message (awaiting indefinitely if necessary) and
+					commits the session.</para>
+			</callout>
+			<callout id="callout-ptp-close" arearefs="ptp-java-close">
+				<para>Closes the Connection. All sessions owned by the Connection along with their
+					MessageConsumers and MessageProducers are automatically closed. The connection
+					to the Broker is closed as this point.</para>
+			</callout>
+			<callout id="callout-ptp-jndi-close" arearefs="ptp-java-jndi-close">
+				<para>Closes the JNDI context.</para>
+			</callout>
+		</calloutlist>
+
+		<para>The contents of the <literal>helloworld.properties</literal> file are shown
+			below.</para>
+
+		<example id="JMS-Client-0-8-Examples-PTP-PropertiesFile">
+			<title>JMS Example - Point to Point Messaging - JNDI Properties</title>
+			<programlisting>
+java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672' <co id="ptp-properties-connectionfactory" linkends="callout-ptp-properties-connectionfactory"/>
+queue.myqueue = queue1 <co id="ptp-properties-destination" linkends="callout-ptp-properties-destination"/>
+	</programlisting>
+		</example>
+
+		<calloutlist>
+			<callout id="callout-ptp-properties-connectionfactory"
+				arearefs="ptp-properties-connectionfactory">
+				<para>Defines a connection factory from which Connections can be created. The syntax
+					of a ConnectionURL is given in <xref
+						linkend="JMS-Client-0-8-JNDI-Properties-Format"/>.</para>
+			</callout>
+			<callout id="callout-ptp-properties-destination" arearefs="ptp-properties-destination">
+				<para>Defines a queue for which MessageProducers and/or MessageConsumers send and
+					receive messages. The format of these entries is described in <xref
+						linkend="JMS-Client-0-8-JNDI-Properties-Format-Queue"/>.</para>
+			</callout>
+		</calloutlist>
+	</section>
+	<section id="JMS-Client-0-8-Examples-PubSub">
+		<title>Publish/subscribe example</title>
+		<para>In this second example, we illustrate publish/subscribe messaging. Again, we create a
+			JNDI context using a properties file, use the context to lookup a connection factory,
+			create and start a connection, create a session, and lookup a destination (a topic) from
+			the JNDI context. Then we create a producer and two durable subscribers , send a message
+			with the producer. Both subscribers receive the same message.</para>
+
+		<example id="JMS-Client-0-8-Examples-PubSub-Java">
+			<title>JMS Example - Publish/subscribe Messaging</title>
+			<programlisting lang="java">
+import javax.jms.*;
+import javax.naming.Context;
+import javax.naming.InitialContext;
+
+import java.util.Properties;
+
+public class StocksExample {
+
+    public StocksExample() {
+    }
+
+    public static void main(String[] args) throws Exception {
+      StocksExample stocks = new StocksExample();
+      stocks.runTest();
+    }
+
+    private void runTest() throws Exception {
+      Properties properties = new Properties();
+      properties.load(this.getClass().getResourceAsStream("stocks.properties"));
+      Context context = new InitialContext(properties);
+
+      ConnectionFactory connectionFactory
+          = (ConnectionFactory) context.lookup("qpidConnectionFactory");
+      Connection connection = connectionFactory.createConnection();
+      connection.start();
+
+      Session session = connection.createSession(true, Session.SESSION_TRANSACTED);
+      Topic priceTopic = (Topic) context.lookup("myprices"); <co id="pubsub-java-destination" linkends="callout-pubsub-destination"/>
+
+      MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1");  <co id="pubsub-java-subscribers" linkends="callout-pubsub-subscribers"/>
+      MessageConsumer subscriber2 = session.createDurableSubscriber(priceTopic, "sub2" /*, "price > 150", false*/ );
+      MessageProducer messageProducer = session.createProducer(priceTopic);
+
+      Message message = session.createMessage();
+      message.setStringProperty("instrument", "IBM");
+      message.setStringProperty("price", "100");
+      messageProducer.send(message);
+      session.commit();
+
+      message = subscriber1.receive(1000);
+      session.commit();
+      System.out.println("Subscriber 1 received : " + message);
+
+      message = subscriber2.receive(1000);
+      session.commit();
+      System.out.println("Subscriber 2 received : " + message);
+
+      session.unsubscribe("sub1"); <co id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
+      session.unsubscribe("sub2");
+      connection.close();
+      context.close();
+    }
+}
+	</programlisting>
+		</example>
+
+		<calloutlist>
+			<callout id="callout-pubsub-destination" arearefs="pubsub-java-destination">
+				<para>Looks up a destination for the topic with JNDI name myprices.</para>
+			</callout>
+			<callout id="callout-pubsub-subscribers" arearefs="pubsub-java-subscribers">
+				<para>Creates two durable subscribers, <literal>sub1</literal> and
+						<literal>sub2</literal>. Durable subscriptions retain messages for the
+					client even when the client is disconnected, until the subscription is
+					unsubscribed. Subscription 2 has a (commented out) message selector argument so
+					you can conveniently experiement with the effect of those. <footnote>
+						<para>Each durable subscription is implemented as a queue on the Broker. See
+								<xref
+								linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-TopicSubscriptions"
+							/> for details.</para>
+					</footnote></para>
+			</callout>
+			<callout id="callout-pubsub-unsubscribe" arearefs="pubsub-java-unsubscribe">
+				<para>Unsubscribes the two durable subscribers, permanently removing the knowledge
+					of the subscriptions from the system. An application would normally
+						<emphasis>NOT</emphasis> do this. The typical use-case for durable
+					subsciption is one where the subscription exists over an extended period of
+					time.</para>
+			</callout>
+		</calloutlist>
+
+		<para>The contents of the <literal>stocks.properties</literal> file are shown below.</para>
+
+		<example id="JMS-Client-0-8-Examples-PubSub-PropertiesFile">
+			<title>JMS Example - Publish/subscribe Messaging - JNDI Properties</title>
+			<programlisting>
+java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672'
+topic.myprices = prices <co id="pubsub-properties-destination" linkends="callout-pubsub-properties-destination"/>
+	</programlisting>
+		</example>
+
+		<calloutlist>
+			<callout id="callout-pubsub-properties-destination"
+				arearefs="pubsub-properties-destination">
+				<para>Defines a topic for which MessageProducers and/or MessageConsumers send and
+					receive messages. The format of this entry is described in <xref
+						linkend="JMS-Client-0-8-JNDI-Properties-Format-Topic"/>.</para>
+			</callout>
+		</calloutlist>
+	</section>
+
+
+</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
index e57b3b0bef..bae5278c1c 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Getting-And-Dependencies.xml
@@ -28,7 +28,7 @@
 
 <chapter id="JMS-Client-0-8-JMS-Getting-And-Dependencies">
   <title>Getting the Client And Dependencies</title>
-  <section>
+  <section id="JMS-Client-0-8-JMS-Getting-And-Dependencies-Getting">
     <title>Getting the Client</title>
     <para>The Qpid JMS client is available as a bundle or from &qpidMavenRepoDesc;.</para>
     <para>The bundle (a .tar.gz) includes the Qpid JMS client itself (formed by two JAR: qpid-client
@@ -47,7 +47,7 @@
     ]]></screen>
     <para><xref linkend="JMS-Client-0-8-Appendix-Maven"/> illustrates a minimal Maven POM required to use the Qpid Client.</para>
   </section>
-  <section>
+  <section id="JMS-Client-0-8-JMS-Getting-And-Dependencies-Dependencies">
     <title>Dependencies</title>
     <para>The Qpid JMS client has minimal set of external dependencies. </para>
     <para> It requires: <itemizedlist>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Hello-World-Example.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Hello-World-Example.xml
deleted file mode 100644
index 7c8d0e1734..0000000000
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Hello-World-Example.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
-[
-<!ENTITY %  entities SYSTEM  "commonEntities.xml">
-%entities;
-]>
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements.  See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership.  The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License.  You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied.  See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-<chapter id="JMS-Client-0-8-Hello-World-Example">
-	<title>Hello World Example</title>
-
-	<para>The following program shows how to send and receive a message using the Qpid JMS client.
-		JMS programs typically use JNDI to obtain connection factory and destination objects which
-		the application needs. In this way the configuration is kept separate from the application
-		code itself.</para>
-
-	<para>In this example, we create a JNDI context using a properties file, use the context to
-		lookup a connection factory, create and start a connection, create a session, and lookup a
-		destination from the JNDI context. Then we create a producer and a consumer, send a message
-		with the producer and receive it with the consumer. This code should be straightforward for
-		anyone familiar with Java JMS.</para>
-
-	<example>
-		<title>"Hello world!" in Java</title>
-		<programlisting lang="java">
-import javax.jms.*;
-import javax.naming.Context;
-import javax.naming.InitialContext;
-import java.util.Properties;
-
-public class Hello {
-
-	public Hello() {
-	}
-	
-	public static void main(String[] args) throws Exception {
-	  Hello producer = new Hello();
-	  producer.runTest();
-	}
-	
-	private void runTest() throws Exception {
-	  Properties properties = new Properties();
-	  properties.load(this.getClass().getResourceAsStream("jndi.properties"));  <co id="hello-java-properties" linkends="callout-java-properties"/>
-	  Context context = new InitialContext(properties);   <co id="hello-java-context" linkends="callout-java-context"/>
-	
-	  ConnectionFactory connectionFactory
-	      = (ConnectionFactory) context.lookup("qpidConnectionFactory"); <co id="hello-java-connection-factory" linkends="callout-java-connection-factory"/>
-	  Connection connection = connectionFactory.createConnection();  <co id="hello-java-connection" linkends="callout-java-connection"/>
-	  connection.start();  <co id="hello-java-start" linkends="callout-java-start"/>
-	
-	  Session session = connection.createSession(true, Session.SESSION_TRANSACTED);<co id="hello-java-session" linkends="callout-java-session"/>
-	  Destination destination = (Destination) context.lookup("myqueue");  <co id="hello-java-destination" linkends="callout-java-destination"/>
-	
-	  MessageConsumer messageConsumer = session.createConsumer(destination);  <co id="hello-java-consumer" linkends="callout-java-consumer"/>
-	  MessageProducer messageProducer = session.createProducer(destination);  <co id="hello-java-producer" linkends="callout-java-producer"/>
-	
-	  TextMessage message = session.createTextMessage("Hello world!");        <co id="hello-java-send" linkends="callout-java-send"/>
-	  messageProducer.send(message);
-	  session.commit();
-	
-	  message = (TextMessage)messageConsumer.receive();    <co id="hello-java-receive" linkends="callout-java-receive"/>
-	  session.commit();
-	  System.out.println(message.getText());
-	
-	  connection.close();  <co id="hello-java-close" linkends="callout-java-close"/>
-	  context.close();   <co id="hello-java-jndi-close" linkends="callout-java-jndi-close"/>
-	}
-}
-	</programlisting>
-	</example>
-
-	<calloutlist>
-		<callout id="callout-java-properties" arearefs="hello-java-properties">
-			<para>Loads the JNDI properties file, which specifies the connection factory, queues and topics. See <xref linkend="JMS-Client-0-8-JNDI-Properties-Format"/> for details.</para>
-		</callout>
-		<callout id="callout-java-context" arearefs="hello-java-context">
-			<para>Creates the JNDI initial context.</para>
-		</callout>
-		<callout id="callout-java-connection-factory" arearefs="hello-java-connection-factory">
-			<para>Looks up a JMS connection factory for Qpid.</para>
-		</callout>
-		<callout id="callout-java-connection" arearefs="hello-java-connection">
-			<para>Creates a JMS connection.  Creating the JMS connections establishes the connection to the Broker.</para>
-		</callout>
-		<callout id="callout-java-start" arearefs="hello-java-start">
-			<para>Starts the connection, required for the consumption of messages.</para>
-		</callout>
-		<callout id="callout-java-session" arearefs="hello-java-session">
-			<para>Creates a transactional session.</para>
-		</callout>
-		<callout id="callout-java-destination" arearefs="hello-java-destination">
-			<para>Looks up a destination for the queue with JNDI name myqueue.</para>
-		</callout>
-		<callout id="callout-java-consumer" arearefs="hello-java-consumer">
-			<para>Creates a consumer that reads messages from the queue<footnote>
-				<para>Creating consumer will automatically create the queue on the Broker and bind it to an exchange. Specifically, in this case
-				 as the <literal>queue.</literal> form is used in the JNDI properties the effect will be to create a queue called
-			     <literal>queue1</literal> on the Broker, and create a binding between the <literal>amq.direct</literal> exchange
-			     and this queue using the queue's name. This process is described in detail in
-			     <xref linkend="JMS-Client-0-8-Client-Understanding-MessageConsumer-ConsumerSideEffect"/></para></footnote>.</para>
-		</callout>
-		<callout id="callout-java-producer" arearefs="hello-java-producer">
-			<para>Creates a producer that sends messages to the queue.</para>
-		</callout>
-		<callout id="callout-java-send" arearefs="hello-java-send">
-			<para>Creates a new TextMessages, publishes the messages and commits the session.</para>
-		</callout>
-		<callout id="callout-java-receive" arearefs="hello-java-receive">
-			<para>Reads the next available message (awaiting indefinitely if necessary) and commits the session.</para>
-		</callout>
-		<callout id="callout-java-close" arearefs="hello-java-close">
-			<para>Closes the Connection. All sessions owned by the Connection along with their
-				MessageConsumers and MessageProducers are automatically closed.  The connection to the
-			    Broker is closed as this point.</para>
-		</callout>
-		<callout id="callout-java-jndi-close" arearefs="hello-java-jndi-close">
-			<para>Closes the JNDI context.</para>
-		</callout>
-	</calloutlist>
-
-	<para>The contents of the <literal>jndi.properties</literal> file are shown below.</para>
-
-	<example id="JMS-Client-0-8-Hello-World-Example-PropertiesFile">
-		<title>JNDI Properties File for "Hello world!" example</title>
-		<programlisting>
-java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
-connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672' <co id="hello-properties-connectionfactory" linkends="callout-hello-properties-connectionfactory"/>
-queue.myqueue = queue1 <co id="hello-properties-destination" linkends="callout-hello-properties-destination"/>
-	</programlisting>
-	</example>
-
-	<calloutlist>
-		<callout id="callout-hello-properties-connectionfactory"
-			arearefs="hello-properties-connectionfactory">
-			<para>Defines a connection factory from which Connections can be created. The syntax of
-				a ConnectionURL is given in <xref linkend="JMS-Client-0-8-JNDI-Properties-Format"/>.</para>
-		</callout>
-		<callout id="callout-hello-properties-destination" arearefs="hello-properties-destination">
-			<para>Defines a queue for which MessageProducers and/or MessageConsumers send and receive messages. The format of these entries is
-				 described in <xref linkend="JMS-Client-0-8-JNDI-Properties-Format"/>.</para>
-		</callout>
-	</calloutlist>
-
-
-</chapter>
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
index b5b2bee4ea..fb7d96fd68 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
@@ -43,7 +43,7 @@ destination.<jndi name>=<binding url>
   <para>An arbitrary number of connection factories, queues, topics, queues or destinations or can
     be declared in the JNDI properties file. Each JNDI name must be unique.</para>
   <para>The application looks up the objects via an InitialContext. This lookup and an example JNDI
-    properties file is provided in <xref linkend="JMS-Client-0-8-Hello-World-Example"/></para>
+    properties file is provided in <xref linkend="JMS-Client-0-8-Examples"/></para>
   <para>We now consider each JMS administered object type in turn.</para>
 
   <section id="JMS-Client-0-8-JNDI-Properties-Format-ConnectionFactory">
diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
index 463cff718f..d22b6b8a48 100644
--- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Understanding.xml
@@ -62,9 +62,9 @@
       implementation is backed by a <ulink url="&oracleJdkDocUrl;java/util/Properties.html"
         >Properties</ulink> object which can of course be loaded from an external properties file, or
       created programatically.</para>
-    <para>The Hello World example in the previous chapter illustrated the Java code required to
-        <link linkend="callout-java-properties">create the InitialContext</link> and an <link
-        linkend="JMS-Client-0-8-Hello-World-Example-PropertiesFile">example properties
+    <para>The examples in the previous chapter illustrated the Java code required to
+      <link linkend="JMS-Client-0-8-Examples-PTP">create the InitialContext</link> and an <link
+        linkend="JMS-Client-0-8-Examples-PTP-PropertiesFile">example properties
       file</link>.</para>
     <para>Note that the Qpid Broker does not present a JNDI interface to the application.</para>
     <figure>
@@ -449,8 +449,8 @@ amqp://guest:guest@clientid/?brokerlist='localhost:5671?trust_store='/path/to/ap
           url="&oracleJeeDocUrl;javax/jms/Session.html#createDurableSubscriber(javax.jms.Topic,%20java.lang.String)"
           >Session#createDurableSubscriber(javax.jms.Topic,java.lang.String)</ulink></para>
       <para>Calling <ulink
-          url="&oracleJeeDocUrl;javax/jms/Session.html#unsubscriber(java.lang.String)"
-          >Session#unsubscriber(java.lang.String)</ulink> deletes the underlying queue.</para>
+          url="&oracleJeeDocUrl;javax/jms/Session.html#unsubscribe(java.lang.String)"
+          >Session#unsubscribe(java.lang.String)</ulink> deletes the underlying queue.</para>
       <para>Non-durable topic subscriptions use a <emphasis>non-durable</emphasis>,
           <emphasis>exclusive</emphasis> and <emphasis>auto-delete</emphasis> queue named as
         follows:</para>
diff --git a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
index d752c5ae41..86105ca95e 100644
--- a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
+++ b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
@@ -37,6 +37,8 @@
 <!ENTITY oracleJmsSpec "http://docs.oracle.com/cd/E19957-01/816-5904-10/816-5904-10.pdf">
 <!ENTITY oracleJdkDocUrl "http://docs.oracle.com/javase/6/docs/api/">
 <!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+<!ENTITY oracleJmsTutorial "http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html">
+