<?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.

-->

<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Appendix-Tomcat-JNDI-Integration">
  <title>How to bind Qpid destinations and connection factories into Tomcat JNDI</title>
  <para>
      Qpid client destinations and connection factories can be registered in external JNDI containers, for example, Tomcat JNDI implementation.
  </para>
  <para>
    <literal>org.apache.qpid.jndi.ObjectFactory</literal> implements
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/spi/ObjectFactory.html">javax.naming.spi.ObjectFactory</link>
    allowing it to create instances of <literal>AMQConnectionFactory</literal>, <literal>PooledConnectionFactory</literal>,
    <literal>AMQConnection</literal>, <literal>AMQQueue</literal> and <literal>AMQTopic</literal> in external JNDI container from
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/Reference.html">javax.naming.Reference</link>s.
  </para>
  <para>Additionally,
    <literal>AMQConnectionFactory</literal>, <literal>PooledConnectionFactory</literal> and <literal>AMQDestination</literal> (parent of
    <literal>AMQQueue</literal> and <literal>AMQTopic</literal>) implement
    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/Referenceable.html">javax.naming.Referenceable</link>
    allowing creation of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/Reference.html">javax.naming.Reference</link> objects
    for binding in external JNDI implementations.
  </para>
  <para>
    <literal>org.apache.qpid.jndi.ObjectFactory</literal> allows the creation of:
    <itemizedlist>
      <listitem>
        <para>
          an instance of <literal>ConnectionFactory</literal> from a <literal>Reference</literal> containing reference
          address (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/RefAddr.html">javax.naming.RefAddr</link>)
          <literal>connectionURL</literal> with content set to a
          <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          an instance of <literal>PooledConnectionFactory</literal> from a <literal>Reference</literal> containing reference
          address (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/RefAddr.html">javax.naming.RefAddr</link>)
          <literal>connectionURL</literal> with content set to a
          <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          an instance of <literal>AMQConnection</literal> from a <literal>Reference</literal> containing reference
          address (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/RefAddr.html">javax.naming.RefAddr</link>)
          <literal>connectionURL</literal> with content set to a
          <link linkend="JMS-Client-0-8-Connection-URL">Connection URL</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          an instance of <literal>AMQQueue</literal> from a <literal>Reference</literal> containing reference
          address (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/RefAddr.html">javax.naming.RefAddr</link>)
          <literal>address</literal> with content set to either <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJmsClient010Book}">Address</link> or
          <link linkend="JMS-Client-0-8-Binding-URL">Binding URL</link>.
        </para>
      </listitem>
      <listitem>
        <para>
          an instance of <literal>AMQTopic</literal> from a <literal>Reference</literal> containing reference
          address (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/RefAddr.html">javax.naming.RefAddr</link>)
          <literal>address</literal> with content set to either <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJmsClient010Book}">Address</link> or
          <link linkend="JMS-Client-0-8-Binding-URL">Binding URL</link>.
        </para>
      </listitem>
    </itemizedlist>
    <note>
      <para>
        For  <literal>AMQQueue</literal> and <literal>AMQTopic</literal> prefix <literal>BURL:</literal> need
        to be specified for <link linkend="JMS-Client-0-8-Binding-URL">Binding URL</link>. Otherwise, client will try
        to parse content using <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJmsClient010Book}">Address</link> format.
      </para>
    </note>
  </para>
  <para>An example below demonstrates how to create JNDI resources in the Tomcat container using Resource declarations in context.xml
    (A Tomcat specific web application configuration file usually added into war under /META-INF/context.xml).
  </para>
  <example>
      <title>An example of Tomcat context.xml declaring Qpid JNDI resources</title>
      <programlisting language="xml">
&lt;?xml version='1.0' encoding='utf-8'?&gt;
&lt;!DOCTYPE xml&gt;
&lt;Context&gt;

  &lt;Resource name="jms/connectionFactory" auth="Container"
            type="org.apache.qpid.client.AMQConnectionFactory"
            factory="org.apache.qpid.jndi.ObjectFactory"
            connectionURL="amqp://guest:guest@clientid/?brokerlist='localhost:5672'"/&gt;

  &lt;Resource name="jms/pooledConnectionFactory" auth="Container"
            type="org.apache.qpid.client.PooledConnectionFactory"
            factory="org.apache.qpid.jndi.ObjectFactory"
            connectionURL="amqp://guest:guest@clientid/?brokerlist='localhost:5672'"
            maxPoolSize="20" connectionTimeout="60000"/&gt;

  &lt;Resource name="jms/queue" auth="Container"
            type="org.apache.qpid.client.AMQQueue"
            factory="org.apache.qpid.jndi.ObjectFactory"
            address="BURL:direct://amq.direct//myQueue?durable='true'"/&gt;

  &lt;Resource name="jms/topic" auth="Container"
            type="org.apache.qpid.client.AMQTopic"
            factory="org.apache.qpid.client.AMQConnectionFactory"
            address="BURL:topic://amq.topic//myTopic?routingkey='myTopic'"/&gt;

&lt;/Context&gt;</programlisting>
  </example>
  <para>In the example above <literal>AMQConnectionFactory</literal> would be registered under JNDI name "jms/connectionFactory",
    <literal>PooledConnectionFactory</literal> would be registered under JNDI name "jms/pooledConnectionFactory",
    <literal>Queue</literal> "myQueue" would be registered under JNDI name "jms/queue" and JMS <literal>Topic</literal>
   destination "myTopic" would be registered under JNDI name "jms/topic". (All resources will be bound under "java:comp/env").
    On declaration of <literal>PooledConnectionFactory</literal> optional maxPoolSize and connectionTimeout are set to
    20 and 60000 milliseconds accordingly.
  </para>
  <para>
    The client application can find the resources declared in Tomcat context.xml using the code below:
  </para>
  <example>
    <title>An example of JNDI lookup for Qpid resources registered in Tomcat JNDI</title>
    <programlisting language="java">
    Context context = new InitialContext();
    Context environmentContext = (Context)context.lookup("java:comp/env");
    ...
    ConnectionFactory connectionFactory = (ConnectionFactory) environmentContext.lookup("jms/connectionFactory");
    ...
    Queue queue = (Queue)environmentContext.lookup("jms/queue");
    ...
    Topic topic = (Topic)environmentContext.lookup("jms/topic");
    ...</programlisting>
  </example>
  <note>
    <para>
      In order to support backward compatibility <literal>AMQConnectionFactory</literal> continues to implement
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/spi/ObjectFactory.html">javax.naming.spi.ObjectFactory</link>
      and can be used to instantiate JNDI resources from
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/Reference.html">javax.naming.Reference</link>s.
      However, its method <literal>getObjectInstance</literal> is marked as <literal>Deprecated</literal> and will be
      removed in future version of client. For backward compatibility, Qpid JNDI resources can be declared using fully
      qualified class names as addresses. That will became unsupported in future version as well.
      An example of Tomcat context.xml with declarations of JNDI resources using deprecated factory and addresses is provided below.
  <example>
      <title>An example of Tomcat context.xml declaring Qpid JNDI resources using deprecated <literal>ObjectFactory</literal> and deprecated addresses</title>
      <programlisting language="xml">
&lt;?xml version='1.0' encoding='utf-8'?&gt;
&lt;!DOCTYPE xml&gt;
&lt;Context&gt;

  &lt;Resource name="jms/queue" auth="Container"
            type="org.apache.qpid.client.AMQQueue"
            factory="org.apache.qpid.client.AMQConnectionFactory"
            org.apache.qpid.client.AMQQueue="direct://amq.direct//myDurableQueue?durable='true'"/&gt;

  &lt;Resource name="jms/topic" auth="Container"
            type="org.apache.qpid.client.AMQTopic"
            factory="org.apache.qpid.client.AMQConnectionFactory"
            org.apache.qpid.client.AMQTopic="topic://amq.topic//myTopic?routingkey='myTopic'"/&gt;

  &lt;Resource name="jms/connectionFactory" auth="Container"
            type="org.apache.qpid.client.AMQConnectionFactory"
            factory="org.apache.qpid.client.AMQConnectionFactory"
            org.apache.qpid.client.AMQConnectionFactory="amqp://guest:guest@clientid/?brokerlist='localhost:5672'"/&gt;

&lt;/Context&gt;</programlisting>
  </example>
    </para>
  </note>
</appendix>