[hornetq-commits] JBoss hornetq SVN: r10036 - trunk/docs/user-manual/en.
do-not-reply at jboss.org
do-not-reply at jboss.org
Sat Dec 11 05:45:01 EST 2010
Author: ataylor
Date: 2010-12-11 05:45:00 -0500 (Sat, 11 Dec 2010)
New Revision: 10036
Modified:
trunk/docs/user-manual/en/clusters.xml
Log:
updates to HA chapter in docs
Modified: trunk/docs/user-manual/en/clusters.xml
===================================================================
--- trunk/docs/user-manual/en/clusters.xml 2010-12-10 23:23:05 UTC (rev 10035)
+++ trunk/docs/user-manual/en/clusters.xml 2010-12-11 10:45:00 UTC (rev 10036)
@@ -310,9 +310,73 @@
there connection details will be propagated via the server it connects to</para>
<section>
<title>Configuring a Cluster Connection</title>
+ <para>For cluster connections there is no extra configuration needed, you just need to make sure that any
+ connectors are defined in the usual manner, (see <xref linkend="configuring-transports"/> for more
+ information on connectors). These are then referenced by the cluster connection configuration.</para>
</section>
<section>
<title>Configuring a Client Connection</title>
+ <para>A static list of possible servers can also be used by a normal client.</para>
+ <section>
+ <title>Configuring client discovery using JMS</title>
+ <para>If you're using JMS and you're also using the JMS Service on the server to
+ load your JMS connection factory instances into JNDI, then you can specify which
+ connectors to use for your JMS connection factory in the server side xml
+ configuration <literal>hornetq-jms.xml</literal>. Let's take a look at an
+ example:</para>
+ <programlisting>
+ <connection-factory name="ConnectionFactory">
+ <connectors>
+ <connector-ref connector-name="netty-connector"/>
+ <connector-ref connector-name="netty-connector2"/>
+ <connector-ref connector-name="netty-connector3"/>
+ </connectors>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ </connection-factory></programlisting>
+ <para>
+ The element <literal>connectors</literal> contains a list of pre defined connectors in the
+ <literal>hornetq-configuration.xml</literal> file. When this connection factory is downloaded
+ from JNDI by a client application and JMS connections are created from it, those connections will
+ be load-balanced across the list of servers defined by these connectors.
+ </para>
+ <para>
+ If you're using JMS, but you're not using JNDI to lookup a connection factory - you're instantiating
+ the JMS connection factory directly then you can specify the connector list directly when creating
+ the JMS connection factory. Here's an example:
+ </para>
+ <programlisting>
+ HashMap<String, Object> map = new HashMap<String, Object>();
+ map.put("host", "myhost");
+ map.put("port", "5445");
+ TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
+ HashMap<String, Object> map2 = new HashMap<String, Object>();
+ map2.put("host", "myhost2");
+ map2.put("port", "5446");
+ TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
+
+ HornetQConnectionFactory cf = HornetQJMSClient.createConnectionFactoryWithHA(JMSFactoryType.CF, server1, server2);
+ </programlisting>
+ </section>
+ <section>
+ <title>Configuring client discovery using JMS</title>
+ <para>If you are using the core API then the same can be done as follows:</para>
+ <programlisting>
+ HashMap<String, Object> map = new HashMap<String, Object>();
+ map.put("host", "myhost");
+ map.put("port", "5445");
+ TransportConfiguration server1 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map);
+ HashMap<String, Object> map2 = new HashMap<String, Object>();
+ map2.put("host", "myhost2");
+ map2.put("port", "5446");
+ TransportConfiguration server2 = new TransportConfiguration(NettyConnectorFactory.class.getName(), map2);
+
+ ServerLocator locator = HornetQClient.createServerLocatorWithHA(server1, server2);
+ ClientSessionFactory factory = locator.createSessionFactory();
+ ClientSession session = factory.createSession();
+ </programlisting>
+ </section>
</section>
</section>
</section>
@@ -452,6 +516,29 @@
that this cluster connection will make connections to.</para>
</listitem>
</itemizedlist>
+ <para>
+ Alternatively if you would like your cluster connections to use a static list of
+ servers for discovery then you can do it like this.
+ </para>
+ <programlisting>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <connector-ref>netty-connector</connector-ref>
+ <retry-interval>500</retry-interval>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>true</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <static-connectors>
+ <connector-ref>server0-connector</connector-ref>
+ <connector-ref>server1-connector</connector-ref>
+ </static-connectors>
+ </cluster-connection>
+ </programlisting>
+ <para>
+ Here we have defined 2 servers that we know for sure will that at least one will be available. There may
+ be many more servers in the cluster but these will; be discovered via one of these connectors once an
+ initial connection has been made.
+ </para>
</section>
<section id="clusters.clusteruser">
<title>Cluster User Credentials</title>
@@ -538,138 +625,30 @@
</section>
<section>
<title>Specifying Members of a Cluster Explicitly</title>
- <para>Sometimes UDP is not enabled on a network so it's not possible to use UDP server
- discovery for clients to discover the list of servers in the cluster, or for servers to
- discover what other servers are in the cluster.</para>
- <para>In this case, the list of servers in the cluster can be specified explicitly on each
- node and on the client side. Let's look at how we do this:</para>
- <section>
- <title>Specify List of Servers on the Client Side</title>
- <para>This differs depending on whether you're using JMS or the Core API</para>
- <section>
- <title>Specifying List of Servers using JMS</title>
- <para>If you're using JMS, and you're using the JMS Service to load your JMS
- connection factory instances directly into JNDI on the server, then you can
- specify the list of servers in the server side configuration file <literal
- >hornetq-jms.xml</literal>. Let's take a look at an example:</para>
- <programlisting><connection-factory name="ConnectionFactory">
- <connectors>
- <connector-ref connector-name="my-connector1"
- backup-connector-name="my-backup-connector1"/>
- <connector-ref connector-name="my-connector2"
- backup-connector-name="my-backup-connector2"/>
- <connector-ref connector-name="my-connector3"
- backup-connector-name="my-backup-connector3"/>
- </connectors>
- <entries>
- <entry name="ConnectionFactory"/>
- </entries>
-</connection-factory></programlisting>
- <para>The <literal>connection-factory</literal> element can contain zero or more
- <literal>connector-ref</literal> elements, each one of which specifies a
- <literal>connector-name</literal> attribute and an optional <literal
- >backup-connector-name</literal> attribute. The <literal
- >connector-name</literal> attribute references a connector defined in
- <literal>hornetq-configuration.xml</literal> which will be used as a live
- connector. The <literal>backup-connector-name</literal> is optional, and if
- specified it also references a connector defined in <literal
- >hornetq-configuration.xml</literal>. For more information on connectors
- please see <xref linkend="configuring-transports"/>.</para>
- <para>The connection factory thus maintains a list of [connector, backup connector]
- pairs, these pairs are then used by the client connection load balancing policy
- on the client side when creating connections to the cluster.</para>
- <para>If you're using JMS but you're not using JNDI then you can also specify the
- list of [connector, backup connector] pairs directly when instantiating the
- <literal>HornetQConnectionFactory</literal>, here's an
- example:<programlisting>List<Pair<TransportConfiguration, TransportConfiguration>> serverList =
- new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
-
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC0, backupTC0));
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC1, backupTC1));
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC2, backupTC2));
-
-ConnectionFactory jmsConnectionFactory = HornetQJMSClient.createConnectionFactory(serverList);
-
-Connection jmsConnection1 = jmsConnectionFactory.createConnection();
-
-Connection jmsConnection2 = jmsConnectionFactory.createConnection();</programlisting></para>
- <para>In the above snippet we create a list of pairs of <literal
- >TransportConfiguration</literal> objects. Each <literal
- >TransportConfiguration</literal> object contains knowledge of how to make a
- connection to a specific server.</para>
- <para>A <literal>HornetQConnectionFactory</literal> instance is then created passing
- the list of servers in the constructor. Any connections subsequently created by
- this factory will create connections according to the client connection load
- balancing policy applied to that list of servers.</para>
- </section>
- <section>
- <title>Specifying List of Servers using the Core API</title>
- <para>If you're using the core API you can also specify the list of servers directly
- when creating the <literal>ClientSessionFactory</literal> instance. Here's an
- example:</para>
- <programlisting>List<Pair<TransportConfiguration, TransportConfiguration>> serverList =
- new ArrayList<Pair<TransportConfiguration, TransportConfiguration>>();
-
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC0, backupTC0));
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC1, backupTC1));
-serverList.add(new Pair<TransportConfiguration,
- TransportConfiguration>(liveTC2, backupTC2));
-
-ClientSessionFactory factory = HornetQClient.createClientSessionFactory(serverList);
-
-ClientSession sesison1 = factory.createClientSession(...);
-
-ClientSession session2 = factory.createClientSession(...);</programlisting>
- <para>In the above snippet we create a list of pairs of <literal
- >TransportConfiguration</literal> objects. Each <literal
- >TransportConfiguration</literal> object contains knowledge of how to make a
- connection to a specific server. For more information on this, please see <xref
- linkend="configuring-transports"/>.</para>
- <para>A <literal>ClientSessionFactoryImpl</literal> instance is then created passing
- the list of servers in the constructor. Any sessions subsequently created by
- this factory will create sessions according to the client connection load
- balancing policy applied to that list of servers.</para>
- </section>
- </section>
- <section id="clusters.static.servers">
- <title>Specifying List of Servers to form a Cluster</title>
- <para>Let's take a look at an example where each cluster connection is defined for a
- symmetric cluster, but we're not using discovery for each node to discover its
- neighbours, instead we'll configure each cluster connection to have explicit
- knowledge of all the other nodes in the cluster.</para>
- <para>Here's an example cluster connection definition showing that:</para>
- <programlisting><cluster-connections>
- <cluster-connection name="my-explicit-cluster">
- <address>jms</address>
- <connector-ref connector-name="my-connector1"
- backup-connector-name="my-backup-connector1"/>
- <connector-ref connector-name="my-connector2"
- backup-connector-name="my-backup-connector2"/>
- <connector-ref connector-name="my-connector3"
- backup-connector-name="my-backup-connector3"/>
- </cluster-connection>
-</cluster-connections></programlisting>
- <para>The <literal>cluster-connection</literal> element can contain zero or more
- <literal>connector-ref</literal> elements, each one of which specifies a
- <literal>connector-name</literal> attribute and an optional <literal
- >backup-connector-name</literal> attribute. The <literal
- >connector-name</literal> attribute references a connector defined in <literal
- >hornetq-configuration.xml</literal> which will be used as a live connector. The
- <literal>backup-connector-name</literal> is optional, and if specified it also
- references a connector defined in <literal>hornetq-configuration.xml</literal>. For
- more information on connectors please see <xref linkend="configuring-transports"
- />.</para>
- <note>
- <para>Due to a limitation in HornetQ 2.0.0, failover is not supported for clusters
- defined using a static set of nodes. To support failover over cluster nodes,
- they must be configured to use a discovery group.</para>
- </note>
- </section>
+ <para>
+ Sometimes you want to explicitly define a cluster more explicitly, that is control which
+ server connect to each other in the cluster. This is typically used to form non symmetrical clusters
+ such as chain cluster or ring clusters. This can only be done using a static list of connectors and is
+ configured as follows:
+ </para>
+ <programlisting>
+ <cluster-connection name="my-cluster">
+ <address>jms</address>
+ <connector-ref>netty-connector</connector-ref>
+ <retry-interval>500</retry-interval>
+ <use-duplicate-detection>true</use-duplicate-detection>
+ <forward-when-no-consumers>true</forward-when-no-consumers>
+ <max-hops>1</max-hops>
+ <static-connectors allow-direct-connections-only="true">
+ <connector-ref>server1-connector</connector-ref>
+ </static-connectors>
+ </cluster-connection>
+ </programlisting>
+ <para>
+ In this example we have set the attribute <literal>allow-direct-connections-only</literal> which means that
+ the only server that this server can create a cluster connection to is server1-connector. This means you can
+ explicitly create any cluster topology you want.
+ </para>
</section>
<section id="clusters.message-redistribution">
<title>Message Redistribution</title>
More information about the hornetq-commits
mailing list