http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/architecture.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/architecture.xml b/docs/user-manual/en/architecture.xml new file mode 100644 index 0000000..8b7085c --- /dev/null +++ b/docs/user-manual/en/architecture.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- ============================================================================= --> +<!-- Copyright © 2009 Red Hat, Inc. and others. --> +<!-- --> +<!-- 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"). --> +<!-- --> +<!-- An explanation of CC-BY-SA is available at --> +<!-- --> +<!-- http://creativecommons.org/licenses/by-sa/3.0/. --> +<!-- --> +<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation --> +<!-- of it, you must provide the URL for the original version. --> +<!-- --> +<!-- Red Hat, as the licensor of this document, waives the right to enforce, --> +<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent --> +<!-- permitted by applicable law. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> +<chapter id="architecture"> + <title>Architecture</title> + <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) - we hope you + like its clean-cut design.</para> + <para>We've also designed it to have as few dependencies on external jars as possible. In + fact, HornetQ core has only one jar dependency, netty.jar, + other than the standard JDK classes! This is because we use some of the netty buffer classes + internally.</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>Each HornetQ server has its own ultra 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> + <orderedlist> + <listitem> + <para>Core client API. This is a simple intuitive Java API that allows the full + set of messaging functionality without some of the complexities of + JMS.</para> + </listitem> + <listitem> + <para>JMS client API. The standard JMS API is available at the client + side.</para> + </listitem> + </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 is 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> + <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> + <graphic fileref="images/architecture1.jpg" align="center"/> + </para> + <para>Figure 3.1 shows two user applications interacting with a HornetQ server. User + Application 1 is using the JMS API, while User Application 2 is using the core client + API directly.</para> + <para>You can see from the diagram that the JMS API is implemented by a thin facade layer on + the client side.</para> + </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 + 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>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> + <para>Probably the most common use of an MDB is to consume messages from a JMS messaging + system.</para> + <para>According to the JEE specification, a JEE application server uses a JCA adapter to + integrate with a JMS messaging system so it can consume messages for MDBs.</para> + <para>However, the JCA adapter is not only used by the JEE application server for <emphasis + role="italic">consuming</emphasis> messages via MDBs, it is also used when sending + message to the JMS messaging system e.g. from inside an EJB or servlet.</para> + <para>When integrating with a JMS messaging system from inside a JEE application server it + is always recommended that this is done via a JCA adaptor. In fact, communicating with a + JMS messaging system directly, without using JCA would be illegal according to the JEE + specification.</para> + <para>The application server's JCA service provides extra functionality such as connection + pooling and automatic transaction enlistment, which are desirable when using messaging, + say, from inside an EJB. It is possible to talk to a JMS messaging system directly from + 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>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> + <para> + <graphic fileref="images/architecture2.jpg"/> + </para> + <para>For more information on using the JCA adaptor, please see <xref + 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>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 Queue, Topic 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 + 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 Queue, Topic or 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> + <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> + <para>The stand-alone server architecture is shown in figure 3.3 below:</para> + <para> + <graphic fileref="images/architecture3.jpg"/> + </para> + <para>For more information on server configuration files see <xref + linkend="server.configuration"/>. $ </para> + </section> +</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/client-classpath.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/client-classpath.xml b/docs/user-manual/en/client-classpath.xml new file mode 100644 index 0000000..be94909 --- /dev/null +++ b/docs/user-manual/en/client-classpath.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- ============================================================================= --> +<!-- Copyright © 2009 Red Hat, Inc. and others. --> +<!-- --> +<!-- 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"). --> +<!-- --> +<!-- An explanation of CC-BY-SA is available at --> +<!-- --> +<!-- http://creativecommons.org/licenses/by-sa/3.0/. --> +<!-- --> +<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation --> +<!-- of it, you must provide the URL for the original version. --> +<!-- --> +<!-- Red Hat, as the licensor of this document, waives the right to enforce, --> +<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent --> +<!-- permitted by applicable law. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> +<chapter id="client-classpath"> + <title>The Client Classpath</title> + <para>HornetQ requires several jars on the <emphasis>Client Classpath</emphasis> depending on + whether the client uses HornetQ Core API, JMS, and JNDI.</para> + <warning> + <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. Mixing and matching different jar versions may cause subtle errors and + failures to occur.</para> + </warning> + <section> + <title>HornetQ Core Client</title> + <para>If you are using just a pure HornetQ Core client (i.e. no JMS) then you need <literal + >hornetq-core-client.jar</literal>, <literal>hornetq-commons.jar</literal>, and + <literal>netty.jar</literal> on your client classpath.</para> + </section> + <section> + <title>JMS Client</title> + <para>If you are using JMS on the client side, then you will also need to include <literal + >hornetq-jms-client.jar</literal> and <literal>jboss-jms-api.jar</literal>.</para> + + <note> + <para><literal>jboss-jms-api.jar</literal> just contains Java EE API interface classes + needed for the <literal>javax.jms.*</literal> classes. If you already have a jar + with these interface classes on your classpath, you will not need it.</para> + </note> + + </section> + <section> + <title>JMS Client with JNDI</title> + <para>If you are looking up JMS resources from the JNDI server co-located with the HornetQ + standalone server, you will 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> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/client-reconnection.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/client-reconnection.xml b/docs/user-manual/en/client-reconnection.xml new file mode 100644 index 0000000..d647011 --- /dev/null +++ b/docs/user-manual/en/client-reconnection.xml @@ -0,0 +1,155 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- ============================================================================= --> +<!-- Copyright © 2009 Red Hat, Inc. and others. --> +<!-- --> +<!-- 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"). --> +<!-- --> +<!-- An explanation of CC-BY-SA is available at --> +<!-- --> +<!-- http://creativecommons.org/licenses/by-sa/3.0/. --> +<!-- --> +<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation --> +<!-- of it, you must provide the URL for the original version. --> +<!-- --> +<!-- Red Hat, as the licensor of this document, waives the right to enforce, --> +<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent --> +<!-- permitted by applicable law. --> +<!-- ============================================================================= --> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [ +<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent"> +%BOOK_ENTITIES; +]> +<chapter id="client-reconnection"> + <title>Client Reconnection and Session Reattachment</title> + <para>HornetQ clients can be configured to automatically reconnect or re-attach to the server in + the event that a failure is detected in the connection between the client and the server. </para> + <section> + <title>100% Transparent session re-attachment</title> + <para>If the failure was due to some transient failure such as a temporary network failure, + and the target server was not restarted, then the sessions will still be existent on the + server, assuming the client hasn't been disconnected for more than connection-ttl <xref + linkend="connection-ttl"/>.</para> + <para>In this scenario, HornetQ will automatically re-attach the client sessions to the + server sessions when the connection reconnects. This is done 100% transparently and the + client can continue exactly as if nothing had happened.</para> + <para>The way this works is as follows:</para> + <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 + reattaches to the same server, as part of the reattachment protocol the server informs + the client during reattachment 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 sent commands from its buffer so that the client and server can reconcile their + states.</para> + <para>The size of this buffer is configured by the <literal>ConfirmationWindowSize</literal> + parameter, when the server has received <literal>ConfirmationWindowSize</literal> bytes + of commands and processed them it will send back a command confirmation to the client, + and the 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 + >confirmation-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 the core API you can set these values directly on the <literal + >ServerLocator</literal> instance using the appropriate setter method.</para> + <para>The window is specified in bytes.</para> + <para>Setting this parameter to <literal>-1</literal> disables any buffering and prevents + any re-attachment from occurring, forcing reconnect instead. The default value for this + parameter is <literal>-1</literal>. (Which means by default no auto re-attachment will occur)</para> + </section> + <section> + <title>Session reconnection</title> + <para>Alternatively, the server might have actually been restarted after crashing or being + stopped. In this case any sessions will no longer be existent on the server and it won't + be possible to 100% transparently re-attach to them.</para> + <para>In this case, HornetQ will automatically reconnect the connection and <emphasis + role="italic">recreate</emphasis> any sessions and consumers on the server + corresponding to the sessions and consumers on the client. This process is exactly the + same as what happens during failover onto a backup server.</para> + <para>Client reconnection is also used internally by components such as core bridges to + allow them to reconnect to their target servers.</para> + <para>Please see the section on failover <xref linkend="ha.automatic.failover"/> to get a + full understanding of how transacted and non-transacted sessions are reconnected during + failover/reconnect and what you need to do to maintain <emphasis role="italic">once and + only once </emphasis>delivery guarantees.</para> + </section> + <section> + <title>Configuring reconnection/reattachment attributes</title> + <para>Client reconnection is configured using the following parameters:</para> + <itemizedlist> + <listitem> + <para><literal>retry-interval</literal>. This optional parameter determines the + period in milliseconds between subsequent reconnection attempts, if the + connection to the target server has failed. The default value is <literal + >2000</literal> milliseconds.</para> + </listitem> + <listitem> + <para><literal>retry-interval-multiplier</literal>. This optional parameter + determines determines a multiplier to apply to the time since the last retry to + compute the time to the next retry.</para> + <para>This allows you to implement an <emphasis>exponential backoff</emphasis> + between retry attempts.</para> + <para>Let's take an example:</para> + <para>If we set <literal>retry-interval</literal> to <literal>1000</literal> ms and + we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>, + then, if the first reconnect attempt fails, we will wait <literal>1000</literal> + ms then <literal>2000</literal> ms then <literal>4000</literal> ms between + subsequent reconnection attempts.</para> + <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is + spaced at equal intervals.</para> + </listitem> + <listitem> + <para><literal>max-retry-interval</literal>. This optional parameter determines the + maximum retry interval that will be used. When setting <literal + >retry-interval-multiplier</literal> it would otherwise be possible that + subsequent retries exponentially increase to ridiculously large values. By + setting this parameter you can set an upper limit on that value. The default + value is <literal>2000</literal> milliseconds.</para> + </listitem> + <listitem> + <para><literal>reconnect-attempts</literal>. This optional parameter determines the + total number of reconnect attempts to make before giving up and shutting down. A + value of <literal>-1</literal> signifies an unlimited number of attempts. The + default value is <literal>0</literal>.</para> + </listitem> + </itemizedlist> + <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS + connection factory instances directly into JNDI, then you can specify these parameters + in the xml configuration in <literal>hornetq-jms.xml</literal>, for example:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + <entry name="XAConnectionFactory"/> + </entries> + <retry-interval>1000</retry-interval> + <retry-interval-multiplier>1.5</retry-interval-multiplier> + <max-retry-interval>60000</max-retry-interval> + <reconnect-attempts>1000</reconnect-attempts> +</connection-factory></programlisting> + <para>If you're using JMS, but instantiating your JMS connection factory directly, you can + specify the parameters using the appropriate setter methods on the <literal + >HornetQConnectionFactory</literal> immediately after creating it.</para> + <para>If you're using the core API and instantiating the <literal + >ServerLocator</literal> instance directly you can also specify the + parameters using the appropriate setter methods on the <literal + >ServerLocator</literal> immediately after creating it.</para> + <para>If your client does manage to reconnect but the session is no longer available on the + server, for instance if the server has been restarted or it has timed out, then the + client won't be able to re-attach, and any <literal>ExceptionListener</literal> or + <literal>FailureListener</literal> instances registered on the connection or session + will be called.</para> + </section> + <section id="client-reconnection.exceptionlistener"> + <title>ExceptionListeners and SessionFailureListeners</title> + <para>Please note, that when a client reconnects or re-attaches, any registered JMS <literal + >ExceptionListener</literal> or core API <literal>SessionFailureListener</literal> + will be called.</para> + </section> +</chapter>
