From 1762961137051d64d56c93876bf675c507781e1b Mon Sep 17 00:00:00 2001
From: Keith Wall <kwall@apache.org>
Date: Tue, 30 Oct 2012 21:55:54 +0000
Subject: QPID-4361: [Java Broker] Add chapters for
 Introduction/Installation/Getting Started

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1403888 13f79535-47bb-0310-9956-ffa450edef68
---
 .../AMQP-Messaging-Broker-Java-Book.xml            |   4 +-
 .../java-broker/Java-Broker-Getting-Started.xml    | 109 +++++++++++++
 .../java-broker/Java-Broker-High-Availability.xml  |   9 +-
 .../src/java-broker/Java-Broker-Installation.xml   | 171 +++++++++++++++++++++
 .../src/java-broker/Java-Broker-Introduction.xml   |  65 ++++++++
 .../java-broker/Java-Broker-Queues-OtherTypes.xml  |   5 +-
 qpid/doc/book/src/java-broker/commonEntities.xml   |  38 +++++
 7 files changed, 391 insertions(+), 10 deletions(-)
 create mode 100644 qpid/doc/book/src/java-broker/commonEntities.xml

(limited to 'qpid/doc/book/src/java-broker')

diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
index 519e4feace..e3ab701257 100644
--- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
+++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
@@ -20,10 +20,10 @@
 
 -->
 
-<book>
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>AMQP Messaging Broker (Java)</title>
 
-<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Introduction.xml"/>
+<xi:include  href="Java-Broker-Introduction.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Installation.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Getting-Started.xml"/>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts.xml"/>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml
index e6c112cf22..8bdd4dc238 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml
@@ -1,4 +1,8 @@
 <?xml version="1.0"?>
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
 <!--
 
  Licensed to the Apache Software Foundation (ASF) under one
@@ -22,4 +26,109 @@
 
 <chapter id="Java-Broker-Getting-Started">
   <title>Getting Started</title>
