7:33 a.m.
Author: ataylor
Date: 2010-12-16 08:33:25 -0500 (Thu, 16 Dec 2010)
New Revision: 10042
Added:
trunk/docs/eap-manual/
trunk/docs/eap-manual/build.bat
trunk/docs/eap-manual/build.sh
trunk/docs/eap-manual/build.xml
trunk/docs/eap-manual/en/
trunk/docs/eap-manual/en/clusters.xml
trunk/docs/eap-manual/en/master.xml
Log:
added eap manual
Copied: trunk/docs/eap-manual/build.bat (from rev 10039,
trunk/docs/user-manual/build.bat)
===================================================================
--- trunk/docs/eap-manual/build.bat (rev 0)
+++ trunk/docs/eap-manual/build.bat 2010-12-16 13:33:25 UTC (rev 10042)
@@ -0,0 +1,13 @@
+@echo off
+
+set "OVERRIDE_ANT_HOME=..\..\tools\ant"
+
+if exist "..\..\src\bin\build.bat" (
+ rem running from TRUNK
+ call ..\..\src\bin\build.bat %*
+) else (
+ rem running from the distro
+ call ..\..\bin\build.bat %*
+)
+
+set "OVERRIDE_ANT_HOME="
Copied: trunk/docs/eap-manual/build.sh (from rev 10039, trunk/docs/user-manual/build.sh)
===================================================================
--- trunk/docs/eap-manual/build.sh (rev 0)
+++ trunk/docs/eap-manual/build.sh 2010-12-16 13:33:25 UTC (rev 10042)
@@ -0,0 +1,15 @@
+#!/bin/sh
+
+OVERRIDE_ANT_HOME=../../tools/ant
+export OVERRIDE_ANT_HOME
+
+if [ -f "../../src/bin/build.sh" ]; then
+ # running from TRUNK
+ ../../src/bin/build.sh "$@"
+else
+ # running from the distro
+ ../../bin/build.sh "$@"
+fi
+
+
+
Copied: trunk/docs/eap-manual/build.xml (from rev 10039,
trunk/docs/user-manual/build.xml)
===================================================================
--- trunk/docs/eap-manual/build.xml (rev 0)
+++ trunk/docs/eap-manual/build.xml 2010-12-16 13:33:25 UTC (rev 10042)
@@ -0,0 +1,30 @@
+<!--
+ ~ 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.
+ -->
+
+<project name="HornetQ User Manual" default="all"
basedir=".">
+
+ <property name="build.dir" value="build"/>
+ <property name="pdf.name" value="HornetQ_EAPManual.pdf"/>
+ <import file="${basedir}/../../lib/docbook-support/support.xml"/>
+
+ <target name="all" depends="clean">
+ <mkdir dir="en/images" />
+ <antcall target="lang.all"><param name="lang"
value="en"/></antcall>
+ </target>
+
+ <target name="html.doc" description="creates the html docs only and
opens a browser">
+ <mkdir dir="en/images" />
+ <antcall target="lang.dochtml"><param name="lang"
value="en"/></antcall>
+ </target>
+
+</project>
Copied: trunk/docs/eap-manual/en/clusters.xml (from rev 10039,
trunk/docs/quickstart-guide/en/about.xml)
===================================================================
--- trunk/docs/eap-manual/en/clusters.xml (rev 0)
+++ trunk/docs/eap-manual/en/clusters.xml 2010-12-16 13:33:25 UTC (rev 10042)
@@ -0,0 +1,382 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ ~ 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.
+ -->
+
+<chapter id="clusters">
+ <title>HornetQ and EAP Cluster Configuration</title>
+ <section>
+ <title>Configuring Failover</title>
+ <para>
+ This chapter explains how to configure HornetQ within EAP with live
backup-groups. Currently in this version
+ HornetQ only supports shared store for backup nodes so we assume that in the
rest of this chapter.
+ </para>
+ <para>There are 2 main ways to configure HornetQ servers to have a backup
server:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Colocated. This is when an EAP instance has both a live and
backup(s) running.</para>
+ </listitem>
+ <listitem>
+ <para>Dedicated. This is when an EAP instance has either a live or
backup running but never both.</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Colocated Live and Backup in Symmetrical cluster</title>
+ <para>
+ The colocated symmetrical topology will be the most widely used topology,
this is where an EAP instance has
+ a
+ live
+ node running plus 1 or
+ more backup nodes. Each backup node will belong to a live node on another EAP
instance. In a simple cluster
+ of
+ 2
+ EAP instances this would mean that each EAP instance would have a live server
and 1 backup server as in
+ diagram1.
+ </para>
+ <para>todo add image</para>
+ <para>
+ With more thn 2 servers it is up to the user as to how many backups per live
server are configured, you can
+ have
+ as many backups as required but usually 1 would suffice. In 3 node topology
you may have each EAP instance
+ configured
+ with 2 backups, 1 for each of the other live servers, or you may just want to
have 1 backup for each live.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ First lets start with the configuration of the live server, we will use
the EAP 'all' configuration as
+ our
+ starting
+ point. Since this version only supports shared store for failover we need
to configure this in the
+ <literal>hornetq-configuration.xml</literal>
+ file like so:
+ </para>
+ <programlisting>
+ <shared-store>true</shared-store>
+ </programlisting>
+ <para>
+ Obviously this means that the location of the journal files etc will have
to be configured to be some
+ where
+ where
+ this lives backup can access. You may change the lives configuration in
+ <literal>hornetq-configuration.xml</literal>
+ to
+ something like:
+ </para>
+ <programlisting>
+
<large-messages-directory>/media/shared/data/large-messages</large-messages-directory>
+
<bindings-directory>/media/shared/data/bindings</bindings-directory>
+
<journal-directory>/media/shared/data/journal</journal-directory>
+
<paging-directory>/media/shared/data/paging</paging-directory>
+ </programlisting>
+ <para>
+ How these paths are configured will of course depend on your network
settings or file system.
+ </para>
+ <para>
+ Now we need to configure how remote JMS clients wull behave if the server
is shutdown in a normal
+ fashion.
+ By
+ default
+ Clients will not failover if the live server is shutdown. Depending on
there connection factory settings
+ they will either fail or try to reconnect to the live server.
+ </para>
+ <para>If you want clients to failover on a normal server shutdown the
you must configure the
+ <literal>failover-on-shutdown</literal>
+ flag to true in the
+ <literal>hornetq-configuration.xml</literal>
+ file like so:
+ </para>
+ <programlisting>
+ <failover-on-shutdown>false</failover-on-shutdown>
+ </programlisting>
+ <para>Don't worry if you have this set to false (which is the
default) but still want failover to occur,
+ simply
+ kill
+ the
+ server process directly or call
+ <literal>forceFailover</literal>
+ via jmx or the admin console on the core server object.
+ </para>
+ <para>
+ No lets look at how to create and configure a backup server on the same
node, lets assume that this
+ backups
+ live
+ server is configured identically to the live server on this node for
simplicities sake.
+ </para>
+ <para>
+ Firstly we need to define a new HornetQ Server that EAP will deploy. We do
this by creating a new
+ <literal>hornetq-jboss-beans.xml</literal>
+ configuration. We will place this under a new directory
+ <literal>hornetq-backup1</literal>
+ which will need creating
+ in the
+ <literal>deploy</literal>
+ directory but in reality it doesn't matter where this is put. This
will look like:
+ </para>
+ <programlisting>
+ <?xml version="1.0" encoding="UTF-8"?>
+
+ <deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- The core configuration -->
+ <bean name="BackupConfiguration"
class="org.hornetq.core.config.impl.FileConfiguration">
+ <property
+
name="configurationUrl">${jboss.server.home.url}/deploy/hornetq-backup1/hornetq-configuration.xml</property>
+ </bean>
+
+
+ <!-- The core server -->
+ <bean name="BackupHornetQServer"
class="org.hornetq.core.server.impl.HornetQServerImpl">
+ <constructor>
+ <parameter>
+ <inject bean="BackupConfiguration"/>
+ </parameter>
+ <parameter>
+ <inject bean="MBeanServer"/>
+ </parameter>
+ <parameter>
+ <inject bean="HornetQSecurityManager"/>
+ </parameter>
+ </constructor>
+ <start ignored="true"/>
+ <stop ignored="true"/>
+ </bean>
+
+ <!-- The JMS server -->
+ <bean name="BackupJMSServerManager"
class="org.hornetq.jms.server.impl.JMSServerManagerImpl">
+ <constructor>
+ <parameter>
+ <inject bean="BackupHornetQServer"/>
+ </parameter>
+ </constructor>
+ </bean>
+
+ </deployment>
+ </programlisting>
+ <para>
+ The first thing to notice is the BackupConfiguration bean. This is
configured to pick up the
+ configuration
+ for
+ the
+ server which we will place in the same directory.
+ </para>
+ <para>
+ After that we just configure a new HornetQ Server and JMS server.
+ </para>
+ <note>
+ <para>
+ Notice that the names of the beans have been changed from that of the
live servers configuration. This
+ is
+ so
+ there is no clash. Obviously if you add more backup servers you will
need to rename those as well,
+ backup1,
+ backup2 etc.
+ </para>
+ </note>
+ <para>
+ Now lets add the server configuration in
+ <literal>hornetq-configuration.xml</literal>
+ and add it to the same directory
+ <literal>deploy/hornetq-backup1</literal>
+ and configure it like so:
+ </para>
+ <programlisting>
+ <configuration xmlns="urn:hornetq"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:hornetq /schema/hornetq-configuration.xsd">
+
+ <jmx-domain>org.hornetq.backup1</jmx-domain>
+
+ <clustered>true</clustered>
+
+ <shared-store>true</shared-store>
+
+ <allow-failback>true</allow-failback>
+
+
<log-delegate-factory-class-name>org.hornetq.integration.logging.Log4jLogDelegateFactory</log-delegate-factory-class-name>
+
+
<bindings-directory>${jboss.server.data.dir}/hornetq-backup/bindings</bindings-directory>
+
+
<journal-directory>${jboss.server.data.dir}/hornetq-backup/journal</journal-directory>
+
+ <journal-min-files>10</journal-min-files>
+
+
<large-messages-directory>${jboss.server.data.dir}/hornetq-backup/largemessages</large-messages-directory>
+
+
<paging-directory>${jboss.server.data.dir}/hornetq/paging</paging-directory>
+
+ <connectors>
+ <connector name="netty-connector">
+
<factory-class>org.hornetq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
+ <param key="host"
value="${jboss.bind.address:localhost}"/>
+ <param key="port"
value="${hornetq.remoting.netty.port:5446}"/>
+ </connector>
+
+ <!--The connetor to the live node that corresponds to this
backup-->
+ <connector name="my-live-connector">
+
<factory-class>org.hornetq.core.remoting.impl.netty.NettyConnectorFactory</factory-class>
+ <param key="host" value="my-live-host"/>
+ <param key="port"
value="${hornetq.remoting.netty.port:5445}"/>
+ </connector>
+
+ <!--invm connector added by th elive server on this node, used by the
bridges-->
+ <connector name="in-vm">
+
<factory-class>org.hornetq.core.remoting.impl.invm.InVMConnectorFactory</factory-class>
+ <param key="server-id"
value="${hornetq.server-id:0}"/>
+ </connector>
+
+ </connectors>
+
+ <acceptors>
+ <acceptor name="netty">
+
<factory-class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</factory-class>
+ <param key="host"
value="${jboss.bind.address:localhost}"/>
+ <param key="port"
value="${hornetq.remoting.netty.port:5446}"/>
+ </acceptor>
+ </acceptors>
+
+ <broadcast-groups>
+ <broadcast-group name="bg-group1">
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <broadcast-period>1000</broadcast-period>
+ <connector-ref>netty-connector</connector-ref>
+ </broadcast-group>
+ </broadcast-groups>
+
+ <discovery-groups>
+ <discovery-group name="dg-group1">
+ <group-address>231.7.7.7</group-address>
+ <group-port>9876</group-port>
+ <refresh-timeout>60000</refresh-timeout>
+ </discovery-group>
+ </discovery-groups>
+
+ <cluster-connections>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <connector-ref>netty-connector</connector-ref>
+ <discovery-group-ref discovery-group-name="dg-group1"/>
+ </cluster-connection>
+ </cluster-connections>
+
+ <!-- We need to create a core queue for the JMS queue explicitly because
the bridge will be deployed
+ before the JMS queue is deployed, so the first time, it otherwise won't find
the queue -->
+ <queues>
+ <queue name="jms.queue.testQueue">
+ <address>jms.queue.testQueue</address>
+ </queue>
+ </queues>
+ <!-- We set-up a bridge that forwards from a the queue on this node to
the same address on the live
+ node.
+ -->
+ <bridges>
+ <bridge name="testQueueBridge">
+ <queue-name>jms.queue.testQueue</queue-name>
+
<forwarding-address>jms.queue.testQueue</forwarding-address>
+ <reconnect-attempts>-1</reconnect-attempts>
+ <static-connectors>
+ <connector-ref>in-vm</connector-ref>
+ </static-connectors>
+ </bridge>
+ </bridges>
+
+ <security-settings>
+ <security-setting match="#">
+ <permission type="createNonDurableQueue"
roles="guest"/>
+ <permission type="deleteNonDurableQueue"
roles="guest"/>
+ <permission type="consume" roles="guest"/>
+ <permission type="send" roles="guest"/>
+ </security-setting>
+ </security-settings>
+
+ <address-settings>
+ <!--default for catch all-->
+ <address-setting match="#">
+
<dead-letter-address>jms.queue.DLQ</dead-letter-address>
+
<expiry-address>jms.queue.ExpiryQueue</expiry-address>
+ <redelivery-delay>0</redelivery-delay>
+ <max-size-bytes>10485760</max-size-bytes>
+
<message-counter-history-day-limit>10</message-counter-history-day-limit>
+ <address-full-policy>BLOCK</address-full-policy>
+ </address-setting>
+ </address-settings>
+
+ </configuration>
+
+ </programlisting>
+ <para>
+ The first thing you can see is we have added a
<literal>jmx-domain</literal> attribute, this is used when
+ adding objects, such as the HornetQ server and JMS server to jmx, we
change this from the default <literal>org.hornetq</literal>
+ to avoid naming clashes with the live server
+ </para>
+ <para>
+ After that we have the same cluster configuration as live, that is
<literal>clustered</literal> is true and
+ <literal>shared-store</literal> is true. However you can see
we have added a new configuration element
+ <literal>allow-failback</literal>. When this is set to true
then this backup server will automatically stop
+ and fall back into backup node if failover occurs and the live server has
become available. If false then
+ the user will have to stop the server manually.
+ </para>
+ <para>
+ Next we can see the configuration for the journal location, as in the live
configuration this must point to
+ the same directory as this backup's live server.
+ </para>
+ <para>
+ Now we see the connectors configuration, we have 3 defined which are
needed for the following
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>netty-connector.</literal> This is the
connector used to connect to this backup server once live.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>my-live-connector.</literal> This is the
connector to the live server that this backup is paied to.
+ It is used by the cluster connection to announce its presence as a
backup and to form the cluster when
+ this backup becomes live. In reality it doesn't matter what
connector the cluster connection uses, it
+ could actually use the invm connector and broadcast its presence via
the server on this node if we wanted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>in-vm.</literal> This is the invm connector
that is created by the live server on the same
+ node. We will use this to create a bridge to the live server to
forward messages to.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>After that you will see the acceptors defined, This is the
acceptor where clients will reconnect.</para>
+ <para>
+ The Broadcast groups, Discovery group and cluster configurations are as
per normal, details of these
+ can be found in the HornetQ user manual.
+ </para>
+ <para>
+ The next part is of interest, here we define a list of queues and bridges.
These must match any queues
+ and addresses used by MDB's in the live servers configuration. At this
point these must be statically
+ defined but this may change in future versions. Basically fow every queue
or topic definition you need a
+ queue configuration using the correct prefix
<literal>jms.queue(topic)</literal> if using jm and a bridge
+ definition that handles the forwarding of any message.
+ </para>
+ <note>
+ <para>
+ There is no such thing as a topic in core HornetQ, this is basically
just an address so we need to create
+ a queue that matches the jms address, that is,
<literal>jms.topic.testTopic</literal>.
+ </para>
+ </note>
+ </section>
+ </section>
+ <section>
+ <title>Dedicated Live and Backup in Symmetrical cluster</title>
+ </section>
+ </section>
+</chapter>
\ No newline at end of file
Copied: trunk/docs/eap-manual/en/master.xml (from rev 10039,
trunk/docs/quickstart-guide/en/master.xml)
===================================================================
--- trunk/docs/eap-manual/en/master.xml (rev 0)
+++ trunk/docs/eap-manual/en/master.xml 2010-12-16 13:33:25 UTC (rev 10042)
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ ~ 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.
+ -->
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+ "../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd" [
+ <!ENTITY clusters SYSTEM "clusters.xml">
+ ]>
+<book lang="en">
+ <bookinfo>
+ <title>HornetQ EAP Guide</title>
+ <subtitle>Putting the buzz in messaging</subtitle>
+ </bookinfo>
+
+ <toc></toc>
+
+ &clusters;
+</book>