1 files changed, 86 insertions, 0 deletions
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
new file mode 100644
index 0000000000..fb7d96fd68
--- /dev/null
+++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JNDI-Properties-Format.xml
@@ -0,0 +1,86 @@
+<?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-JNDI-Properties-Format">
+  <title>JNDI Properties Format</title>
+
+  <para>The Qpid JMS Client comes with own JNDI context factory
+      <literal>org.apache.qpid.jndi.PropertiesFileInitialContextFactory</literal> which utilises a
+    Java properties file for declaring the JMS administered objects: connection factories, queues,
+    topics and destinations. It uses the following syntax:</para>
+  <para>
+    <screen><![CDATA[
+connectionfactory.<jndi name>=<connection url>
+queue.<jndi name>=<queue name>
+topic.<jndi name>=<topic name>
+destination.<jndi name>=<binding url>
+]]></screen></para>
+  <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-Examples"/></para>
+  <para>We now consider each JMS administered object type in turn.</para>
+
+  <section id="JMS-Client-0-8-JNDI-Properties-Format-ConnectionFactory">
+    <title>ConnectionFactory</title>
+    <para><literal>connectionfactory.</literal><emphasis>name</emphasis> declares a <ulink
+        url="&oracleJeeDocUrl;javax/jms/ConnectionFactory.html">ConnectionFactory</ulink> with the
+      given JNDI name. The value must be a legal Connection URL.</para>
+    <para>See <xref linkend="JMS-Client-0-8-Connection-URL"/> for format of the URL and its
+      permitted options.</para>
+  </section>
+  <section id="JMS-Client-0-8-JNDI-Properties-Format-Queue">
+    <title>Queue</title>
+    <para><literal>queue.</literal><emphasis>name</emphasis> declares a <ulink
+        url="&oracleJeeDocUrl;javax/jms/Queue.html">Queue</ulink> with the given JNDI name. The
+      value is simple queue name. This is the name of the queue as known by the Broker.</para>
+    <para>The <literal>queue.</literal> form is a short hand for declaring a destination:</para>
+    <screen><![CDATA[destination.name=direct://amq.direct//<queue name>?routingkey=’<queue name>’&durable=’true’]]></screen>
+  </section>
+  <section id="JMS-Client-0-8-JNDI-Properties-Format-Topic">
+    <title>Topic</title>
+    <para><literal>topic.</literal><emphasis>name</emphasis> declares a <ulink
+        url="&oracleJeeDocUrl;javax/jms/Topic.html">Topic</ulink> with the given JNDI name. The
+      value is topic name. This topic name is used on the Broker as a binding key between the
+        <literal>amq.topic</literal> exchange and the queue corresponding to the topic
+      subscriber.</para>
+    <para>The <literal>topic.</literal> form is a short hand for declaring a destination:</para>
+    <screen><![CDATA[destination.name=topic://amq.topic/<topic name>/?routingkey=<topic name>]]></screen>
+  </section>
+  <section id="JMS-Client-0-8-JNDI-Properties-Format-Destination">
+    <title>Destination</title>
+    <para><literal>destination.</literal><emphasis>name</emphasis> declares either a <ulink
+        url="&oracleJeeDocUrl;javax/jms/Queue.html">Queue</ulink> or <ulink
+        url="&oracleJeeDocUrl;javax/jms/Topic.html">Topic</ulink> (depending on the class) with the
+      given JNDI name. The value must be a Binding URL.</para>
+    <para>See <xref linkend="JMS-Client-0-8-Binding-URL"/> for format of the URL and its permitted
+      options.</para>
+  </section>
+
+
+</chapter>