diff options
5 files changed, 136 insertions, 67 deletions
diff --git a/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml index e3ab701257..b2dbd969bc 100644 --- a/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml +++ b/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml @@ -35,5 +35,6 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-High-Availability.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Miscellaneous.xml"/> </book> diff --git a/doc/book/src/java-broker/Java-Broker-Installation.xml b/doc/book/src/java-broker/Java-Broker-Installation.xml index a2f8e45242..218e39f578 100644 --- a/doc/book/src/java-broker/Java-Broker-Installation.xml +++ b/doc/book/src/java-broker/Java-Broker-Installation.xml @@ -35,11 +35,17 @@ <title>Prerequisites</title> <section role="h3" id="Java-Broker-Installation-Prerequistes-Java"> <title>Java Platform</title> - <para>The Java Broker is an 100% Java implementation and as such it can be used on any operating - system supporting Java 1.6 or higher. This includes Linux, Solaris and Mac OS X, Windows XP/Vista/7.</para> - <para>The Java Broker has been tested with Java implementations from both Oracle and IBM. Whatever - platform you chose, it is recommended that you ensure it is patched with any critical updates made - available from the vendor.</para> + <para> + The Java Broker is an 100% Java implementation and as such it can be used on any operating + system supporting Java 1.6 or higher. This includes Linux, Solaris, Mac OS X, and Windows XP/Vista/7/8.</para> + <para> + The broker has been tested with Java implementations from both Oracle and IBM. Whatever + platform you chose, it is recommended that you ensure it is patched with any critical updates made + available from the vendor. + </para> + <para> + Verify that your JVM is installed properly by following <link linkend="Java-Broker-Miscellaneous-JVM-Verification">these instructions.</link> + </para> </section> <section role="h3" id="Java-Broker-Installation-Prerequistes-Disk"> <title>Disk</title> @@ -65,42 +71,35 @@ <title>Operating System Account</title> <para>Installation or operation of Qpid does <emphasis>not</emphasis> require a privileged account (i.e. root on UNIX platforms or Administrator on Windows). However it is suggested that you use an dedicated account - (e.g. qpid) for the installation and operation of Java Broker.</para> - </section> - <section role="h3" id="Java-Broker-Installation-Prerequistes-OracleBDBJE"> - <title>Oracle BDB JE JAR (optional)</title> - <para>The Java Broker ships with two persistent message store modules, the DerbyMessageStore which uses - Apache Derby and the BDBMessageStore which uses Oracle JE BDB.</para> - <para>If you wish to use the BDBMessageStore, then you must download the <ulink - url="&oracleJeDownloadUrl;">Oracle BDB JE JAR version 5.0.x</ulink> from the Oracle - website as it cannot be distributed with Qpid owing to licence restrictions.</para> - <para>The download has a name in the form je-&oracleBdbProductVersion;.tar.gz. It is recommended that you - confirm the integrity of the download by verifying the MD5.</para> + (e.g. qpid) for the installation and operation of the Java Broker.</para> </section> </section> <section role="h2" id="Java-Broker-Installation-Download"> <title>Download</title> - <para>Download the latest qpid-java-broker-x.x.tar.gz package from <ulink - url="&qpidDownloadUrl;">&qpidDownloadUrl;</ulink>. It is recommended that you confirm the - integrity of the download by verifying the PGP signature matches that available on the - site.</para> + <section role="h3" id="Java-Broker-Installation-Download-Release"> + <title>Broker Release</title> + <para>You can download the latest qpid-java-broker-&qpidCurrentRelease;.tar.gz package from the <ulink + url="&qpidDownloadUrl;">Download Page</ulink>. + </para> + <para> It is recommended that you confirm the integrity of the download by verifying the PGP signature + matches that available on the site. Instrutions are given on the download page. + </para> + </section> + <section role="h3" id="Java-Broker-Installation-Download-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> </section> <section role="h2" id="Java-Broker-Installation-InstallationWindows"> <title>Installation on Windows</title> - <para>Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the - following at the command prompt:</para> - <programlisting><![CDATA[echo %JAVA_HOME%]]></programlisting> - <para>if JAVA_HOME is set you will see something similar to the following:</para> - <screen><![CDATA[c:"\PROGRA~1"\Java\jdk1.6.0_24\]]> - </screen> - <para>Then confirm that a Java installation (1.6 or higher) is available:</para> - <programlisting><![CDATA[java -version]]></programlisting> - <para>If java is available on the path, output similar to the following will be seen:</para> - <screen><![CDATA[java version "1.6.0_24" -Java(TM) SE Runtime Environment (build 1.6.0_24-b07) -Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02, mixed mode)]]></screen> + <para> + Firstly, verify that your JVM is installed properly by following + <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Windows">these instructions.</link> + </para> <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. It need not be the same location as the store used for the persistent messages or the log file (you will chose this location later). For the remainder this example we will assumed that location c:\qpid has been chosen.</para> @@ -121,13 +120,6 @@ Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02, mixed mode)]]></screen> 07/20/2012 08:10 PM 1,346 README.txt 3 File(s) 71,129 bytes 5 Dir(s) 743,228,796,928 bytes free</screen> - <section role="h3" id="Java-Broker-Installation-InstallationWindows-OracleBDBJE"> - <title>Installation of Oracle BDB JE JAR (optional)</title> - <para>If you wish to use the BDBMessageStore, copy the je-&oracleBdbProductVersion;.jar downloaded - <link linkend="Java-Broker-Installation-Prerequistes-OracleBDBJE">above</link> into the following directory.</para> - <programlisting>mkdir c:\qpid\qpid-broker-x.x\lib\opt -copy je-&oracleBdbProductVersion;.jar c:\qpid\qpid-broker-x.x\lib\opt</programlisting> - </section> <section role="h3" id="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK"> <title>Setting the working directory</title> <para>Qpid requires a work directory. This directory is used for the default location of the Qpid log @@ -138,22 +130,20 @@ copy je-&oracleBdbProductVersion;.jar c:\qpid\qpid-broker-x.x\lib\opt</programli <para>If the directory referred to by QPID_WORK does not exist, the Java Broker will attempt to create it on start-up.</para> </section> + <section role="h3" id="Java-Broker-Installation-InstallationWindows-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> </section> <section role="h2" id="Java-Broker-Installation-InstallationUnix"> <title>Installation on UNIX platforms</title> - <para>Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the - following at the command prompt:</para> - <programlisting><![CDATA[echo $JAVA_HOME]]></programlisting> - <para>if JAVA_HOME is set you will see something similar to the following:</para> - <screen><![CDATA[/usr/java/jdk1.6.0_35]]> - </screen> - <para>Then confirm that a Java installation (1.6 or higher) is available:</para> - <programlisting><![CDATA[java -version]]></programlisting> - <para>If java is available on the path, output similar to the following will be seen:</para> - <screen><![CDATA[java version "1.6.0_35" -Java(TM) SE Runtime Environment (build 1.6.0_35-b10-428-11M3811) -Java HotSpot(TM) 64-Bit Server VM (build 20.10-b01-428, mixed mode)]]></screen> + <para> + Firstly, verify that your JVM is installed properly by following + <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Unix">these instructions.</link> + </para> <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. It need not be the same location as the store used for the persistent messages or the log file (you will chose this location later). For the remainder this example we will assumed that location /usr/local/qpid has been chosen.</para> @@ -173,13 +163,6 @@ drwxr-xr-x 10 qpid qpid 340 30 Sep 00:24 bin drwxr-xr-x 9 qpid qpid 306 21 Aug 23:17 etc drwxr-xr-x 34 qpid qpid 1156 25 Jul 23:22 lib </screen> - <section role="h3" id="Java-Broker-Installation-InstallationUnix-OracleBDBJE"> - <title>Installation of Oracle BDB JE JAR (optional)</title> - <para>If you wish to use the BDBMessageStore, copy the je-&oracleBdbProductVersion;.jar downloaded - <link linkend="Java-Broker-Installation-Prerequistes-OracleBDBJE">above</link> into the following directory.</para> - <programlisting>mkdir qpid-broker-x.x/lib/opt -cp je-&oracleBdbProductVersion;.jar qpid-broker-x.x/lib/opt</programlisting> - </section> <section role="h3" id="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK"> <title>Setting the working directory</title> <para>Qpid requires a work directory. This directory is used for the default location of the Qpid log @@ -192,5 +175,11 @@ cp je-&oracleBdbProductVersion;.jar qpid-broker-x.x/lib/opt</programlisting> on start-up. </para> </section> + <section role="h3" id="Java-Broker-Installation-InstallationUnix-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these + stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + </para> + </section> </section> </chapter> diff --git a/doc/book/src/java-broker/Java-Broker-Introduction.xml b/doc/book/src/java-broker/Java-Broker-Introduction.xml index 4e6dc2cbce..651389d0ac 100644 --- a/doc/book/src/java-broker/Java-Broker-Introduction.xml +++ b/doc/book/src/java-broker/Java-Broker-Introduction.xml @@ -45,7 +45,7 @@ <para>JMS 1.1 compliance (Java client).</para> </listitem> <listitem> - <para>Transient and persistent message support</para> + <para>Persistent and non-persistent (transient) message support</para> </listitem> <listitem> <para>Supports for all common messaging patterns (point-to-point, publish/subscribe, fan-out @@ -53,15 +53,14 @@ </listitem> <listitem> <para>Transaction support including XA<footnote> - <para>XA provided by AMQP 0-10 and above</para> + <para>XA provided when using AMQP 0-10</para> </footnote></para> </listitem> <listitem> <para>Supports for all versions of the AMQP protocol</para> </listitem> <listitem> - <para>Automatic translation between the AMQP protocols allowing clients using different AMQP - versions to communicate</para> + <para>Automatic message translation, allowing clients using different AMQP versions to communicate with each other.</para> </listitem> <listitem> <para>Pluggable authentication architecture with out-of-the-box support for Kerberos, LDAP, @@ -70,8 +69,8 @@ <listitem> <para>Pluggable message store architecture with implementations based on <ulink url="http://db.apache.org/derby/">Apache Derby</ulink>, <ulink - url="&oracleBdbProductOverviewUrl;">Oracle BDB</ulink><footnote> - <para>Oracle BDB JE JAR must be downloaded separately.</para> + url="&oracleBdbProductOverviewUrl;">Oracle BDB JE</ulink><footnote> + <para>Oracle BDB JE must be downloaded separately.</para> </footnote>, and Memory Store</para> </listitem> <listitem> @@ -82,8 +81,8 @@ <para>SSL support</para> </listitem> <listitem> - <para>High availability (HA) support<footnote> - <para>HA currently available to users of the BDB-store only</para> + <para>High availability (HA) support.<footnote> + <para>HA currently only available to users of the optional BDB JE HA based message store.</para> </footnote></para> </listitem> </itemizedlist> diff --git a/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml b/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml new file mode 100644 index 0000000000..007d6cde5b --- /dev/null +++ b/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml @@ -0,0 +1,80 @@ +<?xml version="1.0"?> +<!DOCTYPE entities [ +<!ENTITY % entities SYSTEM "commonEntities.xml"> +%entities; +]> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +<chapter id="Java-Broker-Miscellaneous"> + <title>Miscellaneous</title> + + <section role="h2" id="Java-Broker-Miscellaneous-JVM-Verification"> + <title>JVM Installation verification</title> + <section role="h2" id="Java-Broker-Miscellaneous-JVM-Verification-Windows"> + <title>Verify JVM on Windows</title> + <para> + Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the + following at the command prompt: + </para> + <programlisting><![CDATA[echo %JAVA_HOME%]]></programlisting> + <para> + If JAVA_HOME is set you will see something similar to the following: + </para> + <screen><![CDATA[c:"\PROGRA~1"\Java\jdk1.6.0_24\]]> + </screen> + <para> + Then confirm that a Java installation (1.6 or higher) is available: + </para> + <programlisting><![CDATA[java -version]]></programlisting> + <para> + If java is available on the path, output similar to the following will be seen: + </para> + <screen><![CDATA[java version "1.6.0_24" +Java(TM) SE Runtime Environment (build 1.6.0_24-b07) +Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02, mixed mode)]]></screen> + </section> + + <section role="h2" id="Java-Broker-Miscellaneous-JVM-Verification-Unix"> + <title>Verify JVM on Windows</title> + <para> + Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the + following at the command prompt: + </para> + <programlisting><![CDATA[echo $JAVA_HOME]]></programlisting> + <para> + If JAVA_HOME is set you will see something similar to the following: + </para> + <screen><![CDATA[/usr/java/jdk1.6.0_35]]> + </screen> + <para> + Then confirm that a Java installation (1.6 or higher) is available: + </para> + <programlisting><![CDATA[java -version]]></programlisting> + <para> + If java is available on the path, output similar to the following will be seen: + </para> + <screen><![CDATA[java version "1.6.0_35" +Java(TM) SE Runtime Environment (build 1.6.0_35-b10-428-11M3811) +Java HotSpot(TM) 64-Bit Server VM (build 20.10-b01-428, mixed mode)]]></screen> + </section> + </section> +</chapter> diff --git a/doc/book/src/java-broker/commonEntities.xml b/doc/book/src/java-broker/commonEntities.xml index 8edcc65da5..af95997f77 100644 --- a/doc/book/src/java-broker/commonEntities.xml +++ b/doc/book/src/java-broker/commonEntities.xml @@ -21,7 +21,7 @@ <!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html"> <!ENTITY qpidProgrammingBook "../../Programming-In-Apache-Qpid/html/"> -<!ENTITY qpidCppBook "../../MQP-Messaging-Broker-CPP-Book/html/"> +<!ENTITY qpidCppBook "../../AMQP-Messaging-Broker-CPP-Book/html/"> <!ENTITY qpidCurrentRelease "0.18"> |