doc/jms-client-0-8/src/docbkx/JMS-Client-JNDI-Properties-Format.xml

<?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-JNDI-Properties-Format">
  <title>JNDI Properties Format</title>

  <para>The 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>
connectionfactory.&lt;jndi name&gt;=&lt;connection url&gt;
queue.&lt;jndi name&gt;=&lt;queue name&gt;
topic.&lt;jndi name&gt;=&lt;topic name&gt;
destination.&lt;jndi name&gt;=&lt;binding url&gt;
</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 xml:id="JMS-Client-0-8-JNDI-Properties-Format-ConnectionFactory">
    <title>ConnectionFactory</title>
    <para><literal>connectionfactory.</literal><emphasis>name</emphasis> declares a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ConnectionFactory.html">ConnectionFactory</link> 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 xml:id="JMS-Client-0-8-JNDI-Properties-Format-Queue">
    <title>Queue</title>
    <para><literal>queue.</literal><emphasis>name</emphasis> declares a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/Queue.html">Queue</link> 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>destination.name=direct://amq.direct//&lt;queue name&gt;?routingkey=’&lt;queue name&gt;’&amp;durable=’true’</screen>
  </section>
  <section xml:id="JMS-Client-0-8-JNDI-Properties-Format-Topic">
    <title>Topic</title>
    <para><literal>topic.</literal><emphasis>name</emphasis> declares a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/Topic.html">Topic</link> 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>destination.name=topic://amq.topic/&lt;topic name&gt;/?routingkey=&lt;topic name&gt;</screen>
  </section>
  <section xml:id="JMS-Client-0-8-JNDI-Properties-Format-Destination">
    <title>Destination</title>
    <para><literal>destination.</literal><emphasis>name</emphasis> declares either a <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/Queue.html">Queue</link> or <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/Topic.html">Topic</link> (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>