doc/jms-client-0-8/src/docbkx/JMS-Client-Examples.xml - qpid-broker-j - Git at Google

 <?xml version="1.0"?>
 <!--

  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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Examples">
 	<title>Examples</title>

 	<para>The following programs shows how to send and receive messages using the 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 JMS. Readers in
 		need of an introduction are directed towards <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJmsTutorial}">Oracle's JMS
 			tutorial</link>.</para>
 	<section xml: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 xml:id="JMS-Client-0-8-Examples-PTP-Java">
 			<title>JMS Example - Point to Point Messaging</title>
 			<programlisting language="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 xml:id="ptp-java-properties" linkends="callout-ptp-properties"/>
       Context context = new InitialContext(properties);                               <co xml:id="ptp-java-context" linkends="callout-ptp-context"/>

       ConnectionFactory connectionFactory
           = (ConnectionFactory) context.lookup("qpidConnectionFactory");              <co xml:id="ptp-java-connection-factory" linkends="callout-ptp-connection-factory"/>
       Connection connection = connectionFactory.createConnection();                   <co xml:id="ptp-java-connection" linkends="callout-ptp-connection"/>
       connection.start();                                                             <co xml:id="ptp-java-start" linkends="callout-ptp-start"/>

       Session session = connection.createSession(true, Session.SESSION_TRANSACTED);   <co xml:id="ptp-java-session" linkends="callout-ptp-session"/>
       Queue queue = (Queue) context.lookup("myqueue");                                <co xml:id="ptp-java-destination" linkends="callout-ptp-destination"/>

       MessageConsumer messageConsumer = session.createConsumer(queue);                <co xml:id="ptp-java-consumer" linkends="callout-ptp-consumer"/>
       MessageProducer messageProducer = session.createProducer(queue);                <co xml:id="ptp-java-producer" linkends="callout-ptp-producer"/>

       TextMessage message = session.createTextMessage("Hello world!");                <co xml:id="ptp-java-send" linkends="callout-ptp-send"/>
       messageProducer.send(message);
       session.commit();

       message = (TextMessage)messageConsumer.receive();                               <co xml:id="ptp-java-receive" linkends="callout-ptp-receive"/>
       session.commit();
       System.out.println(message.getText());

       connection.close();                                                             <co xml:id="ptp-java-close" linkends="callout-ptp-close"/>
       context.close();                                                                <co xml:id="ptp-java-jndi-close" linkends="callout-ptp-jndi-close"/>
     }
 }
 	</programlisting>
 		</example>

 		<calloutlist>
 			<callout xml: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 xml:id="callout-ptp-context" arearefs="ptp-java-context">
 				<para>Creates the JNDI initial context.</para>
 			</callout>
 			<callout xml:id="callout-ptp-connection-factory" arearefs="ptp-java-connection-factory">
 				<para>Looks up a JMS connection factory for Qpid.</para>
 			</callout>
 			<callout xml: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 xml:id="callout-ptp-start" arearefs="ptp-java-start">
 				<para>Starts the connection, required for the consumption of messages.</para>
 			</callout>
 			<callout xml:id="callout-ptp-session" arearefs="ptp-java-session">
 				<para>Creates a transactional session.</para>
 			</callout>
 			<callout xml:id="callout-ptp-destination" arearefs="ptp-java-destination">
 				<para>Looks up a destination for the queue with JNDI name <emphasis>myqueue</emphasis>.</para>
 			</callout>
 			<callout xml: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 xml:id="callout-ptp-producer" arearefs="ptp-java-producer">
 				<para>Creates a producer that sends messages to the queue.</para>
 			</callout>
 			<callout xml:id="callout-ptp-send" arearefs="ptp-java-send">
 				<para>Creates a new message of type <emphasis>javax.jms.TextMessage</emphasis>, publishes the message and commits the
 					session.</para>
 			</callout>
 			<callout xml: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 xml: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 xml: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 xml:id="JMS-Client-0-8-Examples-PTP-PropertiesFile">
 			<title>JMS Example - Point to Point Messaging - JNDI Properties</title>
 			<programlisting language="properties">
 java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
 connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672' <co xml:id="ptp-properties-connectionfactory" linkends="callout-ptp-properties-connectionfactory"/>
 queue.myqueue = queue1                                                                                   <co xml:id="ptp-properties-destination" linkends="callout-ptp-properties-destination"/>
 	</programlisting>
 		</example>

 		<calloutlist>
 			<callout xml: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-Connection-URL"/>.</para>
 			</callout>
 			<callout xml: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 xml: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 xml:id="JMS-Client-0-8-Examples-PubSub-Java">
 			<title>JMS Example - Publish/subscribe Messaging</title>
 			<programlisting language="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 xml:id="pubsub-java-destination" linkends="callout-pubsub-destination"/>

       MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1"); <co xml:id="pubsub-java-subscribers" linkends="callout-pubsub-subscribers"/>
       MessageConsumer subscriber2 = session.createDurableSubscriber(priceTopic, "sub2" /*, "price &gt; 150", false*/ );
       MessageProducer messageProducer = session.createProducer(priceTopic);

       Message message = session.createMessage();
       message.setStringProperty("instrument", "IBM");
       message.setIntProperty("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 xml:id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
       session.unsubscribe("sub2");
       connection.close();
       context.close();
     }
 }
 	</programlisting>
 		</example>

 		<calloutlist>
 			<callout xml:id="callout-pubsub-destination" arearefs="pubsub-java-destination">
 				<para>Looks up a destination for the topic with JNDI name myprices.</para>
 			</callout>
 			<callout xml: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 xml: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 xml: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 xml:id="pubsub-properties-destination" linkends="callout-pubsub-properties-destination"/>
 	</programlisting>
 		</example>

 		<calloutlist>
 			<callout xml: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>
	<?xml version="1.0"?>
	<!--

	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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Examples">
	<title>Examples</title>

	<para>The following programs shows how to send and receive messages using the 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 JMS. Readers in
	need of an introduction are directed towards <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJmsTutorial}">Oracle's JMS
	tutorial</link>.</para>
	<section xml: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 xml:id="JMS-Client-0-8-Examples-PTP-Java">
	<title>JMS Example - Point to Point Messaging</title>
	<programlisting language="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 xml:id="ptp-java-properties" linkends="callout-ptp-properties"/>
	Context context = new InitialContext(properties); <co xml:id="ptp-java-context" linkends="callout-ptp-context"/>

	ConnectionFactory connectionFactory
	= (ConnectionFactory) context.lookup("qpidConnectionFactory"); <co xml:id="ptp-java-connection-factory" linkends="callout-ptp-connection-factory"/>
	Connection connection = connectionFactory.createConnection(); <co xml:id="ptp-java-connection" linkends="callout-ptp-connection"/>
	connection.start(); <co xml:id="ptp-java-start" linkends="callout-ptp-start"/>

	Session session = connection.createSession(true, Session.SESSION_TRANSACTED); <co xml:id="ptp-java-session" linkends="callout-ptp-session"/>
	Queue queue = (Queue) context.lookup("myqueue"); <co xml:id="ptp-java-destination" linkends="callout-ptp-destination"/>

	MessageConsumer messageConsumer = session.createConsumer(queue); <co xml:id="ptp-java-consumer" linkends="callout-ptp-consumer"/>
	MessageProducer messageProducer = session.createProducer(queue); <co xml:id="ptp-java-producer" linkends="callout-ptp-producer"/>

	TextMessage message = session.createTextMessage("Hello world!"); <co xml:id="ptp-java-send" linkends="callout-ptp-send"/>
	messageProducer.send(message);
	session.commit();

	message = (TextMessage)messageConsumer.receive(); <co xml:id="ptp-java-receive" linkends="callout-ptp-receive"/>
	session.commit();
	System.out.println(message.getText());

	connection.close(); <co xml:id="ptp-java-close" linkends="callout-ptp-close"/>
	context.close(); <co xml:id="ptp-java-jndi-close" linkends="callout-ptp-jndi-close"/>
	}
	}
	</programlisting>
	</example>

	<calloutlist>
	<callout xml: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 xml:id="callout-ptp-context" arearefs="ptp-java-context">
	<para>Creates the JNDI initial context.</para>
	</callout>
	<callout xml:id="callout-ptp-connection-factory" arearefs="ptp-java-connection-factory">
	<para>Looks up a JMS connection factory for Qpid.</para>
	</callout>
	<callout xml: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 xml:id="callout-ptp-start" arearefs="ptp-java-start">
	<para>Starts the connection, required for the consumption of messages.</para>
	</callout>
	<callout xml:id="callout-ptp-session" arearefs="ptp-java-session">
	<para>Creates a transactional session.</para>
	</callout>
	<callout xml:id="callout-ptp-destination" arearefs="ptp-java-destination">
	<para>Looks up a destination for the queue with JNDI name <emphasis>myqueue</emphasis>.</para>
	</callout>
	<callout xml: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 xml:id="callout-ptp-producer" arearefs="ptp-java-producer">
	<para>Creates a producer that sends messages to the queue.</para>
	</callout>
	<callout xml:id="callout-ptp-send" arearefs="ptp-java-send">
	<para>Creates a new message of type <emphasis>javax.jms.TextMessage</emphasis>, publishes the message and commits the
	session.</para>
	</callout>
	<callout xml: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 xml: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 xml: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 xml:id="JMS-Client-0-8-Examples-PTP-PropertiesFile">
	<title>JMS Example - Point to Point Messaging - JNDI Properties</title>
	<programlisting language="properties">
	java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory
	connectionfactory.qpidConnectionFactory = amqp://guest:guest@clientid/?brokerlist='tcp://localhost:5672' <co xml:id="ptp-properties-connectionfactory" linkends="callout-ptp-properties-connectionfactory"/>
	queue.myqueue = queue1 <co xml:id="ptp-properties-destination" linkends="callout-ptp-properties-destination"/>
	</programlisting>
	</example>

	<calloutlist>
	<callout xml: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-Connection-URL"/>.</para>
	</callout>
	<callout xml: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 xml: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 xml:id="JMS-Client-0-8-Examples-PubSub-Java">
	<title>JMS Example - Publish/subscribe Messaging</title>
	<programlisting language="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 xml:id="pubsub-java-destination" linkends="callout-pubsub-destination"/>

	MessageConsumer subscriber1 = session.createDurableSubscriber(priceTopic, "sub1"); <co xml: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.setIntProperty("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 xml:id="pubsub-java-unsubscribe" linkends="callout-pubsub-unsubscribe"/>
	session.unsubscribe("sub2");
	connection.close();
	context.close();
	}
	}
	</programlisting>
	</example>

	<calloutlist>
	<callout xml:id="callout-pubsub-destination" arearefs="pubsub-java-destination">
	<para>Looks up a destination for the topic with JNDI name myprices.</para>
	</callout>
	<callout xml: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 xml: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 xml: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 xml:id="pubsub-properties-destination" linkends="callout-pubsub-properties-destination"/>
	</programlisting>
	</example>

	<calloutlist>
	<callout xml: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>