[hornetq-commits] JBoss hornetq SVN: r8797 - trunk/docs/user-manual/en.

Author: timfox Date: 2010-01-12 12:00:44 -0500 (Tue, 12 Jan 2010) New Revision: 8797 Modified: trunk/docs/user-manual/en/appserver-integration.xml trunk/docs/user-manual/en/clusters.xml trunk/docs/user-manual/en/connection-ttl.xml trunk/docs/user-manual/en/core-bridges.xml trunk/docs/user-manual/en/duplicate-detection.xml trunk/docs/user-manual/en/ha.xml trunk/docs/user-manual/en/jms-bridge.xml trunk/docs/user-manual/en/logging.xml trunk/docs/user-manual/en/perf-tuning.xml trunk/docs/user-manual/en/security.xml trunk/docs/user-manual/en/transaction-config.xml Log: last of the docs edits Modified: trunk/docs/user-manual/en/appserver-integration.xml =================================================================== --- trunk/docs/user-manual/en/appserver-integration.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/appserver-integration.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -18,11 +18,11 @@ <!-- ============================================================================= --> <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 + <para>HornetQ can be easily installed in JBoss Application Server 4 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 + remote JCA adaptor into another application sever, please consult the other 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> @@ -51,7 +51,7 @@ <para>In this example you can see that the MDB will consume messages from a queue that is mapped into JNDI with the binding <literal>queue/testQueue</literal>. This queue must be preconfigured in the usual way using the HornetQ configuration files.</para> - <para>The <literal>ResourceAdapter</literal> annotation is used to specify which ra adapter + <para>The <literal>ResourceAdapter</literal> annotation is used to specify which adaptor should be used. To use this you will need to import <literal <literal>jboss-ejb3-ext-api.jar</literal> which can be found in the jboss @@ -150,11 +150,11 @@ { public void onMessage(Message message) }</programlisting> - <para>When using Bean Managed Transactions the message delivery to the MBD will occur + <para>When using Bean Managed Transactions the message delivery to the MDB 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 + >Dups-ok-acknowledge</literal>. Please note 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> <para>A user would control the lifecycle of the transaction something like the @@ -174,8 +174,9 @@ UserTransaction tx = ctx.getUserTransaction(); tx.begin(); + //do some stuff within the transaction - tx.xommit(); + tx.commit(); } catch (Exception e) @@ -225,7 +226,7 @@ @ResourceAdapter("hornetq-ra.rar") public class MDBMessageSendTxExample implements MessageListener { - @Resource(mappedName = "java:JmsXA") + @Resource(mappedName = "java:/JmsXA") ConnectionFactory connectionFactory; @Resource(mappedName = "queue/replyQueue") @@ -283,7 +284,7 @@ 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 + configuration of the adapter is found in this archive under <literal <para>The configuration will look something like the following:</para> <programlisting>&lt;resourceadapter> @@ -358,7 +359,7 @@ <para>There are 3 main parts to this configuration.</para> <orderedlist> <listitem> - <para>A set of global properties for the Adapter</para> + <para>A set of global properties for the adapter</para> </listitem> <listitem> <para>The configuration for the outbound part of the adapter. This is used for Modified: trunk/docs/user-manual/en/clusters.xml =================================================================== --- trunk/docs/user-manual/en/clusters.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/clusters.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -263,10 +263,16 @@ <para>If you're using the core API to directly instantiate <literal discovery group parameters directly when creating the session factory. Here's an - example:final String groupAddress = "231.7.7.7"; final int groupPort = 9876; + example: + <programlisting> + final String groupAddress = "231.7.7.7"; + final int groupPort = 9876; SessionFactory factory = HornetQClient.createClientSessionFactory(groupAddress, groupPort); ClientSession session1 = factory.createClientSession(...); ClientSession - session2 = factory.createClientSession(...); </para> + session2 = factory.createClientSession(...); + + </programlisting> + </para> <para>The <literal>refresh-timeout</literal> can be set directly on the session factory by using the setter method <literal>setDiscoveryRefreshTimeout() if you want to change the default value.</literal></para> @@ -283,7 +289,7 @@ <section> <title>Server-Side Message Load Balancing</title> <para>If cluster connections are defined between nodes of a cluster, then HornetQ - will load balance messages arriving from at a particular node from a client.</para> + will load balance messages arriving at a particular node from a client.</para> <para>Let's take a simple example of a cluster of four nodes A, B, C, and D arranged in a <emphasis>symmetric cluster</emphasis> (described in <xref linkend="symmetric-cluster" />). We have a queue called @@ -423,13 +429,13 @@ <para>When creating connections between nodes of a cluster to form a cluster connection, HornetQ uses a cluster user and cluster password which is defined in <literal>hornetq-configuration.xml</literal>:</para> <programlisting> - &lt;management-cluster-user&gt;HORNETQ.CLUSTER.ADMIN.USER&lt;/management-cluster-user&gt; - &lt;management-cluster-password&gt;CHANGE ME!!&lt;/management-cluster-password&gt; + &lt;cluster-user&gt;HORNETQ.CLUSTER.ADMIN.USER&lt;/cluster-user&gt; + &lt;cluster-password&gt;CHANGE ME!!&lt;/cluster-password&gt; </programlisting> - <para>It is imperative that these values are changed from their default, or remote clients will be able to make connections + <warning><para>It is imperative that these values are changed from their default, or remote clients will be able to make connections to the server using the default values. If they are not changed from the default, HornetQ will detect this and pester you with a warning on every - start-up.</para> + start-up.</para></warning> </section> </section> <section id="clusters.client.loadbalancing"> Modified: trunk/docs/user-manual/en/connection-ttl.xml =================================================================== --- trunk/docs/user-manual/en/connection-ttl.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/connection-ttl.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -168,6 +168,6 @@ To enable asynchronous connection execution, set the parameter <literal - <literal>false</literal>).</para> + <literal>true</literal>).</para> </section> </chapter> Modified: trunk/docs/user-manual/en/core-bridges.xml =================================================================== --- trunk/docs/user-manual/en/core-bridges.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/core-bridges.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -216,6 +216,8 @@ use when creating the bridge connection to the remote server. If it is not specified the default cluster user specified by <literal>cluster-user</literal> in <literal>hornetq-configuration.xml</literal> will be used. </para> + </listitem> + <listitem> <para><literal>password</literal>. This optional parameter determines the password to use when creating the bridge connection to the remote server. If it is not specified the default cluster password specified by <literal Modified: trunk/docs/user-manual/en/duplicate-detection.xml =================================================================== --- trunk/docs/user-manual/en/duplicate-detection.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/duplicate-detection.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -119,7 +119,7 @@ </section> <section> <title>Duplicate Detection and Bridges</title> - <para>Core bridges can configured to automatically add a unique duplicate id value (if there + <para>Core bridges can be configured to automatically add a unique duplicate id value (if there isn't already one in the message) before forwarding the message to it's target. This ensures that if the target server crashes or the connection is interrupted and the bridge resends the message, then if it has already been received by the target server, Modified: trunk/docs/user-manual/en/ha.xml =================================================================== --- trunk/docs/user-manual/en/ha.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/ha.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -268,7 +268,7 @@ global order to ensure a consistent replica state. This is extremely hard to do in a performant and scalable way, especially when one considers that multiple threads are changing the live server state concurrently.</para> - <para>Some messaging systems which provide full state machine replication use + <para>It is possible to provide full state machine replication using techniques such as <emphasis role="italic">virtual synchrony</emphasis>, but this does not scale well and effectively serializes all operations to a single thread, dramatically reducing concurrency.</para> Modified: trunk/docs/user-manual/en/jms-bridge.xml =================================================================== --- trunk/docs/user-manual/en/jms-bridge.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/jms-bridge.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -246,10 +246,6 @@ <para>This represents a JMS selector expression used for consuming messages from the source destination. Only messages that match the selector expression will be bridged from the source to the target destination</para> - <para> - <note>Ut is always more efficient to apply selectors on source topic - subscriptions to source queue consumers</note> - </para> <para>The selector expression must follow the <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/jms/Message.html&qu... selector syntax</ulink></para> Modified: trunk/docs/user-manual/en/logging.xml =================================================================== --- trunk/docs/user-manual/en/logging.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/logging.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -18,8 +18,8 @@ <!-- ============================================================================= --> <chapter id="logging"> <title>Logging</title> - <para>HornetQ has its own Logging Delegate that has no dependencies on any particular logging - framework. The default Delegate delegates all its logs to the standard <ulink + <para>HornetQ has its own logging delegate that has no dependencies on any particular logging + framework. The default delegate delegates all its logs to the standard <ulink url="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/"&g... logging</ulink>, (a.k.a Java-Util-Logging: JUL). By default the server picks up its JUL configuration from a <literal>logging.properties</literal> file found in the config directories. This is Modified: trunk/docs/user-manual/en/perf-tuning.xml =================================================================== --- trunk/docs/user-manual/en/perf-tuning.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/perf-tuning.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -74,14 +74,14 @@ <para>Disable message timestamp. Use the <literal - need them. Again this makes the message smaller.</para> + need them.</para> </listitem> <listitem> <para>Avoid <literal>ObjectMessage</literal>. <literal>ObjectMessage</literal> is convenient but it comes at a cost. The body of a <literal The Java serialized form of even small objects is very verbose so takes up a lot - of space on the wire, also Java serialization is slow compared to customer + of space on the wire, also Java serialization is slow compared to custom marshalling techniques. Only use <literal>ObjectMessage</literal> if you really can't use one of the other message types, i.e. if you really don't know the type of the payload until run-time.</para> @@ -274,17 +274,6 @@ can.</para> </listitem> <listitem> - <para>Avoid many selectors on a queue. Another common anti-pattern is a single queue - which has many consumers, each one with a distinct message selector. As messages - come into the queue they will typically only match one of the consumers. This - does not normally give good performance since as new consumers are added the - 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> - </listitem> - <listitem> <para>Don't create temporary queues for each request. This common anti-pattern involves the temporary queue request-response pattern. With the temporary queue request-response pattern a message is sent to a target and a reply-to header is Modified: trunk/docs/user-manual/en/security.xml =================================================================== --- trunk/docs/user-manual/en/security.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/security.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -172,7 +172,7 @@ &lt;/configuration&gt; </programlisting> - <para>The first thing to note is the element <literal>default-user</literal>. This defines + <para>The first thing to note is the element <literal>defaultuser</literal>. This defines what user will be assumed when the client does not specify a username/password when creating a session. In this case they will be the user <literal>guest</literal> and have the role also called <literal>guest</literal>. Multiple roles can be specified for a @@ -197,7 +197,7 @@ &lt;/bean&gt; </programlisting> <para>The class <literal>org.hornetq.spi.core.security.HornetQSecurityManagerImpl</literal> - is the default security manager that reads used by the standalone server.</para> + is the default security manager that is 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 @@ -263,12 +263,10 @@ is configured.</para> </section> <section> - <title>Changing the Management Password for Clustering</title> - <para>In order for cluster connections to work correctly, each node in the cluster must - register for management notifications from other nodes. To do this they must perform - 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> + <title>Changing the username/password for clustering</title> + <para>In order for cluster connections to work correctly, each node in the cluster must make + connections to the other nodes. The username/password they use for this should always be + changed from the installation default to prevent a security risk.</para> + <para>Please see <xref linkend="management"/> for instructions on how to do this.</para> </section> </chapter> Modified: trunk/docs/user-manual/en/transaction-config.xml =================================================================== --- trunk/docs/user-manual/en/transaction-config.xml 2010-01-12 15:58:54 UTC (rev 8796) +++ trunk/docs/user-manual/en/transaction-config.xml 2010-01-12 17:00:44 UTC (rev 8797) @@ -21,7 +21,7 @@ <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 + started but then 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 3000000 milliseconds (5 minutes), i.e. any transactions older