8:42 a.m.
Author: ataylor
Date: 2010-10-11 09:42:51 -0400 (Mon, 11 Oct 2010)
New Revision: 9768
Modified:
trunk/docs/user-manual/en/appserver-integration.xml
Log:
https://jira.jboss.org/browse/HORNETQ-462 - added to JCA section
Modified: trunk/docs/user-manual/en/appserver-integration.xml
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml 2010-10-11 12:34:44 UTC (rev
9767)
+++ trunk/docs/user-manual/en/appserver-integration.xml 2010-10-11 13:42:51 UTC (rev
9768)
@@ -28,7 +28,7 @@
outflow of messages sent from other JEE components, e.g. EJBs and
Servlets.</para>
<para>This section explains the basics behind configuring the different JEE
components in the
AS.</para>
- <section>
+ <section id="configuring-mdbs">
<title>Configuring Message-Driven Beans</title>
<para>The delivery of messages to an MDB using HornetQ is configured on the
JCA Adapter via
a configuration file <literal>ra.xml</literal> which can be found
under the <literal
@@ -980,6 +980,202 @@
</section>
</section>
<section>
+ <title>Configuring the JBoss Application Server to connect to Remote
HornetQ Server</title>
+ <para>This is a step by step guide on how to configure a JBoss application
server that doesn't have HornetQ installed
+ to use a remote instance of HornetQ</para>
+ <section>
+ <title>Configuring Jboss 5</title>
+ <para>Firstly download and install JBoss AS 5 as per the JBoss
installation guide and HornetQ as per the
+ HornetQ installation guide. After thatt he following steps are
required</para>
+ <itemizedlist>
+ <listitem>
+ <para>Copy the following jars from the HornetQ distribution to
the <literal>lib</literal> directory of
+ which ever JBossAs configuration you have chosen, i.e.
<literal>default</literal>.</para>
+ <itemizedlist>
+ <listitem>
+ <para>hornetq-core-client.jar</para>
+ </listitem>
+ <listitem>
+ <para>hornetq-jms-client.jar</para>
+ </listitem>
+ <listitem>
+ <para>hornetq-ra.jar (this can be found inside the
<literal>hornetq-ra.rar</literal> archive)</para>
+ </listitem>
+ <listitem>
+ <para>netty.jar</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>create the directories
<literal>hornetq-ra.rar</literal> and
<literal>hornetq-ra.rar/META-INF</literal>
+ under the <literal>deploy</literal> directory in your
JBoss config directory</para>
+ </listitem>
+ <listitem>
+ <para>under the
<literal>hornetq-ra.rar/META-INF</literal> create a
<literal>ra.xml</literal> file or
+ copy it from the HornetQ distribution (again it can be found in the
<literal>hornetq-ra.rar</literal> archive)
+ and configure it as follows</para>
+ <programlisting>
+ <?xml version="1.0"
encoding="UTF-8"?>
+
+ <connector
xmlns="http://java.sun.com/xml/ns/j2ee"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+
http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
+ version="1.5">
+
+ <description>HornetQ 2.0 Resource Adapter Alternate
Configuration</description>
+ <display-name>HornetQ 2.0 Resource Adapter Alternate
Configuration</display-name>
+
+ <vendor-name>Red Hat Middleware
LLC</vendor-name>
+ <eis-type>JMS 1.1 Server</eis-type>
+
<resourceadapter-version>1.0</resourceadapter-version>
+
+ <license>
+ <description>
+ Copyright 2009 Red Hat, Inc.
+ Red Hat 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.
+ </description>
+
<license-required>true</license-required>
+ </license>
+
+ <resourceadapter>
+
<resourceadapter-class>org.hornetq.ra.HornetQResourceAdapter</resourceadapter-class>
+ <config-property>
+ <description>The transport
type</description>
+
<config-property-name>ConnectorClassName</config-property-name>
+
<config-property-type>java.lang.String</config-property-type>
+
<config-property-value>org.hornetq.core.remoting.impl.netty.NettyConnectorFactory</config-property-value>
+ </config-property>
+ <config-property>
+ <description>The transport configuration.
These values must be in the form of key=val;key=val;</description>
+
<config-property-name>ConnectionParameters</config-property-name>
+
<config-property-type>java.lang.String</config-property-type>
+ <emphasis role="bold">
<config-property-value>host=127.0.0.1;port=5445</config-property-value></emphasis>
+ </config-property>
+
+ <outbound-resourceadapter>
+ <connection-definition>
+
<managedconnectionfactory-class>org.hornetq.ra.HornetQRAManagedConnectionFactory</managedconnectionfactory-class>
+
+ <config-property>
+ <description>The default session
type</description>
+
<config-property-name>SessionDefaultType</config-property-name>
+
<config-property-type>java.lang.String</config-property-type>
+
<config-property-value>javax.jms.Queue</config-property-value>
+ </config-property>
+ <config-property>
+ <description>Try to obtain a lock within
specified number of seconds; less than or equal to 0 disable this
functionality</description>
+
<config-property-name>UseTryLock</config-property-name>
+
<config-property-type>java.lang.Integer</config-property-type>
+
<config-property-value>0</config-property-value>
+ </config-property>
+
+
<connectionfactory-interface>org.hornetq.ra.HornetQRAConnectionFactory</connectionfactory-interface>
+
<connectionfactory-impl-class>org.hornetq.ra.HornetQRAConnectionFactoryImpl</connectionfactory-impl-class>
+
<connection-interface>javax.jms.Session</connection-interface>
+
<connection-impl-class>org.hornetq.ra.HornetQRASession</connection-impl-class>
+ </connection-definition>
+
<transaction-support>XATransaction</transaction-support>
+ <authentication-mechanism>
+
<authentication-mechanism-type>BasicPassword</authentication-mechanism-type>
+
<credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface>
+ </authentication-mechanism>
+
<reauthentication-support>false</reauthentication-support>
+ </outbound-resourceadapter>
+
+ <inbound-resourceadapter>
+ <messageadapter>
+ <messagelistener>
+
<messagelistener-type>javax.jms.MessageListener</messagelistener-type>
+ <activationspec>
+
<activationspec-class>org.hornetq.ra.inflow.HornetQActivationSpec</activationspec-class>
+ <required-config-property>
+
<config-property-name>destination</config-property-name>
+ </required-config-property>
+ </activationspec>
+ </messagelistener>
+ </messageadapter>
+ </inbound-resourceadapter>
+
+ </resourceadapter>
+ </connector>
+
+ </programlisting>
+ <para>The important part of this configuration is the part in
bold, i.e.
<config-property-value>host=127.0.0.1;port=5445</config-property-value>.
+ This should be configured to the host and port of the remote HornetQ
server.</para>
+ </listitem>
+ </itemizedlist>
+ <para>At this point you should be able to now deploy MDB's that
consume from the remote server. You will however,
+ have to make sure that your MDB's have the annotation
<literal>(a)ResourceAdapter("hornetq-ra.rar")</literal>
+ added, this is illustrated in the <xref
linkend="configuring-mdbs">Configuring Message-Driven Beans</xref>
section.
+ If you don't want to add this annotation then you can delete the generic
resource adapter <literal>jms-ra.rar</literal>
+ and rename the <literal>hornetq-ra.rar</literal> to
this.</para>
+ <para>If you also want to use the remote HornetQ server for outgoing
connections, i.e. sending messages, then
+ do the following:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Create a file called
<literal>hornetq-ds.xml</literal> in the <literal>deploy</literal>
directory
+ (in fact you can call this anything you want as long as it ends in
<literal>-ds.xml</literal>). Then
+ add the following:</para>
+ <programlisting>
+ <connection-factories>
+ <!--
+ JMS XA Resource adapter, use this for outbound JMS connections.
+ Inbound connections are defined at the @MDB activation or at the
resource-adapter properties.
+ -->
+ <tx-connection-factory>
+ <jndi-name>RemoteJmsXA</jndi-name>
+ <xa-transaction/>
+ <rar-name>hornetq-ra.rar</rar-name>
+
<connection-definition>org.hornetq.ra.HornetQRAConnectionFactory</connection-definition>
+ <config-property name="SessionDefaultType"
type="java.lang.String">javax.jms.Topic</config-property>
+ <config-property name="ConnectorClassName"
type="java.lang.String">org.hornetq.core.remoting.impl.netty.NettyConnectorFactory</config-property>
+ <config-property name="ConnectionParameters"
type="java.lang.String">host=127.0.0.1;port=5445</config-property>
+ <max-pool-size>20</max-pool-size>
+ </tx-connection-factory>
+
+
+ </connection-factories>
+ </programlisting>
+ <para>Again you will see that the host and port are configured
here to match the remote HornetQ servers
+ configuration. The other important attributes are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>jndi-name - This is the name used to look up the
JMS connection factory from within your JEE client</para>
+ </listitem>
+ <listitem>
+ <para>rar-name - This should match the directory that
you created to hold the Resource Adapter
+ configuration</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>Now you should be able to send messages using the JCA JMS
connection pooling within an XA transaction.</para>
+ </section>
+ <section>
+ <title>Configuring Jboss 5</title>
+ <para>The steps to do this are exactly the same as for JBoss 4, you
will have to create a jboss.xml definition
+ file for your MDB with the following entry</para>
+ <programlisting>
+ <message-driven>
+ <ejb-name>MyMDB</ejb-name>
+
<resource-adapter-name>jms-ra.rar</resource-adapter-name>
+ </message-driven>
+ </programlisting>
+ <para>Also you will need to edit the
<literal>standardjboss.xml</literal> and uncomment the section with the
+ following 'Uncomment to use JMS message inflow from jmsra.rar' and
then comment out the invoker-proxy-binding
+ called 'message-driven-bean'</para>
+ </section>
+ </section>
+ <section>
<title>High Availability JNDI (HA-JNDI)</title>
<para>If you are using JNDI to look-up JMS queues, topics and connection
factories from a
cluster of servers, it is likely you will want to use HA-JNDI so that your
JNDI look-ups