<?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-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, 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>
      <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 the Java Broker.</para>
    </section>
  </section>

  <section role="h2" id="Java-Broker-Installation-Download">
    <title>Download</title>
    <section role="h3" id="Java-Broker-Installation-Download-Release">
      <title>Broker Release</title>
      <para>You can download the latest Java broker 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, 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 work directory used for the persistent message store or the log file (you will choose this
      location later).   For the remainder this example we will assume that location c:\qpid has been chosen.</para>
    <para>Next extract the &windowsBrokerDownloadFileName; package into the directory, using either the zip file handling offered
      by Windows (right click the file and select 'Extract All') or a third party tool of your choice.</para>
    <para>The extraction of the broker package will have created a directory &windowsExtractedBrokerDirName; within c:\qpid</para>
    <screen>
 Directory of c:\qpid\&windowsExtractedBrokerDirName;

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
</screen>
    <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=C:\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 role="h3" id="Java-Broker-Installation-InstallationWindows-OptionalDependencies">
      <title>Optional Dependencies</title>
      <para>The broker has 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, 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 work directory used for the persistent message store or the log file (you will choose this
      location later).   For the remainder this example we will assume that location /usr/local/qpid has been chosen.</para>
    <para>Next extract the &unixBrokerDownloadFileName; package into the directory.</para>
    <programlisting>mkdir /usr/local/qpid
cd /usr/local/qpid
tar xvzf &unixBrokerDownloadFileName;</programlisting>
    <para>The extraction of the broker package will have created a directory &unixExtractedBrokerDirName; within /usr/local/qpid</para>
    <screen>ls -la &unixExtractedBrokerDirName;/
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-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 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>
