[jboss-svn-commits] JBL Code SVN: r35351 - in labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US: extras/configuration and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Sep 29 07:45:05 EDT 2010
Author: tfennelly
Date: 2010-09-29 07:45:05 -0400 (Wed, 29 Sep 2010)
New Revision: 35351
Added:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jms-jca-simple.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-rar-config.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-xa-config.xmlt
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jmsrouter-xa-config.xmlt
Modified:
labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml
Log:
https://jira.jboss.org/browse/JBESB-3482
Revisit WSMQ integration instructions
Modified: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml 2010-09-29 11:26:16 UTC (rev 35350)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/Configuration.xml 2010-09-29 11:45:05 UTC (rev 35351)
@@ -183,6 +183,13 @@
<important>
<para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
+
+ <important>
+ <para>
Be sure to include the chosen JMS provider's client
<filename>JAR</filename> files in the class-path.
</para>
@@ -280,6 +287,13 @@
JBossMessaging
</title>
+ <important>
+ <para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
+
<para>
<application>JBoss Messaging</application> is the
<application>JBoss SOA Platform</application>'s default JMS
@@ -331,6 +345,13 @@
ActiveMQ
</title>
+ <important>
+ <para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
+
<para>
To configure <application>ActiveMQ</application>, set these
parameters:
@@ -354,11 +375,17 @@
<section id="websphere_mq_series">
- <title>
-
+ <title>
IBM Websphere MQ Series
</title>
+ <important>
+ <para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
+
<orderedlist>
<listitem>
<para>
@@ -392,7 +419,6 @@
"Maximum Sessions per Connection" section of this chapter.)
</para>
</listitem>
-
<listitem>
<para>
Check that the following items are present on the class-path:
@@ -422,6 +448,11 @@
<filename>com.ibm.mqjms.jar</filename> (client <filename>JAR</filename>)
</para>
</listitem>
+ <listitem>
+ <para>
+ See the <link linkend="websphere_mq_series_xa_transactions">section below</link> if participating in JTA/XA Transactions.
+ </para>
+ </listitem>
</itemizedlist>
<note>
@@ -447,17 +478,65 @@
Service Bus</application> to the <systemitem>mqm
group</systemitem>.
</para>
- </warning>
-
+ </warning>
</listitem>
</orderedlist>
+ <para>
+ If using JCA Inflow, you will need to configure the "adapter" attribute on the
+ <jms-jca-provider> configuration and ensure that the JCA Adapter RAR file is
+ in the ESB/Application Server's deploy folder:
+ </para>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/wmq-jca-provider-rar-config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ Also, be sure to read the <link linkend="jms_and_jca">section on JMS and JCA</link>, as well as how to configure JCA <connection-factories> and AdminObjects for your JMS Destinations
+ on JBoss Application Server.
+ </para>
+
+ <section id="websphere_mq_series_xa_transactions">
+
+ <title>
+ IBM Websphere MQ Series and XA Transactions
+ </title>
+
+ <para>
+ If your Websphere MQ endpoint is to participate in JTA/XA Transactions you will need to install the "Extended Transactional Client" bundle from IBM.
+ This bundle is not part of the default set of client jars for WMQ and is licensed separately. Contact your IBM representative to get these jar files.
+ Once you have the Extended Client bundle, install the .jar files on your ESB/Application Server's classpath, as well as on the classpath of any
+ external client applications.
+ </para>
+ <para>
+ Before you can use extended transactions in WMQ, you need to
+ <ulink url="http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/umj_pjcfm.html">configure XA Connection Factories in your WMQ JNDI namespace</ulink>.
+ Once you have configured the XA Connection Factories you can now reference them using their JNDI name in the "connection-factory" property of the JNDI connection property.
+ </para>
+ <para>
+ The following is an example showing how the <link linkend="jms_and_jca"><jms-jca-provider></link> configuration
+ would look for an Extended Transaction Client configuration, where the XA Connection Factory configured in the WMQ JNDI namespace is
+ called "WMQXAConnectionFactory". Inflow related configurations (adapter, <activation-config> etc) were intentionally omitted as
+ they are not relevant to the Extended Client configuration:
+ </para>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/wmq-jca-provider-xa-config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <para>
+ These configurations are also relevant to a JMSRouter action configuration, using the same "WMQXAConnectionFactory":
+ </para>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/wmq-jmsrouter-xa-config.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ </section>
+
</section>
<section>
<title>
Oracle AQ
</title>
+
+ <important>
+ <para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
<para>
To run <application>Oracle AQ</application>, undertake the
@@ -538,6 +617,13 @@
<title>
Red Hat MRG
</title>
+
+ <important>
+ <para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
<orderedlist>
<listitem>
@@ -583,7 +669,14 @@
Tibco Enterprise Message Service
</title>
+ <important>
<para>
+ Read the <link linkend="jms_and_jca">section on JMS and JCA</link> before
+ configuring your JMS Provider.
+ </para>
+ </important>
+
+ <para>
To use the <application>Tibco Enterprise Message
Service</application>, follow these instructions:
</para>
@@ -665,7 +758,93 @@
</orderedlist>
</section>
+<section id="jms_and_jca">
+ <title>JMS and Java Connector Architecture (JCA)</title>
+ <para>
+ JBoss ESB supports a JMS JCA transport, with a dedicated JMS JCA Provider
+ configuration (<jms-jca-provider>). This transport allows JCA message Inflow in 2 ways:
+ <orderedlist>
+ <listitem><para>JMS Gateway using a JCA connection to the JMS Provider.</para></listitem>
+ <listitem><para>ESB Aware JMS Message Listener using a JCA connection to the JMS Provider.</para></listitem>
+ </orderedlist>
+ </para>
+ <para>
+ The following is a very simple example of a <jms-jca-provider> configuration:
+ </para>
+ <programlisting language="XML" role="XML"><xi:include parse="text" href="extras/configuration/jms-jca-simple.xmlt" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+ <note>
+ <para>
+ The <jms-jca-provider> element configures how the JMS JCA Inflows (Gateway or ESB Aware Listener) receive messages, <emphasis>but also</emphasis> configures how JMS clients deliver messages
+ to them. While these configurations are made in the same location and may appear to be one and the same, they can often be different and lead to confusion
+ for some users. Therefore, it is important for users to be aware of which <jms-jca-provider> configurations relate to Inflow (server side) Vs client connection configuration (client side).
+ Read below for more details.
+ </para>
+ </note>
+ <para>
+ The <jms-jca-provider> configuration configures 2 separate (but related) things, either explicitly
+ or through the application of defaults:
+ <orderedlist>
+ <listitem>
+ <para>The JCA Inflow configuration properties (server side). These configrations configure the JCA Gateway and JCA Listeners listed above.
+ The configurations include:
+ <itemizedlist>
+ <listitem><para>The JCA Adapter Name . This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>The JCA Provider Adapter JNDI. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>The JCA Endpoint Class. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>Transacted flag. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>Message Type. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>JCA Bridge. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>The JCA Adapter activation configuration. This is configured in the <activation-config> element inside the <jms-jca-provider>.</para></listitem>
+ </itemizedlist>
+ Note that the JCA Activation configuration also extracts some configuration properties (for the JCA Inflow) from the <jms-bus> and <jms-message-filter>
+ that are nested inside the <jms-jca-provider> element. These include the destination type, destination name and message selector.
+ </para>
+ </listitem>
+ <listitem>
+ <para>The JMS client connection details (client side) used to deliver messages to the JMS JCA Inflows (Gateway or ESB Aware Listener). This
+ Information is used to generate the EPR for clients connecting to the JMS JCA Inflow. The configurations include:
+ <itemizedlist>
+ <listitem><para>The JMS Connection factory to be used by the client. This is configured as an attribute on the <jms-jca-provider> element.</para></listitem>
+ <listitem><para>The JMS JNDI properties to be used by the client for connecting to the JMS Provider. These are configured as an attributes on the <jms-jca-provider> element ("jndi-*").</para></listitem>
+ <listitem><para>The JMS bus endpoint destination configurations. These are configured on the <jms-message-filter> elements inside the <jms-bus> within the <jms-jca-provider> element.</para></listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <note>
+ <para>
+ Users should be aware of which <jms-jca-provider> configurations relate to message Inflow configuration (server side) and which relate to the client message delivery configuration
+ (client side). Read above for more details.
+ </para>
+ </note>
+ <para>
+ It is important to ensure that the JMS client connection configurations (outlined above) are <emphasis>not configured to connect through
+ JCA managed resources</emphasis>. The JMS client connection configurations should connect directly to the JMS Provider and not through JCA managed resources.
+ This is important because this information is built into the EPRs used by the ESBs
+ <systemitem>ServiceInvoker</systemitem> class, as well as other components that use the ESB's inbuilt JMS Connection Pooling.
+ It is important to avoid a situation where the Inbuilt Connection Pooling is pooling JCA managed connections.
+ </para>
+ <note>
+ <para>
+ Do not configure the JMS client configurations on <jms-jca-provider> to connect through JCA managed resources. Read above for more details.
+ </para>
+ </note>
+ <para>
+ The current list of components that use the ESBs inbuilt JMS Connection Pooling are:
+ <orderedlist>
+ <listitem><para>Routing Actions that use the <systemitem>ServiceInvoker</systemitem> class e.g. the Static and
+ Content Based Routers etc.</para></listitem>
+ <listitem><para>Most/All Gateway Listeners delivering messages to an Action Pipeline that is serviced by an
+ ESB Aware JMS Listener that uses a JCA JMS Provider. Most of these Gateway Listeners deliver messages
+ using the <systemitem>ServiceInvoker</systemitem> class.</para></listitem>
+ <listitem><para>The JMS Router.</para></listitem>
+ </orderedlist>
+ These components should all connect directly to the JMS Provider i.e. not through local JCA managed resources.
+ </para>
+</section>
+
<section id="extension_properties">
<title>
Extension Properties
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jms-jca-simple.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jms-jca-simple.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/jms-jca-simple.xmlt 2010-09-29 11:45:05 UTC (rev 35351)
@@ -0,0 +1,11 @@
+<jms-jca-provider name="JBossMessaging" connection-factory="XAConnectionFactory">
+
+ <jms-bus busid="ordersGwChannel">
+ <jms-message-filter dest-type="QUEUE" dest-name="queue/orders" transacted="true"/>
+ </jms-bus>
+
+ <activation-config>
+ <property name="dLQMaxResent" value="5"/>
+ </activation-config>
+
+</jms-jca-provider>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-rar-config.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-rar-config.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-rar-config.xmlt 2010-09-29 11:45:05 UTC (rev 35351)
@@ -0,0 +1,11 @@
+<jms-jca-provider name="WMQ" ... adapter="wmq.jmsra.rar">
+
+ <jms-bus busid="ordersGwChannel">
+ <jms-message-filter dest-type="QUEUE" dest-name="ORDERS" transacted="true"/>
+ </jms-bus>
+
+ <activation-config>
+ <!-- etc... -->
+ </activation-config>
+
+</jms-jca-provider>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-xa-config.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-xa-config.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jca-provider-xa-config.xmlt 2010-09-29 11:45:05 UTC (rev 35351)
@@ -0,0 +1,18 @@
+<jms-jca-provider name="WMQ" connection-factory="WMQXAConnectionFactory"
+ jndi-URL="wmqserver:1414/SYSTEM.DEF.SVRCONN"
+ jndi-context-factory="com.ibm.mq.jms.context.WMQInitialContextFactory">
+
+ <property name="max-xa-sessions-per-connection" value="1" />
+
+ <jms-bus busid="ordersGwChannel">
+ <jms-message-filter dest-type="QUEUE" dest-name="ORDERS" transacted="true"/>
+ </jms-bus>
+
+ <activation-config>
+ <!--
+ Used by inflow... not relevant to client
+ See section on JMS and JCA.
+ -->
+ </activation-config>
+
+</jms-jca-provider>
\ No newline at end of file
Added: labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jmsrouter-xa-config.xmlt
===================================================================
--- labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jmsrouter-xa-config.xmlt (rev 0)
+++ labs/jbossesb/branches/JBESB_4_9_CP/product/docs/Administration_Guide/en-US/extras/configuration/wmq-jmsrouter-xa-config.xmlt 2010-09-29 11:45:05 UTC (rev 35351)
@@ -0,0 +1,8 @@
+<action name="routeToORDERSQueue" class="org.jboss.soa.esb.actions.routing.JMSRouter">
+ <property name="jndi-context-factory" value="com.ibm.mq.jms.context.WMQInitialContextFactory"/>
+ <property name="jndi-URL" value="wmqserver:1414/SYSTEM.DEF.SVRCONN"/>
+ <property name="connection-factory" value="WMQXAConnectionFactory"/>
+ <property name="jndiName" value="ORDERS"/>
+ <property name="max-xa-sessions-per-connection" value="1"/>
+ <!-- etc... -->
+</action>
More information about the jboss-svn-commits
mailing list