+  <para>This section describes how to start the Java Broker for the first time.</para>
+  <section role="h2" id="Java-Broker-Getting-Started-Starting">
+    <title>Starting/Stopping the Broker</title>
+    <para>To start the Broker, use the <command>qpid-server</command> script (UNIX) or <command>qpid-server.bat</command> (Windows)
+      provided within distribution.</para>
+  </section>
+  <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Windows">
+    <title>Starting/Stopping on Windows</title>
+    <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationWindows">installation</link>
+      and ensure that the <link linkend="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para>
+    <para>Now use the qpid-server.bat to start the server</para>
+    <programlisting><![CDATA[bin\qpid-server.bat]]></programlisting>
+    <para>Output similar to the following will be seen:</para>
+    <screen>[Broker] BRK-1006 : Using configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\config.xml
+[Broker] BRK-1007 : Using logging configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\log4j.xml
+[Broker] MNG-1001 : Startup
+[Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999
+[Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099
+[Broker] MNG-1004 : Ready
+[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1363863
+[Broker] BRK-1010 : Platform : JVM : Sun Microsystems Inc. version: 1.6.0_24-b07 OS : Windows 7 version: 6.1 arch: amd64
+[Broker] BRK-1011 : Maximum Memory : 1,069,416,448 bytes
+[Broker] BRK-1002 : Starting : Listening on TCP port 5672
+[Broker] BRK-1004 : Qpid Broker Ready</screen>
+    <para>The BRK-1004 message confirms that the Broker is ready for work.  The MNG-1002 and BRK-1004 confirm the ports to
+      which the Broker is listening (for JMX management and AMQP respectively).</para>
+    <para>To stop the Broker, use Control-C or use the Shutdown MBean made from the <xref
+        linkend="Java-Broker-Configuring-And-Managing-JMX"/></para>
+  </section>
+  <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Unix">
+    <title>Starting/Stopping on Unix</title>
+    <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationUnix">installation</link>
+      and ensure that the <link linkend="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para>
+    <para>Now use the <command>qpid-server</command> script to start the server:</para>
+    <programlisting><![CDATA[bin\qpid-server]]></programlisting>
+    <para>Output similar to the following will be seen:</para>
+    <screen>[Broker] BRK-1006 : Using configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/config.xml
+[Broker] BRK-1007 : Using logging configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/log4j.xml
+[Broker] MNG-1001 : Startup
+[Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999
+[Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099
+[Broker] MNG-1004 : Ready
+[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1363863
+[Broker] BRK-1010 : Platform : JVM : Apple Inc. version: 1.6.0_35-b10-428-11M3811 OS : Mac OS X version: 10.8.2 arch: x86_64
+[Broker] BRK-1011 : Maximum Memory : 1,069,416,448 bytes
+[Broker] BRK-1002 : Starting : Listening on TCP port 5672
+[Broker] BRK-1004 : Qpid Broker Ready</screen>
+    <para>The BRK-1004 message confirms that the Broker is ready for work.  The MNG-1002 and BRK-1004 confirm the ports to
+    which the Broker is listening (for JMX management and AMQP respectively).</para>
+    <para>To stop the Broker, use Control-C from the controlling shell, use the
+        <command>bin/qpid.stop</command> script, or use <command>kill -TERM &lt;pid&gt;</command> or
+      the Shutdown MBean from <xref linkend="Java-Broker-Configuring-And-Managing-JMX"/></para>
+  </section>
+  <section role="h2" id="Java-Broker-Getting-Started-LogFile">
+    <title>Log file</title>
+    <para>The Java Broker writes a log file to record both details of its normal operation and any exceptional
+      conditions.  By default the log file is written within the log subdirectory beneath the work directory
+      - <computeroutput>$QPID_WORK/log/qpid.log</computeroutput> (UNIX) and
+      <computeroutput>%QPID_WORK%\log\qpid.log</computeroutput> (Windows).</para>
+    <para>For details of how to control the logging, see <xref linkend="Java-Broker-Runtime-Log-Files"/></para>
+  </section>
+  <section role="h2" id="Java-Broker-Getting-Started-CommandLine">
+    <title>Using the command line</title>
+    <para>The Java Broker understands a number of command line options which may be used to override the configuration.</para>
+    <para>To see usage information for all command line options, use the option <option>--help</option></para>
+    <programlisting><![CDATA[bin/qpid-server --help]]></programlisting>
+    <screen><![CDATA[usage: Qpid [-b address>] [-c <file>] [--exclude-0-10 <port>] [--exclude-0-8 <port>] [--exclude-0-9 <port>] [--exclude-0-9-1
+       <port>] [--exclude-1-0 <port>] [-h] [--include-0-10 <port>] [--include-0-8 <port>] [--include-0-9 <port>] [--include-0-9-1
+       <port>] [--include-1-0 <port>] [--jmxconnectorport <port>] [-l <file>] [-m <port>] [-p <port>] [-s <port>] [-v] [-w <period>]
+ -b,--bind <address>            bind to the specified address. Overrides any value in the config file
+ -c,--config <file>             use given configuration file
+    --exclude-0-10 <port>       when listening on the specified port do not accept AMQP0-10 connections. The
+                                specified port must be one specified on the command line
+    --exclude-0-8 <port>        when listening on the specified port do not accept AMQP0-8 connections. The
+                                specified port must be one specified on the command line
+    --exclude-0-9 <port>        when listening on the specified port do not accept AMQP0-9 connections. The
+                                specified port must be one specified on the command line
+    --exclude-0-9-1 <port>      when listening on the specified port do not accept AMQP0-9-1 connections. The
+                                specified port must be one specified on the command line
+    --exclude-1-0 <port>        when listening on the specified port do not accept AMQP1-0 connections. The
+                                specified port must be one specified on the command line
+ -h,--help                      print this message
+    --include-0-10 <port>       accept AMQP0-10 connections on this port, overriding configuration to the contrary.
+                                The specified port must be one specified on the command line
+    --include-0-8 <port>        accept AMQP0-8 connections on this port, overriding configuration to the contrary.
+                                The specified port must be one specified on the command line
+    --include-0-9 <port>        accept AMQP0-9 connections on this port, overriding configuration to the contrary.
+                                The specified port must be one specified on the command line
+    --include-0-9-1 <port>      accept AMQP0-9-1 connections on this port, overriding configuration to the contrary.
+                                The specified port must be one specified on the command line
+    --include-1-0 <port>        accept AMQP1-0 connections on this port, overriding configuration to the contrary.
+                                The specified port must be one specified on the command line
+    --jmxconnectorport <port>   listen on the specified management (connector server) port. Overrides any
+                                value in the config file
+ -l,--logconfig <file>          use the specified log4j xml configuration file. By default looks for a file named
+                                etc/log4j.xml in the same directory as the configuration file
+ -m,--jmxregistryport <port>    listen on the specified management (registry server) port. Overrides any
+                                value in the config file
+ -p,--port <port>               listen on the specified port. Overrides any value in the config file
+ -s,--sslport <port>            SSL port. Overrides any value in the config file
+ -v,--version                   print the version information and exit
+ -w,--logwatch <period>         monitor the log file configuration file for changes. Units are seconds. Zero means
+                                do not check for changes.]]></screen>
+  </section>
+
 </chapter>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
index 45927d20e0..c7a809a3bf 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml
@@ -1,10 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE urls [
-<!ENTITY oracleBdbProductOverviewUrl "http://www.oracle.com/technetwork/products/berkeleydb/overview/index-093405.html">
-<!ENTITY oracleBdbProductVersion "5.0.58">
-<!ENTITY oracleBdbRepGuideUrl "http://oracle.com/cd/E17277_02/html/ReplicationGuide/">
-<!ENTITY oracleBdbJavaDocUrl "http://docs.oracle.com/cd/E17277_02/html/java/">
-<!ENTITY oracleJdkDocUrl "http://oracle.com/javase/6/docs/api/">
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
 ]>
 <!--
 
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
index 150f83710f..a2f8e45242 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
@@ -1,4 +1,8 @@
 <?xml version="1.0"?>
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
 <!--
 
  Licensed to the Apache Software Foundation (ASF) under one
@@ -22,4 +26,171 @@
 
 <chapter id="Java-Broker-Installation">
   <title>Installation</title>
+  <section role="h2" id="Java-Broker-Installation-Introduction">
+    <title>Introduction</title>
+    <para>This document describes how to install the Java Broker on both Windows and UNIX
+      platforms.</para>
+  </section>
+  <section role="h2" id="Java-Broker-Installation-Prerequistes">
+    <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>
+    </section>
+    <section role="h3" id="Java-Broker-Installation-Prerequistes-Disk">
+      <title>Disk</title>
+      <para>The Java Broker installation requires approximately 20MB of free disk space.</para>
+      <para>The Java Broker also requires a working directory.  The working directory is used for
+        the message store, that is, the area of the file-system used to record persistent messages whilst they
+        are passing through the Broker.  The working directory is also used for the default location of the log file.
+        The size of the working directory will depend on the how the Broker is used.</para>
+      <para>The performance of the file system hosting the work directory is key to the performance of Broker as
+        a whole.  For best performance, choose a device that has low latency and one that is uncontended by other
+        applications.</para>
+      <para>Be aware that there are additional considerations if you are considering hosting the working directory on NFS. See
+        <xref linkend="Java-Broker-Stores"/> for further details.</para>
+    </section>
+    <section role="h3" id="Java-Broker-Installation-Prerequistes-Memory">
+      <title>Memory</title>
+      <para>Qpid caches messages on the heap for performance reasons, so in general, the Broker will
+        benefit from as much heap as possible. However, on a 32bit JVM, the maximum addressable memory range
+        for a process is 4GB, after leaving space for the JVM's own use this will give a maximum heap size
+        of approximately ~3.7GB.</para>
+    </section>
+    <section role="h3" id="Java-Broker-Installation-Prerequistes-OperatingSystemAccount">
+      <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>
+    </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>
+
+  <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>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>
+    <para>Now using WinZip<footnote><para>WinZip is a Registered Trademark of WinZip International LLC</para></footnote> (or similar)
+      extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para>
+    <para>The extraction of the Qpid package will have created a directory qpid-broker-&qpidCurrentRelease; within c:\qpid</para>
+    <screen>Volume in drive C has no label
+
+ Directory of c:\qpid\qpid-broker-&qpidCurrentRelease;
+
+07/25/2012  11:22 PM                   .
+09/30/2012  10:51 AM                   ..
+09/30/2012  12:24 AM                   bin
+08/21/2012  11:17 PM                   etc
+07/25/2012  11:22 PM                   lib
+07/20/2012  08:10 PM            65,925 LICENSE
+07/20/2012  08:10 PM             3,858 NOTICE
+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
+        file and is used for the storage of persistent messages.  The work directory can be set on the
+        command-line (for the lifetime of the command interpreter), but you will normally want to set
+        the environment variable permanently via the Advanced System Settings in the Control Panel.</para>
+      <screen>set QPID_WORK=S:\qpidwork</screen>
+      <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>
+
+  <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>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>
+    <para>Extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para>
+    <programlisting>mkdir /usr/local/qpid
+cd /usr/local/qpid
+tar xvzf qpid-java-broker-&qpidCurrentRelease;.tar.gz></programlisting>
+    <para>The extraction of the Qpid package will have created a directory qpid-broker-x.x</para>
+    <screen>ls -la qpid-broker-&qpidCurrentRelease;/
+total 152
+drwxr-xr-x   8 qpid  qpid    272 25 Jul 23:22 .
+drwxr-xr-x  45 qpid  qpid   1530 30 Sep 10:51 ..
+-rw-r--r--@  1 qpid  qpid  65925 20 Jul 20:10 LICENSE
+-rw-r--r--@  1 qpid  qpid   3858 20 Jul 20:10 NOTICE
+-rw-r--r--@  1 qpid  qpid   1346 20 Jul 20:10 README.txt
+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
+        file and is used for the storage of persistent messages.  The work directory can be set on the
+        command-line (for the lifetime of the current shell), but you will normally want to set
+        the environment variable permanently the user's shell profile file (~/.bash_profile for Bash etc).</para>
+      <screen><![CDATA[export QPID_WORK=/var/qpidwork]]>
+      </screen>
+      <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>
 </chapter>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
index 01b29e390e..4e6dc2cbce 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
@@ -1,4 +1,8 @@
 <?xml version="1.0"?>
+<!DOCTYPE chapter[
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
+]>
 <!--
 
  Licensed to the Apache Software Foundation (ASF) under one
@@ -22,4 +26,65 @@
 
 <chapter id="Java-Broker-Introduction">
   <title>Introduction</title>
+  <para>The Java Broker is a powerful open-source message broker that implements all versions of the
+      <ulink url="http://www.amqp.org"> Advanced Message Queuing Protocol (AMQP)</ulink>. The Java
+    Broker is actually one of two message brokers provided by the <ulink
+      url="http://qpid.apache.org">Apache Qpid project</ulink>: the Java Broker and the C++
+    Broker.</para>
+  <para>This document relates to the Java Broker. The <ulink url="&qpidCppBook;">C++ Broker is
+    described separately</ulink>.</para>
+  <para><emphasis>Headline features</emphasis></para>
+  <itemizedlist mark="circle">
+    <listitem>
+      <para>100% Java implementation - runs on any platform supporting Java 1.6 or higher</para>
+    </listitem>
+    <listitem>
+      <para>Messaging clients support in Java, C++, Python.</para>
+    </listitem>
+    <listitem>
+      <para>JMS 1.1 compliance (Java client).</para>
+    </listitem>
+    <listitem>
+      <para>Transient and persistent message support</para>
+    </listitem>
+    <listitem>
+      <para>Supports for all common messaging patterns (point-to-point, publish/subscribe, fan-out
+        etc).</para>
+    </listitem>
+    <listitem>
+      <para>Transaction support including XA<footnote>
+          <para>XA provided by AMQP 0-10 and above</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>
+    </listitem>
+    <listitem>
+      <para>Pluggable authentication architecture with out-of-the-box support for Kerberos, LDAP,
+        External, and file-based authentication mechanisms.</para>
+    </listitem>
+    <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>
+        </footnote>, and Memory Store</para>
+    </listitem>
+    <listitem>
+      <para>Web based management interface and programmatic management interfaces  via REST and JMX
+        APIs.</para>
+    </listitem>
+    <listitem>
+      <para>SSL support</para>
+    </listitem>
+    <listitem>
+      <para>High availability (HA) support<footnote>
+          <para>HA currently available to users of the BDB-store only</para>
+        </footnote></para>
+    </listitem>
+  </itemizedlist>
 </chapter>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
index 75afc58e4e..471d73f283 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE urls [
-<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+<!DOCTYPE entities [
+<!ENTITY %  entities SYSTEM  "commonEntities.xml">
+%entities;
 ]>
 <!--
 
diff --git a/qpid/doc/book/src/java-broker/commonEntities.xml b/qpid/doc/book/src/java-broker/commonEntities.xml
new file mode 100644
index 0000000000..8edcc65da5
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/commonEntities.xml
@@ -0,0 +1,38 @@
+<!--
+
+ 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.
+
+-->
+
+<!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html">
+<!ENTITY qpidProgrammingBook "../../Programming-In-Apache-Qpid/html/">
+<!ENTITY qpidCppBook "../../MQP-Messaging-Broker-CPP-Book/html/">
+
+<!ENTITY qpidCurrentRelease "0.18">
+
+<!-- Oracle javadoc -->
+<!ENTITY oracleJdkDocUrl "http://oracle.com/javase/6/docs/api/">
+<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
+
+<!-- Oracle BDB JE-->
+<!ENTITY oracleJeDownloadUrl "http://www.oracle.com/technetwork/products/berkeleydb/downloads/index.html?ssSourceSiteId=ocomen">
+<!ENTITY oracleBdbProductOverviewUrl "http://www.oracle.com/technetwork/products/berkeleydb/overview/index-093405.html">
+<!ENTITY oracleBdbRepGuideUrl "http://oracle.com/cd/E17277_02/html/ReplicationGuide/">
+<!ENTITY oracleBdbJavaDocUrl "http://docs.oracle.com/cd/E17277_02/html/java/">
+<!ENTITY oracleBdbProductVersion "5.0.58">
+
-- 
cgit v1.2.1