http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/persistence.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/persistence.xml b/docs/user-manual/en/persistence.xml new file mode 100644 index 0000000..1e15c65 --- /dev/null +++ b/docs/user-manual/en/persistence.xml @@ -0,0 +1,357 @@ +<?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="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. Since HornetQ handles its own persistence, + rather than relying on a database or other 3rd party persistence engine it is very highly + optimised for the specific messaging use cases.</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 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 its 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> + <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 extremely good performance and runs on any platform where there's a + Java 6+ runtime.</para> + </listitem> + <listitem id="aio-journal"> + <para>Linux Asynchronous IO</para> + <para>The second implementation uses a thin native code wrapper to talk to the Linux + asynchronous IO library (AIO). 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> + <para>Using AIO will typically provide even better performance than using Java + NIO.</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> + <para>Also, please note that AIO will only work with the following file systems: ext2, + ext3, ext4, jfs, xfs. With other file systems, e.g. NFS it may appear to work, but + it will fall back to a slower synchronous behaviour. Don't put the journal on a NFS + share!</para> + <para>For more information on libaio please see <xref linkend="libaio"/>.</para> + <para>libaio is part of the kernel project.</para> + </listitem> + </itemizedlist> + <para>The standard HornetQ core server uses two instances of the journal:</para> + <itemizedlist id="persistence.journallist"> + <listitem> + <para>Bindings journal.</para> + <para>This journal is used to store bindings related data. That includes the set of + queues that are deployed on the server and their attributes. It also stores data + such as id sequence counters. </para> + <para>The bindings journal is always a NIO journal as it is typically low throughput + compared to the message journal.</para> + <para>The files on this journal are prefixed as <literal>hornetq-bindings</literal>. + Each file has a <literal>bindings</literal> extension. File size is <literal + >1048576</literal>, and it is located at the bindings folder.</para> + </listitem> + <listitem> + <para>JMS journal.</para> + <para>This journal instance stores all JMS related data, This is basically any JMS + Queues, Topics and Connection Factories and any JNDI bindings for these + resources.</para> + <para>Any JMS Resources created via the management API will be persisted to this + journal. Any resources configured via configuration files will not. The JMS Journal + will only be created if JMS is being used.</para> + <para>The files on this journal are prefixed as <literal>hornetq-jms</literal>. Each + file has a <literal>jms</literal> extension. File size is <literal + >1048576</literal>, and it is located at the bindings folder.</para> + </listitem> + <listitem> + <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>The files on this journal are prefixed as <literal>hornetq-data</literal>. Each + file has a <literal>hq</literal> extension. File size is by the default <literal + >10485760</literal> (configurable), and it is located at the journal + folder.</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 can also be configured to page 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 + >hornetq-configuration.xml</literal></para> + <itemizedlist> + <listitem> + <para><literal>bindings-directory</literal></para> + <para>This is the directory in which the bindings journal lives. The default value + is <literal>data/bindings</literal>.</para> + </listitem> + <listitem> + <para><literal>create-bindings-dir</literal></para> + <para>If this is set to <literal>true</literal> then the bindings directory will be + automatically created at the location specified in <literal + >bindings-directory</literal> if it does not already exist. The default + value is <literal>true</literal></para> + </listitem> + </itemizedlist> + </section> + <section id="configuring.bindings.jms"> + <title>Configuring the jms journal</title> + <para>The jms config shares its configuration with the bindings journal.</para> + </section> + <section id="configuring.message.journal"> + <title>Configuring the message journal</title> + <para>The message journal is configured using the following attributes in <literal + >hornetq-configuration.xml</literal></para> + <itemizedlist> + <listitem id="configuring.message.journal.journal-directory"> + <para><literal>journal-directory</literal></para> + <para>This is the directory in which the message journal lives. The default value is + <literal>data/journal</literal>.</para> + <para>For the best performance, we recommend the journal is located on its own + physical volume in order to minimise disk head movement. If the journal is on a + volume which is shared with other processes which might be writing other files + (e.g. bindings journal, database, or transaction coordinator) then the disk head + may well be moving rapidly between these files as it writes them, thus + drastically reducing performance.</para> + <para>When the message journal is stored on a SAN we recommend each journal instance + that is stored on the SAN is given its own LUN (logical unit).</para> + </listitem> + <listitem id="configuring.message.journal.create-journal-dir"> + <para><literal>create-journal-dir</literal></para> + <para>If this is set to <literal>true</literal> then the journal directory will be + automatically created at the location specified in <literal + >journal-directory</literal> if it does not already exist. The default value + is <literal>true</literal></para> + </listitem> + <listitem id="configuring.message.journal.journal-type"> + <para><literal>journal-type</literal></para> + <para>Valid values are <literal>NIO</literal> or <literal>ASYNCIO</literal>.</para> + <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> + </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 make sure all transaction data is + flushed to disk on transaction boundaries (commit, prepare and rollback). 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 make sure non transactional message + data (sends and acknowledgements) are flushed to disk each time. The default + value for this is <literal>true</literal>.</para> + </listitem> + <listitem id="configuring.message.journal.journal-file-size"> + <para><literal>journal-file-size</literal></para> + <para>The size of each journal file in bytes. The default value for this is <literal + >10485760</literal> bytes (10MiB).</para> + </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>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 + pre-creating files, as one is filled the journal can immediately resume with the + next one without pausing to create it.</para> + <para>Depending on how much data you expect your queues to contain at steady state + you should tune this number of files to match that total amount of data.</para> + </listitem> + <listitem id="configuring.message.journal.journal-max-io"> + <para><literal>journal-max-io</literal></para> + <para>Write requests are queued up before being submitted to the system for + execution. This parameter controls the maximum number of write requests that can + be in the IO queue at any one time. If the queue becomes full then writes will + block until space is freed up. </para> + <para>When using NIO, this value should always be equal to <literal + >1</literal></para> + <para>When using AIO, the default should be <literal>500</literal>.</para> + <para>The system maintains different defaults for this parameter depending on whether + it's NIO or AIO (default for NIO is 1, default for AIO is 500)</para> + <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> + </listitem> + <listitem id="configuring.message.journal.journal-buffer-timeout"> + <para><literal>journal-buffer-timeout</literal></para> + <para>Instead of flushing on every write that requires a flush, we maintain an + internal buffer, and flush the entire buffer either when it is full, or when a + timeout expires, whichever is sooner. This is used for both NIO and AIO and + allows the system to scale better with many concurrent writes that require + flushing.</para> + <para>This parameter controls the timeout at which the buffer will be flushed if it + hasn't filled already. AIO can typically cope with a higher flush rate than NIO, + so the system maintains different defaults for both NIO and AIO (default for NIO + is 3333333 nanoseconds - 300 times per second, default for AIO is 500000 + nanoseconds - ie. 2000 times per second).</para> + <note> + <para>By increasing the timeout, you may be able to increase system throughput + at the expense of latency, the default parameters are chosen to give a + reasonable balance between throughput and latency.</para> + </note> + </listitem> + <listitem id="configuring.message.journal.journal-buffer-size"> + <para><literal>journal-buffer-size</literal></para> + <para>The size of the timed buffer on AIO. The default value is <literal + >490KiB</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 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 default for this parameter is <literal>30</literal></para> + </listitem> + </itemizedlist> + </section> + <section id="disk-write-cache"> + <title>An important note on disabling disk write cache.</title> + <warning> + <para>Most disks contain hardware write caches. A write cache can increase the apparent + performance of the disk because writes just go into the cache and are then lazily + written to the disk later. </para> + <para>This happens irrespective of whether you have executed a fsync() from the + operating system or correctly synced data from inside a Java program!</para> + <para>By default many systems ship with disk write cache enabled. This means that even + after syncing from the operating system there is no guarantee the data has actually + made it to disk, so if a failure occurs, critical data can be lost.</para> + <para>Some more expensive disks have non volatile or battery backed write caches which + won't necessarily lose data on event of failure, but you need to test them!</para> + <para>If your disk does not have an expensive non volatile or battery backed cache and + it's not part of some kind of redundant array (e.g. RAID), and you value your data + integrity you need to make sure disk write cache is disabled.</para> + <para>Be aware that disabling disk write cache can give you a nasty shock performance + wise. If you've been used to using disks with write cache enabled in their default + setting, unaware that your data integrity could be compromised, then disabling it + will give you an idea of how fast your disk can perform when acting really + reliably.</para> + <para>On Linux you can inspect and/or change your disk's write cache settings using the + tools <literal>hdparm</literal> (for IDE disks) or <literal>sdparm</literal> or + <literal>sginfo</literal> (for SDSI/SATA disks)</para> + <para>On Windows you can check / change the setting by right clicking on the disk and + clicking properties.</para> + </warning> + </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> + journal for the very best persistence performance.</para> + <para>It's not possible to use the AIO journal under other operating systems or earlier + versions of the Linux kernel.</para> + <para>If you are running Linux kernel 2.6 or later and don't already have <literal + >libaio</literal> installed, you can easily install it using the following + steps:</para> + <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux): + <programlisting>yum install libaio</programlisting></para> + <para>Using aptitude, (e.g. on Ubuntu or Debian system): + <programlisting>apt-get install libaio</programlisting></para> + </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 + >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, + duplicate id caches or paging data will be persisted.</para> + </section> + <section id="persistence.importexport"> + <title>Import/Export the Journal Data</title> + <para>You may want to inspect the existent records on each one of the journals used by + HornetQ, and you can use the export/import tool for that purpose. The export/import are + classes located at the hornetq-core.jar, you can export the journal as a text file by + using this command:</para> + <para><literal>java -cp hornetq-core.jar org.hornetq.core.journal.impl.ExportJournal + <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize> + <FileOutput></literal></para> + <para>To import the file as binary data on the journal (Notice you also require + netty.jar):</para> + <para><literal>java -cp hornetq-core.jar:netty.jar org.hornetq.core.journal.impl.ImportJournal + <JournalDirectory> <JournalPrefix> <FileExtension> <FileSize> + <FileInput></literal></para> + <itemizedlist> + <listitem> + <para>JournalDirectory: Use the configured folder for your selected folder. Example: + ./hornetq/data/journal</para> + </listitem> + <listitem> + <para>JournalPrefix: Use the prefix for your selected journal, as discussed + <link linkend="persistence.journallist">here</link></para> + </listitem> + <listitem> + <para>FileExtension: Use the extension for your selected journal, as discussed + <link linkend="persistence.journallist">here</link></para> + </listitem> + <listitem> + <para>FileSize: Use the size for your selected journal, as discussed <link + linkend="persistence.journallist">here</link></para> + </listitem> + <listitem> + <para>FileOutput: text file that will contain the exported data</para> + </listitem> + </itemizedlist> + </section> +</chapter>
http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/pre-acknowledge.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/pre-acknowledge.xml b/docs/user-manual/en/pre-acknowledge.xml new file mode 100644 index 0000000..81abbe9 --- /dev/null +++ b/docs/user-manual/en/pre-acknowledge.xml @@ -0,0 +1,99 @@ +<?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="pre-acknowledge"> + <title>Extra Acknowledge Modes</title> + <para>JMS specifies 3 acknowledgement modes:</para> + <itemizedlist> + <listitem> + <para><literal>AUTO_ACKNOWLEDGE</literal></para> + </listitem> + <listitem> + <para><literal>CLIENT_ACKNOWLEDGE</literal></para> + </listitem> + <listitem> + <para><literal>DUPS_OK_ACKNOWLEDGE</literal></para> + </listitem> + </itemizedlist> + <para>HornetQ supports two additional modes: <literal>PRE_ACKNOWLEDGE</literal> and <literal>INDIVIDUAL_ACKNOWLEDGE</literal></para> + <para>In some cases you can afford + to lose messages in event of failure, so it would make sense to acknowledge the message on the + server <emphasis>before</emphasis> delivering it to the client.</para> + <para>This extra mode is supported by HornetQ and will call it + <emphasis>pre-acknowledge</emphasis> mode.</para> + <para>The disadvantage of acknowledging on the server before delivery is that the message will be + lost if the system crashes <emphasis>after</emphasis> acknowledging the message on the server + but <emphasis>before</emphasis> it is delivered to the client. In that case, the message is + lost and will not be recovered when the system restart.</para> + <para>Depending on your messaging case, <literal>pre-acknowledgement</literal> mode can avoid + extra network traffic and CPU at the cost of coping with message loss.</para> + <para>An example of a use case for pre-acknowledgement is for stock price update messages. With + these messages it might be reasonable to lose a message in event of crash, since the next + price update message will arrive soon, overriding the previous price. </para> + <note> + <para>Please note, that if you use pre-acknowledge mode, then you will lose transactional + semantics for messages being consumed, since clearly they are being acknowledged first on + the server, not when you commit the transaction. This may be stating the obvious but we + like to be clear on these things to avoid confusion!</para> + </note> + <section id="pre-acknowledge.configure"> + <title>Using PRE_ACKNOWLEDGE</title> + <para>This can be configured in the <literal>hornetq-jms.xml</literal> file on the <literal + >connection factory</literal> like this:</para> + <programlisting> +<connection-factory name="ConnectionFactory"> + <connectors> + <connector-ref connector-name="netty-connector"/> + </connectors> + <entries> + <entry name="ConnectionFactory"/> + </entries> + <pre-acknowledge>true</pre-acknowledge> +</connection-factory></programlisting> + <para>Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session + with the <literal>HornetQSession.PRE_ACKNOWLEDGE</literal> constant.</para> + <programlisting> +// messages will be acknowledge on the server *before* being delivered to the client +Session session = connection.createSession(false, HornetQJMSConstants.PRE_ACKNOWLEDGE);</programlisting> + <para>Or you can set pre-acknowledge directly on the <literal + >HornetQConnectionFactory</literal> instance using the setter method.</para> + <para>To use pre-acknowledgement mode using the core API you can set it directly on the + <literal>ClientSessionFactory</literal> instance using the setter method.</para> + </section> + <section id="individual-ack"> + <title>Individual Acknowledge</title> + <para>A valid use-case for individual acknowledgement would be when you need to have your own scheduling and you don't know when your message processing will be finished. You should prefer having one consumer per thread worker + but this is not possible in some circumstances depending on how complex is your processing. For that you can use the individual Acknowledgement. </para> + <para>You basically setup Individual ACK by creating a session with the acknowledge mode with <literal>HornetQJMSConstants.INDIVIDUAL_ACKNOWLEDGE</literal>. Individual ACK inherits all the semantics from Client Acknowledge, + with the exception the message is individually acked.</para> + <note> + <para>Please note, that to avoid confusion on MDB processing, Individual ACKNOWLEDGE is not supported through MDBs (or the inbound resource adapter). this is because you have to finish the process of your message inside the MDB. + </para> + </note> + </section> + <section> + <title>Example</title> + <para>See <xref linkend="examples.pre-acknowledge"/> for an example which shows how to use + pre-acknowledgement mode with JMS.</para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/preface.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/preface.xml b/docs/user-manual/en/preface.xml new file mode 100644 index 0000000..2c1483b --- /dev/null +++ b/docs/user-manual/en/preface.xml @@ -0,0 +1,87 @@ +<?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="preface"> + <title>Preface</title> + <para>What is HornetQ?</para> + <itemizedlist> + <listitem> + <para>HornetQ is an open source project to build a multi-protocol, embeddable, very 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>For answers to more questions about what HornetQ is and what it 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. HornetQ is licensed using the Apache Software License v + 2.0 to minimise barriers to adoption.</para> + </listitem> + <listitem> + <para>HornetQ is designed with usability in mind.</para> + </listitem> + <listitem> + <para>Written in Java. Runs on any platform with a Java 6+ runtime, that's everything + from Windows desktops to IBM mainframes.</para> + </listitem> + <listitem> + <para>Amazing performance. Our ground-breaking 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> + </listitem> + <listitem> + <para>Full feature set. All the features you'd expect in any serious messaging system, + and others you won't find anywhere else.</para> + </listitem> + <listitem> + <para>Elegant, clean-cut 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. It's up to you.</para> + </listitem> + <listitem> + <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 + balance messages. Link geographically distributed clusters over unreliable + 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> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/project-info.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/project-info.xml b/docs/user-manual/en/project-info.xml new file mode 100644 index 0000000..5bd6ca9 --- /dev/null +++ b/docs/user-manual/en/project-info.xml @@ -0,0 +1,91 @@ +<?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="project-info"> + <title>Project Information</title> + <para>The official HornetQ project page is <ulink url="http://hornetq.org/"; + >http://hornetq.org/</ulink>.</para> + <section id="download.software"> + <title>Software Download</title> + <para>The software can be download from the Download page:<ulink + url="http://hornetq.org/downloads.html";>http://hornetq.org/downloads.html</ulink></para> + </section> + <section id="download.git"> + <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="https://community.jboss.org/en/hornetq";>user + forum</ulink></para> + </listitem> + <listitem> + <para>If you have development related questions, please use our <ulink + url="https://community.jboss.org/en/hornetq/dev"; + >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 Git repository is <ulink + url="https://github.com/hornetq/hornetq"; + >https://github.com/hornetq/hornetq</ulink></para> + </listitem> + <listitem> + <para>All release tags are available from <ulink + url="https://github.com/hornetq/hornetq/tags"; + >https://github.com/hornetq/hornetq/tags</ulink></para> + </listitem> + </itemizedlist> + </para> + <para>Red Hat kindly employs developers to work full time on HornetQ, they are: <itemizedlist> + <listitem> + <para>Clebert Suconic (project lead)</para> + </listitem> + <listitem> + <para>Andy Taylor</para> + </listitem> + <listitem> + <para>Howard Gao</para> + </listitem> + <listitem> + <para>Justin Bertram</para> + </listitem> + </itemizedlist></para> + <para> And many thanks to all our contributors, both old and new who helped create HornetQ, + for a full list of the people who made it happen, take a look at our <ulink + url="http://jboss.org/hornetq/community/team.html";>team page</ulink>. </para> + </section> +</chapter> http://git-wip-us.apache.org/repos/asf/activemq-6/blob/8ecd255f/docs/user-manual/en/queue-attributes.xml ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/queue-attributes.xml b/docs/user-manual/en/queue-attributes.xml new file mode 100644 index 0000000..8ec06b5 --- /dev/null +++ b/docs/user-manual/en/queue-attributes.xml @@ -0,0 +1,160 @@ +<?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="queue-attributes"> + <title>Queue Attributes</title> + <para>Queue attributes can be set in one of two ways. Either by configuring them using the + configuration file or by using the core API. This chapter will explain how to configure each + attribute and what effect the attribute has.</para> + <section id="predefined.queues"> + <title>Predefined Queues</title> + <para>Queues can be predefined via configuration at a core level or at a JMS level. Firstly + let's look at a JMS level.</para> + <para>The following shows a queue predefined in the <literal>hornetq-jms.xml</literal> + configuration file.</para> + <programlisting> +<queue name="selectorQueue"> + <entry name="/queue/selectorQueue"/> + <selector string="color='red'"/> + <durable>true</durable> +</queue></programlisting> + <para>This name attribute of queue defines the name of the queue. When we do this at a jms + level we follow a naming convention so the actual name of the core queue will be + <literal>jms.queue.selectorQueue</literal>.</para> + <para>The entry element configures the name that will be used to bind the queue to JNDI. + This is a mandatory element and the queue can contain multiple of these to bind the same + queue to different names.</para> + <para>The selector element defines what JMS message selector the predefined queue will have. + Only messages that match the selector will be added to the queue. This is an optional + element with a default of null when omitted.</para> + <para>The durable element specifies whether the queue will be persisted. This again is + optional and defaults to true if omitted.</para> + <para>Secondly a queue can be predefined at a core level in the <literal + >hornetq-configuration.xml</literal> file. The following is an example.</para> + <programlisting> +<queues> + <queue name="jms.queue.selectorQueue"> + <address>jms.queue.selectorQueue</address> + <filter string="color='red'"/> + <durable>true</durable> + </queue> +</queues></programlisting> + <para>This is very similar to the JMS configuration, with 3 real differences which + are.</para> + <orderedlist> + <listitem> + <para>The name attribute of queue is the actual name used for the queue with no + naming convention as in JMS.</para> + </listitem> + <listitem> + <para>The address element defines what address is used for routing messages.</para> + </listitem> + <listitem> + <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> + </listitem> + </orderedlist> + </section> + <section> + <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.api.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"> + <title>Configuring Queues Via Address Settings</title> + <para>There are some attributes that are defined against an address wildcard rather than a + specific queue. Here an example of an <literal>address-setting</literal> entry that + would be found in the <literal>hornetq-configuration.xml</literal> file.</para> + <programlisting> +<address-settings> + <address-setting match="jms.queue.exampleQueue"> + <dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address> + <max-delivery-attempts>3</max-delivery-attempts> + <redelivery-delay>5000</redelivery-delay> + <expiry-address>jms.queue.expiryQueue</expiry-address> + <last-value-queue>true</last-value-queue> + <max-size-bytes>100000</max-size-bytes> + <page-size-bytes>20000</page-size-bytes> + <redistribution-delay>0</redistribution-delay> + <send-to-dla-on-no-route>true</send-to-dla-on-no-route> + <address-full-policy>PAGE</address-full-policy> + </address-setting> +</address-settings></programlisting> + <para>The idea with address settings, is you can provide a block of settings which will be + applied against any addresses that match the string in the <literal>match</literal> attribute. In the + above example the settings would only be applied to any addresses which exactly match + the address <literal>jms.queue.exampleQueue</literal>, but you can also use wildcards to apply sets of + configuration against many addresses. The wildcard syntax used is described <link linkend="wildcard-syntax">here</link>.</para> + <para>For example, if you used the <literal>match</literal> string <literal>jms.queue.#</literal> the settings would be applied + to all addresses which start with <literal>jms.queue.</literal> which would be all JMS queues.</para> + <para>The meaning of the specific settings are explained fully throughout the user manual, however 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 + explanation can be found <link linkend="undelivered-messages.configuring" + >here</link>.</para> + <para><literal>redelivery-delay</literal> defines how long to wait before attempting + redelivery of a cancelled message. see <link linkend="undelivered-messages.delay" + >here</link>.</para> + <para><literal>expiry-address</literal> defines where to send a message that has expired. + see <link linkend="message-expiry.configuring">here</link>.</para> + <para><literal>expiry-delay</literal> defines the expiration time that will be used for messages which are using + the default expiration time (i.e. 0). For example, if <literal>expiry-delay</literal> is set to "10" and a + message which is using the default expiration time (i.e. 0) arrives then its expiration time of "0" will be + changed to "10." However, if a message which is using an expiration time of "20" arrives then its expiration + time will remain unchanged. Setting <literal>expiry-delay</literal> to "-1" will disable this feature. The + default is "-1".</para> + <para><literal>last-value-queue</literal> defines whether a queue only uses last values or + not. see <link linkend="last-value-queues">here</link>.</para> + <para><literal>max-size-bytes</literal> and <literal>page-size-bytes</literal> are used to + set paging on an address. This is explained <link linkend="paging">here</link>.</para> + <para><literal>redistribution-delay</literal> defines how long to wait when the last + consumer is closed on a queue before redistributing any messages. see <link + linkend="clusters">here</link>.</para> + <para><literal>send-to-dla-on-no-route</literal>. If a message is sent to an address, but the server does not route it to any queues, + for example, there might be no queues bound to that address, or none of the queues have filters that match, then normally that message + would be discarded. However if this parameter is set to true for that address, if the message is not routed to any queues it will instead + be sent to the dead letter address (DLA) for that address, if it exists.</para> + <para><literal>address-full-policy</literal>. This attribute can have one of the following values: PAGE, DROP, FAIL or BLOCK and determines what happens when + an address where <literal>max-size-bytes</literal> is specified becomes full. The default value is PAGE. If the value is PAGE then further messages will be paged to disk. + If the value is DROP then further messages will be silently dropped. + If the value is FAIL then further messages will be dropped and an exception will be thrown on the client-side. + If the value is BLOCK then client message producers will block when they try and send further messages. + + See the following chapters for more info <xref linkend="flow-control"/>, <xref linkend="paging"/>. + </para> + + + </section> +</chapter>
