[hornetq-commits] JBoss hornetq SVN: r7874 - in trunk/docs/user-manual/en: diagrams and 1 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Aug 21 12:59:00 EDT 2009
Author: timfox
Date: 2009-08-21 12:59:00 -0400 (Fri, 21 Aug 2009)
New Revision: 7874
Modified:
trunk/docs/user-manual/en/appserver-integration.xml
trunk/docs/user-manual/en/architecture.xml
trunk/docs/user-manual/en/client-classpath.xml
trunk/docs/user-manual/en/command-buffering.xml
trunk/docs/user-manual/en/configuration-index.xml
trunk/docs/user-manual/en/configuring-transports.xml
trunk/docs/user-manual/en/connection-ttl.xml
trunk/docs/user-manual/en/core-bridges.xml
trunk/docs/user-manual/en/diagrams/architecture-diagrams.odg
trunk/docs/user-manual/en/embedding-hornetq.xml
trunk/docs/user-manual/en/examples.xml
trunk/docs/user-manual/en/flow-control.xml
trunk/docs/user-manual/en/ha.xml
trunk/docs/user-manual/en/images/architecture1.jpg
trunk/docs/user-manual/en/images/architecture2.jpg
trunk/docs/user-manual/en/images/architecture3.jpg
trunk/docs/user-manual/en/interoperability.xml
trunk/docs/user-manual/en/jms-core-mapping.xml
trunk/docs/user-manual/en/large-messages.xml
trunk/docs/user-manual/en/libaio.xml
trunk/docs/user-manual/en/logging.xml
trunk/docs/user-manual/en/management.xml
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/message-expiry.xml
trunk/docs/user-manual/en/messaging-concepts.xml
trunk/docs/user-manual/en/notice.xml
trunk/docs/user-manual/en/paging.xml
trunk/docs/user-manual/en/perf-tuning.xml
trunk/docs/user-manual/en/persistence.xml
trunk/docs/user-manual/en/preface.xml
trunk/docs/user-manual/en/project-info.xml
trunk/docs/user-manual/en/queue-attributes.xml
trunk/docs/user-manual/en/security.xml
trunk/docs/user-manual/en/send-guarantees.xml
trunk/docs/user-manual/en/thread-pooling.xml
trunk/docs/user-manual/en/transaction-config.xml
trunk/docs/user-manual/en/undelivered-messages.xml
trunk/docs/user-manual/en/using-core.xml
trunk/docs/user-manual/en/using-jms.xml
trunk/docs/user-manual/en/using-server.xml
Log:
proof read and small changes to docs
Modified: trunk/docs/user-manual/en/appserver-integration.xml
===================================================================
--- trunk/docs/user-manual/en/appserver-integration.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/appserver-integration.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,28 +16,25 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="appserver-integration">
<title>Application Server Integration and Java EE</title>
- <para>HornetQ can be easily installed in JBoss Application Server 5.1 or later. For
- details on installing HornetQ in the JBoss Application Server refer to quick-start
- guide.</para>
- <para>Since HornetQ also provides a JCA adaptor, it should also be possible to integrate
- HornetQ as a JMS provider in other JEE compliant app servers. For instructions on
- how to integrate a remote JCA adaptor into another application sever, please consult that
- application server's instructions.</para>
- <para>A JCA Adapter basically controls the incoming of messages to Message Driven Beans and the
- outgoing of messages from other JEE components.</para>
+ <para>HornetQ can be easily installed in JBoss Application Server 5.1 or later. For details on
+ installing HornetQ in the JBoss Application Server please refer to quick-start guide.</para>
+ <para>Since HornetQ also provides a JCA adaptor, it should also be possible to integrate HornetQ
+ as a JMS provider in other JEE compliant app servers. For instructions on how to integrate a
+ remote JCA adaptor into another application sever, please consult that application server's
+ instructions.</para>
+ <para>A JCA Adapter basically controls the inflow of messages to Message Driven Beans and the
+ outflow of messages sent from other JEE components, e.g. EJBs and Servlets.</para>
<para>This section explains the basics behind configuring the different JEE components in the
AS.</para>
<section>
<title>Configuring Message Driven Beans</title>
- <para>The delivery of messages to an MDB using HornetQ is configured on the JCA
- Adapter via a configuration file <literal>ra.xml</literal> which can be found under in
- the <literal>jms-ra.rar</literal> archive of directory. By default this is configured to
- consume messages using an InVM connector from the instance of HornetQ running
- within the application server. A full list of what is configurable is found later in
- this chapter. </para>
+ <para>The delivery of messages to an MDB using HornetQ is configured on the JCA Adapter via
+ a configuration file <literal>ra.xml</literal> which can be found under in the <literal
+ >jms-ra.rar</literal> archive of directory. By default this is configured to consume
+ messages using an InVM connector from the instance of HornetQ running within the
+ application server. A full list of what is configurable is found later in this chapter. </para>
<para>All MDB's however need to have the destination type and the destination configured.
The following example shows how this can be done via annotations.</para>
<programlisting>@MessageDriven(name = "MDBExample",
@@ -56,11 +52,11 @@
preconfigured in the usual way using the HornetQ configuration files.</para>
<section>
<title>Using Container Managed Transactions</title>
- <para>When an MDB is using Container Managed Transactions, the delivery of the message
- is done within the scope of an XA transaction. The commit or rollback of this
- transaction is controlled by the container itself. If the transaction is rolled back
- then the message delivery semantics will kick in (by default this is to try
- and redeliver the message up to 10 times before sending to a DLQ). Using annotations
+ <para>When an MDB is using Container Managed Transactions (CMT), the delivery of the
+ message is done within the scope of a JTA transaction. The commit or rollback of
+ this transaction is controlled by the container itself. If the transaction is rolled
+ back then the message delivery semantics will kick in (by default this is to try and
+ redeliver the message up to 10 times before sending to a DLQ). Using annotations
this would be configured as follows:</para>
<programlisting>@MessageDriven(name = "MDB_CMP_TxRequiredExample",
activationConfig =
@@ -76,10 +72,10 @@
}</programlisting>
<para>The <literal>TransactionManagement</literal> annotation tells the container to
treat this MDB to use Container Managed Persistence. The <literal
- >TransactionAttribute</literal> annotation tells the container that an XA
+ >TransactionAttribute</literal> annotation tells the container that a JTA
transaction is required for this MDB. Note that the only other valid value for this
is <literal>TransactionAttributeType.NOT_SUPPORTED</literal> which tells the
- container that this MDB does not support XA transactions and one should not be
+ container that this MDB does not support JTA transactions and one should not be
created.</para>
<para>It is also possible to inform the container that it must rollback the transaction
by calling <literal>setRollbackOnly</literal> on the <literal
@@ -119,8 +115,9 @@
</section>
<section>
<title>Using Bean Managed Transactions</title>
- <para>Message driven beans can also be configured to use Bean Managed Transactions. In
- this case a User Transaction is created. This would be configured as follows:</para>
+ <para>Message driven beans can also be configured to use Bean Managed Transactions
+ (BMT). In this case a User Transaction is created. This would be configured as
+ follows:</para>
<programlisting>@MessageDriven(name = "MDB_BMPExample",
activationConfig =
{
@@ -133,10 +130,10 @@
{
public void onMessage(Message message)
}</programlisting>
- <para>When using Bean Managed transactions the message will be acknowledged outside the
- scope of the user transaction and use the acknowledge mode specified by the user
- with the <literal>acknowledgeMode</literal> property. There are only 2 acceptable
- values for this <literal>Auto-acknowledge</literal> and <literal
+ <para>When using Bean Managed Transactions the message delivery to the MBD will occur
+ outside the scope of the user transaction and use the acknowledge mode specified by
+ the user with the <literal>acknowledgeMode</literal> property. There are only 2
+ acceptable values for this <literal>Auto-acknowledge</literal> and <literal
>Dups-ok-acknowledge</literal>.Not that because the message delivery is outside
the scope of the transaction a failure within the MDB will not cause the message to
be redelivered.</para>
@@ -190,11 +187,12 @@
<title>Sending Messages from within JEE components</title>
<para>The JCA adapter can also be used for sending messages. The Connection Factory to use
is configured by default in the <literal>jms-ds.xml</literal> file and is mapped to
- <literal>java:/JmsXA</literal>. Using this from within a J2EE component will mean
- that the sending of the message will be done as part of the XA transaction being used by
- the component. This means that if the sending of the message fails the overall
- transaction would rollback and the message redelivered. Heres an example of this from
- within an MDB:</para>
+ <literal>java:/JmsXA</literal>. Using this from within a JEE component will mean
+ that the sending of the message will be done as part of the JTA transaction being used
+ by the component.</para>
+ <para>This means that if the sending of the message fails the overall transaction would
+ rollback and the message redelivered. Heres an example of this from within an
+ MDB:</para>
<programlisting>@MessageDriven(name = "MDBMessageSendTxExample",
activationConfig =
{
@@ -251,14 +249,17 @@
}
}
}
-}</programlisting>
+ }</programlisting>
+ <para>In JBoss Application Server you can use the JMS JCA adapter for sending messages from
+ EJBs (including Session, Entity and Message Driven Beans), Servlets (including jsps) and
+ custom MBeans.</para>
</section>
<section>
<title>Configuring the JCA Adaptor</title>
- <para>The Java Connector Architecture (JCA) Adapter is what allows HornetQ to be integrated with
- JEE components such as MDB's and EJB's. It configures how components such as MDB's
- consume messages from the HornetQ server and also how components such as EJB's or Servlet's
- can send messages.</para>
+ <para>The Java Connector Architecture (JCA) Adapter is what allows HornetQ to be integrated
+ with JEE components such as MDB's and EJB's. It configures how components such as MDB's
+ consume messages from the HornetQ server and also how components such as EJB's or
+ Servlet's can send messages.</para>
<para>The HornetQ JCA adapter is deployed via the <literal>jms-ra.rar</literal> archive. The
configuration of the Adapter is found in this archive under <literal
>META-INF/ra.xml</literal>.</para>
@@ -635,13 +636,13 @@
<para>A bridge is deployed inside a JBoss AS instance. The instance can be the same instance
as either the source or target server. Or could be on a third, separate JBoss AS
instance.</para>
- <para>The bridge can also be used to bridge messages from other non HornetQ JMS
- servers, as long as they are JMS 1.1 compliant.<note>
+ <para>The bridge can also be used to bridge messages from other non HornetQ JMS servers, as
+ long as they are JMS 1.1 compliant.<note>
<para>Don't confuse a JMS bridge with a core bridge. A JMS bridge can be used to
bridge any two JMS 1.1 compliant JMS providers and uses the JMS API. A core
bridge (described in <xref linkend="core-bridges"/>) is used to bridge any two
- HornetQ instances and uses the core API. Always use a core bridge if you
- can in preference to a JMS bridge. The core bridge will typically provide better
+ HornetQ instances and uses the core API. Always use a core bridge if you can in
+ preference to a JMS bridge. The core bridge will typically provide better
performance than a JMS bridge. Also the core bridge can provide <emphasis>once
and only once</emphasis> delivery guarantees without using XA.</para>
</note></para>
@@ -934,8 +935,8 @@
<para>The source and target connection factory factories are used to create the
connection factory used to create the connection for the source or target
server.</para>
- <para>The configuration example above uses the default implementation provided by HornetQ
- that looks up the connection factory using JNDI. For other Application
+ <para>The configuration example above uses the default implementation provided by
+ HornetQ that looks up the connection factory using JNDI. For other Application
Servers or JMS providers a new implementation may have to be provided. This can
easily be done by implementing the interface <literal
>org.hornetq.jms.bridge.ConnectionFactoryFactory</literal>.</para>
@@ -975,8 +976,8 @@
<title>ONCE_AND_ONLY_ONCE</title>
<para>This QoS mode ensures messages will reach the destination from the source once
and only once. (Sometimes this mode is known as "exactly once"). If both the
- source and the destination are on the same HornetQ server instance then
- this can be achieved by sending and acknowledging the messages in the same local
+ source and the destination are on the same HornetQ server instance then this can
+ be achieved by sending and acknowledging the messages in the same local
transaction. If the source and destination are on different servers this is
achieved by enlisting the sending and consuming sessions in a JTA transaction.
The JTA transaction is controlled by JBoss Transactions JTA * implementation
@@ -1014,17 +1015,17 @@
or lose network connectivity. For more information on XA Recovery,please refer to <ulink
url="http://www.jboss.org/community/wiki/JBossTransactions">JBoss
Transactions</ulink>.</para>
- <para>When HornetQ is integrated with JBoss AS, it can take advantage of JBoss
- Transactions to provide recovery of messaging resources. If messages are involved in a
- XA transaction, in the event of a server crash, the recovery manager will ensure that
- the transactions are recovered and the messages will either be committed or rolled back
+ <para>When HornetQ is integrated with JBoss AS, it can take advantage of JBoss Transactions
+ to provide recovery of messaging resources. If messages are involved in a XA
+ transaction, in the event of a server crash, the recovery manager will ensure that the
+ transactions are recovered and the messages will either be committed or rolled back
(depending on the transaction outcome) when the server is restarted.</para>
<section>
<title>XA Recovery Configuration</title>
- <para>To enable HornetQs XA Recovery, the Recovery Manager must be configured to
- connect to HornetQ to recover its resources. The following property must be
- added to the <literal>jta</literal> section of <literal
- >conf/jbossts-properties.xml</literal> of JBoss AS profiles:</para>
+ <para>To enable HornetQs XA Recovery, the Recovery Manager must be configured to connect
+ to HornetQ to recover its resources. The following property must be added to the
+ <literal>jta</literal> section of <literal>conf/jbossts-properties.xml</literal>
+ of JBoss AS profiles:</para>
<programlisting>
<properties depends="arjuna" name="jta">
...
@@ -1034,13 +1035,13 @@
</properties>
</programlisting>
<para>The <literal>[connection configuration]</literal> contains all the information
- required to connect to HornetQ node under the form <literal>[connector
- factory class name],[user name], [password], [connector parameters]</literal>. </para>
+ required to connect to HornetQ node under the form <literal>[connector factory class
+ name],[user name], [password], [connector parameters]</literal>. </para>
<itemizedlist>
<listitem>
<para><literal>[connector factory class name]</literal> corresponds to the name
of the <literal>ConnectorFactory</literal> used to connect to HornetQ.
- Values can be <literal
+ Values can be <literal
>org.hornetq.core.remoting.impl.invm.InVMConnectorFactory</literal> or
<literal
>org.hornetq.integration.transports.netty.NettyConnectorFactory</literal></para>
@@ -1101,9 +1102,8 @@
<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.HORNETQ1"
value="org.hornetq.jms.server.recovery.HornetQXAResourceRecovery;org.hornetq.integration.transports.netty.NettyConnectorFactory, admin, adminpass, hornetq.remoting.netty.port=8888"/>
</programlisting>
- <para>Configuring HornetQ with an invm acceptor and configuring the Recovery
- Manager with an invm connector is the recommended way to enable XA
- Recovery.</para>
+ <para>Configuring HornetQ with an invm acceptor and configuring the Recovery Manager
+ with an invm connector is the recommended way to enable XA Recovery.</para>
</section>
</section>
<section>
Modified: trunk/docs/user-manual/en/architecture.xml
===================================================================
--- trunk/docs/user-manual/en/architecture.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/architecture.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,28 +16,24 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="architecture">
<title>Architecture</title>
- <para>In this section we will give an overview of the HornetQ high level
- architecture.</para>
+ <para>In this section we will give an overview of the HornetQ high level architecture.</para>
<section>
<title>Core Architecture</title>
- <para>HornetQ core is designed simply as set of Plain Old Java Objects
- (POJOs).</para>
+ <para>HornetQ core is designed simply as set of Plain Old Java Objects (POJOs).</para>
<para>We've also designed it to have as few dependencies on external jars as possible. In
- fact, HornetQ core has <emphasis role="italic">zero</emphasis> dependencies on
- any jars other than the standard JDK classes!</para>
- <para>This allows HornetQ to be easily embedded in your own project, or instantiated
- in any dependency injection framework such as JBoss Microcontainer, Spring or Google
+ fact, HornetQ core has <emphasis role="italic">zero</emphasis> dependencies on any jars
+ other than the standard JDK classes!</para>
+ <para>This allows HornetQ to be easily embedded in your own project, or instantiated in any
+ dependency injection framework such as JBoss Microcontainer, Spring or Google
Guice.</para>
- <para>A HornetQ server has its own high performance persistent journal, which it
- uses for message and other persistence.</para>
+ <para>A HornetQ server has its own high performance persistent journal, which it uses for
+ message and other persistence.</para>
<para>Using a high performance journal allows outrageous persistence message performance,
something not achievable when using a relational database for persistence.</para>
- <para>HornetQ clients, potentially on different physical machines interact with the
- HornetQ server. HornetQ currently provides two APIs for messaging at the
- client side:</para>
+ <para>HornetQ clients, potentially on different physical machines interact with the HornetQ
+ server. HornetQ currently provides two APIs for messaging at the client side:</para>
<para>
<orderedlist>
<listitem>
@@ -53,12 +48,12 @@
</orderedlist>
</para>
<para>JMS semantics are implemented by a thin JMS facade layer on the client side.</para>
- <para>The HornetQ server does not speak JMS and in fact does not know anything about
- JMS, it's a protocol agnostic messaging server designed to be used with multiple
- different protocols.</para>
+ <para>The HornetQ server does not speak JMS and in fact does not know anything about JMS,
+ it's a protocol agnostic messaging server designed to be used with multiple different
+ protocols.</para>
<para>When a user uses the JMS API on the client side, all JMS interactions are translated
- into operations on the HornetQ core client API before being transferred over the
- wire using the HornetQ wire format.</para>
+ into operations on the HornetQ core client API before being transferred over the wire
+ using the HornetQ wire format.</para>
<para>The server always just deals with core API interactions.</para>
<para>A schematic illustrating this relationship is shown in figure 3.1 below:</para>
<para>
@@ -72,18 +67,18 @@
</section>
<section>
<title>HornetQ embedded in your own application</title>
- <para>HornetQ core is designed as a set of simple POJOs so if you have an
- application that requires messaging functionality internally but you don't want to
- expose that as a messaging server you can directly instantiate and embed messaging
- servers in your own application.</para>
- <para>For more information on embedding HornetQ, see <xref
- linkend="embedding-hornetq" />.</para>
+ <para>HornetQ core is designed as a set of simple POJOs so if you have an application that
+ requires messaging functionality internally but you don't want to expose that as a
+ HornetQ server you can directly instantiate and embed HornetQ servers in your own
+ application.</para>
+ <para>For more information on embedding HornetQ, see <xref linkend="embedding-hornetq"
+ />.</para>
</section>
<section>
<title>HornetQ integrated with a JEE application server</title>
- <para>HornetQ provides its own fully functional Java Connector Architecture (JCA)
- adaptor which enables it to be integrated easily into any JEE compliant application
- server or servlet engine.</para>
+ <para>HornetQ provides its own fully functional Java Connector Architecture (JCA) adaptor
+ which enables it to be integrated easily into any JEE compliant application server or
+ servlet engine.</para>
<para>JEE application servers provide Message Driven Beans (MDBs), which are a special type
of Enterprise Java Beans (EJBs) that can process messages from sources such as JMS
systems or mail systems.</para>
@@ -102,39 +97,39 @@
an EJB, MDB or servlet without going through a JCA adapter, but this is not recommended
since you will not be able to take advantage of the JCA features, such as caching of JMS
sessions, which can result in poor performance.</para>
- <para>Figure 3.2 below shows a JEE application server integrating with a HornetQ
- server via the HornetQ JCA adaptor. Note that all communication between EJB
- sessions or entity beans and Message Driven beans go through the adaptor and not
- directly to HornetQ.</para>
+ <para>Figure 3.2 below shows a JEE application server integrating with a HornetQ server via
+ the HornetQ JCA adaptor. Note that all communication between EJB sessions or entity
+ beans and Message Driven beans go through the adaptor and not directly to
+ HornetQ.</para>
<para>The large arrow with the prohibited sign shows an EJB session bean talking directly to
- the HornetQ server. This is not recommended as you'll most likely end up
- creating a new connection and session every time you want to interact from the EJB,
- which is an anti-pattern.</para>
+ the HornetQ server. This is not recommended as you'll most likely end up creating a new
+ connection and session every time you want to interact from the EJB, which is an
+ anti-pattern.</para>
<para>
<graphic fileref="images/architecture2.jpg"/>
</para>
<para>For more information on using the JCA adaptor, please see <xref
- linkend="appserver-integration" />.</para>
+ linkend="appserver-integration"/>.</para>
</section>
<section>
<title>HornetQ stand-alone server</title>
- <para>HornetQ can also be deployed as a stand-alone server. This means a fully
- independent messaging server not dependent on a JEE application server.</para>
+ <para>HornetQ can also be deployed as a stand-alone server. This means a fully independent
+ messaging server not dependent on a JEE application server.</para>
<para>The standard stand-alone messaging server configuration comprises a core messaging
server, a JMS service and a JNDI service.</para>
<para>The role of the JMS Service is to deploy any JMS Queues, Topics and ConnectionFactory
- instances from any server side <literal>hornetq-jms.xml</literal> configuration files. It also
- provides a simple management API for creating and destroying Queues, Topics and
+ instances from any server side <literal>hornetq-jms.xml</literal> configuration files.
+ It also provides a simple management API for creating and destroying Queues, Topics and
ConnectionFactory instances which can be accessed via JMX or the connection. It is a
- separate service to the HornetQ core server, since the core server is JMS
- agnostic. If you don't want to deploy any JMS Queues, Topics and ConnectionFactory
- instances via server side XML configuration and don't require a JMS management API on the
- server side then you can disable this service.</para>
+ separate service to the HornetQ core server, since the core server is JMS agnostic. If
+ you don't want to deploy any JMS Queues, Topics and ConnectionFactory instances via
+ server side XML configuration and don't require a JMS management API on the server side
+ then you can disable this service.</para>
<para>We also include a JNDI server since JNDI is a common requirement when using JMS to
lookup Queues, Topics and ConnectionFactory instances. If you do not require JNDI then
- this service can also be disabled. HornetQ allows you to programmatically create
- JMS and core objects directly on the client side as opposed to looking them up from
- JNDI, so a JNDI server is not always a requirement.</para>
+ this service can also be disabled. HornetQ allows you to programmatically create JMS and
+ core objects directly on the client side as opposed to looking them up from JNDI, so a
+ JNDI server is not always a requirement.</para>
<para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and
enforce dependencies between the components. JBoss Microcontainer is a very lightweight
POJO bootstrapper.</para>
@@ -142,7 +137,7 @@
<para>
<graphic fileref="images/architecture3.jpg"/>
</para>
- <para>For more information on server configuration files see <xref linkend="server.configuration" />.
-$ </para>
+ <para>For more information on server configuration files see <xref
+ linkend="server.configuration"/>. $ </para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/client-classpath.xml
===================================================================
--- trunk/docs/user-manual/en/client-classpath.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/client-classpath.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,40 +16,40 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="client-classpath">
<title>The Client Classpath</title>
- <para>In this chapter we explain which jars you need on the Java classpath of a HornetQ
- client application. This depends on various factors including whether you're using just
- core, JMS, JNDI or Netty. We explain which jars are needed in each case.</para>
+ <para>In this chapter we explain which jars you need on the Java classpath of a HornetQ client
+ application. This depends on various factors including whether you're using just core, JMS,
+ JNDI or Netty. We explain which jars are needed in each case.</para>
<note>
<para>All the jars mentioned here can be found in the <literal>lib</literal> directory of
- the HornetQ distribution. Be sure you only use the jars from the correct version
- of the release, you <emphasis>must not</emphasis> mix and match versions of jars from
- different HornetQ versions.</para>
+ the HornetQ distribution. Be sure you only use the jars from the correct version of the
+ release, you <emphasis>must not</emphasis> mix and match versions of jars from different
+ HornetQ versions. Mixing and matching different jar versions may cause subtle errors and
+ failures to occur.</para>
</note>
<section>
<title>Pure Core Client</title>
- <para>If you're using just a pure HornetQ core client (i.e. no JMS) then you need
- <literal>hornetq-core-client.jar</literal> on your client classpath.</para>
+ <para>If you're using just a pure HornetQ core client (i.e. no JMS) then you need <literal
+ >hornetq-core-client.jar</literal> on your client classpath.</para>
<para>If you're using a Netty transport then you will also netty <literal
>netty.jar</literal> and <literal>hornetq-transports.jar</literal>.</para>
</section>
<section>
<title>JMS Client</title>
<para>If you're using JMS on the client side, then you will need <literal
- >hornetq-core-client.jar</literal>, <literal>hornetq-jms-client.jar</literal> and <literal
- >jboss-jms-api.jar</literal>. Note that <literal>jboss-jms-api.jar</literal> just
- contains Java EE API interface classes needed for the <literal>javax.jms.*</literal>
- classes, so if you already have a jar with these interface classes on your classpath you
- won't need it.</para>
+ >hornetq-core-client.jar</literal>, <literal>hornetq-jms-client.jar</literal> and
+ <literal>jboss-jms-api.jar</literal>. Note that <literal>jboss-jms-api.jar</literal>
+ just contains Java EE API interface classes needed for the <literal
+ >javax.jms.*</literal> classes, so if you already have a jar with these interface
+ classes on your classpath you won't need it.</para>
<para>If you're using a Netty transport then you will also netty <literal
>netty.jar</literal> and <literal>hornetq-transports.jar</literal>.</para>
</section>
<section>
<title>JNDI</title>
<para>If you're looking up JNDI objects from the JNDI server co-located with the HornetQ
- standalone server you'll also need the jar <literal>jnp-client.jar</literal>
- jar on your client classpath as well as any other jars mentioned previously.</para>
+ standalone server you'll also need the jar <literal>jnp-client.jar</literal> jar on your
+ client classpath as well as any other jars mentioned previously.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/command-buffering.xml
===================================================================
--- trunk/docs/user-manual/en/command-buffering.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/command-buffering.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,12 +16,11 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="command-buffering">
<title>Command Buffering</title>
- <para>As HornetQ clients send commands to their servers they store each sent command in
- an in-memory buffer. In the case that connection failure occurs and the client subsequently
- reconnects to the same server or fails over onto a replica server, as part of the
+ <para>As HornetQ clients send commands to their servers they store each sent command in an
+ in-memory buffer. In the case that connection failure occurs and the client subsequently
+ reconnects to the same server or fails over onto a backup server, as part of the
reconnection protocol the server informs the client during reconnection with the id of the
last command it successfully received from that client.</para>
<para>If the client has sent more commands than were received before failover it can replay any
@@ -34,9 +32,10 @@
client can then free up space in the buffer.</para>
<para>If you are using JMS and you're using the JMS service on the server to load your JMS
connection factory instances into JNDI then this parameter can be configured in <literal
- >hornetq-jms.xml</literal> using the element <literal>producer-window-size</literal> a. If
- you're using JMS but not using JNDI then you can set these values directly on the <literal
- >HornetQConnectionFactory</literal> instance using the appropriate setter method.</para>
+ >hornetq-jms.xml</literal> using the element <literal>producer-window-size</literal> a.
+ If you're using JMS but not using JNDI then you can set these values directly on the
+ <literal>HornetQConnectionFactory</literal> instance using the appropriate setter
+ method.</para>
<para>If you're using core you can set these values directly on the <literal
>ClientSessionFactory</literal> instance using the appropriate setter method.</para>
<para>The send window is specified in bytes, and has a default value of <literal
Modified: trunk/docs/user-manual/en/configuration-index.xml
===================================================================
--- trunk/docs/user-manual/en/configuration-index.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/configuration-index.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="configuration-index">
<title>Configuration Reference</title>
<para>This section is a quick index for looking up configuration. Click on the element name to
@@ -991,7 +989,7 @@
>connection-factory.scheduled-thread-pool-max-size</link></entry>
<entry>Integer</entry>
<entry>the size of the scheduled thread pool</entry>
- <entry>2</entry>
+ <entry>5</entry>
</row>
<row>
<entry><link linkend="thread-pooling.client.side"
Modified: trunk/docs/user-manual/en/configuring-transports.xml
===================================================================
--- trunk/docs/user-manual/en/configuring-transports.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/configuring-transports.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,14 +16,13 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="configuring-transports">
<title>Configuring the Transport</title>
- <para>HornetQ has a fully pluggable and highly flexible transport layer and defines its
- own Service Provider Interface (SPI) to make plugging in a new transport provider relatively
+ <para>HornetQ has a fully pluggable and highly flexible transport layer and defines its own
+ Service Provider Interface (SPI) to make plugging in a new transport provider relatively
straightforward.</para>
- <para>In this chapter we'll describe the concepts required for understanding HornetQ
- transports and where and how they're configured.</para>
+ <para>In this chapter we'll describe the concepts required for understanding HornetQ transports
+ and where and how they're configured.</para>
<section id="configuring-transports.acceptors">
<title>Understanding Acceptors</title>
<para>One of the most important concepts in HornetQ transports is the
@@ -46,8 +44,9 @@
upper limit to the number of acceptors per server.</para>
<para>Each acceptor defines a way in which connections can be made to the HornetQ
server.</para>
- <para>In the above example we're defining an acceptor that uses Netty to listen for
- connections at port <literal>5446</literal>. </para>
+ <para>In the above example we're defining an acceptor that uses <ulink
+ url="http://jboss.org/netty">Netty</ulink> to listen for connections at port
+ <literal>5446</literal>. </para>
<para>The <literal>acceptor</literal> element contains a sub-element <literal
>factory-class</literal>, this element defines the factory used to create acceptor
instances. In this case we're using Netty to listen for connections so we use the Netty
@@ -80,9 +79,9 @@
</connector>
</connectors>
</programlisting>
- <para>Connectors can be defined inside an <literal>connectors</literal> element. There can
- be one or more connectors defined in the <literal>connectors</literal> element. There's
- no upper limit to the number of connectors per server.</para>
+ <para>Connectors can be defined inside a <literal>connectors</literal> element. There can be
+ one or more connectors defined in the <literal>connectors</literal> element. There's no
+ upper limit to the number of connectors per server.</para>
<para>You make ask yourself, if connectors are used by the <emphasis>client</emphasis> to
make connections then why are they defined on the <emphasis>server</emphasis>? There are
a couple of reasons for this:</para>
@@ -96,12 +95,12 @@
<listitem>
<para>If you're using JMS and the server side JMS service to instantiate JMS
ConnectionFactory instances and bind them in JNDI, then when creating the
- <literal>HornetQConnectionFactory</literal> it needs to know what server that
- connection factory will create connections to.</para>
+ <literal>HornetQConnectionFactory</literal> it needs to know what server
+ that connection factory will create connections to.</para>
<para>That's defined by the <literal>connector-ref</literal> element in the <literal
>hornetq-jms.xml</literal>file on the server side. Let's take a look at a
- snipped from a <literal>hornetq-jms.xml</literal> file that shows a JMS connection
- factory that references our netty connector defined in our <literal
+ snipped from a <literal>hornetq-jms.xml</literal> file that shows a JMS
+ connection factory that references our netty connector defined in our <literal
>hornetq-configuration.xml</literal> file:</para>
<programlisting>
<connection-factory name="ConnectionFactory">
@@ -131,7 +130,7 @@
<programlisting>
Map<String, Object> connectionParams = new HashMap<String, Object>();
- connectionParams.put(org.hornetq.integration.transports.netty.TransportConstants.PORT_PROP_NAME,
+connectionParams.put(org.hornetq.integration.transports.netty.TransportConstants.PORT_PROP_NAME,
5446);
TransportConfiguration transportConfiguration =
@@ -167,16 +166,15 @@
</section>
<section>
<title>Configuring the Netty transport</title>
- <para>Out of the box, HornetQ currently uses <ulink
- url="http://www.jboss.org/netty/">Netty</ulink>, a high performance low level
- network library.</para>
+ <para>Out of the box, HornetQ currently uses <ulink url="http://www.jboss.org/netty/"
+ >Netty</ulink>, a high performance low level network library.</para>
<para>Our Netty transport can be configured in several different ways; to use old (blocking)
Java IO, or NIO (non-blocking), also to use straightforward TCP sockets, SSL, or to
tunnel over HTTP or HTTPS, on top of that we also provide a servlet transport.</para>
<para>We believe this caters for the vast majority of transport requirements.</para>
<section>
<title>Configuring Netty TCP</title>
- <para> Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
+ <para>Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be
configured to use old blocking Java IO or non blocking Java NIO. We recommend you
use the default Java NIO for better scalability. </para>
<para>If you're running connections across an untrusted network please bear in mind this
@@ -187,9 +185,9 @@
with firewall policies that typically only allow connections to be initiated in one
direction.</para>
<para>All the valid Netty transport keys are defined in the class <literal
- >org.hornetq.integration.transports.netty.TransportConstants</literal>.
- The parameters can be used either with acceptors or connectors. The following
- parameters can be used to configure Netty for simple TCP:</para>
+ >org.hornetq.integration.transports.netty.TransportConstants</literal>. The
+ parameters can be used either with acceptors or connectors. The following parameters
+ can be used to configure Netty for simple TCP:</para>
<itemizedlist>
<listitem>
<para><literal>hornetq.remoting.netty.usenio</literal>. If this is <literal
@@ -202,9 +200,9 @@
<literal>true</literal>.</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.host</literal>. This specified the host name
- or ip address to connect to (when configuring a connector) or to listen on
- (when configuring an acceptor). The default value for this property is
+ <para><literal>hornetq.remoting.netty.host</literal>. This specified the host
+ name or ip address to connect to (when configuring a connector) or to listen
+ on (when configuring an acceptor). The default value for this property is
<literal>localhost</literal>. Note that if you want your servers
accessible from other nodes, don't bind to localhost!</para>
</listitem>
@@ -222,9 +220,9 @@
is <literal>true</literal>.</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.tcpsendbuffersize</literal>. This parameter
- determines the size of the TCP send buffer in bytes. The default value for
- this property is <literal>32768</literal> bytes (32KiB).</para>
+ <para><literal>hornetq.remoting.netty.tcpsendbuffersize</literal>. This
+ parameter determines the size of the TCP send buffer in bytes. The default
+ value for this property is <literal>32768</literal> bytes (32KiB).</para>
<para>TCP buffer sizes should be tuned according to the bandwidth and latency of
your network. Here's a good link that explains the theory behind <ulink
url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>.</para>
@@ -239,9 +237,10 @@
defaults.</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.tcpreceivebuffersize</literal>. This parameter
- determines the size of the TCP receive buffer in bytes. The default value
- for this property is <literal>32768</literal> bytes (32KiB).</para>
+ <para><literal>hornetq.remoting.netty.tcpreceivebuffersize</literal>. This
+ parameter determines the size of the TCP receive buffer in bytes. The
+ default value for this property is <literal>32768</literal> bytes
+ (32KiB).</para>
</listitem>
</itemizedlist>
</section>
@@ -258,16 +257,17 @@
>true</literal> to enable SSL.</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.keystorepath</literal>. This is the path to
- the SSL key store on the client which holds the client certificates.</para>
+ <para><literal>hornetq.remoting.netty.keystorepath</literal>. This is the path
+ to the SSL key store on the client which holds the client
+ certificates.</para>
</listitem>
<listitem>
<para><literal>hornetq.remoting.netty.keystorepassword</literal>. This is the
password for the client certificate key store on the client.</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.truststorepath</literal>. This is the path to
- the trusted client certificate store on the server.</para>
+ <para><literal>hornetq.remoting.netty.truststorepath</literal>. This is the path
+ to the trusted client certificate store on the server.</para>
</listitem>
<listitem>
<para><literal>hornetq.remoting.netty.truststorepassword</literal>. This is the
@@ -293,8 +293,8 @@
connection alive</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.httpclientidlescanperiod</literal>. How often,
- in milliseconds, to scan for idle clients</para>
+ <para><literal>hornetq.remoting.netty.httpclientidlescanperiod</literal>. How
+ often, in milliseconds, to scan for idle clients</para>
</listitem>
<listitem>
<para><literal>hornetq.remoting.netty.httpresponsetime</literal>. How long the
@@ -302,29 +302,28 @@
alive</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.httpserverscanperiod</literal>. How often, in
- milliseconds, to scan for clients needing responses</para>
+ <para><literal>hornetq.remoting.netty.httpserverscanperiod</literal>. How often,
+ in milliseconds, to scan for clients needing responses</para>
</listitem>
<listitem>
- <para><literal>hornetq.remoting.netty.httprequiressessionid</literal>. If true the
- client will wait after the first call to receive a session id. Used the http
- connector is connecting to servlet acceptor (not recommended) </para>
+ <para><literal>hornetq.remoting.netty.httprequiressessionid</literal>. If true
+ the client will wait after the first call to receive a session id. Used the
+ http connector is connecting to servlet acceptor (not recommended) </para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Configuring Netty Servlet</title>
- <para>We also provide a Netty servlet transport for use with HornetQ. The
- servlet transport allows HornetQ traffic to be tunneled over HTTP to a
- servlet running in a servlet engine which then redirects it to an in-VM HornetQ
- server.</para>
+ <para>We also provide a Netty servlet transport for use with HornetQ. The servlet
+ transport allows HornetQ traffic to be tunneled over HTTP to a servlet running in a
+ servlet engine which then redirects it to an in-VM HornetQ server.</para>
<para>The servlet transport differs from the Netty HTTP transport in that, with the HTTP
- transport HornetQ effectively acts a web server listening for HTTP traffic
- on, e.g. port 80 or 8080, whereas with the servlet transport HornetQ traffic is proxied
+ transport HornetQ effectively acts a web server listening for HTTP traffic on, e.g.
+ port 80 or 8080, whereas with the servlet transport HornetQ traffic is proxied
through a servlet engine which may already be serving web site or other
- applications. This allows HornetQ to be used where corporate policies may
- only allow a single web server listening on an HTTP port, and this needs to serve
- all applications including messaging.</para>
+ applications. This allows HornetQ to be used where corporate policies may only allow
+ a single web server listening on an HTTP port, and this needs to serve all
+ applications including messaging.</para>
<para>Please see the examples for a full working example of the servlet transport being
used.</para>
<para>To configure a servlet engine to work the Netty Servlet transport we need to do
@@ -338,7 +337,7 @@
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<servlet>
- <servlet-name>NettyServlet</servlet-name>
+ <servlet-name>HornetQServlet</servlet-name>
<servlet-class>org.jboss.netty.channel.socket.http.HttpTunnelingServlet</servlet-class>
<init-param>
<param-name>endpoint</param-name>
@@ -348,7 +347,7 @@
</servlet>
<servlet-mapping>
- <servlet-name>NettyServlet</servlet-name>
+ <servlet-name>HornetQServlet</servlet-name>
<url-pattern>/HornetQServlet</url-pattern>
</servlet-mapping>
</web-app>
@@ -358,8 +357,8 @@
<listitem>
<para>We also need to add a special Netty invm acceptor on the server side
configuration.</para>
- <para>Here's a snippet from the <literal>hornetq-configuration.xml</literal> file
- showing that acceptor being defined:</para>
+ <para>Here's a snippet from the <literal>hornetq-configuration.xml</literal>
+ file showing that acceptor being defined:</para>
<programlisting>
<acceptors>
@@ -433,5 +432,4 @@
servlet ssl example shipped with HornetQ for more detail.</para>
</section>
</section>
-
</chapter>
Modified: trunk/docs/user-manual/en/connection-ttl.xml
===================================================================
--- trunk/docs/user-manual/en/connection-ttl.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/connection-ttl.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,17 +16,16 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="connection-ttl">
<title>Dead Connections and Session Multiplexing</title>
<para>In this section we will discuss connection time-to-live (TTL) and explain how HornetQ
- deals with crashed clients and clients which have exited without cleanly closing
- their resources. We'll also discuss how HornetQ multiplexes several sessions on a
- single connection.</para>
+ deals with crashed clients and clients which have exited without cleanly closing their
+ resources. We'll also discuss how HornetQ multiplexes several sessions on a single
+ connection.</para>
<section id="dead.connections">
<title>Cleaning up Dead Connection Resources on the Server</title>
- <para>Before a HornetQ client application exits it is considered good practice that
- it should close its resources in a controlled manner, using a <literal>finally</literal>
+ <para>Before a HornetQ client application exits it is considered good practice that it
+ should close its resources in a controlled manner, using a <literal>finally</literal>
block.</para>
<para>Here's an example of a well behaved core client application closing its session and
session factory in a finally block:</para>
@@ -83,8 +81,8 @@
over time this result in the server running out of memory or other resources.</para>
<para>We have to balance the requirement for cleaning up dead client resources with the fact
that sometimes the network between the client and the server can fail and then come
- back, allowing the client to reconnect. HornetQ supports client reconnection, so
- we don't want to clean up "dead" server side resources too soon or this will prevent any
+ back, allowing the client to reconnect. HornetQ supports client reconnection, so we
+ don't want to clean up "dead" server side resources too soon or this will prevent any
client from reconnecting, as it won't be able to find its old sessions on the
server.</para>
<para>HornetQ makes all of this configurable. For each <literal
@@ -114,9 +112,9 @@
<para>As previously discussed, it's important that all core client sessions and JMS
connections are always closed explicitly in a <literal>finally</literal> block when
you are finished using them. </para>
- <para>If you fail to do so, HornetQ will detect this at garbage collection time,
- and log a warning similar to the following in the logs (If you are using JMS the
- warning will involve a JMS connection not a client session):</para>
+ <para>If you fail to do so, HornetQ will detect this at garbage collection time, and log
+ a warning similar to the following in the logs (If you are using JMS the warning
+ will involve a JMS connection not a client session):</para>
<programlisting>
[Finalizer] 20:14:43,244 WARNING [org.hornetq.core.client.impl.DelegatingSession] I'm closin
@@ -142,9 +140,7 @@
for pinging, and that's for the <emphasis>client</emphasis> to be able to detect that
the server or network has failed.</para>
<para>As long as the client is receiving data from the server it will consider the
- connection to be still alive. If the connection is idle the server will periodically
- send packets to the client to prevent the client from thinking the connection is
- dead.</para>
+ connection to be still alive. </para>
<para>If the client does not receive any packets for <literal
>client-failure-check-period</literal> milliseconds then it will consider the
connection failed and will either initiate failover, or call any <literal
@@ -174,8 +170,8 @@
<para>Processing operations asynchronously on another thread does however add a little more
latency, so we allow this to be configured using the parameter <literal
>async-connection-execution-enabled</literal> in <literal
- >hornetq-configuration.xml</literal>. The default value for this parameter is <literal
- >true</literal>.</para>
+ >hornetq-configuration.xml</literal>. The default value for this parameter is
+ <literal>true</literal>.</para>
<para>If you do set this parameter to <literal>false</literal> please do so with
caution.</para>
</section>
Modified: trunk/docs/user-manual/en/core-bridges.xml
===================================================================
--- trunk/docs/user-manual/en/core-bridges.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/core-bridges.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,33 +16,31 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="core-bridges">
<title>Core Bridges</title>
<para>The function of a bridge is to consume messages from a source queue, and forward them to a
target address, typically on a different HornetQ server.</para>
<para>The source and target servers do not have to be in the same cluster which makes bridging
suitable for reliably sending messages from one cluster to another, for instance across a
- WAN, and where the connection may be unreliable.</para>
+ WAN, or internet and where the connection may be unreliable.</para>
<para>The bridge has built in resilience to failure so if the target server connection is lost,
e.g. due to network failure, the bridge will retry connecting to the target until it comes
back online. When it comes back online it will resume operation as normal.</para>
- <para>In summary, bridges are a way to reliably connect two separate HornetQ servers
- together. With a core bridge both source and target servers must be HornetQ
- servers.</para>
- <para>Bridges can be configured provide <emphasis>once and only once</emphasis> delivery
+ <para>In summary, bridges are a way to reliably connect two separate HornetQ servers together.
+ With a core bridge both source and target servers must be HornetQ servers.</para>
+ <para>Bridges can be configured to provide <emphasis>once and only once</emphasis> delivery
guarantees even in the event of the failure of the source or the target server. They do this
- by using duplicate detection (described in <xref linkend="duplicate-detection" />).</para>
+ by using duplicate detection (described in <xref linkend="duplicate-detection"/>).</para>
<note>
<para>Although they have similar function, don't confuse core bridges with JMS
bridges!</para>
- <para>Core bridges are for linking a HornetQ node with another HornetQ node
- and do not use the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant
- JMS providers. So, a JMS Bridge could be used for bridging to or from different JMS
- compliant messaging system. It's always preferable to use a core bridge if you can. Core
- bridges use duplicate detection to provide <emphasis>once and only once</emphasis>
- guarantees. To provide the same guarantee using a JMS bridge you would have to use XA
- which has a higher overhead and is more complex to configure.</para>
+ <para>Core bridges are for linking a HornetQ node with another HornetQ node and do not use
+ the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant JMS providers.
+ So, a JMS Bridge could be used for bridging to or from different JMS compliant messaging
+ system. It's always preferable to use a core bridge if you can. Core bridges use
+ duplicate detection to provide <emphasis>once and only once</emphasis> guarantees. To
+ provide the same guarantee using a JMS bridge you would have to use XA which has a
+ higher overhead and is more complex to configure.</para>
</note>
<section>
<title>Configuring Bridges</title>
@@ -86,22 +83,23 @@
<note>
<para>If you're using JMS then normally the JMS configuration <literal
>hornetq-jms.xml</literal> is loaded after the core configuration file
- <literal>hornetq-configuration.xml</literal> is loaded. If your bridge is
- consuming from a JMS queue then you'll need to make sure the JMS queue is
- also deployed as a core queue in the core configuration. Take a look at the bridge
- example for an example of how this is done.</para>
+ <literal>hornetq-configuration.xml</literal> is loaded. If your bridge
+ is consuming from a JMS queue then you'll need to make sure the JMS queue is
+ also deployed as a core queue in the core configuration. Take a look at the
+ bridge example for an example of how this is done.</para>
</note>
</listitem>
<listitem>
- <para><literal>forwarding-address</literal>. This is the address on the target server
- that the message will be forwarded to. If a forwarding address is not specified
- then the original destination of the message will be retained.</para>
+ <para><literal>forwarding-address</literal>. This is the address on the target
+ server that the message will be forwarded to. If a forwarding address is not
+ specified then the original destination of the message will be retained.</para>
</listitem>
<listitem>
<para><literal>filter-string</literal>. An optional filter string can be supplied.
If specified then only messages which match the filter expression specified in
the filter string will be forwarded. The filter string follows the HornetQ
- filter expression syntax described in <xref linkend="filter-expressions" />.</para>
+ filter expression syntax described in <xref linkend="filter-expressions"
+ />.</para>
</listitem>
<listitem>
<para><literal>transformer-class-name</literal>. An optional transformer-class-name
@@ -168,7 +166,7 @@
ignored.</para>
<para>This allows the bridge to provide a <emphasis>once and only once</emphasis>
delivery guarantee without using heavyweight methods such as XA (see <xref
- linkend="duplicate-detection" /> for more information).</para>
+ linkend="duplicate-detection"/> for more information).</para>
<para>The default value for this parameter is <literal>true</literal>.</para>
</listitem>
<listitem>
@@ -178,15 +176,15 @@
<para>A <emphasis>connector</emphasis> encapsulates knowledge of what transport to
use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port
etc). For more information about what connectors are and how to configure them,
- please see <xref linkend="configuring-transports" />.</para>
+ please see <xref linkend="configuring-transports"/>.</para>
<para>The <literal>connector-ref</literal> element can be configured with two
attributes:</para>
<itemizedlist>
<listitem>
<para><literal>connector-name</literal>. This references the name of a
connector defined in the core configuration file <literal
- >hornetq-configuration.xml</literal>. The bridge will use this connector
- to make its connection to the target server. This attribute is
+ >hornetq-configuration.xml</literal>. The bridge will use this
+ connector to make its connection to the target server. This attribute is
mandatory.</para>
</listitem>
<listitem>
Modified: trunk/docs/user-manual/en/diagrams/architecture-diagrams.odg
===================================================================
(Binary files differ)
Modified: trunk/docs/user-manual/en/embedding-hornetq.xml
===================================================================
--- trunk/docs/user-manual/en/embedding-hornetq.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/embedding-hornetq.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,26 +16,25 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="embedding-hornetq">
<title>Embedding HornetQ</title>
- <para>HornetQ is designed as set of simple Plain Old Java Objects (POJOs). This means
- HornetQ can be instantiated and run in any dependency injection framework such as
- JBoss Microcontainer, Spring or Google Guice. It also means that if you have an application
- that could use messaging functionality internally, then it can <emphasis>directly
- instantiate</emphasis> HornetQ clients and servers in its own application code
- to perform that functionality. We call this <emphasis>embedding</emphasis> HornetQ.</para>
+ <para>HornetQ is designed as set of simple Plain Old Java Objects (POJOs). This means HornetQ
+ can be instantiated and run in any dependency injection framework such as JBoss
+ Microcontainer, Spring or Google Guice. It also means that if you have an application that
+ could use messaging functionality internally, then it can <emphasis>directly
+ instantiate</emphasis> HornetQ clients and servers in its own application code to
+ perform that functionality. We call this <emphasis>embedding</emphasis> HornetQ.</para>
<para>Examples of applications that might want to do this include any application that needs
very high performance, transactional, persistent messaging but doesn't want the hassle of
writing it all from scratch.</para>
- <para>Embedding HornetQ can be done in very few easy steps. Instantiate the configuration object,
- instantiate the server, start it, and you have a HornetQ running in your virtual
+ <para>Embedding HornetQ can be done in very few easy steps. Instantiate the configuration
+ object, instantiate the server, start it, and you have a HornetQ running in your virtual
machine. It's as simple and easy as that.</para>
<section>
<title>POJO instantiation</title>
<para>You can follow this step-by-step guide:</para>
- <para>Create the configuration object - this contains configuration information for a HornetQ.
- If you want to configure it from a file on the classpath, use <literal
+ <para>Create the configuration object - this contains configuration information for a
+ HornetQ. If you want to configure it from a file on the classpath, use <literal
>FileConfigurationImpl</literal></para>
<programlisting>import org.hornetq.core.config.Configuration;
import org.hornetq.core.config.impl.FileConfiguration;
@@ -66,8 +64,8 @@
config.setAcceptorConfigurations(transports);</programlisting>
<para>You need to instantiate and start HornetQ server. The class <literal
- >org.hornetq.core.server.Messaging</literal> has a few static methods for
- creating servers with common configurations.</para>
+ >org.hornetq.core.server.Messaging</literal> has a few static methods for creating
+ servers with common configurations.</para>
<programlisting>import org.hornetq.core.server.Messaging;
import org.hornetq.core.server.MessagingServer;
@@ -86,13 +84,14 @@
<title>Dependency Frameworks</title>
<para>You may also choose to use a dependency injection framework such as <trademark>JBoss
Micro Container</trademark> or <trademark>Spring Framework</trademark>.</para>
- <para>HornetQ standalone uses JBoss Micro Container as the injection framework.
- <literal>HornetQBootstrapServer</literal> and <literal>hornetq-beans.xml</literal>
- which are part of the HornetQ distribution provide a very complete
- implementation of what's needed to bootstrap the server using JBoss Micro Container. </para>
- <para>When using JBoss Micro Container, you need to provide a XML declaring the <literal
- >MessagingServer</literal> and <literal>Configuration</literal> object, you can also
- inject a security manager and a MBean server if you want, but those are optional.</para>
+ <para>HornetQ standalone uses JBoss Micro Container as the injection framework. <literal
+ >HornetQBootstrapServer</literal> and <literal>hornetq-beans.xml</literal> which are
+ part of the HornetQ distribution provide a very complete implementation of what's needed
+ to bootstrap the server using JBoss Micro Container. </para>
+ <para>When using JBoss Micro Container, you need to provide an XML file declaring the
+ <literal>MessagingServer</literal> and <literal>Configuration</literal> object, you
+ can also inject a security manager and a MBean server if you want, but those are
+ optional.</para>
<para>A very basic XML Bean declaration for the JBoss Micro Container would be:</para>
<programlisting><?xml version="1.0" encoding="UTF-8"?>
@@ -113,8 +112,8 @@
</constructor>
</bean>
</deployment></programlisting>
- <para><literal>HornetQBootstrapServer</literal> provides an easy encapsulation of JBoss Micro
- Container.</para>
+ <para><literal>HornetQBootstrapServer</literal> provides an easy encapsulation of JBoss
+ Micro Container.</para>
<programlisting>HornetQBootstrapServer bootStrap =
new HornetQBootstrapServer(new String[] {"hornetq-beans.xml"});
bootStrap.run();</programlisting>
@@ -154,9 +153,9 @@
</section>
<section>
<title>JMS API</title>
- <para>Connection on an Embedded HornetQ through JMS is also simple. Just
- instantiate <literal>HornetQConnectionFactory</literal> directly. The following
- example illustrates that.</para>
+ <para>Connection on an Embedded HornetQ through JMS is also simple. Just instantiate
+ <literal>HornetQConnectionFactory</literal> directly. The following example
+ illustrates that.</para>
<programlisting>HornetQConnectionFactory cf =
new HornetQConnectionFactory(
new TransportConfiguration(InVMConnectorFactory.class.getName()));
@@ -188,7 +187,7 @@
</section>
<section>
<title>JMS Embedding Example</title>
- <para>Please see <xref linkend="examples.embedded" /> for an example which shows how
- to setup and run HornetQ embedded with JMS.</para>
+ <para>Please see <xref linkend="examples.embedded"/> for an example which shows how to setup
+ and run HornetQ embedded with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/examples.xml
===================================================================
--- trunk/docs/user-manual/en/examples.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/examples.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,11 +16,10 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="examples">
<title>Examples</title>
- <para>The HornetQ distribution comes with a wide variety of run out-of-the-box examples
- demonstrating many of the features.</para>
+ <para>The HornetQ distribution comes with over 65 run out-of-the-box examples demonstrating many
+ of the features.</para>
<para>The examples are available in the distribution, in the <literal>examples</literal>
directory. Examples are split into JMS and core examples. JMS examples show how a particular
feature can be used by a normal JMS client. Core examples show how the equivalent feature
@@ -37,15 +35,14 @@
<para>Here's a listing of the examples with a brief description.</para>
<section id="application-level-failover">
<title>Application-Layer Failover</title>
- <para>HornetQ implements fully transparent automatic failover of connections
- from a live to backup node, this requires no special coding for failover, and is
- described in a different example. Automatic failover requires server
- replication.</para>
- <para>However, HornetQ also supports Application-Layer failover, useful in the
- case that replication is not enabled on the server side.</para>
+ <para>HornetQ implements fully transparent automatic failover of connections from a live
+ to backup node, this requires no special coding for failover, and is described in a
+ different example. Automatic failover requires server replication.</para>
+ <para>However, HornetQ also supports Application-Layer failover, useful in the case that
+ replication is not enabled on the server side.</para>
<para>With Application-Layer failover, it's up to the application to register a JMS
- <literal>ExceptionListener</literal> with HornetQ which will be called
- by HornetQ in the event that connection failure is detected.</para>
+ <literal>ExceptionListener</literal> with HornetQ which will be called by
+ HornetQ in the event that connection failure is detected.</para>
<para>The code in the <literal>ExceptionListener</literal> then recreates the JMS
connection, session, etc on another node and the application can continue.</para>
<para>Application-layer failover is an alternative approach to High Availability (HA).
@@ -61,23 +58,22 @@
as a live-backup pair for high availability (HA), and a client connection
transparently failing over from live to backup when the live server is
crashed.</para>
- <para>HornetQ implements seamless, transparent failover of client connections
- between live and backup servers. This is implemented by the replication of state
- between live and backup nodes. When replication is configured and a live node
- crashes, the client connections can carry on as if nothing happened and carry on
- sending and consuming messages.</para>
+ <para>HornetQ implements seamless, transparent failover of client connections between
+ live and backup servers. This is implemented by the replication of state between
+ live and backup nodes. When replication is configured and a live node crashes, the
+ client connections can carry on as if nothing happened and carry on sending and
+ consuming messages.</para>
</section>
<section>
<title>Automatic Reconnect</title>
<para>The <literal>reconnect-same-node</literal> example demonstrates how HornetQ
- connections can be configured to be resilient to temporary network
- failures.</para>
+ connections can be configured to be resilient to temporary network failures.</para>
<para> In the case of a network failure being detected, either as a result of a failure
to read/write to the connection, or the failure of a pong to arrive back from the
server in good time after a ping is sent, instead of failing the connection
immediately and notifying any user <literal>ExceptionListener</literal> objects,
- HornetQ can be configured to automatically retry the connection, and
- reconnect to the server when it becomes available again across the network.</para>
+ HornetQ can be configured to automatically retry the connection, and reconnect to
+ the server when it becomes available again across the network.</para>
</section>
<section id="examples.browsers">
<title>Browser</title>
@@ -94,8 +90,8 @@
<para>The <literal>bridge</literal> example demonstrates a core bridge deployed on one
server, which consumes messages from a local queue and forwards them to an address
on a second server.</para>
- <para>Core bridges are used to create message flows between any two HornetQ
- servers which are remotely separated. Core bridges are resilient and will cope with
+ <para>Core bridges are used to create message flows between any two HornetQ servers
+ which are remotely separated. Core bridges are resilient and will cope with
temporary connection failure allowing them to be an ideal choice for forwarding over
unreliable connections, e.g. a WAN.</para>
</section>
@@ -109,8 +105,7 @@
<para>The <literal>client-side-load-balancing</literal> example demonstrates how
subsequent connections created from a JMS <literal>ConnectionFactory</literal> can
be created to different nodes of the cluster. In other words it demonstrates how
- HornetQ does client side load balancing of connections across the
- cluster.</para>
+ HornetQ does client side load balancing of connections across the cluster.</para>
</section>
<section>
<title>Clustered Queue</title>
@@ -118,7 +113,7 @@
on two different nodes. The two nodes are configured to form a cluster. We then
create a consumer for the queue on each node, and we create a producer on only one
of the nodes. We then send some messages via the producer, and we verify that both
- consumers receive the sent messages in a round-robin fashio.</para>
+ consumers receive the sent messages in a round-robin fashion.</para>
</section>
<section>
<title>Clustered Standalone</title>
@@ -151,8 +146,8 @@
</section>
<section id="examples.delayed-redelivery">
<title>Delayed Redelivery</title>
- <para>The <literal>delayed-redelivery</literal> example demonstrates how HornetQ
- can be configured to provide a delayed redelivery in the case a message needs to be
+ <para>The <literal>delayed-redelivery</literal> example demonstrates how HornetQ can be
+ configured to provide a delayed redelivery in the case a message needs to be
redelivered.</para>
<para>Delaying redelivery can often be useful in the case that clients regularly fail or
roll-back. Without a delayed redelivery, the system can get into a "thrashing"
@@ -162,26 +157,26 @@
</section>
<section id="divert-example">
<title>Divert</title>
- <para>HornetQ diverts allow messages to be transparently "diverted" from one
+ <para>HornetQ diverts allow messages to be transparently "diverted" or copied from one
address to another with just some simple configuration defined on the server
side.</para>
</section>
<section>
<title>Durable Subscription</title>
<para>The <literal>durable-subscription</literal> example shows you how to use a durable
- subscription with HornetQ. Durable subscriptions are a standard part of JMS,
- please consult the JMS 1.1 specification for full details.</para>
+ subscription with HornetQ. Durable subscriptions are a standard part of JMS, please
+ consult the JMS 1.1 specification for full details.</para>
<para>Unlike non-durable subscriptions, the key function of durable subscriptions is
that the messages contained in them persist longer than the lifetime of the
subscriber - i.e. they will accumulate messages sent to the topic even if there is
- no active subscriber on them. They will also survive server restarts. Note that for
- the messages to be persisted, the messages sent to them must be marked as persistent
- messages. </para>
+ no active subscriber on them. They will also survive server restarts or crashes.
+ Note that for the messages to be persisted, the messages sent to them must be marked
+ as persistent messages. </para>
</section>
<section>
<title>Embedded</title>
- <para>The <literal>embedded</literal> example shows how to embed the HornetQ
- Server within your own code.</para>
+ <para>The <literal>embedded</literal> example shows how to embed the HornetQ server
+ within your own code.</para>
</section>
<section>
<title>HTTP Transport</title>
@@ -195,46 +190,44 @@
before being used by the client code. This objects are called "administered objects"
in JMS terminology.</para>
<para>However, in some cases a JNDI server may not be available or desired. To come to
- the rescue HornetQ also supports the direct instantiation of these
- administered objects on the client side so you don't have to use JNDI for
- JMS.</para>
+ the rescue HornetQ also supports the direct instantiation of these administered
+ objects on the client side so you don't have to use JNDI for JMS.</para>
</section>
<section id="examples.interceptor">
<title>Interceptor</title>
- <para>HornetQ allows an application to use an interceptor to hook into the
- messaging system. Interceptors allow you to handle various message events in HornetQ.</para>
+ <para>HornetQ allows an application to use an interceptor to hook into the messaging
+ system. Interceptors allow you to handle various message events in HornetQ.</para>
</section>
<section id="examples.jaas">
<title>JAAS</title>
- <para>The <literal>jaas</literal> example shows you how to configure HornetQ to
- use JAAS for security. HornetQ can leverage JAAS to delegate user
- authentication and authorization to existing security infrastructure.</para>
+ <para>The <literal>jaas</literal> example shows you how to configure HornetQ to use JAAS
+ for security. HornetQ can leverage JAAS to delegate user authentication and
+ authorization to existing security infrastructure.</para>
</section>
<section id="examples.jmx">
<title>JMX Management</title>
- <para>The <literal>jmx</literal> example shows how to manage HornetQ using
- JMX.</para>
+ <para>The <literal>jmx</literal> example shows how to manage HornetQ using JMX.</para>
</section>
<section id="examples.large-message">
<title>Large Message</title>
<para>The <literal>large-message</literal> example shows you how to send and receive
- very large messages with HornetQ. HornetQ supports the sending and
- receiving of huge messages, much larger than can fit in available RAM on the client
- or server. Effectively the only limit to message size is the amount of disk space
- you have on the server.</para>
+ very large messages with HornetQ. HornetQ supports the sending and receiving of huge
+ messages, much larger than can fit in available RAM on the client or server.
+ Effectively the only limit to message size is the amount of disk space you have on
+ the server.</para>
<para>Large messages are persisted on the server so they can survive a server restart.
- In other words HornetQ doesn't just do a simple socket stream from the
- sender to the consumer.</para>
+ In other words HornetQ doesn't just do a simple socket stream from the sender to the
+ consumer.</para>
</section>
<section id="examples.last-value-queue">
<title>Last-Value Queue</title>
<para>The <literal>last-value-queue</literal> example shows you how to define and deal
- with last-value queues. Last-Value queues are special queues which discard any
+ with last-value queues. Last-value queues are special queues which discard any
messages when a newer message with the same value for a well-defined last-value
property is put in the queue. In other words, a last-value queue only retains the
last value.</para>
<para>A typical example for last-value queue is for stock prices, where you are only
- interested by the latest value for a particular stock.</para>
+ interested by the latest price for a particular stock.</para>
</section>
<section>
<title>Load Balanced Clustered Queue</title>
@@ -243,29 +236,29 @@
<para>We then create a consumer on the queue on each node, and we create a producer on
only one of the nodes. We then send some messages via the producer, and we verify
that both consumers receive the sent messages in a round-robin fashion.</para>
- <para>In other words, HornetQ load balances the sent messages across all
- consumers on the cluster</para>
+ <para>In other words, HornetQ load balances the sent messages across all consumers on
+ the cluster</para>
</section>
<section id="examples.management">
<title>Management</title>
- <para>The <literal>management</literal> example shows how to manage HornetQ
- using JMS Messages to invoke management operations on the server.</para>
+ <para>The <literal>management</literal> example shows how to manage HornetQ using JMS
+ Messages to invoke management operations on the server.</para>
</section>
<section id="examples.management-notifications">
<title>Management Notification</title>
<para>The <literal>management-notification</literal> example shows how to receive
- management notifications from HornetQ using JMS messages. HornetQ
- servers emit management notifications when events of interest occur (consumers are
- created or closed, destinations are created or deleted, security authentication
- fails, etc.).</para>
+ management notifications from HornetQ using JMS messages. HornetQ servers emit
+ management notifications when events of interest occur (consumers are created or
+ closed, destinations are created or deleted, security authentication fails,
+ etc.).</para>
</section>
<section id="examples.consumer-rate-limit">
<title>Message Consumer Rate Limiting</title>
- <para>With HornetQ you can specify a maximum consume rate at which a JMS
- MessageConsumer will consume messages. This can be specified when creating or
- deploying the connection factory.</para>
- <para>If this value is specified then HornetQ will ensure that messages are
- never consumed at a rate higher than the specified rate. This is a form of consumer
+ <para>With HornetQ you can specify a maximum consume rate at which a JMS MessageConsumer
+ will consume messages. This can be specified when creating or deploying the
+ connection factory.</para>
+ <para>If this value is specified then HornetQ will ensure that messages are never
+ consumed at a rate higher than the specified rate. This is a form of consumer
throttling.</para>
</section>
<section id="examples.message-counters">
@@ -280,17 +273,17 @@
period of time before being removed. JMS specification states that clients should
not receive messages that have been expired (but it does not guarantee this will not
happen).</para>
- <para>HornetQ can assign an expiry destination to a given queue so that when
- messages are expired, they are removed from the queue and sent to the expiry
- destination. These "expired" messages can later be consumed from the expiry
- destination for further inspection.</para>
+ <para>HornetQ can assign an expiry destination to a given queue so that when messages
+ are expired, they are removed from the queue and sent to the expiry destination.
+ These "expired" messages can later be consumed from the expiry destination for
+ further inspection.</para>
</section>
<section id="examples.message-group">
<title>Message Group</title>
<para>The <literal>message-group</literal> example shows you how to configure and use
- message groups with HornetQ. Message groups allow you to pin messages so
- they are only consumed by a single consumer. Message groups are sets of messages
- that has the following characteristics:</para>
+ message groups with HornetQ. Message groups allow you to pin messages so they are
+ only consumed by a single consumer. Message groups are sets of messages that has the
+ following characteristics:</para>
<para>
<itemizedlist>
<listitem>
@@ -306,14 +299,14 @@
</section>
<section id="producer-rate-limiting-example">
<title>Message Producer Rate Limiting</title>
- <para>The <literal>producer-rte-limit</literal> example demonstrates how, with HornetQ,
- you can specify a maximum send rate at which a JMS message producer will
- send messages.</para>
+ <para>The <literal>producer-rte-limit</literal> example demonstrates how, with HornetQ,
+ you can specify a maximum send rate at which a JMS message producer will send
+ messages.</para>
</section>
<section id="examples.message-priority">
<title>Message Priority</title>
- <para>Message Priority carries the delivery preference of messages.</para>
- <para> It can be retrieved by the message's standard header field 'JMSPriority' as
+ <para>Message Priority can be used to influence the delivery order for messages.</para>
+ <para>It can be retrieved by the message's standard header field 'JMSPriority' as
defined in JMS specification version 1.1. </para>
<para>The value is of type integer, ranging from 0 (the lowest) to 9 (the highest). When
messages are being delivered, their priorities will effect their order of delivery.
@@ -331,22 +324,22 @@
</section>
<section id="examples.no-consumer-buffering">
<title>No Consumer Buffering</title>
- <para>By default, HornetQ consumers buffer messages from the server in a client
- side buffer before you actually receive them on the client side. This improves
+ <para>By default, HornetQ consumers buffer messages from the server in a client side
+ buffer before you actually receive them on the client side. This improves
performance since otherwise every time you called receive() or had processed the
last message in a <literal>MessageListener onMessage()</literal> method, the HornetQ
- client would have to go the server to request the next message, which
- would then get sent to the client side, if one was available.</para>
- <para>This would involve a network round trip for every message and really reduce
- performance. Therefore, by default, HornetQ pre-fetches messages into a
- buffer on each consumer.</para>
- <para>In some case buffering is not desirable, and HornetQ allows it to be
- switched off. This example demonstrates that.</para>
+ client would have to go the server to request the next message, which would then get
+ sent to the client side, if one was available.</para>
+ <para>This would involve a network round trip for every message and reduce performance.
+ Therefore, by default, HornetQ pre-fetches messages into a buffer on each
+ consumer.</para>
+ <para>In some case buffering is not desirable, and HornetQ allows it to be switched off.
+ This example demonstrates that.</para>
</section>
<section id="examples.paging">
<title>Paging</title>
- <para>The <literal>paging</literal> example shows how HornetQ can support huge
- queues even when the server is running in limited RAM. It does this by transparently
+ <para>The <literal>paging</literal> example shows how HornetQ can support huge queues
+ even when the server is running in limited RAM. It does this by transparently
<emphasis>paging</emphasis> messages to disk, and <emphasis>depaging</emphasis>
them when they are required.</para>
</section>
@@ -359,8 +352,8 @@
<para>All of these standard modes involve sending acknowledgements from the client to
the server. However in some cases, you really don't mind losing messages in event of
failure, so it would make sense to acknowledge the message on the server before
- delivering it to the client. This example demonstrates how HornetQ allows
- this with an extra acknowledgement mode.</para>
+ delivering it to the client. This example demonstrates how HornetQ allows this with
+ an extra acknowledgement mode.</para>
</section>
<section>
<title>Queue</title>
@@ -382,8 +375,8 @@
<section id="examples.scheduled-message">
<title>Scheduled Message</title>
<para>The <literal>scheduled-message</literal> example shows you how to send a scheduled
- message to a JMS Queue with HornetQ. Scheduled messages won't get delivered
- until a specified time in the future.</para>
+ message to a JMS Queue with HornetQ. Scheduled messages won't get delivered until a
+ specified time in the future.</para>
</section>
<section>
<title>Security</title>
@@ -392,15 +385,15 @@
</section>
<section id="asynchronous-send-acknowledgements-example">
<title>Send Acknowledgements</title>
- <para>The <literal>send-acknowledgements</literal> example shows you how to use HornetQ's
- advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
+ <para>The <literal>send-acknowledgements</literal> example shows you how to use
+ HornetQ's advanced <emphasis>asynchronous send acknowledgements</emphasis> feature
to obtain acknowledgement from the server that sends have been received and
processed in a separate stream to the sent messages. </para>
</section>
<section>
<title>Static Message Selector</title>
- <para>The <literal>static-selector</literal> example shows you how to configure a HornetQ
- core queue with static message selectors (filters).</para>
+ <para>The <literal>static-selector</literal> example shows you how to configure a
+ HornetQ core queue with static message selectors (filters).</para>
</section>
<section>
<title>Static Message Selector Using JMS</title>
@@ -409,17 +402,16 @@
</section>
<section>
<title>SSL Transport</title>
- <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with HornetQ
- to send and receive message.</para>
+ <para>The <literal>ssl-enabled</literal> shows you how to configure SSL with HornetQ to
+ send and receive message.</para>
</section>
<section>
<title>Symmetric Cluster</title>
<para>The <literal>symmetric-cluster</literal> example demonstrates a symmetric cluster
set-up with HornetQ.</para>
- <para>HornetQ has extremely flexible clustering which allows you to set-up
- servers in many different topologies. The most common topology that you'll perhaps
- be familiar with if you are used to application server clustering is a symmetric
- cluster.</para>
+ <para>HornetQ has extremely flexible clustering which allows you to set-up servers in
+ many different topologies. The most common topology that you'll perhaps be familiar
+ with if you are used to application server clustering is a symmetric cluster.</para>
<para>With a symmetric cluster, the cluster is homogeneous, i.e. each node is configured
the same as every other node, and every node is connected to every other node in the
cluster.</para>
@@ -434,9 +426,9 @@
</section>
<section id="topic-hierarchy-example">
<title>Topic Hierarchy</title>
- <para>HornetQ supports topic hierarchies. With a topic hierarchy you can
- register a subscriber with a wild-card and that subscriber will receive any messages
- sent to an address that matches the wild card.</para>
+ <para>HornetQ supports topic hierarchies. With a topic hierarchy you can register a
+ subscriber with a wild-card and that subscriber will receive any messages sent to an
+ address that matches the wild card.</para>
</section>
<section>
<title>Topic Selector 1</title>
@@ -456,8 +448,8 @@
<section>
<title>XA Heuristic</title>
<para>The <literal>xa-heuristic</literal> example shows you how to make an XA heuristic
- decision through HornetQ Management Interface. A heuristic decision is a
- unilateral decision to commit or rollback an XA transaction branch after it has been
+ decision through HornetQ Management Interface. A heuristic decision is a unilateral
+ decision to commit or rollback an XA transaction branch after it has been
prepared.</para>
</section>
<section>
@@ -482,8 +474,7 @@
directory and type <literal>ant</literal></para>
<section id="examples.embedded">
<title>Embedded</title>
- <para>This example shows how to embed the HornetQ server within your own
- code.</para>
+ <para>This example shows how to embed the HornetQ server within your own code.</para>
</section>
</section>
<section>
@@ -503,8 +494,8 @@
</section>
<section>
<title>Resource Adapter Configuration</title>
- <para>This example demonstrates how to configure several properties on the HornetQ
- JCA resource adaptor.</para>
+ <para>This example demonstrates how to configure several properties on the HornetQ JCA
+ resource adaptor.</para>
</section>
<section id="jms-bridge-example">
<title>JMS Bridge</title>
Modified: trunk/docs/user-manual/en/flow-control.xml
===================================================================
--- trunk/docs/user-manual/en/flow-control.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/flow-control.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="flow-control">
<title>Flow Control</title>
<para>Flow control is used to limit the flow of data between a client and server, or a server and
@@ -28,19 +26,20 @@
messages. For performance reasons clients normally buffer messages before delivering to the
consumer via the <literal>receive()</literal> method or asynchronously via a message
listener. If the consumer cannot process messages as fast as they are being delivered and
- stored in the internal buffer, then you could end up with a situation where messages just
- keep building up and are not processed for a long time. </para>
+ stored in the internal buffer, then you could end up with a situation where messages would
+ keep building up possibly causing out of memory on the client if they cannot be processed
+ in time.</para>
<section id="flow-control.consumer.window">
<title>Window-Based Flow Control</title>
- <para>By default, HornetQ consumers buffer messages from the server in a client
- side buffer before the client consumes them. This improves performance: otherwise every
- time the client consumes a message, HornetQ would have to go the server to
- request the next message. In turn, this message would then get sent to the client side,
- if one was available.</para>
+ <para>By default, HornetQ consumers buffer messages from the server in a client side buffer
+ before the client consumes them. This improves performance: otherwise every time the
+ client consumes a message, HornetQ would have to go the server to request the next
+ message. In turn, this message would then get sent to the client side, if one was
+ available.</para>
<para>A network round trip would be involved for <emphasis>every</emphasis> message and
considerably reduce performance.</para>
- <para>To prevent this, HornetQ pre-fetches messages into a buffer on each consumer.
- The total maximum size of messages (in bytes) that will be buffered on each consumer is
+ <para>To prevent this, HornetQ pre-fetches messages into a buffer on each consumer. The
+ total maximum size of messages (in bytes) that will be buffered on each consumer is
determined by the <literal>consumer-window-size</literal> parameter.</para>
<para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024
bytes).</para>
@@ -51,8 +50,8 @@
</listitem>
<listitem>
<para><literal>0</literal> to not buffer any messages. See <xref
- linkend="examples.no-consumer-buffering" />
- for working example of a consumer with no buffering.</para>
+ linkend="examples.no-consumer-buffering"/> for working example of a consumer
+ with no buffering.</para>
</listitem>
<listitem>
<para><literal>>0</literal> for a buffer with the given maximum size in
@@ -89,6 +88,8 @@
0 (for no buffer at all). This will prevent the slow consumer from buffering
any messages on the client side. Messages will remain on the server side ready
to be consumed by other consumers.</para>
+ <para>Setting this to -1 can give deterministic distribution between multiple
+ consumers on a queue.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -98,9 +99,9 @@
find the optimal value, but a value of 1MiB is fine in most cases.</para>
<section id="flow-control.core.api">
<title>Using Core API</title>
- <para>If HornetQ Core API is used, the consumer window size is specified by
- <literal>ClientSessionFactory.setConsumerWindowSize()</literal> method and some of
- the <literal>ClientSession.createConsumer()</literal> methods.</para>
+ <para>If HornetQ Core API is used, the consumer window size is specified by <literal
+ >ClientSessionFactory.setConsumerWindowSize()</literal> method and some of the
+ <literal>ClientSession.createConsumer()</literal> methods.</para>
</section>
<section>
<title>Using JMS</title>
@@ -120,8 +121,8 @@
<para>If the connection factory is directly instantiated, the consumer window size is
specified by <literal>HornetQConnectionFactory.setConsumerWindowSize()</literal>
method.</para>
- <para>Please see <xref linkend="examples.no-consumer-buffering" /> for an example which shows how to configure
- HornetQ to prevent consumer buffering when dealing with slow
+ <para>Please see <xref linkend="examples.no-consumer-buffering"/> for an example which
+ shows how to configure HornetQ to prevent consumer buffering when dealing with slow
consumers.</para>
</section>
</section>
@@ -134,8 +135,8 @@
consumption rate specified in units of messages per second. Setting this to <literal
>-1</literal> disables rate limited flow control. The default value is <literal
>-1</literal>.</para>
- <para>Please see <xref linkend="examples.consumer-rate-limit" /> for a working example
- of limiting consumer rate.</para>
+ <para>Please see <xref linkend="examples.consumer-rate-limit"/> for a working example of
+ limiting consumer rate.</para>
<section id="flow-control.rate.core.api">
<title>Using Core API</title>
<para>If the HornetQ core API is being used the rate can be set via the <literal
@@ -167,34 +168,33 @@
slow rate limit and a high window based limit the clients internal buffer would
soon fill up with messages.</para>
</note>
- <para>Please see <xref linkend="examples.consumer-rate-limit" /> for an example which shows
- how to configure HornetQ to prevent consumer buffering when dealing with slow
+ <para>Please see <xref linkend="examples.consumer-rate-limit"/> for an example which
+ shows how to configure HornetQ to prevent consumer buffering when dealing with slow
consumers.</para>
</section>
</section>
</section>
<section>
<title>Producer flow control</title>
- <para>HornetQ also can limit the amount of data sent from a client to a server to
- prevent the server being overwhelmed.</para>
+ <para>HornetQ also can limit the amount of data sent from a client to a server to prevent the
+ server being overwhelmed.</para>
<section>
<title>Window based flow control</title>
- <para>HornetQ clients maintain a buffer of commands that have been sent to the
- server, thus provides a form of flow control. Please see <xref
- linkend="command-buffering"/> for more information on
- this.</para>
+ <para>HornetQ clients maintain a buffer of commands that have been sent to the server, thus
+ provides a form of flow control. Please see <xref linkend="command-buffering"/> for more
+ information on this.</para>
</section>
<section>
<title>Rate limited flow control</title>
- <para>HornetQ also allows the rate a producer can emit message to be limited, in
- units of messages per second. By specifying such a rate, HornetQ will ensure
- that producer never produces messages at a rate higher than that specified.</para>
+ <para>HornetQ also allows the rate a producer can emit message to be limited, in units of
+ messages per second. By specifying such a rate, HornetQ will ensure that producer never
+ produces messages at a rate higher than that specified.</para>
<para>The rate must be a positive integer to enable and is the maximum desired message
consumption rate specified in units of messages per second. Setting this to <literal
>-1</literal> disables rate limited flow control. The default value is <literal
>-1</literal>.</para>
- <para>Please see the <xref linkend="producer-rate-limiting-example" />
- for a working example of limiting producer rate.</para>
+ <para>Please see the <xref linkend="producer-rate-limiting-example"/> for a working example
+ of limiting producer rate.</para>
<section id="flow-control.producer.rate.core.api">
<title>Using Core API</title>
<para>If the HornetQ core API is being used the rate can be set via the <literal
Modified: trunk/docs/user-manual/en/ha.xml
===================================================================
--- trunk/docs/user-manual/en/ha.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/ha.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="ha">
<title>High Availability and Failover</title>
<para>We define high availability as the <emphasis>ability for the system to continue
@@ -25,18 +23,17 @@
availability is <emphasis>failover</emphasis> which we define as the <emphasis>ability for
client connections to migrate from one server to another in event of server failure so
client applications can continue to operate</emphasis>.</para>
- <para>HornetQ provides high availability by replicating servers in pairs. It also
- provides both 100% transparent client failover and application-level client failover.</para>
+ <para>HornetQ provides high availability by replicating servers in pairs. It also provides both
+ automatic client failover and application-level client failover.</para>
<section>
<title>Server replication</title>
<para>HornetQ allows pairs of servers to be linked together as <emphasis>live -
backup</emphasis> pairs. In this release there is a single backup server for each
live server. Backup servers are not operational until failover occurs. In later releases
we will most likely support replication onto multiple backup servers.</para>
- <para>When a <emphasis>live - backup</emphasis> pair is configured, HornetQ ensures
- that the live server state is replicated to the backup server. Replicated state includes
- session state, and also global state such as the set of queues and addresses on the
- server. </para>
+ <para>When a <emphasis>live - backup</emphasis> pair is configured, HornetQ ensures that the
+ live server state is replicated to the backup server. Replicated state includes session
+ state, and also global state such as the set of queues and addresses on the server. </para>
<para>When a client fails over from live to backup server, the backup server will already
have the correct global and session state, so the client will be able to resume its
session(s) on the backup server as if nothing happened.</para>
@@ -48,13 +45,13 @@
before replicating the next piece of data.</para>
<section id="configuring.live.backup">
<title>Configuring live-backup pairs</title>
- <para>First, on the live server, in <literal>hornetq-configuration.xml</literal> configure
- the live server with knowledge of its backup server. This is done by specifying a
- <literal>backup-connector-ref</literal> element. This element references a
- connector, also specified on the live server which contains knowledge of how to
- connect to the backup server. Here's a snippet from <literal
- >hornetq-configuration.xml</literal> showing a live server configured with a backup
- server:</para>
+ <para>First, on the live server, in <literal>hornetq-configuration.xml</literal>
+ configure the live server with knowledge of its backup server. This is done by
+ specifying a <literal>backup-connector-ref</literal> element. This element
+ references a connector, also specified on the live server which contains knowledge
+ of how to connect to the backup server. Here's a snippet from <literal
+ >hornetq-configuration.xml</literal> showing a live server configured with a
+ backup server:</para>
<programlisting><backup-connector-ref connector-name="backup-connector"/>
<!-- Connectors -->
@@ -72,8 +69,9 @@
</connector>
</connectors></programlisting>
- <para>Secondly, on the backup server, also in <literal>hornetq-configuration.xml</literal> ,
- the element <literal>backup</literal> must be set to true. I.e. :</para>
+ <para>Secondly, on the backup server, also in <literal
+ >hornetq-configuration.xml</literal> , the element <literal>backup</literal>
+ must be set to true. I.e. :</para>
<programlisting><backup>true</backup>
</programlisting>
</section>
@@ -94,9 +92,8 @@
may diverge. After such a failure, at the next available opportunity the <literal
>B</literal> server should be taken down, and its <literal>data</literal>
directory copied back to the <literal>L</literal> server. Live and backup servers
- can then be restarted. In this release of HornetQ we do not provide any
- automatic facility for re-assigning a backup node with a live node while it is
- running.</para>
+ can then be restarted. In this release of HornetQ we do not provide any automatic
+ facility for re-assigning a backup node with a live node while it is running.</para>
<para>For a backup server to function correctly it's also important that it has the same
set of bridges, predefined queues, cluster connections, broadcast groups and
discovery groups as defined on the live node. The easiest way to ensure this is just
@@ -119,37 +116,37 @@
</section>
<section id="ha.client.automatic">
<title>Automatic client failover</title>
- <para>HornetQ clients can be configured with knowledge of live and backup servers,
- so that in event of connection failure of the client - live server connection, the
- client will detect this and reconnect its sessions to the backup server. Because of
- server replication, then backup server will already have those sessions in the same
- state they were left on the live server and the client will be able to reconnect them
- and resume them 100% transparently as if nothing happened.</para>
- <para>For automatic failover HornetQ requires <emphasis>zero</emphasis> coding of
- special failover code on the client or server. This differs from other messaging systems
- which intrusively require you to code special failover handling code. HornetQ
- automatic failover preserves all your normal JMS or core API semantics and allows your
- client code to continue 100% uninterrupted on event of connection failure and failover
- from a live to a backup server.</para>
- <para>HornetQ clients detect connection failure when it has not received packets
- from the server within the time given by <literal>client-failure-check-period</literal>
- as explained in section <xref linkend="connection-ttl"/>. If the client does not receive
+ <para>HornetQ clients can be configured with knowledge of live and backup servers, so that
+ in event of connection failure of the client - live server connection, the client will
+ detect this and reconnect its sessions to the backup server. Because of server
+ replication, then backup server will already have those sessions in the same state they
+ were left on the live server and the client will be able to reconnect them and resume
+ them 100% transparently as if nothing happened.</para>
+ <para>For automatic failover HornetQ requires <emphasis>zero</emphasis> coding of special
+ failover code on the client or server. This differs from other messaging systems which
+ intrusively require you to code special failover handling code. HornetQ automatic
+ failover preserves all your normal JMS or core API semantics and allows your client code
+ to continue 100% uninterrupted on event of connection failure and failover from a live
+ to a backup server.</para>
+ <para>HornetQ clients detect connection failure when it has not received packets from the
+ server within the time given by <literal>client-failure-check-period</literal> as
+ explained in section <xref linkend="connection-ttl"/>. If the client does not receive
data in good time, it will assume the connection has failed and attempt failover.</para>
- <para>HornetQ clients can be configured with the list of live-backup server pairs in
- a number of different ways. They can be configured explicitly or probably the most
- common way of doing this is to use <emphasis>server discovery</emphasis> for the client
- to automatically discover the list. For full details on how to configure clients please
- see <xref linkend="clusters.server-discovery"/>.</para>
+ <para>HornetQ clients can be configured with the list of live-backup server pairs in a
+ number of different ways. They can be configured explicitly or probably the most common
+ way of doing this is to use <emphasis>server discovery</emphasis> for the client to
+ automatically discover the list. For full details on how to configure clients please see
+ <xref linkend="clusters.server-discovery"/>.</para>
<para>Sometimes you want a client to failover onto a backup server even if the live server
is just cleanly shutdown rather than having crashed or the connection failed. To
configure this you can set the property <literal>FailoverOnServerShutdown</literal> to
- false either on the <literal>HornetQConnectionFactory</literal> if you're using JMS or in
- the <literal>hornetq-jms.xml</literal> file when you define the connection factory, or if
- using core by setting the property directly on the <literal
+ false either on the <literal>HornetQConnectionFactory</literal> if you're using JMS or
+ in the <literal>hornetq-jms.xml</literal> file when you define the connection factory,
+ or if using core by setting the property directly on the <literal
>ClientSessionFactoryImpl</literal> instance after creation. The default value for
this property is <literal>false</literal>, this means that by default <emphasis>HornetQ
- clients will not failover to a backup server if the live server is simply
- shutdown cleanly.</emphasis></para>
+ clients will not failover to a backup server if the live server is simply shutdown
+ cleanly.</emphasis></para>
<para>For a fully functional example of automatic failover, please see <xref
linkend="automatic-failover"/>.</para>
</section>
@@ -166,13 +163,12 @@
live server.</para>
<para>To implement application-level failover, if you're using JMS then you need to code an
<literal>ExceptionListener</literal> class on the JMS connection. The <literal
- >ExceptionListener</literal> will be called by HornetQ in the event that
- connection failure is detected. In your <literal>ExceptionListener</literal> you would
- close your old JMS connections, potentially look up new connection factory instances
- from JNDI and creating new connections. In this case you may well be using
- <ulink url="http://www.jboss.org/community/wiki/JBossHAJNDIImpl">HA-JNDI</ulink>
- to ensure that the new connection factory is looked up from a different
- server.</para>
+ >ExceptionListener</literal> will be called by HornetQ in the event that connection
+ failure is detected. In your <literal>ExceptionListener</literal> you would close your
+ old JMS connections, potentially look up new connection factory instances from JNDI and
+ creating new connections. In this case you may well be using <ulink
+ url="http://www.jboss.org/community/wiki/JBossHAJNDIImpl">HA-JNDI</ulink> to ensure
+ that the new connection factory is looked up from a different server.</para>
<para>For a working example of application-level failover, please see <xref
linkend="application-level-failover"/>.</para>
<para>If you are using the core API, then the procedure is very similar: you would code a
Modified: trunk/docs/user-manual/en/images/architecture1.jpg
===================================================================
(Binary files differ)
Modified: trunk/docs/user-manual/en/images/architecture2.jpg
===================================================================
(Binary files differ)
Modified: trunk/docs/user-manual/en/images/architecture3.jpg
===================================================================
(Binary files differ)
Modified: trunk/docs/user-manual/en/interoperability.xml
===================================================================
--- trunk/docs/user-manual/en/interoperability.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/interoperability.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="interoperability">
<title>Interoperability</title>
<section>
@@ -26,28 +24,29 @@
Stomp clients to communicate with Stomp Brokers. <ulink
url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> is a server that
can act as a Stomp broker and proxy the Stomp protocol to the standard JMS API.
- Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and use
- any of the available stomp clients. These include clients written in C, C++, c# and .net
- etc.</para>
- <para>To run StompConnect first start the HornetQ server and make sure that it is
- using JNDI.</para>
+ Consequently, using StompConnect it is possible to turn HornetQ into a Stomp Broker and
+ use any of the available stomp clients. These include clients written in C, C++, c# and
+ .net etc.</para>
+ <para>To run StompConnect first start the HornetQ server and make sure that it is using
+ JNDI.</para>
<para>Stomp requires the file <literal>jndi.properties</literal> to be available on the
classpath. This should look something like:</para>
<programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.provider.url=jnp://localhost:1099
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces</programlisting>
- <para>Make sure this file is in the classpath along with the StompConnect jar and the HornetQ
- jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
- <para>HornetQ will shortly be implementing the Stomp protocol directly, so you won't
- have to use StompConnect to be able to use HornetQ with Stomp clients.</para>
+ <para>Make sure this file is in the classpath along with the StompConnect jar and the
+ HornetQ jars and simply run <literal>java org.codehaus.stomp.jms.Main</literal>.</para>
+ <para>HornetQ will shortly be implementing the Stomp protocol directly, so you won't have to
+ use StompConnect to be able to use HornetQ with Stomp clients.</para>
+ <para>A list of STOMP clients is available <ulink url="http://stomp.codehaus.org/Clients"
+ >here.</ulink></para>
</section>
<section>
- <title>AMQP</title>
- <para>AMQP support coming soon!</para>
- </section>
- <section>
<title>REST</title>
<para>REST support coming soon!</para>
</section>
-
+ <section>
+ <title>AMQP</title>
+ <para>AMQP support coming soon!</para>
+ </section>
</chapter>
Modified: trunk/docs/user-manual/en/jms-core-mapping.xml
===================================================================
--- trunk/docs/user-manual/en/jms-core-mapping.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/jms-core-mapping.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,16 +16,14 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="jms-core-mapping">
<title>Mapping JMS Concepts to the Core API</title>
- <para>This chapter describes how JMS destinations are mapped to HornetQ core
- queues.</para>
- <para>HornetQ core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS
- topic is implemented in core as an address (the topic name) with zero or more queues bound
- to it. Each queue bound to that address represents a topic subscription. Likewise, a JMS
- queue is implemented as an address (the JMS queue name) with one single queue bound to it
- which represents the JMS queue.</para>
+ <para>This chapter describes how JMS destinations are mapped to HornetQ addresses.</para>
+ <para>HornetQ core is JMS-agnostic. It does not have any concept of a JMS topic. A JMS topic is
+ implemented in core as an address (the topic name) with zero or more queues bound to it.
+ Each queue bound to that address represents a topic subscription. Likewise, a JMS queue is
+ implemented as an address (the JMS queue name) with one single queue bound to it which
+ represents the JMS queue.</para>
<para>By convention, all JMS queues map to core queues where the core queue name has the string
<literal>jms.queue.</literal> prepended to it. E.g. the JMS queue with the name
"orders.europe" would map to the core queue with the name "jms.queue.orders.europe". The
Modified: trunk/docs/user-manual/en/large-messages.xml
===================================================================
--- trunk/docs/user-manual/en/large-messages.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/large-messages.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,18 +16,17 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="large-messages">
<title>Large Messages</title>
- <para>HornetQ supports sending and receiving of huge messages, even when the client and
- server are running with limited memory. The only limit to the size of a message that can be
- sent or consumed is the amount of disk space you have available. We have tested sending and
- consuming messages up to 8 GiB in size with a client and server running in just 50MiB of
+ <para>HornetQ supports sending and receiving of huge messages, even when the client and server
+ are running with limited memory. The only realistic limit to the size of a message that can
+ be sent or consumed is the amount of disk space you have available. We have tested sending
+ and consuming messages up to 8 GiB in size with a client and server running in just 50MiB of
RAM!</para>
<para>To send a large message, the user can set an <literal>InputStream</literal> on a message
- body, and when that message is sent, HornetQ will read the <literal
- >InputStream</literal>. A <literal>FileInputStream</literal> could be used for example
- to send a huge message from a huge file on disk.</para>
+ body, and when that message is sent, HornetQ will read the <literal>InputStream</literal>. A
+ <literal>FileInputStream</literal> could be used for example to send a huge message from
+ a huge file on disk.</para>
<para>As the <literal>InputStream</literal> is read the data is sent to the server as a stream
of fragments. The server persists these fragments to disk as it receives them and when the
time comes to deliver them to a consumer they are read back of the disk, also in fragments
@@ -48,7 +46,7 @@
...
-<large-message-directory> *** type any folder you choose *** </large-message-directory>
+<large-message-directory>/data/large-messages</large-message-directory>
...
@@ -62,11 +60,11 @@
<para>Any message large than a certain size is considered a large message. Large messages
will be split up and sent in fragments. This is determined by the parameter <literal
>min-large-message-size</literal></para>
- <para>The default value is 100KiB.</para>
+ <para>The default value is 100KiB.</para>
<section id="large-messages.core.config">
<title>Using Core API</title>
- <para>If the HornetQ Core API is used, the minimal large message size is
- specified by <literal>ClientSessionFactory.setMinLargeMessageSize</literal>.</para>
+ <para>If the HornetQ Core API is used, the minimal large message size is specified by
+ <literal>ClientSessionFactory.setMinLargeMessageSize</literal>.</para>
<programlisting>ClientSessionFactory factory =
new ClientSessionFactoryImpl(new
TransportConfiguration(NettyConnectorFactory.class.getName()), null);
@@ -96,12 +94,12 @@
</section>
<section>
<title>Streaming large messages</title>
- <para>HornetQ supports setting the body of messages using input and output streams
- (<literal>java.lang.io</literal>)</para>
+ <para>HornetQ supports setting the body of messages using input and output streams (<literal
+ >java.lang.io</literal>)</para>
<para>These streams are then used directly for sending (input streams) and receiving (output
streams) messages.</para>
- <para>When receiving messages there are 2 ways to deal with the output stream you may choose
- to block while the output stream is recovered using the method <literal
+ <para>When receiving messages there are 2 ways to deal with the output stream; you may
+ choose to block while the output stream is recovered using the method <literal
>ClientMessage.saveOutputStream</literal> or alternatively using the method <literal
>ClientMessage.setOutputstream</literal> which will asynchronously write the message
to the stream. If you choose the latter the consumer must be kept alive until the
@@ -179,10 +177,10 @@
</section>
<section id="large-messages.streaming.over.jms">
<title>Streaming over JMS</title>
- <para>When using JMS, HornetQ maps the streaming methods on the core API (see
- <xref linkend="large-messages.ClientMessageAPI"/>) by setting object properties
- . You can use the method <literal>Message.setObjectProperty</literal> to set the
- input and output streams.</para>
+ <para>When using JMS, HornetQ maps the streaming methods on the core API (see <xref
+ linkend="large-messages.ClientMessageAPI"/>) by setting object properties . You
+ can use the method <literal>Message.setObjectProperty</literal> to set the input and
+ output streams.</para>
<para>The <literal>InputStream</literal> can be defined through the JMS Object Property
JMS_HQ_InputStream on messages being sent:</para>
<programlisting>
@@ -224,8 +222,8 @@
<section>
<title>Streaming Alternative</title>
<para>If you choose not to use the <literal>InputStream</literal> or <literal
- >OutputStream</literal> capability of HornetQ You could still access the
- data directly in an alternative fashion.</para>
+ >OutputStream</literal> capability of HornetQ You could still access the data
+ directly in an alternative fashion.</para>
<para>On the Core API just get the bytes of the body as you normally would.</para>
<programlisting>ClientMessage msg = consumer.receive();
@@ -247,28 +245,23 @@
// Do whatever you want with the data
} </programlisting>
</section>
-
<section id="large-messages.cache.client">
- <title>Cache Large Messages on client</title>
-
- <para>LargeMessages are transfered like a streaming from server to client.
- The message is broken into smaller packets and as the message is read more
- packets will be received. Because of that the body of the large message
- can be read only once, and by consequence a received message can be sent to another producer only once.
- The JMS Bridge for instance won't be able to resend a large message in case of failure</para>
-
- <para>To solve this problem, you can enable the property <literal>cache-large-message-client</literal> on the connection factory.
- If you enable this property the client consumer
- will create a temporary file to hold the large message content, so it
- would be possible to resend large messages.</para>
-
- <note>Use this option on the connection factory used by the JMS Bridge if the JMS Bridge is being used for large messages.</note>
-
+ <title>Cache Large Messages on client</title>
+ <para>LargeMessages are transferred by streaming from server to client. The message is
+ broken into smaller packets and as the message is read more packets will be received.
+ Because of that the body of the large message can be read only once, and by consequence
+ a received message can be sent to another producer only once. The JMS Bridge for
+ instance won't be able to resend a large message in case of failure</para>
+ <para>To solve this problem, you can enable the property <literal
+ >cache-large-message-client</literal> on the connection factory. If you enable this
+ property the client consumer will create a temporary file to hold the large message
+ content, so it would be possible to resend large messages.</para>
+ <note>Use this option on the connection factory used by the JMS Bridge if the JMS Bridge is
+ being used for large messages.</note>
</section>
-
<section id="large-messages.example">
<title>Large message example</title>
- <para>Please see <xref linkend="examples.large-message" /> for an example which
- shows how large message is configured and used with JMS.</para>
+ <para>Please see <xref linkend="examples.large-message"/> for an example which shows how
+ large message is configured and used with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/libaio.xml
===================================================================
--- trunk/docs/user-manual/en/libaio.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/libaio.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,15 +16,16 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="libaio">
<title>Libaio Native Libraries</title>
- <para>HornetQ distributes a native library, used as a bridge between HornetQ and
- linux libaio.</para>
+ <para>HornetQ distributes a native library, used as a bridge between HornetQ and linux
+ libaio.</para>
<para><literal>libaio</literal> is a library, developed as part of the linux kernel project.
With <literal>libaio</literal> we submit writes to the operating system where they are
processed asynchronously. Some time later the OS will call our code back when they have been
processed.</para>
+ <para>We use this in our high performance journal if configured to do so, please see <xref
+ linkend="persistence"/>.</para>
<para>These are the native libraries distributed by HornetQ:</para>
<itemizedlist>
<listitem>
@@ -38,13 +38,13 @@
<para>libHornetQAIO_ia64.so - Itanium 64 bits</para>
</listitem>
</itemizedlist>
- <para>When using libaio, HornetQ will always try loading these files as long as they are
- on the <link linkend="using-server.library.path">library path</link>.</para>
+ <para>When using libaio, HornetQ will always try loading these files as long as they are on the
+ <link linkend="using-server.library.path">library path</link>.</para>
<section>
<title>Compiling the native libraries</title>
- <para>Case you are using Linux on a platform other than x86_32, x86_64 or IA64 (Itanium),
- (for example IBM POWER) you may need to compile the native library, since we do not
- distribute binaries for those platforms with the release.</para>
+ <para>In the case that you are using Linux on a platform other than x86_32, x86_64 or IA64
+ (Itanium), (for example IBM POWER) you may need to compile the native library, since we
+ do not distribute binaries for those platforms with the release.</para>
<section>
<title>Install requirements</title>
<note>
@@ -118,11 +118,11 @@
...</programlisting>
<para>The produced library will be at <literal
- >./native-src/src/.libs/libHornetQLibAIO.so</literal>. Simply move that file over
- <literal>bin</literal> on the distribution or the place you have chosen on the
+ >./native-src/src/.libs/libHornetQLibAIO.so</literal>. Simply move that file
+ over <literal>bin</literal> on the distribution or the place you have chosen on the
<link linkend="using-server.library.path">library path</link>.</para>
- <para>If you want to perform changes on the HornetQ libaio code, you could just
- call make directly at the <literal>native-src</literal> directory.</para>
+ <para>If you want to perform changes on the HornetQ libaio code, you could just call
+ make directly at the <literal>native-src</literal> directory.</para>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/logging.xml
===================================================================
--- trunk/docs/user-manual/en/logging.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/logging.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,13 +16,12 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="logging">
<title>Logging</title>
- <para>HornetQ uses standard <ulink url="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/">JDK
- logging</ulink>, (a.k.a Java-Util-Logging: JUL), for all its logging. This means we have
- no dependencies on any third party logging framework. Users can provide their own logging
- handler to use or alternatively use the log4j handler supplied by HornetQ.</para>
+ <para>HornetQ uses standard <ulink url="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/"
+ >JDK logging</ulink>, (a.k.a Java-Util-Logging: JUL), for all its logging. This means we
+ have no dependencies on any third party logging framework. Users can provide their own
+ logging handler to use or alternatively use the log4j handler supplied by HornetQ.</para>
<para>The handlers are configured via the JUL <literal>logging.properties</literal> file. This
default location for this file is under the <literal>lib</literal> directory found in the
Java home directory but it can be overridden by setting the <literal
@@ -38,14 +36,16 @@
redirects this to the JUL logger. This is set via a system property, <literal
>-Dorg.jboss.logging.Logger.pluginClass=org.hornetq.integration.logging.HornetQLoggerPlugin</literal>.
This is only needed when starting the standalone server and is set in the run script. This
- is not a problem if you are embedding HornetQ in your own code as the Microcontainer
- won't be being used.</para>
- <para>If you want configure your client's logging, make sure you provide a <literal>logging.properties</literal>
- file and set the <literal>java.util.logging.config.file</literal> property on client startup</para>
+ is not a problem if you are embedding HornetQ in your own code as the Microcontainer won't
+ be being used.</para>
+ <para>If you want configure your client's logging, make sure you provide a <literal
+ >logging.properties</literal> file and set the <literal
+ >java.util.logging.config.file</literal> property on client startup</para>
<section>
<title>Log4j Configuration</title>
- <para>HornetQ supplies a JUL Log4j handler that can be used instead of the defaults.
- To use this simply edit the logging.properties file as such:</para>
+ <para>HornetQ supplies a JUL Log4j handler that can be used instead of the defaults if you
+ prefer to work with log4j logs. To use this simply edit the logging.properties file as
+ such:</para>
<programlisting>handlers=org.hornetq.integration.logging.Log4jLoggerHandler</programlisting>
<para>You will also need to download the Log4j jars and place them in the <literal
>lib</literal> directory and also provide a log4j configuration and place it on the
@@ -53,8 +53,8 @@
</section>
<section>
<title>Logging With The JBoss Application Server</title>
- <para>When HornetQ is deployed within the Application Server then it will still use
- JUL however the logging is redirected to the default JBoss logger. For more information
- on this refer to the JBoss documentation.</para>
+ <para>When HornetQ is deployed within the Application Server then it will still use JUL
+ however the logging is redirected to the default JBoss logger. For more information on
+ this refer to the JBoss documentation.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/management.xml
===================================================================
--- trunk/docs/user-manual/en/management.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/management.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="management">
<title>Management</title>
<para>HornetQ has an extensive management API that allows a user to modify a server
@@ -63,18 +61,16 @@
</itemizedlist>
<para>The way to invoke a <emphasis>management operations</emphasis> depends whether JMX, core
messages, or JMS messages are used.</para>
-
<note>
- <para>A few management operations requires a <literal>filter</literal> parameter to chose which
- messages are involved by the operation. Passing
- <literal>null</literal> or an empty string means that the management operation will be performed
- on <emphasis>all messages</emphasis>.</para>
+ <para>A few management operations requires a <literal>filter</literal> parameter to chose
+ which messages are involved by the operation. Passing <literal>null</literal> or an
+ empty string means that the management operation will be performed on <emphasis>all
+ messages</emphasis>.</para>
</note>
-
<section>
<title>Core Management API</title>
- <para>HornetQ defines a core management API to manage core resources. For full
- details of the API please consult the javadoc. In summary:</para>
+ <para>HornetQ defines a core management API to manage core resources. For full details of
+ the API please consult the javadoc. In summary:</para>
<section>
<title>Core Server Management</title>
<itemizedlist>
@@ -84,8 +80,8 @@
<literal>createQueue()</literal> or <literal>deployQueue()</literal> or
<literal>destroyQueue()</literal>)on the <literal
>HornetQServerControl</literal> (with the ObjectName <literal
- >org.hornetq:module=Core,type=Server</literal> or the resource name
- <literal>core.server</literal>)</para>
+ >org.hornetq:module=Core,type=Server</literal> or the resource name <literal
+ >core.server</literal>)</para>
<para><literal>createQueue</literal> will fail if the queue already exists while
<literal>deployQueue</literal> will do nothing.</para>
</listitem>
@@ -120,20 +116,18 @@
</listitem>
<listitem>
<para>Retrieving the server configuration and attributes</para>
- <para>The <literal>HornetQServerControl</literal> exposes HornetQ
- server configuration through all its attributes (e.g. <literal
- >getVersion()</literal> method to retrieve the server's version,
- etc.)</para>
+ <para>The <literal>HornetQServerControl</literal> exposes HornetQ server
+ configuration through all its attributes (e.g. <literal>getVersion()</literal>
+ method to retrieve the server's version, etc.)</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Core Address Management</title>
- <para>Core addresses can be managed using the <literal>AddressControl</literal>
- class (with the ObjectName <literal
- >org.hornetq:module=Core,type=Address,name="<the address
- name>"</literal> or the resource name <literal>core.address.<the address
- name></literal>). </para>
+ <para>Core addresses can be managed using the <literal>AddressControl</literal> class
+ (with the ObjectName <literal>org.hornetq:module=Core,type=Address,name="<the
+ address name>"</literal> or the resource name <literal>core.address.<the
+ address name></literal>). </para>
<itemizedlist>
<listitem>
<para>Modifying roles and permissions for an address</para>
@@ -147,9 +141,8 @@
<section>
<title>Core Queue Management</title>
<para>The bulk of the core management API deals with core queues. The <literal
- >QueueControl</literal> class defines the Core queue management operations
- (with the ObjectName <literal
- >org.hornetq:module=Core,type=Queue,address="<the bound
+ >QueueControl</literal> class defines the Core queue management operations (with
+ the ObjectName <literal>org.hornetq:module=Core,type=Queue,address="<the bound
address>",name="<the queue name>"</literal> or the resource name <literal
>core.queue.<the queue name></literal>).</para>
<para>Most of the management operations on queues take either a single message ID (e.g.
@@ -207,10 +200,10 @@
</listitem>
<listitem>
<para>Retrieving the queue attributes</para>
- <para>The <literal>QueueControl</literal> exposes Core queue settings through
- its attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's
- filter if it was created with one, <literal>isDurable()</literal> to know
- wether the queue is durable or not, etc.)</para>
+ <para>The <literal>QueueControl</literal> exposes Core queue settings through its
+ attributes (e.g. <literal>getFilter()</literal> to retrieve the queue's filter
+ if it was created with one, <literal>isDurable()</literal> to know wether the
+ queue is durable or not, etc.)</para>
</listitem>
</itemizedlist>
</section>
@@ -224,8 +217,8 @@
<listitem>
<para>Acceptors</para>
<para>They can be started or stopped using the <literal>start()</literal> or.
- <literal>stop()</literal> method on the <literal
- >AcceptorControl</literal> class (with the ObjectName <literal
+ <literal>stop()</literal> method on the <literal>AcceptorControl</literal>
+ class (with the ObjectName <literal
>org.hornetq:module=Core,type=Acceptor,name="<the acceptor
name>"</literal> or the resource name <literal>core.acceptor.<the
address name></literal>). The acceptors parameters can be retrieved using
@@ -235,19 +228,18 @@
<listitem>
<para>Diverts</para>
<para>They can be started or stopped using the <literal>start()</literal> or
- <literal>stop()</literal> method on the <literal
- >DivertControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=Core,type=Divert,name=<the divert
- name></literal> or the resource name <literal>core.divert.<the divert
- name></literal>). Diverts parameters can be retrieved using the <literal
- >DivertControl</literal> attributes (see <xref linkend="diverts"
- />)</para>
+ <literal>stop()</literal> method on the <literal>DivertControl</literal>
+ class (with the ObjectName <literal
+ >org.hornetq:module=Core,type=Divert,name=<the divert name></literal>
+ or the resource name <literal>core.divert.<the divert name></literal>).
+ Diverts parameters can be retrieved using the <literal>DivertControl</literal>
+ attributes (see <xref linkend="diverts"/>)</para>
</listitem>
<listitem>
<para>Bridges</para>
<para>They can be started or stopped using the <literal>start()</literal> (resp.
- <literal>stop()</literal>) method on the <literal
- >BridgeControl</literal> class (with the ObjectName <literal
+ <literal>stop()</literal>) method on the <literal>BridgeControl</literal>
+ class (with the ObjectName <literal
>org.hornetq:module=Core,type=Bridge,name="<the bridge
name>"</literal> or the resource name <literal>core.bridge.<the bridge
name></literal>). Bridges parameters can be retrieved using the <literal
@@ -259,8 +251,8 @@
<para>They can be started or stopped using the <literal>start()</literal> or
<literal>stop()</literal> method on the <literal
>BroadcastGroupControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=Core,type=BroadcastGroup,name="<the broadcast
- group name>"</literal> or the resource name <literal
+ >org.hornetq:module=Core,type=BroadcastGroup,name="<the broadcast group
+ name>"</literal> or the resource name <literal
>core.broadcastgroup.<the broadcast group name></literal>). Broadcast
groups parameters can be retrieved using the <literal
>BroadcastGroupControl</literal> attributes (see <xref
@@ -271,20 +263,19 @@
<para>They can be started or stopped using the <literal>start()</literal> or
<literal>stop()</literal> method on the <literal
>DiscoveryGroupControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=Core,type=DiscoveryGroup,name="<the discovery
- group name>"</literal> or the resource name <literal
- >core.discovery.<the discovery group name></literal>). Discovery
- groups parameters can be retrieved using the <literal
- >DiscoveryGroupControl</literal> attributes (see <xref
- linkend="clusters.discovery-groups"/>)</para>
+ >org.hornetq:module=Core,type=DiscoveryGroup,name="<the discovery group
+ name>"</literal> or the resource name <literal>core.discovery.<the
+ discovery group name></literal>). Discovery groups parameters can be
+ retrieved using the <literal>DiscoveryGroupControl</literal> attributes (see
+ <xref linkend="clusters.discovery-groups"/>)</para>
</listitem>
<listitem>
<para>Cluster connections</para>
<para>They can be started or stopped using the <literal>start()</literal> or
<literal>stop()</literal> method on the <literal
>ClusterConnectionControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=Core,type=ClusterConnection,name="<the
- cluster connection name>"</literal> or the resource name <literal
+ >org.hornetq:module=Core,type=ClusterConnection,name="<the cluster
+ connection name>"</literal> or the resource name <literal
>core.clusterconnection.<the cluster connection name></literal>).
Cluster connections parameters can be retrieved using the <literal
>ClusterConnectionControl</literal> attributes (see <xref
@@ -301,25 +292,24 @@
<title>JMS Server Management</title>
<para>JMS Resources (connection factories and destinations) can be created using the
<literal>JMSServerControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=JMS,type=Server</literal> or the resource name
- <literal>jms.server</literal>).</para>
+ >org.hornetq:module=JMS,type=Server</literal> or the resource name <literal
+ >jms.server</literal>).</para>
<itemizedlist>
<listitem>
<para>Creating/destroying connection factories</para>
<para>JMS connection factories can be created or destroyed using the <literal
>createConnectionFactory()</literal> methods or <literal
>destroyConnectionFactory()</literal> methods. These connection factories
- are bound to JNDI so that JMS clients can look them up.
- If a graphical console is used to create the connection factories, the
- transport parameters are specified in the text fied input as a comma-separated
- list of key=value
- (e.g. <literal>key1=10, key2="value", key3=false</literal>). If there are multiple
- transports defined, you need to enclose the key/value pairs between curly braces.
- For example <literal>{key=10}, {key=20}</literal>. In that case, the first
- <literal>key</literal> will be associated to the first transport configuration and the
- second <literal>key</literal> will be associated to the second transport configuration
- (see <xref
- linkend="configuring-transports"/> for a list of the transport parameters)</para>
+ are bound to JNDI so that JMS clients can look them up. If a graphical console
+ is used to create the connection factories, the transport parameters are
+ specified in the text fied input as a comma-separated list of key=value (e.g.
+ <literal>key1=10, key2="value", key3=false</literal>). If there are multiple
+ transports defined, you need to enclose the key/value pairs between curly
+ braces. For example <literal>{key=10}, {key=20}</literal>. In that case, the
+ first <literal>key</literal> will be associated to the first transport
+ configuration and the second <literal>key</literal> will be associated to the
+ second transport configuration (see <xref linkend="configuring-transports"/>
+ for a list of the transport parameters)</para>
</listitem>
<listitem>
<para>Creating/destroying queues</para>
@@ -350,9 +340,9 @@
<title>JMS ConnectionFactory Management</title>
<para>JMS Connection Factories can be managed using the <literal
>ConnectionFactoryControl</literal> class (with the ObjectName <literal
- >org.hornetq:module=JMS,type=ConnectionFactory,name="<the connection
- factory name>"</literal> or the resource name <literal
- >jms.connectionfactory.<the connection factory name></literal>).</para>
+ >org.hornetq:module=JMS,type=ConnectionFactory,name="<the connection factory
+ name>"</literal> or the resource name <literal>jms.connectionfactory.<the
+ connection factory name></literal>).</para>
<itemizedlist>
<listitem>
<para>Retrieving connection factory attributes</para>
@@ -367,9 +357,9 @@
</section>
<section>
<title>JMS Queue Management</title>
- <para>JMS queues can be managed using the <literal>JMSQueueControl</literal> class
- (with the ObjectName <literal>org.hornetq:module=JMS,type=Queue,name="<the
- queue name>"</literal> or the resource name <literal>jms.queue.<the queue
+ <para>JMS queues can be managed using the <literal>JMSQueueControl</literal> class (with
+ the ObjectName <literal>org.hornetq:module=JMS,type=Queue,name="<the queue
+ name>"</literal> or the resource name <literal>jms.queue.<the queue
name></literal>). </para>
<para><emphasis>The management operations on a JMS queue are very similar to the
operations on a core queue. </emphasis></para>
@@ -423,18 +413,18 @@
</listitem>
<listitem>
<para>Retrieving the queue attributes</para>
- <para>The <literal>JMSQueueControl</literal> exposes JMS queue settings
- through its attributes (e.g. <literal>isTemporary()</literal> to know wether
- the queue is temporary or not, <literal>isDurable()</literal> to know wether
- the queue is durable or not, etc.)</para>
+ <para>The <literal>JMSQueueControl</literal> exposes JMS queue settings through
+ its attributes (e.g. <literal>isTemporary()</literal> to know wether the queue
+ is temporary or not, <literal>isDurable()</literal> to know wether the queue is
+ durable or not, etc.)</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>JMS Topic Management</title>
- <para>JMS Topics can be managed using the <literal>TopicControl</literal> class
- (with the ObjectName <literal>org.hornetq:module=JMS,type=Topic,name="<the
- topic name>"</literal> or the resource name <literal>jms.topic.<the topic
+ <para>JMS Topics can be managed using the <literal>TopicControl</literal> class (with
+ the ObjectName <literal>org.hornetq:module=JMS,type=Topic,name="<the topic
+ name>"</literal> or the resource name <literal>jms.topic.<the topic
name></literal>).</para>
<itemizedlist>
<listitem>
@@ -468,9 +458,8 @@
<para>HornetQ can be managed using <ulink
url="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/"
>JMX</ulink>. </para>
- <para>The management API is exposed by HornetQ using MBeans interfaces. HornetQ
- registers its resources with the domain <literal
- >org.hornetq</literal>.</para>
+ <para>The management API is exposed by HornetQ using MBeans interfaces. HornetQ registers its
+ resources with the domain <literal>org.hornetq</literal>.</para>
<para>For example, the <literal>ObjectName</literal> to manage a JMS Queue <literal
>exampleQueue</literal> is:</para>
<programlisting>
@@ -484,61 +473,55 @@
>org.hornetq.core.management.ObjectNames</literal>. You can also use <literal
>jconsole</literal> to find the <literal>ObjectName</literal> of the MBeans you want to
manage. </para>
- <para>Managing HornetQ using JMX is identical to management of any Java Applications
- using JMX. It can be done by reflection or by creating proxies of the MBeans.</para>
+ <para>Managing HornetQ using JMX is identical to management of any Java Applications using
+ JMX. It can be done by reflection or by creating proxies of the MBeans.</para>
<section id="management.jmx.configuration">
<title>Configuring JMX</title>
- <para>By default, JMX is enabled to manage HornetQ. It can be disabled by setting
- <literal>jmx-management-enabled</literal> to <literal>false</literal> in <literal
+ <para>By default, JMX is enabled to manage HornetQ. It can be disabled by setting <literal
+ >jmx-management-enabled</literal> to <literal>false</literal> in <literal
>hornetq-configuration.xml</literal>:</para>
<programlisting>
<!-- false to disable JMX management for HornetQ -->
<jmx-management-enabled>false</jmx-management-enabled>
</programlisting>
- <para>If JMX is enabled, HornetQ can be managed locally using <literal
- >jconsole</literal>. Remote connections to JMX are not enabled by default for
- security reasons. Please refer to <ulink
- url="http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote">Java
- Management guide</ulink> to configure the server for remote management (system
+ <para>If JMX is enabled, HornetQ can be managed locally using <literal>jconsole</literal>.
+ Remote connections to JMX are not enabled by default for security reasons. Please refer
+ to <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#remote"
+ >Java Management guide</ulink> to configure the server for remote management (system
properties must be set in <literal>run.sh</literal> or <literal>run.bat</literal>
scripts).</para>
-
<section>
<title>MBeanServer configuration</title>
-
- <para>When HornetQ is run in standalone, it uses the Java Virtual Machine's <literal>Platform
- MBeanServer</literal> to register its MBeans. This is configured in JBoss
- Microcontainer Beans file (see <xref linkend="server.microcontainer.configuration"
- />):</para>
+ <para>When HornetQ is run in standalone, it uses the Java Virtual Machine's <literal
+ >Platform MBeanServer</literal> to register its MBeans. This is configured in
+ JBoss Microcontainer Beans file (see <xref
+ linkend="server.microcontainer.configuration"/>):</para>
<programlisting><!-- MBeanServer -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
<constructor factoryClass="java.lang.management.ManagementFactory"
factoryMethod="getPlatformMBeanServer" />
</bean>
</programlisting>
-
- <para>When it is integrated in JBoss AS 5, it uses the Application Server's own
- MBean Server so that it can be managed using AS 5's jmx-console:</para>
+ <para>When it is integrated in JBoss AS 5+, it uses the Application Server's own MBean
+ Server so that it can be managed using AS 5's jmx-console:</para>
<programlisting><!-- MBeanServer -->
<bean name="MBeanServer" class="javax.management.MBeanServer">
<constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
factoryMethod="locateJBoss" />
</bean>
</programlisting>
- </section>
+ </section>
</section>
-
<section>
<title>Example</title>
- <para>See <xref linkend="examples.jmx" /> for an example which
- shows how to use a remote connection to JMX and MBean proxies to
- manage HornetQ.</para>
+ <para>See <xref linkend="examples.jmx"/> for an example which shows how to use a remote
+ connection to JMX and MBean proxies to manage HornetQ.</para>
</section>
</section>
<section>
<title>Using Management Via Core API</title>
- <para>The core management API in HornetQ is called by sending Core messages to a
- special address, the <emphasis>management address</emphasis>.</para>
+ <para>The core management API in HornetQ is called by sending Core messages to a special
+ address, the <emphasis>management address</emphasis>.</para>
<para><emphasis>Management messages</emphasis> are regular Core messages with well-known
properties that the server needs to understand to interact with the management API:</para>
<itemizedlist>
@@ -552,16 +535,16 @@
<para>The parameters of the management operation</para>
</listitem>
</itemizedlist>
- <para>When such a management message is sent to the management address, HornetQ server
- will handle it, extract the information, invoke the operation on the managed resources and
- send a <emphasis>management reply</emphasis> to the management message's reply-to address
+ <para>When such a management message is sent to the management address, HornetQ server will
+ handle it, extract the information, invoke the operation on the managed resources and send
+ a <emphasis>management reply</emphasis> to the management message's reply-to address
(specified by <literal>ClientMessageImpl.REPLYTO_HEADER_NAME</literal>). </para>
<para>A <literal>ClientConsumer</literal> can be used to consume the management reply and
retrieve the result of the operation (if any) stored in the reply's body. For portability,
results are returned as a <ulink url="http://json.org">JSON</ulink> String rather than Java
Serialization (the <literal
- >org.hornetq.core.client.management.impl.ManagementHelper</literal> can be used
- to convert the JSON string to Java objects).</para>
+ >org.hornetq.core.client.management.impl.ManagementHelper</literal> can be used to
+ convert the JSON string to Java objects).</para>
<para>These steps can be simplified to make it easier to invoke management operations using
Core messages:</para>
<orderedlist>
@@ -574,16 +557,16 @@
</listitem>
<listitem>
<para>Use the helper class <literal
- >org.hornetq.core.client.management.impl.ManagementHelper</literal> to
- fill the message with the management properties</para>
+ >org.hornetq.core.client.management.impl.ManagementHelper</literal> to fill the
+ message with the management properties</para>
</listitem>
<listitem>
<para>Send the message using the <literal>ClientRequestor</literal></para>
</listitem>
<listitem>
<para>Use the helper class <literal
- >org.hornetq.core.client.management.impl.ManagementHelper</literal> to
- retrieve the operation result from the management reply</para>
+ >org.hornetq.core.client.management.impl.ManagementHelper</literal> to retrieve
+ the operation result from the management reply</para>
</listitem>
</orderedlist>
<para>For example, to find out the number of messages in the core queue <literal
@@ -600,10 +583,10 @@
<para>Management operation name and parameters must conform to the Java interfaces defined in
the <literal>management</literal> packages.</para>
<para>Names of the resources are built using the helper class <literal
- >org.hornetq.core.management.ResourceNames</literal> and are straightforward
- (<literal>core.queue.exampleQueue</literal> for the Core Queue <literal
- >exampleQueue</literal>, <literal>jms.topic.exampleTopic</literal> for the JMS Topic
- <literal>exampleTopic</literal>, etc.).</para>
+ >org.hornetq.core.management.ResourceNames</literal> and are straightforward (<literal
+ >core.queue.exampleQueue</literal> for the Core Queue <literal>exampleQueue</literal>,
+ <literal>jms.topic.exampleTopic</literal> for the JMS Topic <literal
+ >exampleTopic</literal>, etc.).</para>
<section id="management.core.configuration">
<title>Configuring Core Management</title>
<para>The management address to send management messages is configured in <literal
@@ -646,16 +629,16 @@
</listitem>
<listitem>
<para>use the helper class <literal
- >org.hornetq.jms.server.management.impl.JMSManagementHelper</literal> to
- fill the message with the management properties</para>
+ >org.hornetq.jms.server.management.impl.JMSManagementHelper</literal> to fill the
+ message with the management properties</para>
</listitem>
<listitem>
<para>send the message using the <literal>QueueRequestor</literal></para>
</listitem>
<listitem>
<para>use the helper class <literal
- >org.hornetq.jms.server.management.impl.JMSManagementHelper</literal> to
- retrieve the operation result from the management reply</para>
+ >org.hornetq.jms.server.management.impl.JMSManagementHelper</literal> to retrieve
+ the operation result from the management reply</para>
</listitem>
</orderedlist>
<para>For example, to know the number of messages in the JMS queue <literal
@@ -679,51 +662,50 @@
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.management" /> for an example which shows how to use
- JMS messages to manage HornetQ server.</para>
+ <para>See <xref linkend="examples.management"/> for an example which shows how to use JMS
+ messages to manage HornetQ server.</para>
</section>
</section>
<section id="management.replication">
<title>Management Cluster Credentials</title>
- <para>HornetQ allows <emphasis>replication</emphasis> of a live server to a backup
- server. This impacts management as resources created on the live server (e.g. a core
- address) must also be created on the backup server. Otherwise, when failover occurs, the
- backup server will not be able to handle messages sent to this address since its resources
- will have been created on the live server only and not on the backup.</para>
+ <para>HornetQ allows <emphasis>replication</emphasis> of a live server to a backup server.
+ This impacts management as resources created on the live server (e.g. a core address) must
+ also be created on the backup server. Otherwise, when failover occurs, the backup server
+ will not be able to handle messages sent to this address since its resources will have been
+ created on the live server only and not on the backup.</para>
<para>HornetQ <emphasis>replicates management operations</emphasis> regardless of the
management API used (JMX, Core messages, JMS messages). Any management operation invoked on
a live server will also be invoked on its backup server to ensure a proper replication of
resources and state. For example, you only need to manage the live server: if a queue is
- created on the live server, HornetQ will ensure that the same resource will also be
- created on the backup server.</para>
+ created on the live server, HornetQ will ensure that the same resource will also be created
+ on the backup server.</para>
<para>If core or JMS messages are used to invoke management operations, replication is handled
automatically by HornetQ.</para>
- <para>To allow this management replication with JMX, HornetQ defines
- <emphasis>management cluster credentials</emphasis>: this special user/password <emphasis>must
- be shared by all nodes</emphasis>. To configure it, change the value in <literal
+ <para>To allow this management replication with JMX, HornetQ defines <emphasis>management
+ cluster credentials</emphasis>: this special user/password <emphasis>must be shared by
+ all nodes</emphasis>. To configure it, change the value in <literal
>hornetq-configuration.xml</literal>:</para>
<programlisting>
<management-cluster-user>HORNETQ.MANAGEMENT.ADMIN.USER</management-cluster-user>
<management-cluster-password>CHANGE ME!!</management-cluster-password>
</programlisting>
- <para>It is strongly suggested to
- change these values from their default. If they are not changed from the default, HornetQ will
- detect this and pester you with a warning on every start-up.</para>
- <para>HornetQ internally uses Core messages to replicate management operations between
- the live and backup server when JMX is used. By default, there is a timeout of 5s (5000ms)
- to send a management request from the live server to the backup server and wait for a
- reply. If a reply is not received before the timeout is hit, HornetQ considers the
- replication has failed. This timeout can be configured in <literal
- >hornetq-configuration.xml</literal>:</para>
+ <para>It is strongly suggested to change these values from their default. If they are not
+ changed from the default, HornetQ will detect this and pester you with a warning on every
+ start-up.</para>
+ <para>HornetQ internally uses Core messages to replicate management operations between the
+ live and backup server when JMX is used. By default, there is a timeout of 5s (5000ms) to
+ send a management request from the live server to the backup server and wait for a reply.
+ If a reply is not received before the timeout is hit, HornetQ considers the replication has
+ failed. This timeout can be configured in <literal
+ >hornetq-configuration.xml</literal>:</para>
<programlisting>
<management-request-timeout>5000</management-request-timeout>
</programlisting>
</section>
<section id="management.notifications">
<title>Management Notifications</title>
- <para>HornetQ emits <emphasis>notifications</emphasis> to inform listeners of
- potentially interesting events (creation of new resources, security violation,
- etc.).</para>
+ <para>HornetQ emits <emphasis>notifications</emphasis> to inform listeners of potentially
+ interesting events (creation of new resources, security violation, etc.).</para>
<para>These notifications can be received by 3 different ways:</para>
<itemizedlist>
<listitem>
@@ -742,20 +724,20 @@
notifications can be received by subscribing to 2 MBeans:</para>
<itemizedlist>
<listitem>
- <para><literal>org.hornetq:module=Core,type=Server</literal> for
- notifications on <emphasis>Core</emphasis> resources</para>
+ <para><literal>org.hornetq:module=Core,type=Server</literal> for notifications on
+ <emphasis>Core</emphasis> resources</para>
</listitem>
<listitem>
- <para><literal>org.hornetq:module=JMS,type=Server</literal> for notifications
- on <emphasis>JMS</emphasis> resources</para>
+ <para><literal>org.hornetq:module=JMS,type=Server</literal> for notifications on
+ <emphasis>JMS</emphasis> resources</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Core Messages Notifications</title>
- <para>HornetQ defines a special <emphasis>management notification
- address</emphasis>. Core queues can be bound to this address so that clients will
- receive management notifications as Core messages</para>
+ <para>HornetQ defines a special <emphasis>management notification address</emphasis>. Core
+ queues can be bound to this address so that clients will receive management
+ notifications as Core messages</para>
<para>A Core client which wants to receive management notifications must create a core
queue bound to the management notification address. It can then receive the
notifications from its queue.</para>
@@ -816,10 +798,9 @@
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.management-notifications" /> for an example which
- shows how to use a
- JMS <literal>MessageListener</literal> to receive management notifications from HornetQ
- server.</para>
+ <para>See <xref linkend="examples.management-notifications"/> for an example which shows
+ how to use a JMS <literal>MessageListener</literal> to receive management notifications
+ from HornetQ server.</para>
</section>
</section>
<section id="management.message-counters">
@@ -869,8 +850,7 @@
<section id="configuring.message.counters">
<title>Configuring Message Counters</title>
<para>By default, message counters are disabled as it might have a small negative effect on
- memory (the metrics are kept in memory) and CPU (the queues are sampled at regular
- interval).</para>
+ memory.</para>
<para>To enable message counters, you can set it to <literal>true</literal> in <literal
>hornetq-configuration.xml</literal>:</para>
<programlisting>
@@ -906,9 +886,8 @@
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.message-counters" /> for an example which
- shows how to use message counters to
- retrieve information on a JMS <literal>Queue</literal>.</para>
+ <para>See <xref linkend="examples.message-counters"/> for an example which shows how to use
+ message counters to retrieve information on a JMS <literal>Queue</literal>.</para>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/master.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -69,8 +69,8 @@
<!ENTITY libaio SYSTEM "libaio.xml">
]>
<book lang="en">
- <bookinfo>
- <title>HornetQ User Manual</title>
+ <bookinfo>
+ <title>HornetQ 2.0 User Manual</title>
<subtitle>Putting the buzz in messaging</subtitle>
</bookinfo>
@@ -78,6 +78,7 @@
¬ice;
&preface;
+ &project-info;
&messaging-concepts;
&architecture;
&using-server;
@@ -122,6 +123,6 @@
&interoperability;
&perf-tuning;
&configuration-index;
- &project-info;
+
</book>
Modified: trunk/docs/user-manual/en/message-expiry.xml
===================================================================
--- trunk/docs/user-manual/en/message-expiry.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/message-expiry.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,20 +16,20 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="message-expiry">
<title>Message Expiry</title>
- <para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending them.
- Such messages will be retained in the messaging system until their <emphasis>time to
- live</emphasis> is reached.</para>
- <para>HornetQ's addresses can be assigned a expiry address so that, when messages are
- expired, they are removed from the queue and sent to the expiry address. Many different queues
- can be bound to an expiry address. These <emphasis>expired</emphasis> messages can later be
- consumed for further inspection.</para>
+ <para>Messages can be set with an optional <emphasis>time to live</emphasis> when sending
+ them.</para>
+ <para>HornetQ will not deliver a message to a consumer after it's time to live has been exceeded.
+ If the message hasn't been delivered by the time that time to live is reached the server can
+ discard it.</para>
+ <para>HornetQ's addresses can be assigned a expiry address so that, when messages are expired,
+ they are removed from the queue and sent to the expiry address. Many different queues can be
+ bound to an expiry address. These <emphasis>expired</emphasis> messages can later be consumed
+ for further inspection.</para>
<section>
<title>Message Expiry</title>
- <para>Using HornetQ Core API, you can set an expiration time directly on the
- message:</para>
+ <para>Using HornetQ Core API, you can set an expiration time directly on the message:</para>
<programlisting>
// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
@@ -65,12 +64,12 @@
</address-setting>
</programlisting>
<para>If messages are expired and no expiry address is specified, messages are simply removed
- from the queue. Address wildcards can be used to configure expiry address for a set of
- addresses (see <xref linkend="wildcard-syntax"/>).</para>
+ from the queue and dropped. Address wildcards can be used to configure expiry address for a
+ set of addresses (see <xref linkend="wildcard-syntax"/>).</para>
</section>
<section id="configuring.expiry.reaper">
<title>Configuring The Expiry Reaper Thread</title>
- <para>A reaper thread is periodically inspecting the queues to check if messages have
+ <para>A reaper thread will periodically inspect the queues to check if messages have
expired.</para>
<para>The reaper thread can be configured with the following properties in <literal
>hornetq-configuration.xml</literal></para>
@@ -89,7 +88,7 @@
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.expiry" /> for an example which
- shows how message expiry is configured and used with JMS.</para>
+ <para>See <xref linkend="examples.expiry"/> for an example which shows how message expiry is
+ configured and used with JMS.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/messaging-concepts.xml
===================================================================
--- trunk/docs/user-manual/en/messaging-concepts.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/messaging-concepts.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="messaging-concepts">
<title>Messaging Concepts</title>
<para>HornetQ is an asynchronous messaging system, an example of <ulink
@@ -54,12 +52,12 @@
loosely couples heterogeneous systems together. Message buses often form the core of an
<ulink url="http://en.wikipedia.org/wiki/Enterprise_service_bus">Enterprise Service
Bus</ulink>. (ESB). Using a message bus to de-couple disparate systems can allow the
- system to grow and adapt. It also allows more flexibility add new systems or retire old
- ones since they don't have brittle dependencies on each other.</para>
+ system to grow and adapt more easily. It also allows more flexibility to add new systems
+ or retire old ones since they don't have brittle dependencies on each other.</para>
</section>
<section>
<title>Messaging styles</title>
- <para>Messaging systems normally support two main styles of asynchronous messaging: <ulink
+ <para>Messaging systems normally support two main styles of asynchronous messaging: <ulink
url="http://en.wikipedia.org/wiki/Message_queue"> message queue</ulink> messaging
(also known as <emphasis role="italic">point-to-point messaging</emphasis>) and <ulink
url="http://en.wikipedia.org/wiki/Publish_subscribe">publish subscribe</ulink>
@@ -82,15 +80,15 @@
existence.</para>
<para>A classic example of point to point messaging would be an order queue in a
company's book ordering system. Each order is represented as a message which is sent
- to the order queue. There are many front end ordering systems which send orders to
- the order queue. When a message arrives on the queue it is persisted - this ensures
- that if the server crashes the order is not lost. There are many consumers on the
- order queue - each representing an instance of an order processing component - these
- can be on different physical machines but consuming from the same queue. The
- messaging system delivers each message to one and only one of the ordering
- processing components. Different messages can be processed by order processors, but
- a single order is only processed by one order processor - this ensures orders aren't
- processed twice.</para>
+ to the order queue. Let's imagine there are many front end ordering systems which
+ send orders to the order queue. When a message arrives on the queue it is persisted
+ - this ensures that if the server crashes the order is not lost. Let's also imagine
+ there are many consumers on the order queue - each representing an instance of an
+ order processing component - these can be on different physical machines but
+ consuming from the same queue. The messaging system delivers each message to one and
+ only one of the ordering processing components. Different messages can be processed
+ by different order processors, but a single order is only processed by one order
+ processor - this ensures orders aren't processed twice.</para>
<para>As an order processor receives a message, it fulfills the order, sends order
information to the warehouse system and then updates the order database with the
order details. Once it's done that it acknowledges the message to tell the server
@@ -104,13 +102,16 @@
<para>With publish-subscribe messaging many senders can send messages to an entity on
the server, often called a <emphasis role="italic">topic</emphasis> (e.g. in the JMS
world).</para>
- <para>There can be many subscriptions on a topic, each subscription receives a copy of
- <emphasis role="italic">each</emphasis> message sent to the topic. This differs
- from the message queue pattern where each message is only consumed by a single
- consumer.</para>
+ <para>There can be many <emphasis>subscriptions</emphasis> on a topic, a subscription is
+ just another word for a consumer of a topic. Each subscription receives a
+ <emphasis>copy</emphasis> of <emphasis role="italic">each</emphasis> message
+ sent to the topic. This differs from the message queue pattern where each message is
+ only consumed by a single consumer.</para>
<para>Subscriptions can optionally be <emphasis role="italic">durable</emphasis> which
means they retain a copy of each message sent to the topic until the subscriber
- consumes it.</para>
+ consumes it - even if the server crashes or is restarted in between. Non-durable
+ subscriptions only last a maximum of the lifetime of the connection that created
+ them.</para>
<para>An example of publish-subscribe messaging would be a news feed. As news articles
are created by different editors around the world they are sent to a news feed
topic. There are many subscribers around the world who are interested in receiving
@@ -139,11 +140,11 @@
</section>
<section>
<title>Durability</title>
- <para>Messages are either durable or non durable. Durable messages will persisted in
- permanent storage and will survive server failure. Non durable messages will not survive
- server failure or restart. Examples of durable messages might be orders or trades, where
- they cannot be lost. An example of a non durable message might be a stock price update.
- This is transitory and there's no need for it to survive a restart. </para>
+ <para>Messages are either durable or non durable. Durable messages will be persisted in
+ permanent storage and will survive server failure or restart. Non durable messages will
+ not survive server failure or restart. Examples of durable messages might be orders or
+ trades, where they cannot be lost. An example of a non durable message might be a stock
+ price update which is transitory and doesn't need to survive a restart.</para>
</section>
<section>
<title>Messaging APIs and protocols</title>
@@ -176,11 +177,28 @@
functionality to be exposed to the client application. API's like JMS are not
normally rich enough to expose all the extra features that most messaging systems
provide.</para>
- <para>HornetQ provides its own core client API for clients to use if they wish
- to have access to functionality over and above that accessible via the JMS
- API.</para>
+ <para>HornetQ provides its own core client API for clients to use if they wish to have
+ access to functionality over and above that accessible via the JMS API.</para>
</section>
<section>
+ <title>RESTful API</title>
+ <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer"
+ >REST</ulink> approaches to messaging are showing a lot interest
+ recently.</para>
+ <para>It seems fairly likely that API standards for cloud computing will eventually
+ converge on a REST style set of interfaces and consequently a REST messaging
+ approach is a very strong contender for becoming the defacto method for messaging
+ interoperability.</para>
+ <para>With a REST approach messaging resources are manipulated as resources defined by a
+ URI and typically using a simple set of operations on those resources, e.g. PUT,
+ POST, GET etc. REST approaches to messaging often use HTTP as their underlying
+ protocol.</para>
+ <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
+ internet is already tuned to deal with HTTP optimally.</para>
+ <para>HornetQ will shortly be implementing RESTful approach to messaging
+ interoperability.</para>
+ </section>
+ <section>
<title>STOMP</title>
<para><ulink
url="http://en.wikipedia.org/wiki/Streaming_Text_Orientated_Messaging_Protocol"
@@ -202,63 +220,47 @@
available in many different programming languages.</para>
<para>HornetQ will shortly be implementing AMQP.</para>
</section>
- <section>
- <title>REST</title>
- <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer"
- >REST</ulink> approaches to messaging are showing a lot interest recently. With
- a REST approach messaging resources are manipulated as resources defined by a URI
- and typically using a simple set of operations on those resources, e.g. PUT, POST,
- GET etc. REST approaches to messaging often use HTTP as their underlying
- protocol.</para>
- <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
- internet is already tuned to deal with HTTP optimally.</para>
- <para>HornetQ will shortly be implementing REST.</para>
- </section>
</section>
<section>
<title>High Availability</title>
<para>High Availability (HA) means that the system should remain operational after failure
of one or more of the servers. The degree of support for HA varies between various
messaging systems.</para>
- <para>Some messaging systems require you to deal with server side failure by writing some
- client side code which gets called on event of server failure, and in which you are
- supposed to recreate your connections to another server.</para>
- <para>HornetQ provides 100% transparent failover where you don't have have to write
- any special client side code to deal with failure. On failover HornetQ will
- automatically fail over your client connections to another server, and your client
- sessions can continue as if nothing happened.</para>
- <para>For more information on HA, please see <xref linkend="ha" />.</para>
+ <para>HornetQ provides automatic failover where your sessions are automatically reconnected
+ to the backup server on event of live serve failure.</para>
+ <para>For more information on HA, please see <xref linkend="ha"/>.</para>
</section>
<section>
<title>Clusters</title>
<para>Many messaging systems allow you to create groups of messaging servers called
<emphasis role="italic">clusters</emphasis>. Clusters allow the load of sending and
- consuming messages to be spread over many servers. This allows your system to be able
- scale horizontally by adding new servers to the cluster.</para>
+ consuming messages to be spread over many servers. This allows your system to scale
+ horizontally by adding new servers to the cluster.</para>
<para>Degrees of support for clusters varies between messaging systems, with some systems
having fairly basic clusters with the cluster members being hardly aware of each
other.</para>
- <para>HornetQ provides very configurable state of the art clustering where messages
+ <para>HornetQ provides very configurable state-of-the-art clustering model where messages
can be intelligently load balanced between the servers in the cluster, according to the
number of consumers on each node, and whether they are ready for messages.</para>
- <para>HornetQ also has the ability to automatically redistribute messages between
- nodes of a cluster to prevent starvation on any particular node.</para>
+ <para>HornetQ also has the ability to automatically redistribute messages between nodes of a
+ cluster to prevent starvation on any particular node.</para>
<para>For full details on clustering, please see <xref linkend="clusters"/>.</para>
</section>
<section>
<title>Bridges and routing</title>
<para>Some messaging systems allow isolated clusters or single nodes to be bridged together,
- typically over unreliable connections like a wide area network (WAN).</para>
+ typically over unreliable connections like a wide area network (WAN), or the
+ internet.</para>
<para>A bridge normally consumes from a queue on one server and forwards messages to another
queue on a different server. Bridges cope with unreliable connections, automatically
reconnecting when the connections becomes available again.</para>
- <para>HornetQ bridges can be configured with filter expressions to only forward
- certain messages, and transformation can also be hooked in.</para>
+ <para>HornetQ bridges can be configured with filter expressions to only forward certain
+ messages, and transformation can also be hooked in.</para>
<para>HornetQ also allows routing between queues to be configured in server side
configuration. This allows complex routing networks to be set up forwarding or copying
messages from one destination to another, forming a global network of interconnected
brokers.</para>
- <para>For more information please see <xref linkend="core-bridges"/>
- and <xref linkend="diverts"/>.</para>
+ <para>For more information please see <xref linkend="core-bridges"/> and <xref
+ linkend="diverts"/>.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/notice.xml
===================================================================
--- trunk/docs/user-manual/en/notice.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/notice.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -18,9 +18,7 @@
<chapter id="notice">
<title>Legal Notice</title>
-
- <graphic fileref="images/hornetQ_logo_600px.png" />
-
+
<para>Copyright © 2009 Red Hat, Inc. and others.</para>
<para>The text of and illustrations in this document are licensed by Red Hat under
a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA").</para>
Modified: trunk/docs/user-manual/en/paging.xml
===================================================================
--- trunk/docs/user-manual/en/paging.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/paging.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,16 +16,15 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="paging">
<title>Paging</title>
- <para>HornetQ transparently supports huge queues containing millions of messages while
- the server is running with limited memory.</para>
+ <para>HornetQ transparently supports huge queues containing millions of messages while the
+ server is running with limited memory.</para>
<para>In such a situation it's not possible to store all of the queues in memory at any one
- time, so HornetQ transparently <emphasis>pages</emphasis> messages into and out of
- memory as they are needed, thus allowing massive queues with a low memory footprint.</para>
- <para>HornetQ will start paging messages to disk, when either the size of the queue
- reaches a total configured maximum size.</para>
+ time, so HornetQ transparently <emphasis>pages</emphasis> messages into and out of memory as
+ they are needed, thus allowing massive queues with a low memory footprint.</para>
+ <para>HornetQ will start paging messages to disk, when the size of all messages in memory for an
+ address exceeds a configured maximum size.</para>
<section>
<title>Page Files</title>
<para>Messages are stored per address on the file system. Each address has an individual
@@ -66,9 +64,8 @@
<tbody>
<row>
<entry><literal>paging-directory</literal></entry>
- <entry>Where page files are stored. HornetQ will create one
- folder for each address being paged under this configured
- location.</entry>
+ <entry>Where page files are stored. HornetQ will create one folder for
+ each address being paged under this configured location.</entry>
<entry>data/paging</entry>
</row>
</tbody>
Modified: trunk/docs/user-manual/en/perf-tuning.xml
===================================================================
--- trunk/docs/user-manual/en/perf-tuning.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/perf-tuning.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="perf-tuning">
<title>Performance Tuning</title>
<para>In this chapter we'll discuss how to tune HornetQ for optimum performance.</para>
@@ -25,6 +23,16 @@
<title>Tuning the journal</title>
<itemizedlist>
<listitem>
+ <para>Put the journal on its own physical volume. If the disk is shared with other
+ processes e.g. transaction co-ordinator, database or other journals which are
+ also reading and writing from it, then this may greatly reduce performance since
+ the disk head may be skipping all over the place between the different files.
+ One of the advantages of an append only journal is that disk head movement is
+ minimised - this advantage is destroyed if the disk is shared. If you're using
+ paging or large messages make sure they're ideally put on separate volumes
+ too.</para>
+ </listitem>
+ <listitem>
<para>Minimum number of journal files. Set <literal>journal-min-files</literal> to a
number of files that would fit your average sustainable rate. If you see new
files being created on the journal data directory too often, i.e. lots of data
@@ -37,12 +45,13 @@
systems.</para>
</listitem>
<listitem>
- <para>Use AIO journal. If using Linux, try to keep your journal type as AIO.</para>
+ <para>Use AIO journal. If using Linux, try to keep your journal type as AIO. AIO
+ will scale better than Java NIO.</para>
</listitem>
<listitem>
<para><literal>journal-aio-flush-on-sync</literal>. If you don't have many producers
- in your system you may consider setting journal-aio-flush-on-sync to true. HornetQ
- by default is optimized by the case where you have many producers. We
+ in your system you may consider setting journal-aio-flush-on-sync to true.
+ HornetQ by default is optimized by the case where you have many producers. We
try to combine multiple writes in a single OS operation. However if that's not
your case setting this option to true will give you a performance boost.</para>
<para>On the other hand when you have multiple producers, keeping <literal
@@ -64,7 +73,7 @@
of creating a unique ID.</para>
</listitem>
<listitem>
- <para> Disable message timestamp. Use the <literal
+ <para>Disable message timestamp. Use the <literal
>setDisableMessageTimeStamp()</literal> method on the <literal
>MessageProducer</literal> class to disable message timestamps if you don't
need them. Again this makes the message smaller.</para>
@@ -85,7 +94,7 @@
received on the client, this means more traffic on the network. If you can, use
<literal>DUPS_OK_ACKNOWLEDGE</literal> or use <literal
>CLIENT_ACKNOWLEDGE</literal> or a transacted session and batch up many
- acknowledgements with one acknowledge/commit.</para>
+ acknowledgements with one acknowledge/commit. </para>
</listitem>
<listitem>
<para>Avoid persistent messages. By default JMS messages are persistent. If you
@@ -97,8 +106,7 @@
</section>
<section>
<title>Other Tunings</title>
- <para>There are various other places in HornetQ where we can perform some
- tuning:</para>
+ <para>There are various other places in HornetQ where we can perform some tuning:</para>
<itemizedlist>
<listitem>
<para>Use Asynchronous Send Acknowledgements. If you need to send persistent
@@ -127,9 +135,9 @@
<listitem>
<para>Sync transactions lazily. Setting <literal
>journal-sync-transactional</literal> to <literal>false</literal> in
- <literal>hornetq-configuration.xml</literal> can give you better transactional
- persistent performance at the expense of some possibility of loss of
- transactions on failure. See <xref linkend="send-guarantees"/> for more
+ <literal>hornetq-configuration.xml</literal> can give you better
+ transactional persistent performance at the expense of some possibility of loss
+ of transactions on failure. See <xref linkend="send-guarantees"/> for more
information.</para>
</listitem>
<listitem>
@@ -176,7 +184,7 @@
<section>
<title>Tuning the VM</title>
<para>We highly recommend you use the latest Java 6 JVM, especially in the area of
- networking many improvements have been made since Java 5. We test internally using the
+ networking, many improvements have been made since Java 5. We test internally using the
Sun JVM, so some of these tunings won't apply to JDKs from other providers (e.g. IBM or
JRockit)</para>
<itemizedlist>
@@ -186,13 +194,13 @@
>-XX:+UseParallelGC</literal> on Sun JDKs.</para>
</listitem>
<listitem>
- <para>Memory settings. Give as much memory as you can to the server. HornetQ
- can run in low memory by using paging (described in <xref linkend="paging"/>)
- but if it can run with all queues in RAM this will improve performance. The
- amount of memory you require will depend on the size and number of your queues
- and the size and number of your messages. Use the JVM arguments <literal
- >-Xms</literal> and <literal>-Xmx</literal> to set server available RAM. We
- recommend setting them to the same high value.</para>
+ <para>Memory settings. Give as much memory as you can to the server. HornetQ can run
+ in low memory by using paging (described in <xref linkend="paging"/>) but if it
+ can run with all queues in RAM this will improve performance. The amount of
+ memory you require will depend on the size and number of your queues and the
+ size and number of your messages. Use the JVM arguments <literal>-Xms</literal>
+ and <literal>-Xmx</literal> to set server available RAM. We recommend setting
+ them to the same high value.</para>
</listitem>
<listitem>
<para>Aggressive options. Different JVMs provide different sets of JVM tuning
@@ -234,8 +242,8 @@
entire queue has to be scanned for matching messages.</para>
<para>This anti-pattern can normally be avoided by instead using a topic with many
durable subscriptions, each subscription defines a message selector. With topic
- subscriptions the selector expression is evaluated by HornetQ before the
- message goes into the subscription, so no scanning is involved.</para>
+ subscriptions the selector expression is evaluated by HornetQ before the message
+ goes into the subscription, so no scanning is involved.</para>
</listitem>
<listitem>
<para>Don't create temporary queues for each request. This common anti-pattern
@@ -247,6 +255,12 @@
temporary queue on each message sent. This will drastically reduce performance.
Instead the temporary queue should be re-used for many requests.</para>
</listitem>
+ <listitem>
+ <para>Don't use Mesage Driven Beans for the sake of it. As soon as you start using MDBs you are greatly
+ increasing the codepath for each message received compared to a straightforward message consumer, since a lot of
+ extra application server code is executed. Ask yourself
+ do you really need MDBs? Can you accomplish the same task using just a normal message consumer?</para>
+ </listitem>
</itemizedlist>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/persistence.xml
===================================================================
--- trunk/docs/user-manual/en/persistence.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/persistence.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,46 +16,46 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="persistence">
<title>Persistence</title>
- <para>In this chapter we will describe how persistence works with HornetQ and how to
- configure it.</para>
- <para>HornetQ ships with a high performance journal. This journal has been implemented
- by the HornetQ team with a view to providing high performance in a messaging system.
- Since HornetQ handles its own persistence, rather than relying on a database or
- other 3rd party persistence engine, we have been able to tune the journal to gain optimal
- performance for the persistence of messages and transactions.</para>
- <para>A HornetQ journal is an <emphasis>append only</emphasis> journal. It consists of a
- set of files on disk. Each file is pre-created to a fixed size and initially filled with
- padding. As operations are performed on the server, e.g. add message, update message, delete
- message, records are appended to the journal. When one journal file is full we move to the
- next one.</para>
+ <para>In this chapter we will describe how persistence works with HornetQ and how to configure
+ it.</para>
+ <para>HornetQ ships with a high performance journal. This journal has been implemented by the
+ HornetQ team with a view to providing high performance in a messaging system. Since HornetQ
+ handles its own persistence, rather than relying on a database or other 3rd party
+ persistence engine, we have been able to tune the journal to gain optimal performance for
+ the persistence of messages and transactions.</para>
+ <para>A HornetQ journal is an <emphasis>append only</emphasis> journal. It consists of a set of
+ files on disk. Each file is pre-created to a fixed size and initially filled with padding.
+ As operations are performed on the server, e.g. add message, update message, delete message,
+ records are appended to the journal. When one journal file is full we move to the next
+ one.</para>
<para>Because records are only appended, i.e. added to the end of the journal we minimise disk
- head movement, i.e. we minimise random access operations.</para>
+ head movement, i.e. we minimise random access operations which is typically the slowest
+ operation on a disk.</para>
<para>Making the file size configurable means that an optimal size can be chosen, i.e. making
each file fit on a disk cylinder. Modern disk topologies are complex and we are not in
control over which cylinder(s) the file is mapped onto so this is not an exact science. But
by minimising the number of disk cylinders the file is using, we can minimise the amount of
disk head movement, since an entire disk cylinder is accessible simply by the disk rotating
- the head does not have to move.</para>
- <para>As delete records are added to the journal, HornetQ has a sophisticated file
- garbage collection algorithm which can determine if a particular journal file is needed any
- more - i.e. has all it's data been deleted in the same or other files. If so, the file can
- be reclaimed and re-used. </para>
- <para>HornetQ also has a compaction algorithm which removes dead space from the journal
- and compresses up the data so it takes up less files on disk.</para>
+ <para>As delete records are added to the journal, HornetQ has a sophisticated file garbage
+ collection algorithm which can determine if a particular journal file is needed any more -
+ i.e. has all it's data been deleted in the same or other files. If so, the file can be
+ reclaimed and re-used. </para>
+ <para>HornetQ also has a compaction algorithm which removes dead space from the journal and
+ compresses up the data so it takes up less files on disk.</para>
<para>The journal also fully supports transactional operation if required, supporting both local
and XA transactions.</para>
<para>The majority of the journal is written in Java, however we abstract out the interaction
- with the actual file system to allow different pluggable implementations. HornetQ ships
- with two implementations:</para>
+ with the actual file system to allow different pluggable implementations. HornetQ ships with
+ two implementations:</para>
<itemizedlist>
<listitem>
<para>Java <ulink url="http://en.wikipedia.org/wiki/New_I/O">NIO</ulink>.</para>
<para>The first implementation uses standard Java NIO to interface with the file system.
- This provides very good performance and runs on any platform where there's a
- JDK.</para>
+ This provides very good performance and runs on any platform where there's a Java 5+
+ runtime.</para>
</listitem>
<listitem id="aio-journal">
<para>Linux Asynchronous IO</para>
@@ -66,9 +65,9 @@
transaction boundary to be synced to disk. Most disks can only support a limited
number of syncs per second, so a syncing approach does not scale well when the
number of concurrent transactions needed to be committed grows too large. With AIO,
- HornetQ will be called back when the data has made it to disk, allowing us
- to avoid explicit syncs altogether and simply send back confirmation of completion
- when AIO informs us that the data has been persisted.</para>
+ HornetQ will be called back when the data has made it to disk, allowing us to avoid
+ explicit syncs altogether and simply send back confirmation of completion when AIO
+ informs us that the data has been persisted.</para>
<para>The AIO journal is only available when running Linux kernel 2.6 or later and after
having installed libaio (if it's not already installed). For instructions on how to
install libaio please see <xref linkend="installing-aio"/>.</para>
@@ -90,19 +89,18 @@
<para>Message journal.</para>
<para>This journal instance stores all message related data, including the message
themselves and also duplicate id caches.</para>
- <para>By default HornetQ will try and use an AIO journal. If AIO is not
- available, e.g. the platform is not Linux with the correct kernel version or AIO has
- not been installed then it will automatically fall back to using Java NIO which is
- available on any Java platform.</para>
+ <para>By default HornetQ will try and use an AIO journal. If AIO is not available, e.g.
+ the platform is not Linux with the correct kernel version or AIO has not been
+ installed then it will automatically fall back to using Java NIO which is available
+ on any Java platform.</para>
</listitem>
</itemizedlist>
- <para>For large messages, HornetQ persists them outside the message journal. This is
- discussed in <xref linkend="large-messages"/>.</para>
- <para>HornetQ also pages messages to disk in low memory situations. This is discussed in
- <xref linkend="paging"/>.</para>
- <para>If no persistence is required at all, HornetQ can also be configured not to
- persist any data at all to storage as discussed in <xref linkend="persistence.enabled"
- />.</para>
+ <para>For large messages, HornetQ persists them outside the message journal. This is discussed
+ in <xref linkend="large-messages"/>.</para>
+ <para>HornetQ also pages messages to disk in low memory situations. This is discussed in <xref
+ linkend="paging"/>.</para>
+ <para>If no persistence is required at all, HornetQ can also be configured not to persist any
+ data at all to storage as discussed in <xref linkend="persistence.enabled"/>.</para>
<section id="configuring.bindings.journal">
<title>Configuring the bindings journal</title>
<para>The bindings journal is configured using the following attributes in <literal
@@ -153,21 +151,20 @@
<para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
<literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
choose <literal>AIO</literal> but are not running Linux or you do not have
- libaio installed then HornetQ will detect this and automatically fall
- back to using <literal>NIO</literal>.</para>
+ libaio installed then HornetQ will detect this and automatically fall back to
+ using <literal>NIO</literal>.</para>
</listitem>
<listitem id="configuring.message.journal.journal-sync-transactional">
<para><literal>journal-sync-transactional</literal></para>
- <para>If this is set to true then HornetQ will wait for all transaction data
- to be persisted to disk on a commit before sending a commit response OK back to
- the client. The default value is <literal>true</literal>.</para>
+ <para>If this is set to true then HornetQ will wait for all transaction data to be
+ persisted to disk on a commit before sending a commit response OK back to the
+ client. The default value is <literal>true</literal>.</para>
</listitem>
<listitem id="configuring.message.journal.journal-sync-non-transactional">
<para><literal>journal-sync-non-transactional</literal></para>
- <para>If this is set to true then HornetQ will wait for any non
- transactional data to be persisted to disk on a send before sending the response
- back to the client. The default value for this is <literal
- >false</literal>.</para>
+ <para>If this is set to true then HornetQ will wait for any non transactional data
+ to be persisted to disk on a send before sending the response back to the
+ client. The default value for this is <literal>false</literal>.</para>
</listitem>
<listitem id="configuring.message.journal.journal-file-size">
<para><literal>journal-file-size</literal></para>
@@ -176,9 +173,9 @@
</listitem>
<listitem id="configuring.message.journal.journal-min-files">
<para><literal>journal-min-files</literal></para>
- <para>The minimum number of files the journal will maintain. When HornetQ
- starts and there is no initial message data, HornetQ will pre-create
- <literal>journal-min-files</literal> number of files.</para>
+ <para>The minimum number of files the journal will maintain. When HornetQ starts and
+ there is no initial message data, HornetQ will pre-create <literal
+ >journal-min-files</literal> number of files.</para>
<para>Creating journal files and filling them with padding is a fairly expensive
operation and we want to minimise doing this at run-time as files get filled. By
precreating files, as one is filled the journal can immediately resume with the
@@ -189,24 +186,24 @@
<listitem id="configuring.message.journal.journal-max-aio">
<para><literal>journal-max-aio</literal></para>
<para>When using an AIO journal, write requests are queued up before being submitted
- to AIO for execution. Then when AIO has completed them it calls HornetQ
- back. This parameter controls the maximum number of write requests that can be
- in the AIO queue at any one time. If the queue becomes full then writes will
- block until space is freed up. This parameter has no meaning when using the NIO
+ to AIO for execution. Then when AIO has completed them it calls HornetQ back.
+ This parameter controls the maximum number of write requests that can be in the
+ AIO queue at any one time. If the queue becomes full then writes will block
+ until space is freed up. This parameter has no meaning when using the NIO
journal.</para>
- <para>There is a limit and the total max AIO can't be higher than what is configured
+ <para>There is a limit and the total max AIO can't be higher than what is configured
at the OS level (/proc/sys/fs/aio-max-nr) usually at 65536.</para>
- <para>The default value for this is <literal>500</literal>.
- </para>
+ <para>The default value for this is <literal>500</literal>. </para>
</listitem>
<listitem id="configuring.message.journal.journal-aio-buffer-timeout">
<para><literal>journal-aio-buffer-timeout</literal></para>
<para>Flush period on the internal AIO timed buffer, configured in nano seconds. For
- performance reasons we buffer data before submitting it to the kernel in a single batch.
- This parameter determines the maximum amount of time to wait before flushing the buffer, if it does not get full
- by itself in that time.</para>
- <para>The default value for this paramater is <literal>20000</literal> nano seconds (i.e. 20 microseconds).
- </para>
+ performance reasons we buffer data before submitting it to the kernel in a
+ single batch. This parameter determines the maximum amount of time to wait
+ before flushing the buffer, if it does not get full by itself in that
+ time.</para>
+ <para>The default value for this paramater is <literal>20000</literal> nano seconds
+ (i.e. 20 microseconds). </para>
</listitem>
<listitem id="configuring.message.journal.journal-aio-flush-on-sync">
<para><literal>journal-aio-flush-on-sync</literal></para>
@@ -214,37 +211,41 @@
sync request is performed. Sync requests are performed on transactions if
<literal>journal-sync-transactional</literal> is true, or on sending regular
messages if <literal>journalsync-non-transactional</literal> is true.</para>
- <para>HornetQ was made to scale up to hundreds of producers. We try to use
- most of the hardware resources by scheduling multiple writes and syncs in a
- single OS call.</para>
+ <para>HornetQ was made to scale up to hundreds of producers. We try to use most of
+ the hardware resources by scheduling multiple writes and syncs in a single OS
+ call.</para>
<para>However in some use cases it may be better to not wait any data and just flush
and write to the OS right away. For example if you have a single producer
writing small transactions. On this case it would be better to always
flush-on-sync.</para>
- <para>The default value for this parameter is <literal>false</literal>.
- </para>
+ <para>The default value for this parameter is <literal>false</literal>. </para>
</listitem>
<listitem id="configuring.message.journal.journal-aio-buffer-size">
<para><literal>journal-aio-buffer-size</literal></para>
- <para>The size of the timed buffer on AIO. The default value is <literal>128KiB</literal>.</para>
+ <para>The size of the timed buffer on AIO. The default value is <literal
+ >128KiB</literal>.</para>
</listitem>
<listitem id="configuring.message.journal.journal-compact-min-files">
<para><literal>journal-compact-min-files</literal></para>
- <para>The minimal number of files before we can consider compacting the journal. The compacting algorithm won't start until you have at least <literal>journal-compact-min-files</literal></para>
+ <para>The minimal number of files before we can consider compacting the journal. The
+ compacting algorithm won't start until you have at least <literal
+ >journal-compact-min-files</literal></para>
<para>The default for this parameter is <literal>10</literal></para>
</listitem>
<listitem id="configuring.message.journal.journal-compact-percentage">
<para><literal>journal-compact-percentage</literal></para>
- <para>The threshold to start compacting. When less than this percentage is considered live data, we start compacting.
- Note also that compacting won't kick in until you have at least <literal>journal-compact-min-files</literal> data files on the journal</para>
+ <para>The threshold to start compacting. When less than this percentage is
+ considered live data, we start compacting. Note also that compacting won't kick
+ in until you have at least <literal>journal-compact-min-files</literal> data
+ files on the journal</para>
<para>The default for this parameter is <literal>30</literal></para>
</listitem>
</itemizedlist>
</section>
<section id="installing-aio">
<title>Installing AIO</title>
- <para>The Java NIO journal gives great performance, but If you are running HornetQ
- using Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
+ <para>The Java NIO journal gives great performance, but If you are running HornetQ using
+ Linux Kernel 2.6 or later, we highly recommend you use the <literal>AIO</literal>
journal for the best persistence performance especially under high concurrency.</para>
<para>It's not possible to use the AIO journal under other operating systems or earlier
versions of the Linux kernel.</para>
@@ -258,9 +259,9 @@
</section>
<section id="persistence.enabled">
<title>Configuring HornetQ for Zero Persistence</title>
- <para> In some situations, zero persistence is sometimes required for a messaging system.
- Configuring HornetQ to perform zero persistence is straightforward. Simply set
- the parameter <literal>persistence-enabled</literal> in <literal
+ <para>In some situations, zero persistence is sometimes required for a messaging system.
+ Configuring HornetQ to perform zero persistence is straightforward. Simply set the
+ parameter <literal>persistence-enabled</literal> in <literal
>hornetq-configuration.xml</literal> to <literal>false</literal>. </para>
<para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
persistence will occur. That means no bindings data, message data, large message data,
Modified: trunk/docs/user-manual/en/preface.xml
===================================================================
--- trunk/docs/user-manual/en/preface.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/preface.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,22 +16,42 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="preface">
<title>Preface</title>
- <para>The goal of HornetQ is simple and uncompromising; to bring unrivaled levels of
- performance and reliability to messaging, and to be the fastest, best featured and most
- scalable multi-protocol messaging system.</para>
+ <para>What is HornetQ?</para>
+ <itemizedlist>
+ <listitem>
+ <para>HornetQ is an open source project to build a multi-protocol, embeddable, high
+ performance, clustered, asynchronous messaging system.</para>
+ </listitem>
+ <listitem>
+ <para>HornetQ is an example of Message Oriented Middleware (MoM) For a description of
+ MoMs and other messaging concepts please see the <xref linkend="messaging-concepts"
+ />.</para>
+ </listitem>
+ <listitem>
+ <para>HornetQ is Red Hat's flagship Java messaging system.</para>
+ </listitem>
+ <listitem>
+ <para>For answers to more questions about what HornetQ is and isn't please visit
+ the<ulink url="http://www.jboss.org/community/wiki/HornetQGeneralFAQs">FAQs wiki
+ page</ulink>.</para>
+ </listitem>
+ </itemizedlist>
<para>Why use HornetQ? Here are just a few of the reasons:</para>
<itemizedlist>
<listitem>
- <para>100% open source software.</para>
+ <para>100% open source software. HornetQ is licenced using the Apache Software License v
+ 2.0 to minimise barriers to adoption.</para>
</listitem>
<listitem>
- <para>Written in Java. Runs on any platform with a J2SE 5.0 JDK, that's everything from
- Windows desktops to IBM mainframes.</para>
+ <para>HornetQ is designed with usability in mind.</para>
</listitem>
<listitem>
+ <para>Written in Java. Runs on any platform with a Java 5+ runtime, that's everything
+ from Windows desktops to IBM mainframes.</para>
+ </listitem>
+ <listitem>
<para>Superb performance. Our class beating high performance journal provides persistent
messaging performance at rates normally seen for non persistent messaging, our non
persistent messaging performance rocks the boat too.</para>
@@ -43,13 +62,13 @@
</listitem>
<listitem>
<para>Elegant POJO based design with minimal third party dependencies. Run HornetQ
- stand-alone, run it in integrated in your favourite JEE application
- server, or run it embedded inside your own product.</para>
+ stand-alone, run it in integrated in your favourite JEE application server, or run
+ it embedded inside your own product.</para>
</listitem>
<listitem>
- <para>Seamless high availability. We provide server replication and completely
- transparent client failover so you don't have to worry about coding your client
- specially for an HA environment.</para>
+ <para>Seamless high availability. We provide a HA solution with automatic client
+ failover so you can guarantee zero message loss or duplication in event of server
+ failure.</para>
</listitem>
<listitem>
<para>Hugely flexible clustering. Create clusters of servers that know how to load
@@ -57,5 +76,10 @@
connections to form a global network. Configure routing of messages in a highly
flexible way.</para>
</listitem>
+ <listitem>
+ <para>For a full list of features, please see the <ulink
+ url="http://www.jboss.org/community/wiki/HornetQFeatures">features wiki
+ page</ulink> .</para>
+ </listitem>
</itemizedlist>
</chapter>
Modified: trunk/docs/user-manual/en/project-info.xml
===================================================================
--- trunk/docs/user-manual/en/project-info.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/project-info.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -30,17 +30,25 @@
</section>
<section id="download.svn">
- <title>Project Information</title>
- <para>If you have any user questions please use our <ulink
- url="http://n2.nabble.com/hornetq-users-f3404100.html">user
- forum</ulink></para>
- <para>If you have development related questions, please use our <ulink
- url="http://n2.nabble.com/hornetq-dev-f3404069.html">development
- forum</ulink></para>
- <para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/hornetq">IRC channel</ulink></para>
- <para>HornetQ Subversion trunk is <ulink url="http://anonsvn.jboss.org/repos/hornetq/trunk">http://anonsvn.jboss.org/repos/hornetq/trunk</ulink></para>
- <para>All release tags are availble from <ulink url="http://anonsvn.jboss.org/repos/hornetq/tags">http://anonsvn.jboss.org/repos/hornetq/tags</ulink></para>
- </section>
+ <title>Project Information</title>
+ <para>
+ <itemizedlist>
+ <listitem><para>Please take a look at our project <ulink url="http://www.jboss.org/community/wiki/HornetQ">wiki</ulink></para></listitem>
+ <listitem> <para>If you have any user questions please use our <ulink
+ url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=312">user
+ forum</ulink></para></listitem>
+ <listitem><para>If you have development related questions, please use our <ulink
+ url="http://www.jboss.org/index.html?module=bb&op=viewforum&f=313">developer
+ forum</ulink></para></listitem>
+ <listitem><para>Pop in and chat to us in our <ulink url="irc://irc.freenode.net:6667/hornetq">IRC channel</ulink></para></listitem>
+ <listitem><para>Our project <ulink url="http://hornetq.blogspot.com/">blog</ulink></para></listitem>
+ <listitem><para>Follow us on <ulink url="http://twitter.com/hornetq">twitter</ulink></para></listitem>
+ <listitem><para>HornetQ Subversion trunk is <ulink url="http://anonsvn.jboss.org/repos/hornetq/trunk">http://anonsvn.jboss.org/repos/hornetq/trunk</ulink></para></listitem>
+ <listitem><para>All release tags are availble from <ulink url="http://anonsvn.jboss.org/repos/hornetq/tags">http://anonsvn.jboss.org/repos/hornetq/tags</ulink></para></listitem>
+ </itemizedlist>
+ </para>
+
+
<para>Red Hat kindly employs developers to work full time on HornetQ, the motley crew are:
<itemizedlist>
<listitem><para> <ulink url="http://jbossfox.blogspot.com">Tim Fox</ulink> (project lead)</para></listitem>
@@ -50,6 +58,6 @@
<listitem><para>Andy Taylor</para></listitem>
</itemizedlist>
</para>
+ </section>
-
</chapter>
Modified: trunk/docs/user-manual/en/queue-attributes.xml
===================================================================
--- trunk/docs/user-manual/en/queue-attributes.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/queue-attributes.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="queue-attributes">
<title>Queue Attributes</title>
<para>Queue attributes can be set in one of two ways. Either by configuring them using the
@@ -68,9 +66,9 @@
<para>There is no entry element.</para>
</listitem>
<listitem>
- <para>The filter uses the <emphasis>Core filter syntax</emphasis>
- (described in <xref linkend="filter-expressions" />),
- <emphasis>not</emphasis> the JMS selector syntax.</para>
+ <para>The filter uses the <emphasis>Core filter syntax</emphasis> (described in
+ <xref linkend="filter-expressions"/>), <emphasis>not</emphasis> the JMS
+ selector syntax.</para>
</listitem>
</orderedlist>
</section>
@@ -78,12 +76,12 @@
<title>Using the API</title>
<para>Queues can also be created using the core API or the management API.</para>
<para>For the core API, queues can be created via the <literal
- >org.hornetq.core.client.ClientSession</literal> interface. There are
- multiple <literal>createQueue</literal> methods that support setting all of the
- previously mentioned attributes. There is one extra attribute that can be set via this
- API which is <literal>temporary</literal>. setting this to true means that the queue
- will be deleted once the session is disconnected.</para>
- <para>Take a look at <xref linkend="management" /> for a description of the management API
+ >org.hornetq.core.client.ClientSession</literal> interface. There are multiple
+ <literal>createQueue</literal> methods that support setting all of the previously
+ mentioned attributes. There is one extra attribute that can be set via this API which is
+ <literal>temporary</literal>. setting this to true means that the queue will be
+ deleted once the session is disconnected.</para>
+ <para>Take a look at <xref linkend="management"/> for a description of the management API
for creating queues.</para>
</section>
<section id="queue-attributes.address-settings">
@@ -104,7 +102,7 @@
<redistribution-delay>0</redistribution-delay>
</address-setting>
</address-settings></programlisting>
- <para>These are explained fully throughout the user manual, howvere here is a breif
+ <para>These are explained fully throughout the user manual, howvere here is a brief
description with a link to the appropriate chapter if available. </para>
<para><literal>max-delivery-attempts</literal> defines how many time a cancelled message can
be redelivered before sending to the <literal>dead-letter-address</literal>. A full
Modified: trunk/docs/user-manual/en/security.xml
===================================================================
--- trunk/docs/user-manual/en/security.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/security.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,26 +16,25 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="security">
<title>Security</title>
- <para>This chapter describes how security works with HornetQ and how you can configure
- it. To disable security completely simply set the <literal>security-enabled</literal>
- property to false in the <literal>hornetq-configuration.xml</literal> file.</para>
+ <para>This chapter describes how security works with HornetQ and how you can configure it. To
+ disable security completely simply set the <literal>security-enabled</literal> property to
+ false in the <literal>hornetq-configuration.xml</literal> file.</para>
<para>For performance reasons security is cached and invalidated every so long. To change this
period set the property <literal>security-invalidation-interval</literal>, which is in
milliseconds. The default is <literal>10000</literal> ms.</para>
<section id="security.settings.roles">
<title>Role based security for addresses</title>
- <para>HornetQ contains a flexible role-based security model for applying security to
- queues, based on their addresses.</para>
- <para>As explained in <xref linkend="using-core" />, HornetQ core consists
- mainly of sets of queues bound to addresses. A message is sent to an address and the
- server looks up the set of queues that are bound to that address, the server then routes
- the message to those set of queues.</para>
- <para>HornetQ allows sets of permissions to be defined against the queues based on
- their address. An exact match on the address can be used or a wildcard match can be used
- using the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
+ <para>HornetQ contains a flexible role-based security model for applying security to queues,
+ based on their addresses.</para>
+ <para>As explained in <xref linkend="using-core"/>, HornetQ core consists mainly of sets of
+ queues bound to addresses. A message is sent to an address and the server looks up the
+ set of queues that are bound to that address, the server then routes the message to
+ those set of queues.</para>
+ <para>HornetQ allows sets of permissions to be defined against the queues based on their
+ address. An exact match on the address can be used or a wildcard match can be used using
+ the wildcard characters '<literal>#</literal>' and '<literal>*</literal>'.</para>
<para>Seven different permissions can be given to the set of queues which match the address.
Those permissions are:</para>
<itemizedlist>
@@ -74,7 +72,8 @@
the user has any of those roles, he/she will be granted that permission for that set of
addresses.</para>
<para>Let's take a simple example, here's a security block from <literal
- >hornetq-configuration.xml</literal> or <literal>hornetq-queues.xml</literal> file:</para>
+ >hornetq-configuration.xml</literal> or <literal>hornetq-queues.xml</literal>
+ file:</para>
<programlisting>
<security-setting match="globalqueues.europe.#">
<permission type="createDurableQueue" roles="admin"/>
@@ -87,9 +86,8 @@
</programlisting>
<para>The '<literal>#</literal>' character signifies "any sequence of words". Words are
delimited by the '<literal>.</literal>' character. For a full description of the
- wildcard syntax please see <xref linkend="wildcard-syntax"/>.
- The above security block applies to any address that starts with the
- string "globalqueues.europe.":</para>
+ wildcard syntax please see <xref linkend="wildcard-syntax"/>. The above security block
+ applies to any address that starts with the string "globalqueues.europe.":</para>
<para>Only users who have the <literal>admin</literal> role can create or delete durable
queues bound to an address that starts with the string "globalqueues.europe."</para>
<para>Only users who have the <literal>admin</literal> role can create or delete durable
@@ -101,10 +99,10 @@
can send messages to these addresses or consume messages from queues bound to an address
that starts with the string "globalqueues.europe."</para>
<para>The mapping between a user and what roles they have is handled by the security
- manager. HornetQ ships with a user manager that reads user credentials from a
- file on disk, and can also plug into JAAS or JBoss Application Server security.</para>
+ manager. HornetQ ships with a user manager that reads user credentials from a file on
+ disk, and can also plug into JAAS or JBoss Application Server security.</para>
<para>For more information on configuring the security manager, please see <xref
- linkend="change-security-manager" />.</para>
+ linkend="change-security-manager"/>.</para>
<para>There can be zero or more <literal>security-setting</literal> elements in each xml
file. Where more than one match applies to a set of addresses the <emphasis>more
specific</emphasis> match takes precedence.</para>
@@ -136,17 +134,16 @@
<section>
<title>Secure Sockets Layer (SSL) Transport</title>
<para>When messaging clients are connected to servers, or servers are connected to other
- servers (e.g. via bridges) over an untrusted network then HornetQ allows that
- traffic to be encrypted using the Secure Sockets Layer (SSL) transport.</para>
+ servers (e.g. via bridges) over an untrusted network then HornetQ allows that traffic to
+ be encrypted using the Secure Sockets Layer (SSL) transport.</para>
<para>For more information on configuring the SSL transport, please see <xref
- linkend="configuring-transports" />.</para>
+ linkend="configuring-transports"/>.</para>
</section>
<section>
<title>Basic user credentials</title>
- <para> HornetQ ships with a security manager implementation that reads user
- credentials, i.e. user names, passwords and role information from an xml file on the
- classpath called <literal>hornetq-users.xml</literal>. This is the default security
- manager.</para>
+ <para>HornetQ ships with a security manager implementation that reads user credentials, i.e.
+ user names, passwords and role information from an xml file on the classpath called
+ <literal>hornetq-users.xml</literal>. This is the default security manager.</para>
<para>If you wish to use this security manager, then users, passwords and roles can easily
be added into this file.</para>
<para>Let's take a look at an example file:</para>
@@ -188,10 +185,9 @@
<section id="change-security-manager">
<title>Changing the security manager</title>
<para>If you do not want to use the default security manager then you can specify a
- different one by editing the file <literal>hornetq-beans.xml</literal>
- (or <literal>hornetq-jboss-beans.xml</literal> if you're running JBoss Application Server)
- and changing
- the class for the <literal>HornetQSecurityManager</literal> bean.</para>
+ different one by editing the file <literal>hornetq-beans.xml</literal> (or <literal
+ >hornetq-jboss-beans.xml</literal> if you're running JBoss Application Server) and
+ changing the class for the <literal>HornetQSecurityManager</literal> bean.</para>
<para>Let's take a look at a snippet from the default beans file:</para>
<programlisting>
<bean name="HornetQSecurityManager"
@@ -200,16 +196,15 @@
<stop ignored="true"/>
</bean>
</programlisting>
- <para>The class <literal
- >org.hornetq.core.security.impl.HornetQSecurityManagerImpl</literal> is the
- default security manager that reads used by the standalone server.</para>
+ <para>The class <literal>org.hornetq.core.security.impl.HornetQSecurityManagerImpl</literal>
+ is the default security manager that reads used by the standalone server.</para>
<para>HornetQ ships with two other security manager implementations you can use
off-the-shelf; one a JAAS security manager and another for integrating with JBoss
Application Sever security, alternatively you could write your own implementation by
- implementing the <literal>org.hornetq.core.security.SecurityManager</literal>
- interface, and specifying the classname of your implementation in the
- file <literal>hornetq-beans.xml</literal>
- (or <literal>hornetq-jboss-beans.xml</literal> if you're running JBoss Application Server).</para>
+ implementing the <literal>org.hornetq.core.security.SecurityManager</literal> interface,
+ and specifying the classname of your implementation in the file <literal
+ >hornetq-beans.xml</literal> (or <literal>hornetq-jboss-beans.xml</literal> if
+ you're running JBoss Application Server).</para>
<para>These two implementations are discussed in the next two sections.</para>
</section>
<section>
@@ -252,8 +247,8 @@
</itemizedlist>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.jaas" /> for an example which
- shows how HornetQ can be configured to use JAAS.</para>
+ <para>See <xref linkend="examples.jaas"/> for an example which shows how HornetQ can be
+ configured to use JAAS.</para>
</section>
</section>
<section>
@@ -274,7 +269,6 @@
these actions as a user with a role that has <literal>admin</literal> permissions on the
management addresses.</para>
<para>This password should always be changed from its default after installation. Please see
- <xref linkend="management" /> for instructions on how to do
- this.</para>
+ <xref linkend="management"/> for instructions on how to do this.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/send-guarantees.xml
===================================================================
--- trunk/docs/user-manual/en/send-guarantees.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/send-guarantees.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,15 +16,13 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="send-guarantees">
- <title>Guarantees of Transactional and Non-Transactional Sends and Asynchronous Send
- Acknowledgements</title>
+ <title>Guarantees of sends and commits</title>
<section>
<title>Guarantees of Transaction Completion</title>
- <para>When committing or rolling back a transaction with HornetQ, the request to
- commit or rollback is sent to the server, and the call will block on the client side
- until a response has been received from the server that the commit or rollback was
+ <para>When committing or rolling back a transaction with HornetQ, the request to commit or
+ rollback is sent to the server, and the call will block on the client side until a
+ response has been received from the server that the commit or rollback was
executed.</para>
<para>When the commit or rollback is received on the server, it will be committed to the
journal, and depending on the value of the parameter <literal
@@ -43,11 +40,11 @@
</section>
<section id="non-transactional-sends">
<title>Guarantees of Non Transactional Message Sends</title>
- <para>If you are sending messages to a server using a non transacted session, HornetQ
- can be configured to block the call to send until the message has definitely
- reached the server, and a response has been sent back to the client. This can be
- configured individually for persistent and non-persistent messages, and is determined by
- the following two parameters:</para>
+ <para>If you are sending messages to a server using a non transacted session, HornetQ can be
+ configured to block the call to send until the message has definitely reached the
+ server, and a response has been sent back to the client. This can be configured
+ individually for persistent and non-persistent messages, and is determined by the
+ following two parameters:</para>
<itemizedlist>
<listitem>
<para><literal>BlockOnPersistentSend</literal>. If this is set to <literal
@@ -69,9 +66,9 @@
performance of sending messages will be limited by the network round trip time (RTT) of
your network, rather than the bandwidth of your network. For better performance we
recommend either batching many messages sends together in a transaction since with a
- transactional session, only the commit / rollback blocks not every send, or, using HornetQ's
- advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
- described in <xref linkend="asynchronous-send-acknowledgements" />.</para>
+ transactional session, only the commit / rollback blocks not every send, or, using
+ HornetQ's advanced <emphasis>asynchronous send acknowledgements feature</emphasis>
+ described in <xref linkend="asynchronous-send-acknowledgements"/>.</para>
<para>If you are using JMS and you're using the JMS service on the server to load your JMS
connection factory instances into JNDI then these parameters can be configured in
<literal>hornetq-jms.xml</literal> using the elements <literal
@@ -93,26 +90,25 @@
<section id="send-guarantees.nontrans.acks">
<title>Guarantees of Non Transactional Acknowledgements</title>
<para>If you are acknowledging the delivery of a message at the client side using a non
- transacted session, HornetQ can be configured to block the call to acknowledge
- until the acknowledge has definitely reached the server, and a response has been sent
- back to the client. This is configured with the parameter <literal
- >BlockOnAcknowledge</literal>. If this is set to <literal>true</literal> then all
- calls to acknowledge on non transacted sessions will block until the acknowledge has
- reached the server, and a response has been sent back. You might want to set this to
- <literal>true</literal> if you want to implement a strict <emphasis>at most
- once</emphasis> delivery policy. The default value is <literal
- >false</literal></para>
+ transacted session, HornetQ can be configured to block the call to acknowledge until the
+ acknowledge has definitely reached the server, and a response has been sent back to the
+ client. This is configured with the parameter <literal>BlockOnAcknowledge</literal>. If
+ this is set to <literal>true</literal> then all calls to acknowledge on non transacted
+ sessions will block until the acknowledge has reached the server, and a response has
+ been sent back. You might want to set this to <literal>true</literal> if you want to
+ implement a strict <emphasis>at most once</emphasis> delivery policy. The default value
+ is <literal>false</literal></para>
</section>
<section id="asynchronous-send-acknowledgements">
<title>Asynchronous Send Acknowledgements</title>
<para>If you are using a non transacted session but want a guarantee that every message sent
to the server has reached it, then, as discussed in <xref
- linkend="non-transactional-sends"/>, you can configure HornetQ to block the
- call to send until the server has received the message, persisted it and sent back a
- response. This works well but has a severe performance penalty - each call to send needs
- to block for at least the time of a network round trip (RTT) - the performance of
- sending is thus limited by the latency of the network, <emphasis>not</emphasis> limited
- by the network bandwidth.</para>
+ linkend="non-transactional-sends"/>, you can configure HornetQ to block the call to
+ send until the server has received the message, persisted it and sent back a response.
+ This works well but has a severe performance penalty - each call to send needs to block
+ for at least the time of a network round trip (RTT) - the performance of sending is thus
+ limited by the latency of the network, <emphasis>not</emphasis> limited by the network
+ bandwidth.</para>
<para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
1Gib ethernet network with a network round trip between the server and the client of
0.25 ms.</para>
@@ -123,28 +119,27 @@
* 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
blocking! These figures aren't an exact science but you can clearly see that being
limited by network RTT can have serious effect on performance.</para>
- <para>To remedy this, HornetQ provides an advanced new feature called
- <emphasis>asynchronous send acknowledgements</emphasis>. With this feature, HornetQ
- can be configured to send messages without blocking in one direction and
- asynchronously getting acknowledgement from the server that the messages were received
- in a separate stream. By de-coupling the send from the acknowledgement of the send, the
- system is not limited by the network RTT, but is limited by the network bandwidth.
- Consequently better throughput can be achieved than is possible using a blocking
- approach, while at the same time having absolute guarantees that messages have
- successfully reached the server.</para>
+ <para>To remedy this, HornetQ provides an advanced new feature called <emphasis>asynchronous
+ send acknowledgements</emphasis>. With this feature, HornetQ can be configured to
+ send messages without blocking in one direction and asynchronously getting
+ acknowledgement from the server that the messages were received in a separate stream. By
+ de-coupling the send from the acknowledgement of the send, the system is not limited by
+ the network RTT, but is limited by the network bandwidth. Consequently better throughput
+ can be achieved than is possible using a blocking approach, while at the same time
+ having absolute guarantees that messages have successfully reached the server.</para>
<section>
<title>Asynchronous Send Acknowledgements</title>
<para>To use the feature using the core API, you implement the interface <literal
- >org.hornetq.core.client.SendAcknowledgementHandler</literal> and set a
- handler instance on your <literal>ClientSession</literal>.</para>
+ >org.hornetq.core.client.SendAcknowledgementHandler</literal> and set a handler
+ instance on your <literal>ClientSession</literal>.</para>
<para>Then, you just send messages as normal using your <literal
>ClientSession</literal>, and as messages reach the server, the server will send
back an acknowledgment of the send asynchronously, and some time later you are
informed at the client side by HornetQ calling your handler's <literal
>sendAcknowledged(ClientMessage message)</literal> method, passing in a
reference to the message that was sent.</para>
- <para>Please see <xref linkend="asynchronous-send-acknowledgements-example" />
- for a full working example.</para>
+ <para>Please see <xref linkend="asynchronous-send-acknowledgements-example"/> for a full
+ working example.</para>
</section>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/thread-pooling.xml
===================================================================
--- trunk/docs/user-manual/en/thread-pooling.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/thread-pooling.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="thread-pooling">
<title>Thread management</title>
<para>This chapter describes how HornetQ uses and pools threads and how you can manage
@@ -26,10 +24,10 @@
at the client side.</para>
<section>
<title>Server-Side Thread Management</title>
- <para>Each HornetQ Server maintains a single thread pool for general use, and a
- scheduled thread pool for scheduled use. A Java scheduled thread pool cannot be
- configured to use a standard thread pool, otherwise we could use a single thread pool
- for both scheduled and non scheduled activity.</para>
+ <para>Each HornetQ Server maintains a single thread pool for general use, and a scheduled
+ thread pool for scheduled use. A Java scheduled thread pool cannot be configured to use
+ a standard thread pool, otherwise we could use a single thread pool for both scheduled
+ and non scheduled activity.</para>
<para>There are also a small number of other places where threads are used directly, we'll
discuss each in turn.</para>
<section id="server.scheduled.thread.pool">
@@ -79,9 +77,9 @@
<section>
<title>Asynchronous IO</title>
<para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
- native layer. You will find it on a thread dump with the prefix HornetQ-AIO-poller-pool.
- HornetQ uses one thread per opened file on the journal (there is usually
- one).</para>
+ native layer. You will find it on a thread dump with the prefix
+ HornetQ-AIO-poller-pool. HornetQ uses one thread per opened file on the journal
+ (there is usually one).</para>
<para>There is also a single thread used to invoke writes on libaio. We do that to avoid
context switching on libaio what would cause performance issues. You will find this
thread on a thread dump with the prefix HornetQ-AIO-writer-pool.</para>
@@ -89,10 +87,10 @@
</section>
<section id="thread-pooling.client.side">
<title>Client-Side Thread Management</title>
- <para>On the client side, HornetQ maintains a single static scheduled thread pool
- and a single static general thread pool for use by all clients using the same
- classloader in that JVM instance.</para>
- <para>The static scheduled thread pool has a maximum size of <literal>2</literal> threads,
+ <para>On the client side, HornetQ maintains a single static scheduled thread pool and a
+ single static general thread pool for use by all clients using the same classloader in
+ that JVM instance.</para>
+ <para>The static scheduled thread pool has a maximum size of <literal>5</literal> threads,
and the general purpose thread pool has an unbounded maximum size.</para>
<para>If required HornetQ can also be configured so that each <literal
>ClientSessionFactory</literal> instance does not use these static pools but instead
@@ -112,8 +110,8 @@
myFactory.setScheduledThreadPoolMaxSize(10);
myFactory.setThreadPoolMaxSize(-1); </programlisting>
<para>If you're using JNDI to instantiate <literal>HornetQConnectionFactory</literal>
- instances, you can also set these parameters in the <literal>hornetq-jms.xml</literal> file
- where you describe your connection factory, for example:</para>
+ instances, you can also set these parameters in the <literal>hornetq-jms.xml</literal>
+ file where you describe your connection factory, for example:</para>
<programlisting><connection-factory name="ConnectionFactory">
<connector-ref connector-name="netty"/>
<entries>
Modified: trunk/docs/user-manual/en/transaction-config.xml
===================================================================
--- trunk/docs/user-manual/en/transaction-config.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/transaction-config.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,19 +16,17 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="transaction-config">
<title>Resource Manager Configuration</title>
- <para>HornetQ has its own Resource Manager for handling the lifespan of XA transactions.
- When a transaction is started the resource manager is notified and keeps a record of the
+ <para>HornetQ has its own Resource Manager for handling the lifespan of JTA transactions. When a
+ transaction is started the resource manager is notified and keeps a record of the
transaction and its current state. It is possible in some cases for a transaction to be
started but the forgotten about. Maybe the client died and never came back. If this happens
then the transaction will just sit there indefinitely.</para>
- <para>To cope with this HornetQ can, if configured, scan for old transactions and
- rollback any it finds. The default for this is 60000 milliseconds (1 minute), i.e. any
- transactions older than 60 seconds are removed, however this can be changed by editing the
- <literal>transaction-timeout</literal> property in <literal
- >hornetq-configuration.xml</literal>. The property <literal
- >transaction-timeout-scan-period</literal> configures how often, in milliseconds, to
- scan for old transactions.</para>
+ <para>To cope with this HornetQ can, if configured, scan for old transactions and rollback any
+ it finds. The default for this is 60000 milliseconds (1 minute), i.e. any transactions older
+ than 60 seconds are removed, however this can be changed by editing the <literal
+ >transaction-timeout</literal> property in <literal>hornetq-configuration.xml</literal>.
+ The property <literal>transaction-timeout-scan-period</literal> configures how often, in
+ milliseconds, to scan for old transactions.</para>
</chapter>
Modified: trunk/docs/user-manual/en/undelivered-messages.xml
===================================================================
--- trunk/docs/user-manual/en/undelivered-messages.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/undelivered-messages.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="undelivered-messages">
<title>Message Redelivery and Undelivered Messages</title>
<para>Messages can be delivered unsuccessfully (e.g. if the transacted session used to consume
@@ -54,31 +52,32 @@
<redelivery-delay>5000</redelivery-delay>
</address-setting>
</programlisting>
- <para>If a <literal>redelivery-delay</literal> is specified, HornetQ will wait this
- delay before redelivering the messages</para>
+ <para>If a <literal>redelivery-delay</literal> is specified, HornetQ will wait this delay
+ before redelivering the messages</para>
<para>By default, there is no redelivery delay (<literal>redelivery-delay</literal>is set
to 0).</para>
<para>Address wildcards can be used to configure redelivery delay for a set of addresses
- (see <xref linkend="wildcard-syntax"/>).</para>
+ (see <xref linkend="wildcard-syntax"/>), so you don't have to specify redelivery delay
+ individually for each address.</para>
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.delayed-redelivery" /> for an example which
- shows how delayed redelivery is configured and used with JMS.</para>
+ <para>See <xref linkend="examples.delayed-redelivery"/> for an example which shows how
+ delayed redelivery is configured and used with JMS.</para>
</section>
</section>
<section>
<title>Dead Letter Addresses</title>
<para>To prevent a client infinitely receiving the same undelivered message (regardless of
- what is causing the unsuccessful deliveries), messaging systems define dead letter
- messages: after a specified unsuccessful delivery attempts, the message is removed from the
- queue and send instead to a dead letter address. </para>
- <para>Any dead letter messages can then be diverted to queue(s) where they can later be
- perused by the system administrator for action to be taken.</para>
- <para>HornetQ's addresses can be assigned a dead letter address. Once the messages
- have be unsuccessfully delivered for a given number of attempts, they are removed from the
- queue and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages
- can later be consumed for further inspection.</para>
+ what is causing the unsuccessful deliveries), messaging systems define <emphasis
+ role="italic">dead letter addresses</emphasis>: after a specified unsuccessful delivery
+ attempts, the message is removed from the queue and send instead to a dead letter address. </para>
+ <para>Any such messages can then be diverted to queue(s) where they can later be perused by
+ the system administrator for action to be taken.</para>
+ <para>HornetQ's addresses can be assigned a dead letter address. Once the messages have be
+ unsuccessfully delivered for a given number of attempts, they are removed from the queue
+ and sent to the dead letter address. These <emphasis>dead letter</emphasis> messages can
+ later be consumed for further inspection.</para>
<section id="undelivered-messages.configuring">
<title>Configuring Dead Letter Addresses</title>
<para>Dead letter address is defined in the address-setting configuration:</para>
@@ -115,27 +114,26 @@
</section>
<section>
<title>Example</title>
- <para>See <xref linkend="examples.dead-letter" /> for an example which
- shows how dead letter is configured and used with JMS.</para>
+ <para>See <xref linkend="examples.dead-letter"/> for an example which shows how dead letter
+ is configured and used with JMS.</para>
</section>
</section>
<section id="configuring.delivery.count.persistence">
<title>Delivery Count Persistence</title>
- <para>In normal use, HornetQ does not update delivery count
- <emphasis>persistently</emphasis> until a message is rolled back (i.e. the delivery
- count is not updated <emphasis>before</emphasis> the message is delivered to the consumer).
- In most messaging use cases, the messages are consumed, acknowledged and forgotten as soon
- as they are consumed. In these cases, updating the delivery count persistently before
- delivering the message would add an extra persistent step <emphasis>for each message
- delivered</emphasis>, implying a significant performance penalty.</para>
+ <para>In normal use, HornetQ does not update delivery count <emphasis>persistently</emphasis>
+ until a message is rolled back (i.e. the delivery count is not updated
+ <emphasis>before</emphasis> the message is delivered to the consumer). In most messaging
+ use cases, the messages are consumed, acknowledged and forgotten as soon as they are
+ consumed. In these cases, updating the delivery count persistently before delivering the
+ message would add an extra persistent step <emphasis>for each message delivered</emphasis>,
+ implying a significant performance penalty.</para>
<para>However, if the delivery count is not updated persistently before the message delivery
happens, in the event of a server crash, messages might have been delivered but that will
not have been reflected in the delivery count. During the recovery phase, the server will
not have knowledge of that and will deliver the message with <literal>redelivered</literal>
set to <literal>false</literal> while it should be <literal>true</literal>. </para>
- <para>As this behavior breaks strict JMS semantics, HornetQ allows to persist delivery
- count before message delivery but disabled it by default for performance
- implications.</para>
+ <para>As this behavior breaks strict JMS semantics, HornetQ allows to persist delivery count
+ before message delivery but disabled it by default for performance implications.</para>
<para>To enable it, set <literal>persist-delivery-count-before-delivery</literal> to <literal
>true</literal> in <literal>hornetq-configuration.xml</literal>:</para>
<programlisting>
Modified: trunk/docs/user-manual/en/using-core.xml
===================================================================
--- trunk/docs/user-manual/en/using-core.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/using-core.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,21 +16,19 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="using-core">
<title>Using Core</title>
- <para>HornetQ core is a completely JMS-agnostic messaging system with its own core
- API.</para>
+ <para>HornetQ core is a completely JMS-agnostic messaging system with its own core API.</para>
<para>If you don't want to use JMS you can use the core API directly. The core API provides all
the functionality of JMS but without much of the complexity. It also provides features that
- are not normally available using JMS.</para>
+ are not available using JMS.</para>
<section>
<title>Core Messaging Concepts</title>
<para>Some of the core messaging concepts are similar to JMS concepts, but core messaging
concepts differ in some ways. In general the core messaging API is simpler than the JMS
- API, since we remove distinctions between queues, topics and subscriptions. We'll
- discuss each of the major core messaging concepts in turn, but to see the API in
- detail, please consult the Javadoc.</para>
+ API, since we remove distinctions between queues, topics and subscriptions. We'll
+ discuss each of the major core messaging concepts in turn, but to see the API in detail,
+ please consult the Javadoc.</para>
<section>
<title>Message</title>
<para>A message is the unit of data which is sent between clients and servers.</para>
@@ -42,15 +39,16 @@
<para>A message has a destination which represents the <emphasis>address</emphasis> it
is being sent to. When the message arrives on the server it is routed to any queues
that are bound to the address. An address may have many queues bound to it or even
- none.</para>
+ none. There may also be entities other than queues, like <emphasis role="italic"
+ >diverts</emphasis> bound to addresses.</para>
<para>Messages can be either durable or non durable. Durable messages in a durable queue
will survive a server crash or restart. Non durable messages will never survive a
server crash or restart.</para>
<para>Messages can be specified with a priority value between 0 and 9. 0 represents the
- highest priority and 9 represents the lowest. HornetQ will attempt to
- deliver higher priority messages before lower priority ones.</para>
- <para>Messages can be specified with an optional expiry time. HornetQ will not
- deliver messages after its expiry time has been exceeded.</para>
+ highest priority and 9 represents the lowest. HornetQ will attempt to deliver higher
+ priority messages before lower priority ones.</para>
+ <para>Messages can be specified with an optional expiry time. HornetQ will not deliver
+ messages after its expiry time has been exceeded.</para>
<para>Messages also have an optional timestamp which represents the time the message was
sent.</para>
</section>
@@ -62,6 +60,8 @@
queues bound to the message's destination address. If any of the queues are bound
with a filter expression, then the message will only be routed to the subset of
bound queues which match that filter expression.</para>
+ <para>Other entities, such as <emphasis role="italic">diverts</emphasis> can also be
+ bound to an address and messages will also be routed there.</para>
<note>
<para>In core, there is no concept of a Topic, Topic is a JMS only term. Instead, in
core, we just deal with <emphasis>addresses</emphasis> and
Modified: trunk/docs/user-manual/en/using-jms.xml
===================================================================
--- trunk/docs/user-manual/en/using-jms.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/using-jms.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,7 +16,6 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="using-jms">
<title>Using JMS</title>
<para>Although HornetQ provides a JMS agnostic messaging API, many users will be more
@@ -26,10 +24,10 @@
API. If you are completely new to JMS we suggest you following the<ulink
url="http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/jms_tutorialTOC.html"> Sun
JMS tutorial</ulink> - a full JMS tutorial is out of scope for this guide.</para>
- <para>HornetQ also ships with a wide range of examples, many of which demonstrate JMS
- API usage. A good place to start would be to play around with the simple JMS Queue and Topic
- example, but we also provide examples for many other parts of the JMS API. A full
- description of the examples is available in <xref linkend="examples"/>.</para>
+ <para>HornetQ also ships with a wide range of examples, many of which demonstrate JMS API usage.
+ A good place to start would be to play around with the simple JMS Queue and Topic example,
+ but we also provide examples for many other parts of the JMS API. A full description of the
+ examples is available in <xref linkend="examples"/>.</para>
<para>In this section we'll go through the main steps in configuring the server for JMS and
creating a simple JMS program. We'll also show how to configure and use JNDI, and also how
to use JMS with HornetQ without using any JNDI.</para>
@@ -106,11 +104,10 @@
<para>Where <literal>myhost</literal> is the hostname or IP address of the JNDI server. 1099
is the port used by the JNDI server and may vary depending on how you have configured
your JNDI server.</para>
- <para>In the default standalone configuration, JNDI server ports are configured in the
- file <literal>hornetq-beans.xml</literal>
- (or <literal>hornetq-beans.xml</literal> if you're running JBoss Application Server)
- where the JNDIServer bean is confgured,
- here's a snippet from the file:</para>
+ <para>In the default standalone configuration, JNDI server ports are configured in the file
+ <literal>hornetq-beans.xml</literal> (or <literal>hornetq-beans.xml</literal> if
+ you're running JBoss Application Server) where the JNDIServer bean is confgured, here's
+ a snippet from the file:</para>
<programlisting>
<bean name="JNDIServer" class="org.jnp.server.Main">
<property name="namingInfo">
@@ -164,9 +161,9 @@
Objects</emphasis> (that's JMS Queues, Topics and Connection Factories) from JNDI,
in some cases a JNDI server is not available and you still want to use JMS, or you just
think "Why do I need JNDI? Why can't I just instantiate these objects directly?"</para>
- <para>With HornetQ you can do exactly that. HornetQ supports the direct
- instantiation of JMS Queue, Topic and Connection Factory instances, so you don't have to
- use JNDI at all.</para>
+ <para>With HornetQ you can do exactly that. HornetQ supports the direct instantiation of JMS
+ Queue, Topic and Connection Factory instances, so you don't have to use JNDI at
+ all.</para>
<para>For a full working example of direct instantiation please see the JMS examples in
<xref linkend="examples"/>.</para>
<para>Here's our simple example, rewritten to not use JNDI at all:</para>
@@ -176,7 +173,7 @@
<programlisting>
TransportConfiguration transportConfiguration =
new TransportConfiguration(NettyConnectorFactory.class.getName());
-ConnectionFactory cf = new HornetQConnectionFactory();
+ConnectionFactory cf = new HornetQConnectionFactory(transportConfiguration);
</programlisting>
<para>We create the JMS Queue Object directly:</para>
<programlisting>Queue orderQueue = new HornetQQueue("OrderQueue");</programlisting>
@@ -212,7 +209,7 @@
configure the consumer so that it sends the acknowledgements in batches rather that one
at a time, saving valuable bandwidth. This can be configured via the connection factory
via the <literal>dups-ok-batch-size</literal> element and is set in bytes. The default
- is 1024 * 1024.</para>
+ is 1024 * 1024 bytes = 1 MiB.</para>
</section>
<section id="using-jms.txbatchsize">
<title>Setting The Transaction Batch Size</title>
Modified: trunk/docs/user-manual/en/using-server.xml
===================================================================
--- trunk/docs/user-manual/en/using-server.xml 2009-08-21 15:55:28 UTC (rev 7873)
+++ trunk/docs/user-manual/en/using-server.xml 2009-08-21 16:59:00 UTC (rev 7874)
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
-
<!-- ============================================================================= -->
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
<!-- -->
@@ -17,15 +16,14 @@
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
-
<chapter id="using-server">
<title>Using the Server</title>
<para>This chapter will familiarise you with how to use the HornetQ server.</para>
<para>We'll show where it is, how to start and stop it, and we'll describe the directory layout
and what all the files are and what they do.</para>
- <para>For the remainder of this chapter when we talk about the HornetQ server we mean
- the HornetQ standalone server, in its default configuration with a JMS Service and
- JNDI service enabled.</para>
+ <para>For the remainder of this chapter when we talk about the HornetQ server we mean the
+ HornetQ standalone server, in its default configuration with a JMS Service and JNDI service
+ enabled.</para>
<para>When running embedded in JBoss Application Server the layout may be slightly different but
by-and-large will be the same.</para>
<section>
@@ -43,7 +41,7 @@
a windows batch file <literal>run.bat</literal></para>
<para>To run on Unix/Linux type <literal>./stop.sh</literal></para>
<para>To run on Windows type <literal>stop.bat</literal></para>
- <para>Please note that HornetQ requires a Java 5 or later JDK to run. We recommend
+ <para>Please note that HornetQ requires a Java 5 or later runtime to run. We recommend
running on Java 6.</para>
<para>Both the run and the stop scripts use the config under <literal
>config/stand-alone/non-clustered</literal> by default. The configuration can be
@@ -56,10 +54,10 @@
<para>The run scripts <literal>run.sh</literal> and <literal>run.bat</literal> set some JVM
settings for tuning running on Java 6 and choosing the garbage collection policy. We
recommend using a parallel garbage collection algorithm to smooth out latency and
- minimises large GC pauses.</para>
- <para>By default HornetQ runs in a maximum of 1GB of RAM. To increase the memory
- settings change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings
- as you would for any Java program.</para>
+ minimise large GC pauses.</para>
+ <para>By default HornetQ runs in a maximum of 1GiB of RAM. To increase the memory settings
+ change the <literal>-Xms</literal> and <literal>-Xmx</literal> memory settings as you
+ would for any Java program.</para>
<para>If you wish to add any more JVM arguments or tune the existing ones, the run scripts
are the place to do it.</para>
</section>
@@ -70,9 +68,9 @@
classpath when calling Java to run the server.</para>
<para>In the distribution, the run scripts will add the non clustered configuration
directory to the classpath. This is a directory which contains a set of configuration
- files for running the HornetQ server in a basic non-clustered configuration. In
- the distribution this directory is <literal>config/stand-alone/non-clustered/</literal>
- from the root of the distribution.</para>
+ files for running the HornetQ server in a basic non-clustered configuration. In the
+ distribution this directory is <literal>config/stand-alone/non-clustered/</literal> from
+ the root of the distribution.</para>
<para>The distribution contains several standard configuration sets for running:</para>
<itemizedlist>
<listitem>
@@ -90,8 +88,8 @@
</itemizedlist>
<para>You can of course create your own configuration and specify any configuration
directory when running the run script.</para>
- <para>Just make sure the directory is on the classpath and HornetQ will search there
- when starting up.</para>
+ <para>Just make sure the directory is on the classpath and HornetQ will search there when
+ starting up.</para>
</section>
<section id="using-server.library.path">
<title>Library Path</title>
@@ -105,9 +103,9 @@
<title>System properties</title>
<para>HornetQ also takes a couple of Java system properties on the command line for
configuring logging properties</para>
- <para>HornetQ uses JDK logging to minimise dependencies on other logging systems.
- JDK logging can then be configured to delegate to some other framework, e.g. log4j if
- that's what you prefer.</para>
+ <para>HornetQ uses JDK logging to minimise dependencies on other logging systems. JDK
+ logging can then be configured to delegate to some other framework, e.g. log4j if that's
+ what you prefer.</para>
<para>For more information on configuring logging, please see <xref linkend="logging"
/>.</para>
</section>
@@ -118,16 +116,14 @@
following files.</para>
<itemizedlist>
<listitem>
- <para><literal>hornetq-beans.xml</literal>
- (or <literal>hornetq-jboss-beans.xml</literal> if you're running inside JBoss
- Application Server).
- This is the JBoss Microcontainer beans
- file which defines what beans the Microcontainer should create and what
- dependencies to enforce between them. Remember that HornetQ is just a
- set of POJOs. In the stand-alone server, it's the JBoss Microcontainer which
- instantiates these POJOs and enforces dependencies between them and other beans.
- Please see <xref linkend="usingserver.mainconfig"/> for more information on this
- file.</para>
+ <para><literal>hornetq-beans.xml</literal> (or <literal
+ >hornetq-jboss-beans.xml</literal> if you're running inside JBoss
+ Application Server). This is the JBoss Microcontainer beans file which defines
+ what beans the Microcontainer should create and what dependencies to enforce
+ between them. Remember that HornetQ is just a set of POJOs. In the stand-alone
+ server, it's the JBoss Microcontainer which instantiates these POJOs and
+ enforces dependencies between them and other beans. Please see <xref
+ linkend="usingserver.mainconfig"/> for more information on this file.</para>
</listitem>
<listitem>
<para><literal>hornetq-configuration.xml</literal>. This is the main HornetQ
@@ -135,26 +131,26 @@
linkend="configuration-index"/>.</para>
</listitem>
<listitem>
- <para><literal>hornetq-queues.xml</literal>. This file contains predefined queues, queue
- settings and security settings. The file is optional - all this configuration
- can also live in <literal>hornetq-configuration.xml</literal>. In fact, the default
- configuration sets do not have a <literal>hornetq-queues.xml</literal> file. The
- purpose of allowing queues to be configured in these files is to allow you to
- manage your queue configuration over many files instead of being forced to
- maintain it in a single file. There can be many <literal
- >hornetq-queues.xml</literal> files on the classpath. All will be loaded if
- found.</para>
+ <para><literal>hornetq-queues.xml</literal>. This file contains predefined queues,
+ queue settings and security settings. The file is optional - all this
+ configuration can also live in <literal>hornetq-configuration.xml</literal>. In
+ fact, the default configuration sets do not have a <literal
+ >hornetq-queues.xml</literal> file. The purpose of allowing queues to be
+ configured in these files is to allow you to manage your queue configuration
+ over many files instead of being forced to maintain it in a single file. There
+ can be many <literal>hornetq-queues.xml</literal> files on the classpath. All
+ will be loaded if found.</para>
</listitem>
<listitem>
<para><literal>hornetq-users.xml</literal> HornetQ ships with a security manager
implementation which obtains user credentials from the <literal
- >hornetq-users.xml</literal> file. This file contains user, password and role
- information. For more information on security ,please see <xref
+ >hornetq-users.xml</literal> file. This file contains user, password and
+ role information. For more information on security ,please see <xref
linkend="security"/>.</para>
</listitem>
<listitem>
- <para><literal>hornetq-jms.xml</literal> The distro configuration by default includes a
- server side JMS service which mainly deploys JMS Queues, Topics and
+ <para><literal>hornetq-jms.xml</literal> The distro configuration by default
+ includes a server side JMS service which mainly deploys JMS Queues, Topics and
ConnectionFactorys from this file into JNDI. If you're not using JMS, or you
don't need to deploy JMS objects on the server side, then you don't need this
file. For more information on using JMS, please see <xref linkend="using-jms"
@@ -172,8 +168,8 @@
</itemizedlist>
<note>
<para>The property <literal>file-deployment-enabled</literal> in the <literal
- >hornetq-configuration.xml</literal> configuration when set to false mans that the
- other configuration files are not loaded. This is true by default.</para>
+ >hornetq-configuration.xml</literal> configuration when set to false mans that
+ the other configuration files are not loaded. This is true by default.</para>
</note>
<para>It is also possible to use system property substitution in all the configuration
files. by replacing a value with the name of a system property. Here is an example of
@@ -184,11 +180,12 @@
<param key="hornetq.remoting.netty.port" value="${hornetq.remoting.netty.port:5445}" type="Integer"/>
</connector></programlisting>
<para>here you can see we have replaced 2 values with system properties <literal
- >hornetq.remoting.netty.host</literal> and <literal>hornetq.remoting.netty.port</literal>.
- These values will be replaced by the value found in the system property if there is one,
- if not they default back to localhost or 5445 respectively. It is also possible to not
- supply a default. i.e. <literal>${hornetq.remoting.netty.host}</literal>, however the system
- property <emphasis>must</emphasis> be supplied in that case.</para>
+ >hornetq.remoting.netty.host</literal> and <literal
+ >hornetq.remoting.netty.port</literal>. These values will be replaced by the value
+ found in the system property if there is one, if not they default back to localhost or
+ 5445 respectively. It is also possible to not supply a default. i.e. <literal
+ >${hornetq.remoting.netty.host}</literal>, however the system property
+ <emphasis>must</emphasis> be supplied in that case.</para>
</section>
<section id="server.microcontainer.configuration">
<title>JBoss Microcontainer Beans File</title>
@@ -283,7 +280,7 @@
</listitem>
<listitem>
<para>Configuration</para>
- <para>The messaging server is configured with a Configuration object. In the default
+ <para>The HornetQ server is configured with a Configuration object. In the default
stand-alone set-up it uses a FileConfiguration object which knows to read
configuration information from the file system. In different configurations such
as embedded you might want to provide configuration information from somewhere
@@ -292,11 +289,11 @@
<listitem>
<para>Security Manager. The security manager used by the messaging server is
pluggable. The default one used just reads user-role information from the
- <literal>hornetq-users.xml</literal> file on disk. However it can be replaced by
- a JAAS security manager, or when running inside JBoss Application Server it can
- be configured to use the JBoss AS security manager for tight integration with
- JBoss AS security. If you've disabled security altogether you can remove this
- too.</para>
+ <literal>hornetq-users.xml</literal> file on disk. However it can be
+ replaced by a JAAS security manager, or when running inside JBoss Application
+ Server it can be configured to use the JBoss AS security manager for tight
+ integration with JBoss AS security. If you've disabled security altogether you
+ can remove this too.</para>
</listitem>
<listitem>
<para>HornetQServer</para>
@@ -316,12 +313,12 @@
<section id="usingserver.mainconfig">
<title>The main configuration file.</title>
<para>The configuration for the HornetQ core server is contained in <literal
- >hornetq-configuration.xml</literal>. This is what the FileConfiguration bean uses to
- configure the messaging server.</para>
- <para>There are many attributes which you can configure HornetQ. In most cases the
- defaults will do fine, in fact every attribute can be defaulted which means a file with
- a single empty <literal>configuration</literal> element is a valid configuration file.
- The different configuration will be explained throughout the manual or you can refer to
- the configuration reference <link linkend="configuration-index">here</link>.</para>
+ >hornetq-configuration.xml</literal>. This is what the FileConfiguration bean uses
+ to configure the messaging server.</para>
+ <para>There are many attributes which you can configure HornetQ. In most cases the defaults
+ will do fine, in fact every attribute can be defaulted which means a file with a single
+ empty <literal>configuration</literal> element is a valid configuration file. The
+ different configuration will be explained throughout the manual or you can refer to the
+ configuration reference <link linkend="configuration-index">here</link>.</para>
</section>
</chapter>
More information about the hornetq-commits
mailing list