[hornetq-commits] JBoss hornetq SVN: r9158 - trunk/docs/user-manual/en.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Apr 23 09:39:19 EDT 2010
Author: jmesnil
Date: 2010-04-23 09:39:19 -0400 (Fri, 23 Apr 2010)
New Revision: 9158
Modified:
trunk/docs/user-manual/en/appserver-integration.xml
Log:
https://jira.jboss.org/jira/browse/HORNETQ-326: Improve documentation on configuring MDBs and resource adapter
* updated MDB doc
Modified: trunk/docs/user-manual/en/appserver-integration.xml
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml 2010-04-23 12:21:46 UTC (rev 9157)
+++ trunk/docs/user-manual/en/appserver-integration.xml 2010-04-23 13:39:19 UTC (rev 9158)
@@ -20,23 +20,23 @@
<title>Application Server Integration and Java EE</title>
<para>HornetQ can be easily installed in JBoss Application Server 4 or later. For details on
installing HornetQ in the JBoss Application Server please refer to quick-start guide.</para>
- <para>Since HornetQ also provides a JCA adaptor, it should also be possible to integrate HornetQ
+ <para>Since HornetQ also provides a JCA adapter, it is also possible to integrate HornetQ
as a JMS provider in other JEE compliant app servers. For instructions on how to integrate a
remote JCA adaptor into another application sever, please consult the other application server's
instructions.</para>
- <para>A JCA Adapter basically controls the inflow of messages to Message Driven Beans and the
+ <para>A JCA Adapter basically controls the inflow of messages to Message-Driven Beans (MDBs) and the
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>
- <title>Configuring Message Driven Beans</title>
+ <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 in the <literal
- >jms-ra.rar</literal> archive of directory. By default this is configured to consume
+ a configuration file <literal>ra.xml</literal> which can be found under the <literal
+ >jms-ra.rar</literal> directory. By default this is configured to consume
messages using an InVM connector from the instance of HornetQ running within the
- application server. A full list of what is configurable is found later in this chapter. </para>
- <para>All MDB's however need to have the destination type and the destination configured.
- The following example shows how this can be done via annotations.</para>
+ application server. The configuration properties are listed later in this chapter. </para>
+ <para>All MDBs however need to have the destination type and the destination configured.
+ The following example shows how this can be done using annotations:</para>
<programlisting>@MessageDriven(name = "MDBExample",
activationConfig =
{
@@ -54,25 +54,29 @@
<para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor
should be used. To use this you will need to import <literal
>org.jboss.ejb3.annotation.ResourceAdapter</literal> which can be found in the
- <literal>jboss-ejb3-ext-api.jar</literal> which can be found in the jboss
+ <literal>jboss-ejb3-ext-api.jar</literal> which can be found in the JBoss
repository. Alternatively you can add use a deployment descriptor and add something like
the following to <literal
>jboss.xml</literal><programlisting><message-driven>
<ejb-name>ExampleMDB</ejb-name>
- <resource-adapter-name>quartz-ra.rar</resource-adapter-name>
+ <resource-adapter-name>hornetq-ra.rar</resource-adapter-name>
</message-driven>
</programlisting>You
can also rename the hornetq-ra.rar directory to jms-ra.rar and neither the annotation or
the extra descriptor information will be needed. If you do this you will need to edit
the <literal>jms-ds.xml</literal> datasource file and change <literal>rar-name</literal>
element.</para>
+ <note>
+ <para>HornetQ is the default JMS provider for JBoss AS 6. Starting with this AS version, HornetQ resource
+ adapter is named <literal>jms-ra.rar</literal>.</para>
+ </note>
<para>All the examples shipped with the HornetQ distribution use the annotation.</para>
<section>
- <title>Using Container Managed Transactions</title>
- <para>When an MDB is using Container Managed Transactions (CMT), the delivery of the
+ <title>Using Container-Managed Transactions</title>
+ <para>When an MDB is using Container-Managed Transactions (CMT), the delivery of the
message is done within the scope of a JTA transaction. The commit or rollback of
this transaction is controlled by the container itself. If the transaction is rolled
- back then the message delivery semantics will kick in (by default this is to try and
+ back then the message delivery semantics will kick in (by default, it will try to
redeliver the message up to 10 times before sending to a DLQ). Using annotations
this would be configured as follows:</para>
<programlisting>@MessageDriven(name = "MDB_CMP_TxRequiredExample",
@@ -88,9 +92,8 @@
{
public void onMessage(Message message)...
}</programlisting>
- <para>The <literal>TransactionManagement</literal> annotation tells the container to
- treat this MDB to use Container Managed Persistence. The <literal
- >TransactionAttribute</literal> annotation tells the container that a JTA
+ <para>The <literal>TransactionManagement</literal> annotation tells the container to manage the
+ transaction. The <literal>TransactionAttribute</literal> annotation tells the container that a JTA
transaction is required for this MDB. Note that the only other valid value for this
is <literal>TransactionAttributeType.NOT_SUPPORTED</literal> which tells the
container that this MDB does not support JTA transactions and one should not be
@@ -100,7 +103,7 @@
>MessageDrivenContext</literal>. The code for this would look something
like:</para>
<programlisting> @Resource
- MessageDrivenContext ctx;
+ MessageDrivenContextContext ctx;
public void onMessage(Message message)
{
@@ -113,7 +116,7 @@
ctx.setRollbackOnly();
}
}</programlisting>
- <para>If you don't want the over head of an xa transaction being created every time but
+ <para>If you do not want the overhead of an XA transaction being created every time but
you would still like the message delivered within a transaction (i.e. you are only
using a JMS resource) then you can configure the MDB to use a local transaction.
This would be configured as such:</para>
@@ -133,8 +136,8 @@
}</programlisting>
</section>
<section>
- <title>Using Bean Managed Transactions</title>
- <para>Message driven beans can also be configured to use Bean Managed Transactions
+ <title>Using Bean-Managed Transactions</title>
+ <para>Message-driven beans can also be configured to use Bean-Managed Transactions
(BMT). In this case a User Transaction is created. This would be configured as
follows:</para>
<programlisting>@MessageDriven(name = "MDB_BMPExample",
@@ -150,7 +153,7 @@
{
public void onMessage(Message message)
}</programlisting>
- <para>When using Bean Managed Transactions the message delivery to the MDB will occur
+ <para>When using Bean-Managed Transactions the message delivery to the MDB will occur
outside the scope of the user transaction and use the acknowledge mode specified by
the user with the <literal>acknowledgeMode</literal> property. There are only 2
acceptable values for this <literal>Auto-acknowledge</literal> and <literal
@@ -176,6 +179,7 @@
tx.begin();
//do some stuff within the transaction
+
tx.commit();
}
@@ -186,8 +190,8 @@
}</programlisting>
</section>
<section>
- <title>Using Message Selectors with MDB's</title>
- <para>It is also possible to use MDB's with message selectors. To do this simple define
+ <title>Using Message Selectors with Message-Driven Beans</title>
+ <para>It is also possible to use MDBs with message selectors. To do this simple define
your message selector as follows:</para>
<programlisting>@MessageDriven(name = "MDBMessageSelectorExample",
activationConfig =
@@ -213,7 +217,7 @@
that the sending of the message will be done as part of the JTA transaction being used
by the component.</para>
<para>This means that if the sending of the message fails the overall transaction would
- rollback and the message redelivered. Heres an example of this from within an
+ rollback and the message be redelivered. Heres an example of this from within an
MDB:</para>
<programlisting>@MessageDriven(name = "MDBMessageSendTxExample",
activationConfig =
@@ -274,15 +278,15 @@
}
}</programlisting>
<para>In JBoss Application Server you can use the JMS JCA adapter for sending messages from
- EJBs (including Session, Entity and Message Driven Beans), Servlets (including jsps) and
+ EJBs (including Session, Entity and Message-Driven Beans), Servlets (including jsps) and
custom MBeans.</para>
</section>
<section>
<title>Configuring the JCA Adaptor</title>
<para>The Java Connector Architecture (JCA) Adapter is what allows HornetQ to be integrated
- with JEE components such as MDB's and EJB's. It configures how components such as MDB's
- consume messages from the HornetQ server and also how components such as EJB's or
- Servlet's can send messages.</para>
+ with JEE components such as MDBs and EJBs. It configures how components such as MDBs
+ consume messages from the HornetQ server and also how components such as EJBs or
+ Servlets can send messages.</para>
<para>The HornetQ JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
configuration of the adapter is found in this archive under <literal
>META-INF/ra.xml</literal>.</para>
@@ -293,8 +297,7 @@
<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.invm.InVMConnectorF
- actory</config-property-value>
+ <config-property-value>org.hornetq.core.remoting.impl.invm.InVMConnectorFactory</config-property-value>
</config-property>
<config-property>
<description>The transport configuration. These values must be in the form of key=val;key=val;</description>
@@ -356,7 +359,7 @@
</inbound-resourceadapter>
</resourceadapter></programlisting>
- <para>There are 3 main parts to this configuration.</para>
+ <para>There are three main parts to this configuration.</para>
<orderedlist>
<listitem>
<para>A set of global properties for the adapter</para>
@@ -367,7 +370,7 @@
</listitem>
<listitem>
<para>The configuration of the inbound part of the adapter. This is used for
- controlling the consumption of messages via MDB's. </para>
+ controlling the consumption of messages via MDBs. </para>
</listitem>
</orderedlist>
<section>
@@ -375,7 +378,7 @@
<para>The first element you see is <literal>resourceadapter-class</literal> which should
be left unchanged. This is the HornetQ resource adapter class.</para>
<para>After that there is a list of configuration properties. This will be where most of
- the configuration is done. The first 2 configure the transport used by the adapter
+ the configuration is done. The first two properties configure the transport used by the adapter
and the rest configure the connection factory itself.
</para>
<note>
More information about the hornetq-commits
mailing list