Author: timfox Date: 2010-01-07 07:25:45 -0500 (Thu, 07 Jan 2010) New Revision: 8765 Modified: trunk/docs/user-manual/en/architecture.xml trunk/docs/user-manual/en/messaging-concepts.xml trunk/docs/user-manual/en/notice.xml trunk/docs/user-manual/en/preface.xml trunk/docs/user-manual/en/project-info.xml trunk/docs/user-manual/en/using-server.xml Log: user manual edits part 1 Modified: trunk/docs/user-manual/en/architecture.xml =================================================================== --- trunk/docs/user-manual/en/architecture.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/architecture.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -21,7 +21,8 @@ <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) - we hope you + like it's 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 @@ -29,8 +30,8 @@ <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>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 @@ -91,7 +92,9 @@ 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.</para> + 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 @@ -118,14 +121,14 @@ 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 + <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 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> + 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 Modified: trunk/docs/user-manual/en/messaging-concepts.xml =================================================================== --- trunk/docs/user-manual/en/messaging-concepts.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/messaging-concepts.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -92,7 +92,7 @@ <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 - that the order message is done and can be forgotten about. Often the send to the + that the order has been processed and can be forgotten about. Often the send to the warehouse system, update in database and acknowledgement will be completed in a single transaction to ensure <ulink url="http://en.wikipedia.org/wiki/ACID" @@ -109,7 +109,7 @@ 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 - even if the server crashes or is restarted in between. Non-durable + consumes them - 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 @@ -125,18 +125,20 @@ messaging</emphasis>. With reliable messaging the server gives a guarantee that the message will be delivered once and only once to each consumer of a queue or each durable subscription of a topic, even in the event of system failure. This is crucial for many - businesses, you don't want your orders fulfilled more than once or your orders to be - lost.</para> + businesses; e.g. you don't want your orders fulfilled more than once or any of your + orders to be lost.</para> <para>In other cases you may not care about a once and only once delivery guarantee and are - happy to cope with duplicate deliveries. The messaging system allows you to configure - which delivery guarantees you require.</para> + happy to cope with duplicate deliveries or lost messages - an example of this might be + transient stock price updates - which are quickly superseded by the next update on the + same stock. The messaging system allows you to configure which delivery guarantees you + require.</para> </section> <section> <title>Transactions</title> <para>Messaging systems typically support the sending and acknowledgement of multiple messages in a single local transaction. HornetQ also supports the sending and acknowledgement of message as part of a large global transaction - using the Java - mapping of XA, JTA.</para> + mapping of XA; JTA.</para> </section> <section> <title>Durability</title> @@ -163,11 +165,11 @@ specification - i.e. it was created to encapsulate common functionality of the already existing messaging systems that were available at the time of its creation.</para> - <para>JMS is a very popular API and is implemented by most messaging systems. JMS is + <para>JMS is a very popular API and is implemented by most, messaging systems. JMS is only available to clients running Java.</para> <para>JMS does not define a standard wire format - it only defines a programmatic API so - JMS clients and servers from different vendors cannot interoperate since they will - most likely use the vendor's own internal wire protocol.</para> + JMS clients and servers from different vendors cannot directly interoperate since + each will use the vendor's own internal wire protocol.</para> <para>HornetQ provides a fully compliant JMS 1.1 API.</para> </section> <section> @@ -185,10 +187,9 @@ <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer" 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>It seems plausible that API standards for cloud computing may 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 @@ -214,10 +215,10 @@ </section> <section> <title>AMQP</title> - <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is an emerging - standard for interoperable messaging. It also defines a wire format, so any AMQP - client can work with any messaging system that supports AMQP. AMQP clients are - available in many different programming languages.</para> + <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is a specification for + interoperable messaging. It also defines a wire format, so any AMQP client can work + with any messaging system that supports AMQP. AMQP clients are available in many + different programming languages.</para> <para>HornetQ will shortly be implementing AMQP.</para> </section> </section> Modified: trunk/docs/user-manual/en/notice.xml =================================================================== --- trunk/docs/user-manual/en/notice.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/notice.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -19,7 +19,7 @@ <chapter id="notice"> <title>Legal Notice</title> - <para>Copyright © 2009 Red Hat, Inc. and others.</para> + <para>Copyright © 2010 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> <para>An explanation of CC-BY-SA is available at Modified: trunk/docs/user-manual/en/preface.xml =================================================================== --- trunk/docs/user-manual/en/preface.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/preface.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -21,7 +21,7 @@ <para>What is HornetQ?</para> <itemizedlist> <listitem> - <para>HornetQ is an open source project to build a multi-protocol, embeddable, high + <para>HornetQ is an open source project to build a multi-protocol, embeddable, very high performance, clustered, asynchronous messaging system.</para> </listitem> <listitem> @@ -30,8 +30,8 @@ />.</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">... wiki + <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">... wiki page</ulink>.</para> </listitem> </itemizedlist> @@ -49,7 +49,7 @@ from Windows desktops to IBM mainframes.</para> </listitem> <listitem> - <para>Superb performance. Our ground-breaking high performance journal provides + <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> @@ -58,9 +58,9 @@ and others you won't find anywhere else.</para> </listitem> <listitem> - <para>Elegant POJO based design with minimal third party dependencies. Run HornetQ + <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.</para> + 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 Modified: trunk/docs/user-manual/en/project-info.xml =================================================================== --- trunk/docs/user-manual/en/project-info.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/project-info.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -1,5 +1,4 @@ <?xml version="1.0" encoding="UTF-8"?> - <!-- ============================================================================= --> <!-- Copyright © 2009 Red Hat, Inc. and others. --> <!-- --> @@ -17,47 +16,75 @@ <!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent --> <!-- permitted by applicable law. --> <!-- ============================================================================= --> - <chapter id="project-info"> - <title>Project Information</title> - <para>The official HornetQ project page is <ulink - url="http://hornetq.org/">http://hornetq.org/</ulink>.... - - <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/d... - </section> - - <section id="download.svn"> - <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</u... - <listitem> <para>If you have any user questions please use our <ulink - url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... - 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&amp;op=viewforum&... - 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></pa... - <listitem><para>Follow us on <ulink url="http://twitter.com/hornetq">twitter</ulink></p... - <listitem><para>HornetQ Subversion trunk is <ulink url="http://anonsvn.jboss.org/repos/hornetq/trunk">http://an... - <listitem><para>All release tags are availble from <ulink url="http://anonsvn.jboss.org/repos/hornetq/tags">http://ano... - </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> - <listitem><para>Howard Gao</para></listitem> - <listitem><para><ulink url="http://jmesnil.net/weblog/">Jeff Mesnil</ulink></para></listitem> - <listitem><para>Clebert Suconic</para></listitem> - <listitem><para>Andy Taylor</para></listitem> - </itemizedlist> - </para> - </section> - + <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/d... + </section> + <section id="download.svn"> + <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</u... + </listitem> + <listitem> + <para>If you have any user questions please use our <ulink + url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... + 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&amp;op=viewforum&... + >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></pa... + </listitem> + <listitem> + <para>Follow us on <ulink url="http://twitter.com/hornetq">twitter</ulink></p... + </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 available 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, they are: <itemizedlist> + <listitem> + <para> + <ulink url="http://jbossfox.blogspot.com">Tim Fox</ulink> (project lead)</para> + </listitem> + <listitem> + <para>Howard Gao</para> + </listitem> + <listitem> + <para><ulink url="http://jmesnil.net/weblog/">Jeff Mesnil</ulink></para> + </listitem> + <listitem> + <para>Clebert Suconic</para> + </listitem> + <listitem> + <para>Andy Taylor</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> Modified: trunk/docs/user-manual/en/using-server.xml =================================================================== --- trunk/docs/user-manual/en/using-server.xml 2010-01-07 11:56:10 UTC (rev 8764) +++ trunk/docs/user-manual/en/using-server.xml 2010-01-07 12:25:45 UTC (rev 8765) @@ -118,13 +118,13 @@ 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> + enforces dependencies between them and other beans. </para> </listitem> <listitem> <para><literal>hornetq-configuration.xml</literal>. This is the main HornetQ configuration file. All the parameters in this file are described in <xref - linkend="configuration-index"/>.</para> + linkend="configuration-index"/>. Please see <xref + linkend="usingserver.mainconfig"/> for more information on this file.</para> </listitem> <listitem> <para><literal>hornetq-queues.xml</literal>. This file contains predefined queues, @@ -138,8 +138,8 @@ 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 + <para><literal>hornetq-users.xml</literal> HornetQ ships with a basic security + manager implementation which obtains user credentials from the <literal role information. For more information on security ,please see <xref linkend="security"/>.</para> @@ -176,7 +176,7 @@ &lt;param key="host" value="${hornetq.remoting.netty.host:localhost}" type="String"/> &lt;param key="port" value="${hornetq.remoting.netty.port:5445}" type="Integer"/> &lt;/connector></programlisting> - <para>here you can see we have replaced 2 values with system properties <literal + <para>Here you can see we have replaced 2 values with system properties <literal found in the system property if there is one, if not they default back to localhost or @@ -310,7 +310,8 @@ <section id="server.microkernel.configuration"> <title>JBoss AS4 MBean Service.</title> <note> - <para>The section is only to configure HornetQ on JBoss AS4. The service funtionality is similar to Microcontainer Beans</para> + <para>The section is only to configure HornetQ on JBoss AS4. The service funtionality is + similar to Microcontainer Beans</para> </note> <para> <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; @@ -344,21 +345,24 @@ &lt;/server&gt; </programlisting> </para> - <para>This jboss-service.xml configuration file is included inside the hornetq-service.sar on AS4 with embebbed HornetQ. - As you can see, on this configuration file we are starting various services:</para> + <para>This jboss-service.xml configuration file is included inside the hornetq-service.sar + on AS4 with embebbed HornetQ. As you can see, on this configuration file we are starting + various services:</para> <itemizedlist> <listitem> <para>HornetQFileConfigurationService</para> - <para>This services instances the configuration object that reads the Configuration File - inside the SAR archive and configure the HornetQ instance.</para> + <para>This services instances the configuration object that reads the Configuration + File inside the SAR archive and configure the HornetQ instance.</para> </listitem> <listitem> <para>JBossASSecurityManagerService</para> - <para>The service that starts the Security Manager as the Microcontainer Bean.</para> + <para>The service that starts the Security Manager as the Microcontainer + Bean.</para> </listitem> <listitem> <para>HornetQStarterService</para> - <para>The HornetQ core server that depends on JBossASSecurityManagerService and HornetQFileConfigurationService MBeans</para> + <para>The HornetQ core server that depends on JBossASSecurityManagerService and + HornetQFileConfigurationService MBeans</para> </listitem> <listitem> <para>HornetQJMSStarterService</para> @@ -366,7 +370,8 @@ </listitem> <listitem> <para>JMSServerManager</para> - <para>Has the responsability to start the JMSServerManager and the same behaviour that JMSServerManager Bean</para> + <para>Has the responsibility to start the JMSServerManager and the same behaviour + that JMSServerManager Bean</para> </listitem> </itemizedlist> </section>