[jboss-cvs] JBoss Messaging SVN: r2527 - trunk/docs/userguide-1.2/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Mar 1 04:17:01 EST 2007
Author: ovidiu.feodorov at jboss.com
Date: 2007-03-01 04:17:01 -0500 (Thu, 01 Mar 2007)
New Revision: 2527
Modified:
trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml
trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml
trunk/docs/userguide-1.2/en/modules/UG12_installation.xml
trunk/docs/userguide-1.2/en/modules/UG12_performance.xml
Log:
doc update
Modified: trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml 2007-03-01 08:51:48 UTC (rev 2526)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_installation.xml 2007-03-01 09:17:01 UTC (rev 2527)
@@ -1,7 +1,12 @@
<chapter id="CLUST_installation">
- <title>JBoss Messaging Clustering Installation</title>
+ <title>JBoss Messaging Clustered Installation</title>
+ <note>
+ You need at least ant 1.6.3 installed in order for the installation procedure to work
+ correctly.
+ </note>
+
<para>
Use the <filename>release-admin.xml</filename> ant script shipped with the release to
create individual cluster node configurations.
@@ -12,7 +17,8 @@
</para>
<programlisting>
- ant -f release-admin.xml [-Did=node-id] [-Dports=port-config-label] cluster-node
+ cd util
+ ant -f release-admin.xml [-Did=node-id] [-Dports=port-config-label] [-Ddatabase=db-name] cluster-node
</programlisting>
<para>
@@ -50,19 +56,29 @@
documentation, at the following address
<ulink url="http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_single/#ch10.bindingmanager">http://docs.jboss.com/jbossas/guides/j2eeguide/r2/en/html_single/#ch10.bindingmanager</ulink>
</listitem>
+ <listitem>
+ <filename>db-name</filename> is the name of the database you want to create the configurations for. Supported database names are: mysql, oracle,
+ postgresql, mssql, and sybase. Notice that if you create database configuration to any database other than MySQL, you will still need to
+ manually install the database JDBC drivers (MySQL drivers are provided as part of the distribution).
+ </listitem>
</itemizedlist>
</para>
<para>
+ Notice that you should have environment variable JBOSS_HOME correctly set to point to your JBoss AS distribution directory before executing any of the
+ scripts.
+ </para>
+
+ <para>
For example, in order to create the configuration for a four-node cluster intended to run
on the same physical machine, use the following sequence:
</para>
<programlisting>
-ant -f release-admin.xml cluster-node
-ant -f release-admin.xml -Did=1 -Dports=ports-01 cluster-node
-ant -f release-admin.xml -Did=2 -Dports=ports-02 cluster-node
-ant -f release-admin.xml -Did=3 -Dports=ports-03 cluster-node
+ ant -f release-admin.xml cluster-node
+ ant -f release-admin.xml -Did=1 -Dports=ports-01 cluster-node
+ ant -f release-admin.xml -Did=2 -Dports=ports-02 cluster-node
+ ant -f release-admin.xml -Did=3 -Dports=ports-03 cluster-node
</programlisting>
<para>
@@ -97,17 +113,17 @@
</para>
<programlisting>
-cd $JBOSS_HOME/bin
-./run.sh -c messaging-node0
+ cd $JBOSS_HOME/bin
+ ./run.sh -c messaging-node0
-cd $JBOSS_HOME/bin
-./run.sh -c messaging-node1
+ cd $JBOSS_HOME/bin
+ ./run.sh -c messaging-node1
-cd $JBOSS_HOME/bin
-./run.sh -c messaging-node2
+ cd $JBOSS_HOME/bin
+ ./run.sh -c messaging-node2
-cd $JBOSS_HOME/bin
-./run.sh -c messaging-node3
+ cd $JBOSS_HOME/bin
+ ./run.sh -c messaging-node3
</programlisting>
@@ -249,4 +265,14 @@
</programlisting>
+ <note>
+ The installation script may fail while installing Messaging with source-generated
+ JBoss 4.0.5.GA-ejb3 instance. This is because release-admin.xml relies on finding
+ <filename>$JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml</filename>.
+ 4.0.5.GA-ejb3 installations seem not to have a "docs" sub-directory. A very simple work-around
+ for this situation is to recursively copy the "docs" sub-directory available under a regular
+ (non-EJB3) source-generated 4.0.5.GA instance and retry the installation process.
+ </note>
+
+
</chapter>
Modified: trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml 2007-03-01 08:51:48 UTC (rev 2526)
+++ trunk/docs/userguide-1.2/en/modules/CLUST_overview.xml 2007-03-01 09:17:01 UTC (rev 2527)
@@ -37,7 +37,7 @@
<para>
When a message is sent from a message producer attached to a particular node to a
- distributed quueue, a routing policy determines which partial queue will receive
+ distributed queue, a routing policy determines which partial queue will receive
the message.
</para>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml 2007-03-01 08:51:48 UTC (rev 2526)
+++ trunk/docs/userguide-1.2/en/modules/UG12_gettingstarted.xml 2007-03-01 09:17:01 UTC (rev 2527)
@@ -6,12 +6,19 @@
<ulink url="http://www.jboss.com/products/messaging">the JBoss Messaging project landing page</ulink>.
</para>
+ <para>
+ The recommended download location is the JBoss Labs Messaging Project download zone:
+ <ulink url="http://labs.jboss.com/portal/jbossmessaging/downloads">http://labs.jboss.com/portal/jbossmessaging/downloads</ulink>
+ We also maintain an alternate download location on sourceforge.net:
+ <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22866&package_id=157261">http://sourceforge.net/project/showfiles.php?group_id=22866&package_id=157261</ulink>
+ </para>
+
<section id="releasebundle">
<title>The JBoss Messaging Release Bundle</title>
<para>
- The JBoss Messaging release bundle (<filename>jboss-messaging-1.0.x.zip</filename>)
- will expand in a <filename>jboss-messaging-1.0.x</filename> directory that contains:
+ The JBoss Messaging release bundle (<filename>jboss-messaging-1.2.x.zip</filename>)
+ will expand in a <filename>jboss-messaging-1.2.x</filename> directory that contains:
</para>
<itemizedlist>
@@ -22,7 +29,7 @@
<warning>
Do not simply attempt to copy the archive under a JBoss instance <filename>deploy</filename> directory,
since additional steps (such as un-installing JBossMQ and various other configurations
- tasks) are required for a successful installation. See <xref linkend="installation"/> for
+ tasks) are required for a successful installation. See <xref linkend="UG2_installation"/> for
more details.
</warning>
</listitem>
@@ -30,19 +37,44 @@
<filename>jboss-messaging-client.jar</filename>
- the client-side library that need to be in the classpath of the client that opens
a remote connection to the Messaging server.
+
+ <note>
+ <para>
+ This is an important note on the Messaging client jar. JBoss Messaging has an
+ extensive tree of dependencies and bundling all right dependencies in one easy
+ to use archive, so no wrong versions inadvertently get in the class path is, as
+ experience shows, extremely convenient. However, this could cause problems if a
+ different version of a dependency is required by the user's client code.
+ </para>
+ <para>
+ If, for example, the log4j.jar bundled with the release causes problems for being
+ too old, one could just simply build the client-side class path so a newer version
+ of log4j.jar precedes jboss-messaging-client.jar in that class path. This approach
+ may work, but is not guaranteed to work, because we did not run the full test suite
+ with any other log4j.jar version except the one we bundle with the release.
+ </para>
+
+ <para>
+ A list of required dependencies for a specific release can be found in the
+ <filename>build-thirdpary.xml</filename> file that is part of the companion source
+ bundle that ships with each release. It can also be looked up online in
+ <ulink url="http://fisheye.jboss.org">http://fisheye.jboss.org</ulink>.
+ </para>
+ </note>
</listitem>
<listitem>
<filename>util</filename>
- a collection of <literal>ant</literal> configuration files used to automate
installation and release
- management procedures. See the Installation chapter for more details.
+ management procedures. See <xref linkend="UG2_installation"/> for
+ more details.
</listitem>
<listitem>
<filename>examples</filename>
- a collection of examples that should run out of the box and help you validate the
installation. Detailed instructions are provided with each example, which range from
very simple JMS queue and topic examples to relatively sophisticated use cases in which
- EJBs and JCA JMS ConnectionFactories are involved.
+ EJBs and JCA JMS ConnectionFactories are involved, as well as clustering use cases.
The <filename>examples/config</filename> sub-directory contains various configuration
file examples.
</listitem>
@@ -51,22 +83,15 @@
- this user's guide.
</listitem>
<listitem>
- <filename>src/jboss-messaging-1.0.x-src.zip</filename>
+ <filename>src/jboss-messaging-1.2.x-src.zip</filename>
- the zipped source directory. The file can be directly installed into and used
with a debugger.
- <note>
- JBoss Messaging cannot be built using exclusively this source snapshot, which is
- provided for reference only.
- </note>
</listitem>
<listitem>
- <filename>src/jboss-messaging-tests-1.0.x-src.zip</filename>
- - the functional testsuite source archive.
- </listitem>
- <listitem>
<filename>test-results</filename>
- the output of the functional testsuite, stress and smoke test runs for this release.
- All these files have been generated during the release procedure.
+ All these files have been generated during the release procedure and are bundled here
+ for reference.
</listitem>
<listitem>
<filename>api</filename>
@@ -82,17 +107,19 @@
</section>
- <section id="CVS">
- <title>CVS Access</title>
+ <section id="SVN">
+ <title>SVN Access</title>
<para>
If you want to experiment with the latest developments you may checkout the latest code
- from the 5.0 head branch. Be aware that the information provided in this manual might then
- not be accurate.
- For the latest instructions, check out the
+ from the Messaging SVN trunk. Be aware that the information provided in this manual might
+ then not be accurate.
+ For the latest instructions on how to check out and build source code, please go to
<ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingDevelopment">
- Messaging Development wiki page
- </ulink>.
+ Messaging Development wiki page</ulink>, specifically
+
+ <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossMessagingBuildInstructions">
+ "Building and Running JBoss Messaging"</ulink> section.
</para>
</section>
Modified: trunk/docs/userguide-1.2/en/modules/UG12_installation.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_installation.xml 2007-03-01 08:51:48 UTC (rev 2526)
+++ trunk/docs/userguide-1.2/en/modules/UG12_installation.xml 2007-03-01 09:17:01 UTC (rev 2527)
@@ -1,13 +1,20 @@
<chapter id="UG2_installation">
- <title>Installation</title>
+ <title>JBoss Messaging Non-Clustered Installation</title>
<para>
- By default, a JBoss AS 4.0.x instance ships with JBossMQ as default JMS provider.
- In order to use the JBoss AS instance with JBoss Messaging, you need to perform the installation
- procedure described below.
+ This section describes the procedure to perfom a non-clustered installation. At the
+ end of this procedure, you will create a JBoss Messaging configuration that will
+ start a non-clustered Messaging server. To find out how you can install JBoss Messaging
+ in a clustered configuration, please proceed to <xref linkend="CLUST_installation"/>.
</para>
<para>
+ By default, a JBoss AS 4.0.x and 4.2.0 instance ships with JBossMQ as default JMS provider.
+ In order to use the JBoss AS instance with JBoss Messaging, you need to perform the
+ installation procedure described below.
+ </para>
+
+ <para>
<warning>
A JBossMQ and a JBoss Messaging instance cannot coexist, at least not unless special
precautions are taken. Do not simply attempt to copy the Messaging release artifact
@@ -18,9 +25,8 @@
</para>
-
<section id="install4">
- <title>Installing JBoss Messaging with JBoss AS 4.x</title>
+ <title>Installing JBoss Messaging with JBoss AS 4.0.x and 4.2.1</title>
<section id="install4.automated">
Modified: trunk/docs/userguide-1.2/en/modules/UG12_performance.xml
===================================================================
--- trunk/docs/userguide-1.2/en/modules/UG12_performance.xml 2007-03-01 08:51:48 UTC (rev 2526)
+++ trunk/docs/userguide-1.2/en/modules/UG12_performance.xml 2007-03-01 09:17:01 UTC (rev 2527)
@@ -4,6 +4,17 @@
<para>As we discussed in <xref linkend="about"/>, the key advantage of JBoss Messaging is its superior performance. In fact, the JBoss Messaging comes with a set of standard performance test. You can run them on your server and generate your own performance benchmark results. In this chapter, we will show you how to run a JBoss Messaging server and a JBossMQ server side-by-side on a single machine, and compare their performance. To get the performance tests, you have to obtain the JBoss Messaging source code from CVS as described in <xref linkend="gettingstarted"/>.</para>
+ <para>
+ To get the performance tests, you first need to check out the source code and build the project. The location of the framework's source code will be
+ referred to as $PERF_HOME throughout the rest of the document.
+ </para>
+
+ <programlisting>
+ svn co https://svn.jboss.org/repos/messaging/projects/perf/trunk messaging-perf
+ cd $PERF_HOME
+ ant
+ </programlisting>
+
<para>The test consists in sending bursts of 1000 0 Kilobytes non-persistent messages to both JBoss Messaging and JBossMQ instances while gradually increasing the send rate (200 messages/sec, 400 messages/sec, etc) and measuring the receive rate. At the end, the framework generates the graph representing the receive rate as function of the send rate for two executions (JBoss Messaging and JBossMQ).</para>
<section>
@@ -44,7 +55,6 @@
<para>In order to correctly deploy the colocated executors, the framework relies on the <literal>JBOSS_HOME</literal> environment variable. It assumes directories <literal>$JBOSS_HOME/server/messaging</literal> and <literal>$JBOSS_HOME/server/jbossmq</literal> exist.</para>
<programlisting>
-cd perf
ant sar
ant start-executors
</programlisting>
@@ -60,7 +70,7 @@
<section>
<title>Configure Test Runs</title>
- <para>The <literal>perf/perf.xml</literal> file is used to configure tests. In our setting (i.e., <literal>jbossmq</literal> runs in +100 port range from default), the <literal><providers></literal> section should look like the following. We can easily run the two JMS server configurations on different machines or in other port ranges. You just need to change the host and port numbers here for tests.</para>
+ <para>The <literal>etc/perf.xml</literal> file is used to configure tests. In our setting (i.e., <literal>jbossmq</literal> runs in +100 port range from default), the <literal><providers></literal> section should look like the following. We can easily run the two JMS server configurations on different machines or in other port ranges. You just need to change the host and port numbers here for tests.</para>
<programlisting>
<provider name="JBossMessaging">
@@ -69,8 +79,8 @@
<pkg>org.jboss.naming:org.jnp.interfaces</pkg>
<executor name="REMOTE" url="rmi://localhost:7777/standalone"/>
<executor name="REMOTE2" url="rmi://localhost:7777/standalone2"/>
- <executor name="COLOCATED" url="rmi://localhost:7777/colocated-messaging"/>
- <executor name="COLOCATED2" url="rmi://localhost:7777/colocated-messaging2"/>
+ <executor name="COLOCATED" url="rmi://localhost:7777/local-messaging"/>
+ <executor name="COLOCATED2" url="rmi://localhost:7777/local-messaging2"/>
</provider>
<provider name="JBossMQ">
@@ -79,8 +89,8 @@
<pkg>org.jboss.naming:org.jnp.interfaces</pkg>
<executor name="REMOTE" url="rmi://localhost:7777/standalone"/>
<executor name="REMOTE2" url="rmi://localhost:7777/standalone2"/>
- <executor name="COLOCATED" url="rmi://localhost:7777/colocated-jbossmq"/>
- <executor name="COLOCATED2" url="rmi://localhost:7777/colocated-jbossmq2"/>
+ <executor name="COLOCATED" url="rmi://localhost:7777/local-jbossmq"/>
+ <executor name="COLOCATED2" url="rmi://localhost:7777/local-jbossmq2"/>
</provider>
</programlisting>
@@ -146,12 +156,12 @@
<section>
<title>Run the Tests</title>
- <para>To run the tests, simply executes <literal>ant</literal> from the command line. You can access the benchmark result graphs from <literal>output/results/benchmark-results.html</literal>.</para>
+ <para>To run the tests, simply execute <literal>ant run</literal> from the command line. You can access the benchmark result graphs from <literal>output/results/benchmark-results.html</literal>.</para>
<para>After running the test, you can clean up the executors and test destinations using the following commands.</para>
<programlisting>
-ant kill-executors
+ant stop-executors
ant undeploy-destinations
</programlisting>
More information about the jboss-cvs-commits
mailing list