| <?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"> |
| <?xml version='1.0' encoding='utf-8'?> |
| <!DOCTYPE xml> |
| <Context> |
| |
| <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'"/> |
| |
| <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"/> |
| |
| <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'"/> |
| |
| <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'"/> |
| |
| </Context></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"> |
| <?xml version='1.0' encoding='utf-8'?> |
| <!DOCTYPE xml> |
| <Context> |
| |
| <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'"/> |
| |
| <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'"/> |
| |
| <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'"/> |
| |
| </Context></programlisting> |
| </example> |
| </para> |
| </note> |
| </appendix> |
