[jboss-cvs] JBoss Messaging SVN: r7187 - projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 3 22:37:53 EDT 2009
Author: irooskov at redhat.com
Date: 2009-06-03 22:37:53 -0400 (Wed, 03 Jun 2009)
New Revision: 7187
Added:
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/ordering_group.xml
Removed:
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/About_This_Book.xml
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/Important_Features.xml
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/installation.xml
Modified:
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/configuration.xml
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/introduction.xml
projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/runningexamples.xml
Log:
updated book for new CP
Deleted: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/About_This_Book.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/About_This_Book.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/About_This_Book.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="about_this_book">
- <title>About this book</title>
- <para>
- The goal of this book is to give you an overview of JBoss Messaging. It explains the important features of JBoss Messaging and its capability to provide a high-performance and robust messaging system for Enterprise Java Applications.
- </para>
- <para>
- JBoss Messaging is the new state-of-the-art enterprise messaging system from JBoss, providing superior performance, reliability and scalability with high throughput and low latency. JBoss Messaging has replaced JBossMQ as the default JMS provider in JBoss Enterprise Application Platform 4.3. The version used is JBoss Messaging 1.4. You should use this version or later with the examples demonstrating JBoss Messaging. The book is not intended to teach you the basics of Enterprise Messaging. Use it to familiarize with JBoss Messaging features and various configurations.
- </para>
-</chapter>
Deleted: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/Important_Features.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/Important_Features.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/Important_Features.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -1,159 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="A_QUICK_TOUR">
- <title>JBoss Messaging - A Quick Tour</title>
- <section id="Limitations_of_JBossMQ">
- <title>Limitations of JBossMQ</title>
- <para>
- JBossMQ has two fundamental limitations:
- <itemizedlist>
- <listitem>
- <para>
- JBossMQ is based on SpyderMQ (the open source project) which is a non-clustered broker.
- </para>
- </listitem>
- <listitem>
- <para>
- The threading model and the overall design of the non-clustered broker leads to performance limitations in certain high load usage scenarios.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-<!-- <section id="JBoss_Messaging_Features">
- <title>JBoss Messaging Features</title>
- <para>
- JBoss Messaging implements a high-performance and robust messaging core that is designed to support the largest and most heavily utilized Service Oriented Architectures(SOAs), Enterprise Service Buses (ESBs) and other integration needs ranging from the simplest to the highest demand networks.
- </para>
- <para>
- It will allow you to smoothly distribute your application load across your cluster, intelligently balancing and utilizing each node's CPU cycles. It comes with no single point of failure and no single point of bottleneck, sophisticated and fully configurable message expiration handling and XA transaction recovery. Thus providing a highly scalable and performant clustering implementation. It includes a JMS front-end to deliver messaging in a standards-based format as well as being designed to be able to support other messaging protocols in the future.
- </para>
- <note>
- <para>
- <emphasis>JMS compliance</emphasis>: A fully compatible and Sun certified JMS 1.1 implementation, that currently works with JBoss Enterprise Application Platform 4.3 or later.
- </para>
- </note>
- <para>
- JBoss Messaging contains a host of other features, including:
- <itemizedlist>
- <listitem>
- <para>Publish-subscribe and point-to-point messaging models</para>
- </listitem>
- <listitem>
- <para>Persistent and non-persistent messages</para>
- </listitem>
- <listitem>
- <para>Guaranteed message delivery that ensures that messages
- arrive once and only once where required</para>
- </listitem>
- <listitem>
- <para>Transactional and reliable - supporting ACID
- semantics</para>
- </listitem>
- <listitem>
- <para>Customizable security framework based on JAAS</para>
- </listitem>
- <listitem>
- <para>Fully integrated with JBoss Transactions (formerly known as
- Arjuna JTA) for full transaction recoverability.</para>
- </listitem>
- <listitem>
- <para>Extensive JMX management interface</para>
- </listitem>
- <listitem>
- <para>Support for most major databases including Oracle, Sybase,
- MS SQL Server, PostgreSQL and MySQL</para>
- </listitem>
- <listitem>
- <para>HTTP transport to allow use through firewalls that only
- allow HTTP traffic</para>
- </listitem>
- <listitem>
- <para>SSL transport</para>
- </listitem>
- <listitem>
- <para>Configurable DLQs (Dead Letter Queues) and Expiry
- Queues</para>
- </listitem>
- <listitem>
- <para>Message statistics: Gives you a rolling historical view of
- what messages were delivered to what queues and
- subscriptions</para>
- </listitem>
- <listitem>
- <para>Automatic paging of messages to storage. Allows the use of
- very large queues - too large to fit in memory at once</para>
- </listitem>
- </itemizedlist>
- </para>
- </section> -->
- <section id="clustering">
- <title>Clustering Features</title>
- <formalpara>
- <title>Fully clustered queues and topics</title>
- <para>
- "Logical" queues and topics are distributed across the cluster. You can send to a queue or a topic from any node, and receive from any other.
- </para>
- </formalpara>
- <formalpara>
- <title>Fully clustered durable subscriptions</title>
- <para>
- A particular durable subscription can be accessed from any node of the cluster - allowing you to spread processing load from that subscription across the cluster.
- </para>
- </formalpara>
- <formalpara>
- <title>Fully clustered temporary queues</title>
- <para>
- Send a message with a <literal>replyTo</literal> of a temp queue and it can be sent back on any node of the cluster.
- </para>
- </formalpara>
- <formalpara>
- <title>Intelligent message redistribution</title>
- <para>
- Messages are automatically moved between different nodes of the cluster if consumers are faster on one node than another. This can help prevent starvation or build up of messages on particular nodes.
- </para>
- </formalpara>
- <formalpara>
- <title>Message order protection</title>
- <para>
- If you want to ensure that the order of messages produced by a producer is the same as is consumed by a consumer then you can set this to true. This works even in the presence of message redistribution.
- </para>
- </formalpara>
- <formalpara>
- <title>Fully transparent failover</title>
- <para>
- When a server fails, your sessions continue without exceptions on a new node as if nothing happened. (Fully configurable - If you don't want this you can fall back to exceptions being thrown and manually recreation of connections on another node)
- </para>
- </formalpara>
- <formalpara>
- <title>High availability and seamless fail-over</title>
- <para>
- If the node you are connected to fails, you will automatically fail over to another node and will not lose any persistent messages. You can carry on with your session seamlessly where you left off. Once and only once delivery of persistent messages is respected at all times.
- </para>
- </formalpara>
- <formalpara>
- <title>Message bridge</title>
- <para>
- JBoss Messaging contains a message bridge component which enables you to bridge messages between any two JMS1.1 destinations on the same or physical separate locations. (E.g. separated by a WAN). This allows you to connect geographically separate clusters, forming huge globally distributed logical queues and topics.
- </para>
- </formalpara>
- </section>
- <section id="compatibility_JBossMQ">
- <title>Compatibility with JBossMQ</title>
- <para>
- Since JBoss Messaging is JMS 1.1 and JMS 1.0.2b compatible, the JMS code written against JBossMQ will run with JBoss Messaging without any changes.
- </para>
- <para>
- JBoss Messaging does not have wire format compatibility with JBossMQ so it would be necessary to upgrade JBoss MQ clients with JBoss Messaging client jars.
- </para>
- <important>
- <para>
- Even if JBoss Messaging deployment descriptors are very similar to JBoss MQ deployment descriptors, they are <emphasis>not</emphasis> identical, so they will require some simple adjustments to get them to work with JBoss Messaging. Also, the database data model is completely different, so don't attempt to use JBoss Messaging with a JBoss MQ data schema and vice-versa.
- </para>
- </important>
- <note>
- <para>
- JBoss Messaging is built against the JBoss AS 4.2 libraries which are built using Java 5. Therefore JBoss Messaging only runs with Java 5 or later.
- </para>
- </note>
- </section>
-</chapter>
Modified: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/configuration.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/configuration.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/configuration.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -2254,8 +2254,27 @@
creates connections that use the HTTP transport to communicate to the
server and another that creates connections that use the bisocket
transport to communicate.</para>
- </section>
+ </section>
+ <section id="conf.connectionfactory.attributes.enableorderinggroup">
+ <title>EnableOrderingGroup</title>
+
+ <para>This parameter controls whether the strict message ordering is enabled or not
+ on the ConnectionFactory. If set to 'true', all messages that are sent from any producers
+ created from this connection factory become ordering group messages.</para>
+
+ <para>The default value is false.</para>
+ </section>
+
+ <section id="conf.connectionfactory.attributes.defaultorderinggroupname">
+ <title>DefaultOrderingGroupName</title>
+
+ <para>the default name for the message ordering group. If absent,
+ the group name will be generated automatically.</para>
+
+ <para>This attribute takes effect only if the EnableOrderingGroup attribute is true.</para>
+ </section>
+
<!-- End conf.connectionfactory.attributes -->
</section>
Deleted: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/installation.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/installation.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/installation.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -1,1220 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="installation">
- <title>JBoss Messaging Installation</title>
-
- <para>This section describes procedures on how to install JBoss Messaging
- into JBoss Application Server community edition 4.2. At the end of this
- procedure, you will create a JBoss Messaging configuration that will start a
- clustered or non-clustered messaging server.</para>
-
- <para>Please note that JBoss EAP 4.3 or later comes with JBoss Messaging
- pre-installed as default JMS provider so if you are using that, there is no need to manually
- install JBoss Messaging</para>
-
- <para>By default, JBoss AS 4.2 ships with JBossMQ as default JMS provider.
- In order to use the JBoss AS instance with JBoss Messaging, you need to
- perform the installation procedure described below.</para>
-
- <para><note>
- A JBossMQ and a JBoss Messaging instance cannot coexist, at least not unless special precautions are taken. Do not simply attempt to copy the Messaging release artifact
-
- <filename>jboss-messaging.sar</filename>
-
- over to the JBoss instance w
-
- <filename>deploy</filename>
-
- directory. Follow one of the alternate installation procedures outlined below instead.
- </note></para>
-
- <para><note>
- We only recommend and support installing JBoss Messaging in JBoss AS 4.2 or later. You should avoid using JBoss Messaging on any version of JBoss AS prior to JBoss 4.2.0.GA, such as 4.0.5.GA and 4.0.4.GA.
- </note><note>
- JBoss Messaging is built against the JBoss AS 4.2 libraries which are built using Java 5. Therefore JBoss Messaging only runs with Java 5 or later.
- </note></para>
-
- <section id="install">
- <title>Installing JBoss Messaging on JBoss AS 4.2</title>
-
- <para>In this section we present two different methods of installing JBoss
- Messaging in JBoss AS 4.2</para>
-
- <itemizedlist>
- <listitem>
- If you have a completely clean JBoss AS 4.2.0 installation then you can do an
-
- <xref linkend="install.automated">automatic install</xref>
-
- .
- </listitem>
-
- <listitem>
- If you have a JBoss 4.2.0 that you have changed in some way from a clean JBoss AS 4.2.0 installation then you will need to do a
-
- <xref linkend="install.manual">manual install</xref>
-
- .
- </listitem>
- </itemizedlist>
-
- <section id="install.automated">
- <title>Automated Installation</title>
-
- <para><note>
- This procedure should only be performed from a clean JBoss AS 4.2 installation. If you have modified the JBoss AS 4.2 installation at all since installation then you will need to perform a manual clustered JBoss Messaging installation
- </note></para>
-
- <itemizedlist>
- <listitem>
- <para>Set up the <literal>JBOSS_HOME</literal> environment variable
- to point to the JBoss 4.2 installation you want to use JBoss
- Messaging with.</para>
-
- <para>Run the installation script, available in the
- <filename>util</filename> directory of the release bundle as
- follows:</para>
-
- <para>If you want to create a simple non clustered installation based
- on the default configuration:</para>
-
- <programlisting>
- cd util
- ant -f release-admin.xml
- </programlisting>
-
- <para>If you want to create a clustered installation based on the
- all configuration or change the configuration name:</para>
-
- <programlisting>
- cd util
- ant -f release-admin.xml -Dmessaging.config.source=all -Dmessaging.config.name=messaging-node0
- </programlisting>
-
- <para>In the above you would substitute
- <literal>messaging-node0</literal> with whatever is the name you
- want to give the configuration. If you want several cluster nodes on
- the same machine, e.g. for development purposes then a good
- convention is to name them <literal>messaging-node0,
- messaging-node1</literal> to match
- <literal>messaging-node<ServerPeerID></literal></para>
-
- <para>The messaging.config.source variable determines which JBoss AS
- configuration (e.g. default or all) to base the installation
- on</para>
-
- <para>The installation script will create a
- <filename>$JBOSS_HOME/server/messaging-node0</filename>
- configuration. (If you have chosen
- <literal>messaging-node0</literal>)</para>
- </listitem>
-
- <para>For the rest of the procedure we assume JBOSS_CONFIG refers to
- your new messaging configuration (e.g. messaging-node0 or
- messaging)</para>
-
- <para>You don't actually have to create an environment variable
- <literal>JBOSS_CONFIG</literal>, this is just used in the installation
- instructions to describe the steps</para>
-
- <listitem>
- <para>
- <warning>For a clustered installation it is mandatory that a
- shared database is available to all nodes in the cluster. The
- default JBoss AS uses HSQLDB for its database which is a local
- shared database. Therefore in order to use clustering you must
- replace this with a different shared database. If the database is
- not replaced then clustering will not work.</warning>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Replace
- <literal>$JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml</literal>
- by the <literal>databasename>-persistence-service</literal>
- from
- <literal><downloadPackage>/examples/config.</literal>. For
- instance <literal>mysql-persistence-service.xml</literal></para>.
- <para>If you are installing in a clustered configuration
- make sure to set the <literal>Clustered</literal> attribute to <literal>true</literal></para>
- </listitem>
-
- <listitem><para>Configure a JCA datasource using an example from
- <literal>$JBOSS_HOME/docs/examples/jca</literal></para> and
- copying to <literal>$JBOSS_CONFIG/deploy</literal> <para>JBoss
- Messaging uses <literal>DefaultDS</literal> by default so you
- should configure your datasource to bind to that</para></listitem>
-
- <listitem>
- <para>Remove hsqldb-ds.xml from
- <literal>$JBOSS_CONFIG/deploy</literal></para>
- </listitem>
-
- <listitem>
- <para>Copy your database driver to
- <literal>$JBOSS_CONFIG/lib</literal></para>
-
- <para>Your database driver can probably be downloaded from your
- database provider's web site</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Ensure the <literal>ServerPeerID</literal> MBean attribute
- value in messaging-service.xml is unique for each node. The
- <literal>ServerPeerID</literal> value must be a valid integer. Every
- node MUST have a unique id, including those just connected by
- message bridges.</para>
-
- <para>
- <warning>Each node must have a unique
- <literal>ServerPeerID</literal> irrespective of whether you are
- using clustering.</warning>
- </para>
- </listitem>
-
- <listitem>
- <para>If you want to run multiple JBoss Messaging nodes on the same
- box using the same IP address, e.g. for development purposes, then
- you can use the ServiceBindingManager to do this as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>Uncomment binding manager service from
- $JBOSS_CONFIG/conf/jboss-service.xml</para>
- </listitem>
-
- <listitem>
- <para>Specify the desired port rage (e.g. ports-01, ports-02...
- etc)</para>
- </listitem>
-
- <listitem>
- <para>Look at
- $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml.
- Here is an example:</para>
-
- <programlisting>
- <service-config name="jboss.messaging:service=Connector,transport=bisocket"
- delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
- <delegate-config>
- <attribute name="Configuration"><![CDATA[
- <config>
- <invoker transport="bisocket">
-
- <!-- There should be no reason to change these parameters - warning!
- Changing them may stop JBoss Messaging working correctly -->
- <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
- <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
- <attribute name="dataType" isParam="true">jms</attribute>
- <attribute name="socket.check_connection" isParam="true">false</attribute>
- <attribute name="timeout" isParam="true">0</attribute>
- <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
- <attribute name="serverBindPort">4657</attribute>
- <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
- <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
- <attribute name="numberOfCallRetries" isParam="true">1</attribute>
- <attribute name="pingFrequency" isParam="true">214748364</attribute>
- <attribute name="pingWindowFactor" isParam="true">10</attribute>
- <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
-
- <!-- Periodicity of client pings. Server window by default is twice this figure -->
- <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
-
- <!-- Number of seconds to wait for a connection in the client pool to become free -->
- <attribute name="numberOfRetries" isParam="true">10</attribute>
-
- <!-- Max Number of connections in client pool. This should be significantly higher than
- the max number of sessions/consumers you expect -->
- <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
-
- <!-- Use these parameters to specify values for binding and connecting control connections to
- work with your firewall/NAT configuration
- <attribute name="secondaryBindPort">xyz</attribute>
- <attribute name="secondaryConnectPort">abc</attribute>
- -->
-
- </invoker>
- <handlers>
- <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
- </handlers>
- </config>
- ]]></attribute>
- </delegate-config>
- <binding port="4657"/>
- </service-config>
-
- </programlisting>
-
- <warning>You must ensure that the config (like above) is
- identical to that in
- <literal>remoting-bisocket-service.xml</literal> With the
- exception of the actual serverBindPort which clearly must be
- different for each ports range. Please note that the default
- JBoss Messaging service binding manager bindings in
- <literal>sample-bindings.xml</literal> shipped with JBAS 4.2.0
- may be out of date and you will need to copy the config from
- <literal>remoting-bisocket-service.xml. DO NOT just copy and
- paste from the above example - copy it from the JBoss Messaging
- distribution.</literal></warning>
-
- <para>You should ensure that each node is configured to use a
- different ports range.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>There are few extra steps at <xref
- linkend="install.extra-steps" /></para>
- </listitem>
-
- <listitem>That's it</listitem>
- </itemizedlist>
- </section>
-
- <section id="install.manual">
- <title>Manual Installation</title>
-
- <para><note>
- This installation procedure should be performed if you are installing into a JBoss AS configuration that you have changed in some way from the default JBoss AS distribution. If you are just using the standard, untouched JBoss AS 4.2 distribution you can use the automated procedure above
- </note></para>
-
- <para>For this procedure we assume you already have your custom
- configuration located at
- <literal>JBOSS_CONFIG=$JBOSS_HOME/server/<myconfiguration></literal>,
- and that it contains a JBoss MQ installation.</para>
-
- <para>You don't actually have to create an environment variable
- <literal>JBOSS_CONFIG</literal>, this is just used in the installation
- instructions to describe the steps</para>
-
- <itemizedlist>
- <listitem>
- <para>Move
- <literal>$JBOSS_CONFIG/deploy/jms/hajndi-jms-ds.xml</literal> and
- <literal>$JBOSS_CONFIG/deploy/jms/jms-ra.rar</literal> to
- <literal>$JBOSS_CONFIG/deploy</literal></para>
- </listitem>
-
- <listitem>
-
-
- <para>Remove the old JBoss MQ by removing the directory
- <literal>$JBOSS_CONFIG/deploy/jms.</literal></para>
-
- .
-
- <para>Remove the old JBoss MQ jar file:
- <literal>$JBOSS_CONFIG/lib/jbossmq.jar</literal></para>
-
-
-
- <para>Make sure you don't have any JBossMQ files under
- <literal>$JBOSS_CONFIG/deploy-hasingleton</literal>. For that just
- remove
- <literal>$JBOSS_CONFIG/deploy-hasingleton/jms</literal></para>
-
-
- </listitem>
-
- <listitem>
-
-
- <para>Add a security policy called "messaging" on
- $JBOSS_CONFIG/config/login-config.xml. You could use this as an
- example, or create one according to JBoss Security
- Documentation:</para>
-
-
-
- <programlisting>
-<application-policy name = "messaging">
-<authentication>
-<login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required" >
- <module-option name = "unauthenticatedIdentity">guest</module-option>
- <module-option name = "usersProperties">props/messaging-users.properties</module-option>
- <module-option name = "rolesProperties">props/messaging-roles.properties</module-option>
-</login-module>
-</authentication>
-</application-policy>
- </programlisting>
-
-
-
- <para>In case you are using the above policy you should also create
- files <literal>messaging-users.properties</literal> and
- <literal>messaging-roles.properties</literal> in the
- <literal>$JBOSS_CONFIG/config/props/</literal> directory</para>
-
- .
-
- <para>
- <note>You can find an example
- <literal>messaging-users.properties</literal> and
- <literal>messaging-roles.properties</literal> in the JBoss
- Messaging distribution in the
- <literal><downloadPackage>src/etc/server/default/config</literal>
- directory.</note>
- </para>
-
-
-
- <programlisting>
-# messaging-roles.properties
-# Add roles as you like
-# user=role1,role2,...
-#
-guest=guest
- </programlisting>
-
-
-
- <programlisting>
-# messaging-users.properties
-
-# Add users as you like
-# user=password
-#
-guest=guest
- </programlisting>
-
-
- </listitem>
-
- <listitem>
- <para>Unzip jboss-messaging.sar from your download package into the
- directory
- <literal>JBOSS_CONFIG/deploy/jboss-messaging.sar</literal></para>
-
- <para>JBoss Messaging should be deployed unzipped (exploded) so you
- have easy access to its config files which are stored there.</para>
- </listitem>
-
- <listitem>
- <para>Copy jboss-messaging.jar from your download package into the
- directory <literal>JBOSS_CONFIG/lib</literal></para>
-
- <para>jboss-messaging.jar needs to go in the lib directory so it is
- accessible to other services e.g. the JBoss Transactions Recovery
- Manager</para>
- </listitem>
-
- <listitem>
- <para><warning>
- For a clustered installation it is mandatory that a shared database is available to all nodes in the cluster. The default JBoss AS uses HSQLDB for its database which is a local shared database. Therefore in order to use clustering you must replace this with a different shared database. If the database is not replaced then clustering will not work.
- </warning></para>
-
- <itemizedlist>
- <listitem>
- <para>Replace
- <literal>$JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml</literal>
- by the <literal>databasename>-persistence-service</literal>
- from
- <literal><downloadPackage>/examples/config.</literal>. For
- instance <literal>mysql-persistence-service.xml</literal></para>
-
- <para>If you are installing in a clustered configuration
- make sure to set the <literal>Clustered</literal> attribute to <literal>true</literal></para>
- </listitem>
-
- <listitem>
-
-
- <para>Configure a JCA datasource using an example from
- <literal>$JBOSS_HOME/docs/examples/jca</literal></para>
-
- and copying to
-
- <literal>$JBOSS_CONFIG/deploy</literal>
-
-
-
- <para>JBoss Messaging uses <literal>DefaultDS</literal> by
- default so you should configure your datasource to bind to
- that</para>
-
-
- </listitem>
-
- <listitem>
- <para>Remove hsqldb-ds.xml from
- <literal>$JBOSS_CONFIG/deploy</literal></para>
- </listitem>
-
- <listitem>
- <para>Copy your database driver to
- <literal>$JBOSS_CONFIG/lib</literal></para>
-
- <para>Your database driver can probably be downloaded from your
- database provider's web site</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Ensure the <literal>ServerPeerID</literal> MBean attribute
- value in messaging-service.xml is unique for each node on the
- cluster. The <literal>ServerPeerID</literal> value must be a valid
- integer.</para>
-
- <para><warning>
- Each node must have a unique
-
- <literal>ServerPeerID</literal>
-
- irrespective of whether you are using clustering.
- </warning></para>
- </listitem>
-
- <listitem>
- <para>If you want to run multiple JBoss Messaging nodes on the same
- box using the same IP address, e.g. for development purposes, then
- you can use the ServiceBindingManager to do this as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>Uncomment binding manager service from
- $JBOSS_CONFIG/conf/jboss-service.xml</para>
- </listitem>
-
- <listitem>
- <para>Specify the desired port rage (e.g. ports-01, ports-02...
- etc)</para>
- </listitem>
-
- <listitem>
- <para>Look at
- $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml.
- On each port range, JBoss Remoting configuration should look
- like:</para>
-
- <programlisting>
- <service-config name="jboss.messaging:service=Connector,transport=bisocket"
- delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
- <delegate-config>
- <attribute name="Configuration"><![CDATA[
- <config>
- <invoker transport="bisocket">
-
- <!-- There should be no reason to change these parameters - warning!
- Changing them may stop JBoss Messaging working correctly -->
- <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
- <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
- <attribute name="dataType" isParam="true">jms</attribute>
- <attribute name="socket.check_connection" isParam="true">false</attribute>
- <attribute name="timeout" isParam="true">0</attribute>
- <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
- <attribute name="serverBindPort">4657</attribute>
- <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
- <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
- <attribute name="numberOfCallRetries" isParam="true">1</attribute>
- <attribute name="pingFrequency" isParam="true">214748364</attribute>
- <attribute name="pingWindowFactor" isParam="true">10</attribute>
- <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
-
- <!-- Periodicity of client pings. Server window by default is twice this figure -->
- <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
-
- <!-- Number of seconds to wait for a connection in the client pool to become free -->
- <attribute name="numberOfRetries" isParam="true">10</attribute>
-
- <!-- Max Number of connections in client pool. This should be significantly higher than
- the max number of sessions/consumers you expect -->
- <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
-
- <!-- Use these parameters to specify values for binding and connecting control connections to
- work with your firewall/NAT configuration
- <attribute name="secondaryBindPort">xyz</attribute>
- <attribute name="secondaryConnectPort">abc</attribute>
- -->
-
- </invoker>
- <handlers>
- <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
- </handlers>
- </config>
- ]]></attribute>
- </delegate-config>
- <binding port="4657"/>
- </service-config>
-
- </programlisting>
-
- <warning>
- You must ensure that the config (like above) is identical to that in
-
- <literal>remoting-bisocket-service.xml</literal>
-
- With the exception of the actual serverBindPort which clearly must be different for each ports range. Please note that the default JBoss Messaging service binding manager bindings in
-
- <literal>sample-bindings.xml</literal>
-
- shipped with JBAS 4.2.0 may be out of date and you will need to copy the config from
-
- <literal>remoting-bisocket-service.xml. DO NOT just copy and
- paste from the above example - copy it from the JBoss
- Messaging distribution.</literal>
-
-
-
- <literal />
-
-
-
- <literal />
-
-
-
- <literal />
-
-
- </warning>
-
- <para>You should ensure that each node is configured to use a
- different ports range.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>There are few extra steps at <xref
- linkend="install.extra-steps" /></para>
- </listitem>
-
- <listitem>
- That's it
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="install.extra-steps">
- <title>Extra steps to complete your installation</title>
-
- <itemizedlist>
- <listitem>
- <para>
- <warning>SECURITY RISK! To avoid a security risk, you MUST specify
- the value of the attribute SuckerPassword in the Server Peer
- config (messaging-service.xml). If you do not specify a value, the
- default value will be used. Any person that knows the default
- value will be able to access to all destinations on the server.
- The password chosen should only be exposed to
- administrators</warning>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <note>JBoss Messaging 1.4.0 and 1.4.1 requires a patched version
- of jboss-remoting.jar. This version is available can be downloaded from here <ulink
- url="http://repository.jboss.com/jboss/remoting/2.2.2.SP10-brew/ ">here</ulink>The
- version is JBoss Remoting 2.2.2.SP10-brew. Please download it and
- copy it into the <literal>$JBOSS_HOME/server/<your server
- name>/lib directory</literal> of any server profiles that use
- JBoss Messaging. If you are using JBoss Messaging
- from a standalone client also make sure this jar is on your
- classpath *before* jbossall-client.jar.</note>
- </para>
- </listitem>
-
- <para>You should also make these changes on any configuration you
- choose, to remove all references to the old JBossMQ:</para>
-
- <listitem>
- <para>Edit <literal>$JBOSS_CONFIG/deploy/jms-ds.xml</literal> and
- replace jboss.mq by jboss.messaging on every occurrence</para>
-
- <para>If you are in a clustered installation, then do the above with
- the file
- <literal>$JBOSS_CONFIG/deploy/hajndi-jms-ds.xml</literal></para>
- </listitem>
-
- <listitem>
- <para>Edit <literal>$JBOSS_CONFIG/conf/standardjboss.xml</literal>
- and set <literal>CreateJBossMQDestination</literal> to false on
- every occurrence</para>
-
- <para>Make sure it looks like this:</para>
-
- <para>
- <literal><CreateJBossMQDestination>false</CreateJBossMQDestination></literal>
- </para>
-
- <para>Those Proxies will try to create a Destination on JBossMQ if
- they can't find it on JNDI, what would cause some errors related to
- JBoss MQ.</para>
- </listitem>
-
- <listitem>
- <para>Edit $JBOSS_CONFIG/conf/jboss-service.xml and remove the
- reference to JBoss MQ on JSR-77 Management Bean:</para>
-
- <programlisting>
- <!-- ==================================================================== -->
- <!-- JSR-77 Single JBoss Server Management Domain -->
- <!-- ==================================================================== -->
- <mbean code="org.jboss.management.j2ee.LocalJBossServerDomain"
-
- ... Remove this line ...
- <attribute name="JMSService">jboss.mq:service=DestinationManager</attribute>
- </programlisting>
- </listitem>
-
- <listitem>
- <para>Change <literal>$JBOSS_CONFIG/conf/login-config.xml</literal>
- and remove jboss-mq security policies</para>
-
- <programlisting>
-### Remove these lines:
-
-<!-- Security domain for JBossMQ -->
-<application-policy name = "jbossmq">
- <authentication>
- <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule"
- flag = "required">
- <module-option name = "unauthenticatedIdentity">guest</module-option>
- <module-option name = "dsJndiName">java:/DefaultDS</module-option>
- <module-option name = "principalsQuery">
- SELECT PASSWD FROM JMS_USERS WHERE USERID=?</module-option>
- <module-option name = "rolesQuery">
- SELECT ROLEID, 'Roles' FROM JMS_ROLES WHERE USERID=?</module-option>
- </login-module>
- </authentication>
-</application-policy>
-
-<!-- Security domain for JBossMQ when using file-state-service.xml
-<application-policy name = "jbossmq">
- <authentication>
- <login-module code = "org.jboss.mq.sm.file.DynamicLoginModule"
- flag = "required">
- <module-option name = "unauthenticatedIdentity">guest</module-option>
- <module-option name = "sm.objectname">jboss.mq:service=StateManager</module-option>
- </login-module>
- </authentication>
-</application-policy>
--->
-
- </programlisting>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section id="startingtheservice">
- <title>Starting the Server</title>
-
- <para>To run the server, execute the <filename>run.bat</filename> or
- <filename>run.sh</filename> script as appropriate for your operating
- system, in the <filename>$JBOSS_HOME/bin</filename> directory.</para>
-
- <programlisting>
-cd $JBOSS_HOME/bin
-./run.sh -c <config name>
- </programlisting>
-
- <para>Where config_name is the name of the JBoss AS configuration where
- you have installed messaging. (The default is 'messaging')</para>
-
- <para>A successful JBoss Messaging deployment generates logging output
- similar to for a non clustered installation (for a clustered installation
- you will also see extra cluster related output)</para>
-
- <programlisting>
-....
-13:19:14,914 WARN [JDBCPersistenceManager]
-
-JBoss Messaging Warning: DataSource connection transaction isolation should be READ_COMMITTED,
-but it is currently NONE.
- Using an isolation level less strict than READ_COMMITTED may lead to
-data consistency problems.
- Using an isolation level more strict than READ_COMMITTED may lead to
-deadlock.
-
-13:19:15,166 INFO [ServerPeer] JBoss Messaging 1.4.0.GA server [0] started
-13:19:15,411 INFO [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
-, lease period 10000 milliseconds
-13:19:15,412 INFO [ConnectionFactory] [/ConnectionFactory, /XAConnectionFactory, java:/Connec
-tionFactory, java:/XAConnectionFactory] started
-13:19:15,412 WARN [ConnectionFactoryJNDIMapper] supportsFailover attribute is true on connect
-ion factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory but
-post office is non clustered. So connection factory will *not* support failover
-13:19:15,413 WARN [ConnectionFactoryJNDIMapper] supportsLoadBalancing attribute is true on co
-nnection factory: jboss.messaging.connectionfactory:service=ClusteredConnectionFactory
-but post office is non clustered. So connection factory will *not* support load balanc
-ing
-13:19:15,449 INFO [ConnectionFactory] Connector bisocket://127.0.0.1:4457 has leasing enabled
-, lease period 10000 milliseconds
-13:19:15,449 INFO [ConnectionFactory] [/ClusteredConnectionFactory, /ClusteredXAConnectionFac
-tory, java:/ClusteredConnectionFactory, java:/ClusteredXAConnectionFactory] started
-13:19:15,468 INFO [QueueService] Queue[/queue/DLQ] started, fullSize=200000, pageSize=2000, d
-ownCacheSize=2000
-13:19:15,474 INFO [QueueService] Queue[/queue/ExpiryQueue] started, fullSize=200000, pageSize
-=2000, downCacheSize=2000
-13:19:15,476 INFO [TopicService] Topic[/topic/testTopic] started, fullSize=200000, pageSize=2
-000, downCacheSize=2000
-13:19:15,478 INFO [TopicService] Topic[/topic/securedTopic] started, fullSize=200000, pageSiz
-e=2000, downCacheSize=2000
-13:19:15,479 INFO [TopicService] Topic[/topic/testDurableTopic] started, fullSize=200000, pag
-eSize=2000, downCacheSize=2000
-13:19:15,482 INFO [QueueService] Queue[/queue/testQueue] started, fullSize=200000, pageSize=2
-000, downCacheSize=2000
-13:19:15,483 INFO [QueueService] Queue[/queue/A] started, fullSize=200000, pageSize=2000, dow
-nCacheSize=2000
-13:19:15,485 INFO [QueueService] Queue[/queue/B] started, fullSize=200000, pageSize=2000, dow
-nCacheSize=2000
-13:19:15,487 INFO [QueueService] Queue[/queue/C] started, fullSize=200000, pageSize=2000, dow
-nCacheSize=2000
-13:19:15,489 INFO [QueueService] Queue[/queue/D] started, fullSize=200000, pageSize=2000, dow
-nCacheSize=2000
-13:19:15,490 INFO [QueueService] Queue[/queue/ex] started, fullSize=200000, pageSize=2000, do
-wnCacheSize=2000
-13:19:15,501 INFO [QueueService] Queue[/queue/PrivateDLQ] started, fullSize=200000, pageSize=
-2000, downCacheSize=2000
-13:19:15,503 INFO [QueueService] Queue[/queue/PrivateExpiryQueue] started, fullSize=200000, p
-ageSize=2000, downCacheSize=2000
-13:19:15,507 INFO [QueueService] Queue[/queue/QueueWithOwnDLQAndExpiryQueue] started, fullSiz
-e=200000, pageSize=2000, downCacheSize=2000
-13:19:15,508 INFO [TopicService] Topic[/topic/TopicWithOwnDLQAndExpiryQueue] started, fullSiz
-e=200000, pageSize=2000, downCacheSize=2000
-13:19:15,511 INFO [QueueService] Queue[/queue/QueueWithOwnRedeliveryDelay] started, fullSize=
-200000, pageSize=2000, downCacheSize=2000
-13:19:15,512 INFO [TopicService] Topic[/topic/TopicWithOwnRedeliveryDelay] started, fullSize=
-200000, pageSize=2000, downCacheSize=2000
-13:19:15,514 INFO [QueueService] Queue[/queue/testDistributedQueue] started, fullSize=200000,
-pageSize=2000, downCacheSize=2000
-13:19:15,519 INFO [TopicService] Topic[/topic/testDistributedTopic] started, fullSize=200000,
-pageSize=2000, downCacheSize=2000
-13:19:15,809 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:servic
-e=ConnectionFactoryBinding,name=JmsXA' to JNDI name 'java:JmsXA'
-13:19:15,834 INFO [TomcatDeployer] deploy, ctxPath=/jmx-console, warUrl=.../deploy/jmx-consol
-e.war/
-13:19:16,322 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
-13:19:16,342 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
-13:19:16,480 INFO [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA dat
-e=200705111440)] Started in 19s:359ms
-
- </programlisting>
-
- <note>
- The warning message
-
- <literal>"DataSource connection transaction isolation should be
- READ_COMMITTED, but it is currently NONE"</literal>
-
- is there to remind you that by default JBossAS ships with Hypersonic, an in-memory Java-based database engine, which is appropriate for demo purposes, but not for heavy load production environments. The
-
- <ulink
- url="http://wiki.jboss.org/wiki/Wiki.jsp?page=ConfigJBossMQDB">Critique
- of Hypersonic</ulink>
-
- wiki page outlines some of the well-known issues occurring when using this database.
- </note>
-
- <warning>
- Before using Messaging in production, you
-
- <emphasis>must</emphasis>
-
- configure the Messaging instance to use an enterprise-class database backend such as Oracle, Sybase, PostgreSQL, MS SQL or MySQL, otherwise you risk losing your data. See
-
- <xref linkend="conf.changingds" />
-
- for details about replacing Hypersonic.
- </warning>
- </section>
-
- <section id="inst.validation">
- <title>Installation Validation</title>
-
- <para>The release bundle contains a series of examples that should run
- "out of the box" and could be used to validate a new installation. Such an
- example sends a persistent JMS message to a queue called
- <literal>queue/testQueue</literal>.</para>
-
- <para>To run the example and validate the installation, open an new
- command line window and set the <literal>JBOSS_HOME</literal> environment
- variable to point to the JBoss AS 4.x installation you've just installed
- Messaging on. Navigate to the folder where you extracted the release
- bundle and drill down to <filename>/examples/queue</filename>. Apache Ant
- must be present in your path in order to be able to run the
- example.</para>
-
- <para>Make sure you start the JBoss server before trying to run the
- tests</para>
-
- <programlisting>
-
-setenv JBOSS_HOME=<your_JBoss_installation>
-cd .../examples/queue
-$ant
-
- </programlisting>
-
- <para>A successful execution log output looks similar to:</para>
-
- <programlisting>
-[tim at Vigor14 queue]$ ant
-Buildfile: build.xml
-
-identify:
- [echo] ###########################################################################
- [echo] # Running the QUEUE example #
- [echo] ###########################################################################
- [echo] The queue: testQueue
- [echo] The client jar: ../../../output/lib/jboss-messaging-client.jar
-
-sanity-check:
-
-init:
- [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/queue/output/classe
-s
- [mkdir] Created dir: /home/tim/dev/jboss-messaging/trunk/docs/examples/common/output/class
-es
-
-compile:
- [javac] Compiling 5 source files to /home/tim/dev/jboss-messaging/trunk/docs/examples/comm
-on/output/classes
- [javac] Compiling 1 source file to /home/tim/dev/jboss-messaging/trunk/docs/examples/queue
-/output/classes
-
-run:
- [java] Queue /queue/testQueue exists
- [java] The message was successfully sent to the testQueue queue
- [java] Received message: Hello!
- [java] The example connected to JBoss Messaging version 1.4.0.GA (1.4)
-
- [java] #####################
- [java] ### SUCCESS! ###
- [java] #####################
-
-BUILD SUCCESSFUL
-Total time: 5 seconds
-[tim at Vigor14 queue]$
-
-</programlisting>
-
- <para>It is recommended to run <literal>all</literal> validation examples
- available in the <filename>example</filename> directory
- (<filename>queue</filename>, <filename>topic</filename>,
- <filename>mdb</filename>, <filename>stateless</filename>, etc.). In <xref
- linkend="examples" />, we will have a look at each of those
- examples.</para>
- </section>
-
- <section id="inst.remoteclient">
- <title>Accessing JBoss Messaging from a remote client</title>
-
- <para>In order to access JBoss Messaging from a client outside the JBoss
- app server, you will need to ensure the following jar files are on the
- client classpath:</para>
-
- <itemizedlist>
- <listitem>
- <para><note>
- JBoss Messaging 1.4.0 requires a patched version of jboss-remoting.jar. The version is JBoss Remoting 2.2.2.SP10-brew. This version is available on JBoss EAP 4.3, so if you're using a different version you should download it. The patched jar can be found
-
- <ulink
- url="http://repository.jboss.com/jboss/remoting/2.2.2.SP10-brew/lib/">here</ulink>
-
- . Please download it and make sure this jar is on your classpath *before* jbossall-client.jar.
- </note></para>
- </listitem>
-
- <listitem>
- <para>jboss-messaging-client.jar - This is available in the messaging
- distribution</para>
- </listitem>
-
- <listitem>
- <para>jbossall-client.jar - This is available in your
- $JBOSS_HOME/client directory</para>
- </listitem>
-
- <listitem>
- <para>$JBOSS_HOME/server/<SERVER_NAME>/deploy/jboss-aop.deployer/jboss-aop.jar</para>
-
- <para>JBoss AOP 1.5.5.GA_CP03</para>
-
- <para><ulink url="http://repository.jboss.com/jboss/aop/1.5.5.GA_CP03-brew/lib/">http://repository.jboss.com/jboss/aop/1.5.5.GA_CP03-brew/lib/</ulink></para>
-
- <para>(For AOP, sometimes you have to use a specific JAR according to
- your JVM of choice. Use the most convenient for you)</para>
- </listitem>
-
- <listitem>
- <para>$JBOSS_HOME/server/<SERVER_NAME>/lib/javassist.jar</para>
-
- <para>Javassist 3.8.0.GA-brew</para>
-
- <para><ulink
- url="http://repository.jboss.com/javassist/3.8.0.GA-brew/lib/">http://repository.jboss.com/javassist/3.8.0.GA-brew/lib/</ulink></para>
- </listitem>
-
- <listitem>
- <para>$JBOSS_HOME/server/<SERVER_NAME>/lib/trove.jar</para>
-
- <para>trove 1.0.2-brew</para>
-
- <para><ulink
- url="http://repository.jboss.com/trove/1.0.2-brew/lib/">http://repository.jboss.com/trove/1.0.2-brew/lib/</ulink></para>
- </listitem>
-
- <listitem>
- <para>log4j</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="inst.mqmessagemigration">
- <title>Migrating Messages from JBoss MQ to JBoss Messaging</title>
-
- <para>This configuration will allow you to migrate your systems using
- JBossMQ to JBM(JBoss Messaging). Many Enterprise systems are complex and
- have multiple applications and can't be migrated from JBossMQ to JBM all
- at one time.</para>
-
- <para>Made up Use Case: For instance, your business is selling items, some
- you make directly and some you farm out to other distributors. Your
- ordering system is JBossMQ based. Customers place orders that are then
- queued up to be processed(via JBossMQ). You also use MQ to queue up the
- orders that you need to produce and you also queue up the orders that will
- go to your other distributors. You use MDB's in three separate places in
- your operation. You want to do a staged migration from JBossMQ to JBM.
- That requires that JBossMQ and JBM work together. This is exactly what the
- JBM bridge was meant to do. It's meant to take messages from one
- queue/topic and transfer them to another queue/topic. This helps with the
- migration by allowing you to pull messages from your JBossMQ queues
- automatically and push them into your JBM Queues. You can also do the
- opposite, you can push messages from your JBM system to your JBossMQ
- system. In our example, we want to replace the ordering side(producer)
- with JBM. We push messages into the JBM Order queue, but we set the bridge
- up to send all of those messages to the JBossMQ Order queue. The rest of
- your processing happens as normal. Lets say you want to leave your
- ordering system intact, but you want to have JBM and EJB3 MDBs process the
- orders. You can have your old client put messages in JBossMQ as normal,
- but you set the bridge up to pull the messages from JBossMQ Order queue
- and push them into the JBM Order queue.</para>
-
- <para>This allows JBM and JBossMQ to interact together by pushing messages
- back and forth between different systems.</para>
-
- <para>The Following Assumptions are made:</para>
-
- <itemizedlist>
- <listitem>You have one JBoss instance set up for JBoss Messaging and One
- Jboss instance set up that has your old JBoss MQ on it.</listitem>
-
- <listitem>We are copying messages from JBossMQ(Source) to
- JBM(Target)</listitem>
- </itemizedlist>
-
- <section id="inst.mqmessagemigration.steps">
- <title>Steps to Set up the bridge</title>
-
- <itemizedlist>
- <listitem>
- <para>Copy the jbossmq.jar from the Source Machine(JBossMQ) under
- the server/default/lib/ to the messaging configuration on the Target
- JBM machine(server/messaging/lib)</para>
-
- <note>substitute what ever your messaging server configuration is
- above. I used the default stand alone messaging server configuration
- note: This is required to de-reference the JBossMQ objects that are
- de-referenced on the JBM side. If you don't copy the jar over, you
- will get a "java.lang.ClassCastException: javax.naming.Reference"
- exception and the bridge will not be able to start</note>
- </listitem>
-
- <listitem>
- <para>Add the remote JBossMQ provider to the jms-ds.xml file in the
- server/messaging/deploy directory on your target(JBM)
- machine.</para>
-
- <para>Here is an example of the provider to add.</para>
-
- <programlisting>
-<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
- name="jboss.messaging:service=JMSProviderLoader,
- name=MyRemoteJMSProvider">
- <attribute name="ProviderName">RemoteXAConnectionFactory</attribute>
- <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
- <!-- The combined connection factory -->
- <attribute name="FactoryRef">XAConnectionFactory</attribute>
- <!-- The queue connection factory -->
- <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
- <!-- The topic factory -->
- <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
- <attribute name="Properties">
- java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
- java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
- java.naming.provider.url=192.168.0.199:1099
- </attribute>
-</mbean>
- </programlisting>
-
- <note>you will need to change the java.naming.provider.url so that
- it points to your JBossMQ machine. Everything else should remain the
- same. Keep your jms-ds.xml file open, because you will be adding
- another entry in it for the next step.</note>
- </listitem>
-
- <listitem>
- <para>Add the Bridge provider to the jms-ds.xml file in the
- server/messaging/deploy directory on your target(JBM)
- machine.</para>
-
- <para>Here is an example bridge configuration</para>
-
- <programlisting>
-<mbean code="org.jboss.jms.server.bridge.BridgeService"
- name="jboss.messaging:service=Bridge,name=TestBridge"
- xmbean-dd="xmdesc/Bridge-xmbean.xml">
- <depends optional-attribute-name="SourceProviderLoader">
- jboss.messaging:service=JMSProviderLoader,
- name=MyRemoteJMSProvider</depends>
- <depends optional-attribute-name="TargetProviderLoader">
- jboss.messaging:service=JMSProviderLoader,
- name=JMSProvider</depends>
- <attribute name="SourceDestinationLookup">/queue/testQueue</attribute>
- <attribute name="TargetDestinationLookup">/queue/A</attribute>
- <attribute name="QualityOfServiceMode">0</attribute>
- <attribute name="MaxBatchSize">5</attribute>
- <attribute name="MaxBatchTime">-1</attribute>
- <attribute name="FailureRetryInterval">5000</attribute>
- <attribute name="MaxRetries">-1</attribute>
- <attribute name="AddMessageIDInHeader">false</attribute>
-</mbean>
- </programlisting>
-
- <note>my target is the current JBM JMS Provider and the source is
- the JBossMQ remote provider. If you have a pretty stock system and
- you want to move messages from JBossMQ to JBM, you will not have to
- change this example except for the queue Names. If you wish to move
- from JBM to JBossMQ, just switch the source and target
- definitions.</note>
- </listitem>
- </itemizedlist>
-
- <para>Start the JBossMQ system and then just start the JBM system and
- the messages will begin to move over.</para>
-
- <para>The following is an example of the jms-ds.xml file that was used
- for the test. If you want to test the bridge first and you have a stock
- JBM system(JBM has been installed using the default configuration), then
- you can just copy the jms-ds.xml file over the one in
- server/messaging/deploy and begin to put messages in the JBossMQ system
- under the /queue/TestQueue. The messages will then be moved over to your
- JBM queue /queue/A. Both of these queues exist in the stock versions of
- JBM and JBossMQ.</para>
- </section>
-
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-
-<connection-factories>
-
- <!-- ==================================================================== -->
- <!-- JMS Stuff -->
- <!-- ==================================================================== -->
-
- <!-- The JMS provider loader -->
- <mbean code="org.jboss.jms.jndi.JMSProviderLoader"
- name="jboss.messaging:service=JMSProviderLoader,name=JMSProvider">
- <attribute name="ProviderName">DefaultJMSProvider</attribute>
-
- <attribute name="ProviderAdapterClass">
- org.jboss.jms.jndi.JNDIProviderAdapter
- </attribute>
- <!-- The combined connection factory -->
- <attribute name="FactoryRef">java:/XAConnectionFactory</attribute>
- <!-- The queue connection factory -->
- <attribute name="QueueFactoryRef">java:/XAConnectionFactory</attribute>
- <!-- The topic factory -->
-
- <attribute name="TopicFactoryRef">java:/XAConnectionFactory</attribute>
- <!-- Uncomment to use HAJNDI to access JMS
- <attribute name="Properties">
- java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
- java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
- java.naming.provider.url=localhost:1100
- </attribute>
- -->
- </mbean>
-
-
-<mbean code="org.jboss.jms.jndi.JMSProviderLoader"
- name="jboss.messaging:service=JMSProviderLoader,
- name=MyRemoteJMSProvider">
- <attribute name="ProviderName">RemoteXAConnectionFactory</attribute>
- <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
- <!-- The combined connection factory -->
-
- <attribute name="FactoryRef">XAConnectionFactory</attribute>
- <!-- The queue connection factory -->
- <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
- <!-- The topic factory -->
- <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
- <attribute name="Properties">
- java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
- java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
- java.naming.provider.url=192.168.0.199:1099
- </attribute>
-
-</mbean>
-
-<mbean code="org.jboss.jms.server.bridge.BridgeService"
- name="jboss.messaging:service=Bridge,name=TestBridge"
- xmbean-dd="xmdesc/Bridge-xmbean.xml">
- <depends optional-attribute-name="SourceProviderLoader">
- jboss.messaging:service=JMSProviderLoader,
- name=MyRemoteJMSProvider</depends>
- <depends optional-attribute-name="TargetProviderLoader">
- jboss.messaging:service=JMSProviderLoader,
- name=JMSProvider</depends>
- <attribute name="SourceDestinationLookup">/queue/testQueue</attribute>
- <attribute name="TargetDestinationLookup">/queue/A</attribute>
- <attribute name="QualityOfServiceMode">0</attribute>
-
- <attribute name="MaxBatchSize">5</attribute>
- <attribute name="MaxBatchTime">-1</attribute>
- <attribute name="FailureRetryInterval">5000</attribute>
- <attribute name="MaxRetries">-1</attribute>
- <attribute name="AddMessageIDInHeader">false</attribute>
-</mbean>
-
- <!-- The server session pool for Message Driven Beans -->
- <mbean code="org.jboss.jms.asf.ServerSessionPoolLoader"
- name="jboss.messaging:service=ServerSessionPoolMBean,name=StdJMSPool">
- <depends optional-attribute-name="XidFactory">jboss:service=XidFactory</depends>
- <attribute name="PoolName">StdJMSPool</attribute>
- <attribute name="PoolFactoryClass">
- org.jboss.jms.asf.StdServerSessionPoolFactory
- </attribute>
- </mbean>
-
- <!-- JMS XA Resource adapter, use this to get transacted JMS in beans -->
- <tx-connection-factory>
- <jndi-name>JmsXA</jndi-name>
- <xa-transaction/>
- <rar-name>jms-ra.rar</rar-name>
- <connection-definition>org.jboss.resource.adapter.jms.JmsConnectionFactory
- </connection-definition>
- <config-property name="SessionDefaultType" type="java.lang.String">javax.jms.Topic
- </config-property>
-
- <config-property name="JmsProviderAdapterJNDI" type="java.lang.String">
- java:/DefaultJMSProvider</config-property>
- <max-pool-size>20</max-pool-size>
- <security-domain-and-application>JmsXARealm</security-domain-and-application>
- </tx-connection-factory>
-
-</connection-factories>
-
- </programlisting>
-
- <para>You can also merge topics back and forth from JBM to JBossMQ, by
- setting the subscription name and client id. You can see these arguments
- in the JBM Bridge chapter.</para>
- </section>
-</chapter>
\ No newline at end of file
Modified: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/introduction.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/introduction.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/introduction.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -76,7 +76,7 @@
</listitem>
<listitem>
- <para>Support for most major databases including Oracle, Sybase, MS
+ <para>Support for most major databases including Oracle, DB2, Sybase, MS
SQL Server, PostgreSQL and MySQL</para>
</listitem>
@@ -86,6 +86,10 @@
</listitem>
<listitem>
+ <para>Servlet transport to allow messaging through a dedicated servlet.</para>
+ </listitem>
+
+ <listitem>
<para>SSL transport</para>
</listitem>
@@ -102,6 +106,14 @@
<para>Automatic paging of messages to storage. Allows the use of very
large queues - too large to fit in memory at once</para>
</listitem>
+
+ <listitem>
+ <para>Strict message ordering. JBoss Messaging's implementation of strict message ordering
+ is called message ordering groups. Messages in one ordering group obey strict delivering order, which means
+ that messages in an ordering group will be delivered exactly in the order of their arrival at the target queue (FIFO).
+ Ordering groups can be enabled by either programming APIs or configuration.</para>
+ </listitem>
+
</itemizedlist>
<para>Clustering features:</para>
Added: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/ordering_group.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/ordering_group.xml (rev 0)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/ordering_group.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ordering-group">
+ <title>Enabling JBoss Messaging Ordering Group</title>
+
+ <para>This section describes how to use JBoss Messaging ordering group feature to achieve strict message ordering.
+ </para>
+
+ <para>JBoss Messaging's implementation of strict message ordering is called message ordering groups. Messages in one orddering group obey strict delivering order,
+ which means that messages in an ordering group will be delivered exactly in the order of their arrival at the target queue (FIFO).
+ Ordering groups are identified by their string names.</para>
+
+ <para>When ordering group is enabled, message priorities will not take any effect on the ordering of the messages. Message ordering groups obey the following rules:</para>
+
+ <para>Rule 1. Messages in the ordering group are delivered one at a time. Next message will not be delivered until the delivery of previous message is completed.</para>
+
+ <itemizedlist>
+ <listitem>For CLIENT_ACKNOWLEDGE mode, the Message.acknowledge() method signals the completion state.</listitem>
+ <listitem>For AUTO_ACKNOWLEDGE and DUPS_OK_ACKNOWLEDGE modes, the completion of the message is identified by either
+
+ <para>1) successful returning from the MessageConsumer.receive() methods, or</para>
+ <para>2) successful returning from the onMessage() call of the MessageListener();</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>If the message consumer is closed, the current message processing is deemed to be finished, even if the acknowledge is not called before consumer close.</para>
+
+ <para>Rule 2. In case of transactional receiving, the next message will not be delivered until the transaction that includes the receiving of the previous message has been committed. If the transaction is rolled back, the previous message will be cancelled back to the JMS server and thus available for the next delivery.
+</para>
+
+<section id="enable.ordering.group">
+ <title>How to Enable Message Ordering Group</title>
+
+<para>There are two ways to use message ordering group: through programming and through configuration.</para>
+
+ <itemizedlist>
+<listitem>The Programming Way</listitem>
+ </itemizedlist>
+
+<para>To make use of JBoss Messaging's ordering group feature, one has to obtain a JBossMessageProducer.</para>
+
+ <programlisting>
+ JBossMessageProducer producer = (JBossMessageProducer)session.createProducer(queue);
+ </programlisting>
+
+<para>JBossMessageProducer has two methods for starting/ending an ordering group.</para>
+
+ <programlisting>
+public void enableOrderingGroup(String ogrpName) throws JMSException
+ </programlisting>
+
+<para>Creating a ordering group with name ogrpName. Once called, the producer will send messages on behave of the ordering group. If null parameter is given, the name of the ordering group will be automatically generated. Calling this method more than once will always override the previous calls.</para>
+
+ <programlisting>
+public void disableOrderingGroup() throws JMSException
+ </programlisting>
+
+<para>Stop producing ordering group messages. Once called, the producer will stop sending out ordering group messages and return to its normal behavior.</para>
+
+ <itemizedlist>
+<listitem>The Configuration Way</listitem>
+ </itemizedlist>
+
+<para>Users can configure a JBoss Messaging connection factory to enable ordering group. Two new attributes are added to the factory service configuration file.</para>
+
+ <programlisting>
+EnableOrderingGroup -- set this property to true to enable the ordering group. Default is false; and
+DefaultOrderingGroupName -- the default name for the message ordering group. If absent, the group
+ name will be generated automatically.
+ </programlisting>
+
+<para>Once configured to enable ordering group on a connection factory, all messages that are sent from any producers created from this connection factory become ordering group messages.</para>
+
+<para>Example:</para>
+
+ <programlisting>
+ <mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
+ name="jboss.messaging.connectionfactory:service=ConnectionFactory"
+ xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
+ <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
+ <depends optional-attribute-name="Connector">jboss.messaging:service=Connector,transport=bisocket</depends>
+ <depends>jboss.messaging:service=PostOffice</depends>
+
+ <attribute name="JNDIBindings">
+ <bindings>
+ <binding>/MyConnectionFactory</binding>
+ <binding>/XAConnectionFactory</binding>
+ <binding>java:/MyConnectionFactory</binding>
+ <binding>java:/XAConnectionFactory</binding>
+ </bindings>
+ </attribute>
+
+ <!-- This are the two properties -->
+ <attribute name="EnableOrderingGroup">true</attribute>
+ <attribute name="DefaultOrderingGroupName">MyOrderingGroup</attribute>
+ </mbean>
+ </programlisting>
+
+<para>The good thing about this way is the user doesn't need to make any coding effort to get message ordering functionality.</para>
+
+</section>
+
+<section id="note.ordering.group">
+ <title>Notes and Limitations</title>
+
+ <itemizedlist>
+
+<listitem>Ordering group doesn't work with topics. Users requiring order groups have to user queues.</listitem>
+<listitem>Ordering group shouldn't be used together with message selectors and scheduled delivery.</listitem>
+<listitem>If a message is 'dead' (goes to DLQ) or expired (goes to ExpiryQueue), this message is considered completed and next message will be available for delivery.</listitem>
+<listitem>When using a ConnectionConsumer, ordering of the messages will be observed. However, it doesn't control which session will be receiving the next message.</listitem>
+<listitem>In case of Distributed Queue, user should use HASingleton to make sure ordering group works properly.</listitem>
+ </itemizedlist>
+
+</section>
+
+</chapter>
Modified: projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/runningexamples.xml
===================================================================
--- projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/runningexamples.xml 2009-06-03 21:57:16 UTC (rev 7186)
+++ projects/eap-docs/trunk/JBoss_Messaging_User_Guide/en-US/runningexamples.xml 2009-06-04 02:37:53 UTC (rev 7187)
@@ -103,6 +103,22 @@
message bridge in JBoss AS which then proceeds to move messages from a
source to a target queue</para>
</listitem>
+
+ <listitem>
+ <para>docs/example/servlet</para>
+
+ <para>This example demonstrates how to use servlet transport with JBoss Messaging.
+ It deploys a servlet and a ConnectionFactory that uses the servlet transport.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>docs/example/ordering-group</para>
+
+ <para>This example demonstrates using strict message ordering with JBoss Messaging.
+ It uses JBoss Messaging ordering group API to deliver strictly ordered messages, regardless of
+ their priorities.</para>
+ </listitem>
</itemizedlist></para>
<para>It is highly recommended that you familiarize yourself with the
More information about the jboss-cvs-commits
mailing list