You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/06/20 00:15:13 UTC
svn commit: r956304 [8/33] - in /qpid/site/docs/books/0.7: ./
AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html-single/
AMQP-Messaging-Broker-CPP-Book/html-single/images/
AMQP-Messaging-Broker-CPP-Book/html-single/images/jmx_console/ ...
Added: qpid/site/docs/books/0.7/AMQP-Messaging-Broker-Java-Book/html-single/AMQP-Messaging-Broker-Java-Book.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.7/AMQP-Messaging-Broker-Java-Book/html-single/AMQP-Messaging-Broker-Java-Book.html?rev=956304&view=auto
==============================================================================
--- qpid/site/docs/books/0.7/AMQP-Messaging-Broker-Java-Book/html-single/AMQP-Messaging-Broker-Java-Book.html (added)
+++ qpid/site/docs/books/0.7/AMQP-Messaging-Broker-Java-Book/html-single/AMQP-Messaging-Broker-Java-Book.html Sat Jun 19 22:15:03 2010
@@ -0,0 +1,3417 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AMQP Messaging Broker (Implemented in Java)</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AMQP Messaging Broker (Implemented in Java)"><div class="titlepage"><div><div><h1 class="title"><a name="id2282955"></a>AMQP Messaging Broker (Implemented in Java)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id2528294">Introduction</a></span></dt><dt><span class="chapter"><a href="#id2528352">1. General User Guides</a></span></dt><dd><dl><dt><span class="section"><a href="#id2283001">1.
+ Java Broker Feature Guide
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#JavaBrokerFeatureGuide-TheQpidpureJavabrokercurrentlysupportsthefollowingfeatures-3A">1.1.
+ The Qpid pure Java broker currently supports the following
+ features:
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2527609">2.
+ Qpid Java FAQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJavaFAQ-Purpose">2.1. Purpose</a></span></dt></dl></dd><dt><span class="section"><a href="#id2530604">3.
+ Java Environment Variables
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#JavaEnvironmentVariables-SettingQpidEnvironmentVariables">3.1.
+ Setting
+ Qpid Environment Variables
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2530607">4.
+ Qpid Troubleshooting Guide
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F">4.1.
+ I'm getting a java.lang.UnsupportedClassVersionError when I
+ try to start the broker. What does this mean ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F">4.2.
+ I'm having a problem binding to the required host:port at
+ broker startup ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F">4.3.
+ I'm having problems with my classpath. How can I ensure that
+ my classpath is ok ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F">4.4.
+ I can't get the broker to start. How can I diagnose the
+ problem ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F">4.5.
+ When I try to send messages to a queue I'm getting a error as
+ the queue does not exist. What can I do ?
+ </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Qpid-Java-Broker-HowTos">2. How Tos</a></span></dt><dd><dl><dt><span class="section"><a href="#id2528262">1.
+ Add New Users
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#AddNewUsers-AvailablePasswordfileformats">1.1.
+ Available
+ Password file formats
+ </a></span></dt><dt><span class="section"><a href="#AddNewUsers-Dynamicchangestopasswordfiles.">1.2.
+ Dynamic
+ changes to password files.
+ </a></span></dt><dt><span class="section"><a href="#AddNewUsers-HowpasswordfilesandPrincipalDatabasesrelatetoauthenticationmechanisms">1.3.
+ How password files and PrincipalDatabases relate to
+ authentication mechanisms
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2527674">2.
+ Configure ACLs
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureACLs-ConfigureACLs">2.1.
+ Configure ACLs
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528192">3.
+ Configure Java Qpid to use a SSL connection.
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-UsingSSLconnectionwithQpidJava.">3.1.
+ Using SSL connection with Qpid Java.
+ </a></span></dt><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-Setup">3.2.
+ Setup
+ </a></span></dt><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-Performingtheconnection.">3.3.
+ Performing
+ the connection.
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2530096">4.
+ Configure Log4j CompositeRolling Appender
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureLog4jCompositeRollingAppender-HowtoconfiguretheCompositeRollinglog4jAppender">4.1.
+ How to configure the CompositeRolling log4j Appender
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528191">5.
+ Configure the Broker via config.xml
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfiguretheBrokerviaconfig.xml-Brokerconfig.xmlOverview">5.1.
+ Broker config.xml Overview
+ </a></span></dt><dt><span class="section"><a href="#ConfiguretheBrokerviaconfig.xml-QpidVersion">5.2.
+ Qpid
+ Version
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528927">6.
+ Configure the Virtual Hosts via virtualhosts.xml
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfiguretheVirtualHostsviavirtualhosts.xml-virtualhosts.xmlOverview">6.1.
+ virtualhosts.xml Overview
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528256">7.
+ Debug using log4j
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#Debugusinglog4j-Debuggingwithlog4jconfigurations">7.1.
+ Debugging
+ with log4j configurations
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#How-to-Tune-M3-Java-Broker-Performance">8.
+ How to Tune M3 Java Broker Performance
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-ProblemStatement">8.1.
+ Problem
+ Statement
+ </a></span></dt><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-SuccessfulTuningOptions">8.2.
+ Successful
+ Tuning Options
+ </a></span></dt><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-NextSteps">8.3.
+ Next
+ Steps
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528243">9.
+ Qpid Java Build How To
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJavaBuildHowTo-BuildInstructionsGeneral">9.1.
+ Build
+ Instructions - General
+ </a></span></dt><dt><span class="section"><a href="#QpidJavaBuildHowTo-BuildInstructionsTrunk">9.2.
+ Build
+ Instructions - Trunk
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2532013">10.
+ Use Priority Queues
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#UsePriorityQueues-GeneralInformation">10.1.
+ General
+ Information
+ </a></span></dt><dt><span class="section"><a href="#UsePriorityQueues-DefiningPriorityQueues">10.2.
+ Defining
+ Priority Queues
+ </a></span></dt><dt><span class="section"><a href="#UsePriorityQueues-Clientconfiguration-2Fmessagingmodelforpriorityqueues">10.3.
+ Client configuration/messaging model for priority queues
+ </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Qpid-JMX-Management-Console">3.
+ Qpid JMX Management Console
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJMXManagementConsole-QpidJMXManagementConsole">1. Qpid JMX Management Console </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJMXManagementConsole-Overview">1.1.
+ Overview
+ </a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#QpidJavaBroker-ManagementTools">4. Management Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#id2530497">1.
+ MessageStore Tool
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#MessageStoreTool-MessageStoreTool">1.1.
+ MessageStore Tool
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2535035">2.
+ Qpid Java Broker Management CLI
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJavaBrokerManagementCLI-HowtobuildApacheQpidCLI">2.1.
+ How to
+ build Apache Qpid CLI
+ </a></span></dt></dl></dd></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>1.1. <a href="#id2530697">
+ Command Line Options
+ </a></dt><dt>2.1. <a href="#id2529715"></a></dt><dt>2.2. <a href="#id2532098"></a></dt><dt>2.3. <a href="#id2531954"></a></dt><dt>2.4. <a href="#id2532361"></a></dt><dt>2.5. <a href="#id2532416"></a></dt></dl></div><div class="preface" title="Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="id2528294"></a>Introduction</h2></div></div></div><p>Qpid provides two AMQP messaging brokers:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Implemented in C++ - high performance, low latency, and RDMA support.</p></li><li class="listitem"><p>Implemented in Java - Fully JMS compliant, runs on any Java platform.</p></li></ul></div><p>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <a class="link" href="#">???</a> to see which messaging clients work with each broker.</p><p>This manual contains information
specific to the broker that is implemented in Java.</p></div><div class="chapter" title="Chapter 1. General User Guides"><div class="titlepage"><div><div><h2 class="title"><a name="id2528352"></a>Chapter 1. General User Guides</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2283001">1.
+ Java Broker Feature Guide
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#JavaBrokerFeatureGuide-TheQpidpureJavabrokercurrentlysupportsthefollowingfeatures-3A">1.1.
+ The Qpid pure Java broker currently supports the following
+ features:
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2527609">2.
+ Qpid Java FAQ
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJavaFAQ-Purpose">2.1. Purpose</a></span></dt></dl></dd><dt><span class="section"><a href="#id2530604">3.
+ Java Environment Variables
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#JavaEnvironmentVariables-SettingQpidEnvironmentVariables">3.1.
+ Setting
+ Qpid Environment Variables
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2530607">4.
+ Qpid Troubleshooting Guide
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F">4.1.
+ I'm getting a java.lang.UnsupportedClassVersionError when I
+ try to start the broker. What does this mean ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F">4.2.
+ I'm having a problem binding to the required host:port at
+ broker startup ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F">4.3.
+ I'm having problems with my classpath. How can I ensure that
+ my classpath is ok ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F">4.4.
+ I can't get the broker to start. How can I diagnose the
+ problem ?
+ </a></span></dt><dt><span class="section"><a href="#QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F">4.5.
+ When I try to send messages to a queue I'm getting a error as
+ the queue does not exist. What can I do ?
+ </a></span></dt></dl></dd></dl></div><div class="section" title="1. Java Broker Feature Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2283001"></a>1.
+ Java Broker Feature Guide
+ </h2></div></div></div><div class="section" title="1.1. The Qpid pure Java broker currently supports the following features:"><div class="titlepage"><div><div><h3 class="title"><a name="JavaBrokerFeatureGuide-TheQpidpureJavabrokercurrentlysupportsthefollowingfeatures-3A"></a>1.1.
+ The Qpid pure Java broker currently supports the following
+ features:
+ </h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>All features required by the Sun JMS 1.1 specification, fully
+ tested
+ </p></li><li class="listitem"><p>Transaction support
+ </p></li><li class="listitem"><p>Persistence using a pluggable layer
+ </p></li><li class="listitem"><p>Pluggable security using SASL
+ </p></li><li class="listitem"><p>Management using JMX and an Eclipse Management Console
+ application
+ </p></li><li class="listitem"><p>High performance header-based routing for messages
+ </p></li><li class="listitem"><p>Message Priorities
+ </p></li><li class="listitem"><p>Configurable logging and log archiving
+ </p></li><li class="listitem"><p>Threshold alerting
+ </p></li><li class="listitem"><p>ACLs
+ </p></li><li class="listitem"><p>Extensively tested on each release, including performance
+ & reliability testing
+ </p></li><li class="listitem"><p>Automatic client failover using configurable connection
+ properties
+ </p></li><li class="listitem"><p>Durable Queues/Subscriptions
+ </p></li></ul></div><div class="section" title="1.1.1. Upcoming features:"><div class="titlepage"><div><div><h4 class="title"><a name="JavaBrokerFeatureGuide-Upcomingfeatures-3A"></a>1.1.1.
+ Upcoming
+ features:
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Flow To Disk
+ </p></li><li class="listitem"><p>IP Whitelist
+ </p></li><li class="listitem"><p>AMQP 0-10 Support (for interoperability)
+ </p></li></ul></div></div></div></div><div class="section" title="2. Qpid Java FAQ"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2527609"></a>2.
+ Qpid Java FAQ
+ </h2></div></div></div><div class="section" title="2.1. Purpose"><div class="titlepage"><div><div><h3 class="title"><a name="QpidJavaFAQ-Purpose"></a>2.1. Purpose</h3></div></div></div><p>
+ Here are a list of commonly asked questions and answers. Click on
+ the the bolded questions for the answer to unfold. If you have
+ any questions which are not on this list, please email our
+ qpid-user list.
+ </p><div class="section" title="2.1.1. What is Qpid ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-WhatisQpid-3F"></a>2.1.1.
+ What is Qpid ?
+ </h4></div></div></div><p>
+ The java implementation of Qpid is a pure Java message broker
+ that implements the AMQP protocol. Essentially, Qpid is a robust,
+ performant middleware component that can handle your messaging
+ traffic.
+ </p><p>
+ It currently supports the following features:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>High performance header-based routing for messages
+ </p></li><li class="listitem"><p>All features required by the JMS 1.1 specification. Qpid
+ passes all tests in the Sun JMS compliance test suite
+ </p></li><li class="listitem"><p>Transaction support
+ </p></li><li class="listitem"><p>Persistence using the high performance Berkeley DB Java
+ Edition. The persistence layer is also pluggable should an
+ alternative implementation be required. The BDB store is
+ available from the <a class="xref" href="#">???</a> page
+ </p></li><li class="listitem"><p>Pluggable security using SASL. Any Java SASL provider can be
+ used
+ </p></li><li class="listitem"><p>Management using JMX and a custom management console built
+ using Eclipse RCP
+ </p></li><li class="listitem"><p>Naturally, interoperability with other clients including the
+ Qpid .NET, Python, Ruby and C++ implementations
+ </p></li></ul></div></div><div class="section" title="2.1.2. Why am I getting a ConfigurationException at broker startup ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-WhyamIgettingaConfigurationExceptionatbrokerstartup-3F"></a>2.1.2.
+ Why am I getting a ConfigurationException at broker startup ?
+ </h4></div></div></div><div class="section" title="2.1.2.1. InvocationTargetException"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-InvocationTargetException"></a>2.1.2.1.
+ InvocationTargetException
+ </h5></div></div></div><p>
+ If you get a java.lang.reflect.InvocationTargetException on
+ startup, wrapped as ConfigurationException like this:
+ </p><pre class="programlisting">
+Error configuring message broker: org.apache.commons.configuration.ConfigurationException: java.lang.reflect.InvocationTargetException
+2008-09-26 15:14:56,529 ERROR [main] server.Main (Main.java:206) - Error configuring message broker: org.apache.commons.configuration.ConfigurationException: java.lang.reflect.InvocationTargetException
+org.apache.commons.configuration.ConfigurationException: java.lang.reflect.InvocationTargetException
+at org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager.initialisePrincipalDatabase(ConfigurationFilePrincipalDatabaseManager.java:158)
+at org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager.initialisePrincipalDatabases(ConfigurationFilePrincipalDatabaseManager.java:87)
+at org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager.<init>(ConfigurationFilePrincipalDatabaseManager.java:56)
+at org.apache.qpid.server.registry.ConfigurationFileApplicationRegistry.initialise(ConfigurationFileApplicationRegistry.java:117)
+at org.apache.qpid.server.registry.ApplicationRegistry.initialise(ApplicationRegistry.java:79)
+at org.apache.qpid.server.registry.ApplicationRegistry.initialise(ApplicationRegistry.java:67)
+at org.apache.qpid.server.Main.startup(Main.java:260)
+at org.apache.qpid.server.Main.execute(Main.java:196)
+at org.apache.qpid.server.Main.<init>(Main.java:96)
+at org.apache.qpid.server.Main.main(Main.java:454)
+at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+at java.lang.reflect.Method.invoke(Method.java:597)
+at com.intellij.rt.execution.application.AppMain.main(AppMain.java:90)
+Caused by: java.lang.reflect.InvocationTargetException
+at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+at java.lang.reflect.Method.invoke(Method.java:597)
+at org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager.initialisePrincipalDatabase(ConfigurationFilePrincipalDatabaseManager.java:148)
+</pre><p>
+ .. then it means you have a missing password file.
+ </p><p>
+ You need to create a password file for your deployment and update
+ your config.xml to reflect the location of the password file for
+ your instance.
+ </p><p>
+ The config.xml can be a little confusing in terms of element
+ names and file names for passwords.
+ </p><p>
+ To do this, you need to edit the passwordDir element for the
+ broker, which may have a comment to that effect:
+ </p><pre class="programlisting">
+<passwordDir><!-- Change to the location --></passwordDir>
+</pre><p>
+ The file should be named passwd by default but if you want to you
+ can change this by editing this element:
+ </p><pre class="programlisting">
+<value>${passwordDir}/passwd</value>
+</pre></div><div class="section" title="2.1.2.2. Cannot locate configuration source null/virtualhosts.xml"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-Cannotlocateconfigurationsourcenull-2Fvirtualhosts.xml"></a>2.1.2.2.
+ Cannot locate configuration source null/virtualhosts.xml
+ </h5></div></div></div><p>
+ If you get this message, wrapped inside a ConfigurationException
+ then you've come across a known issue, see JIRA <a class="xref" href="#">???</a>
+ </p><p>
+ The work around is to use a qualified path as the parameter value
+ for your -c option, rather than (as you migth be) starting the
+ broker from your installed etc directory. Even going up one level
+ and using a path relative to your £QPID_HOME directory
+ would sort this e.g qpid-server -c ./etc/myconfig.xml
+ </p></div></div><div class="section" title="2.1.3. How do I run the Qpid broker ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIruntheQpidbroker-3F"></a>2.1.3.
+ How do I run
+ the Qpid broker ?
+ </h4></div></div></div><p>
+ The broker comes with a script for unix/linux/cygwin called
+ qpid-server, which can be found in the bin directory of the
+ installed package. This command can be executed without any
+ paramters and will then use the default configuration file
+ provided on install.
+ </p><p>
+ For the Windows OS, please use qpid-server.bat.
+ </p><p>
+ There's no need to set your classpath for QPID as the scripts
+ take care of that by adding jar's with classpath defining
+ manifest files to your classpath.
+ </p><p>
+ For more information on running the broker please see our
+ <a class="xref" href="#">???</a> page.
+ </p></div><div class="section" title="2.1.4. How can I create a connection using a URL ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIcreateaconnectionusingaURL-3F"></a>2.1.4.
+ How can I
+ create a connection using a URL ?
+ </h4></div></div></div><p>
+ Please see the <a class="xref" href="#">???</a> documentation.
+ </p></div><div class="section" title="2.1.5. How do I represent a JMS Destination string with QPID ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIrepresentaJMSDestinationstringwithQPID-3F"></a>2.1.5.
+ How
+ do I represent a JMS Destination string with QPID ?
+ </h4></div></div></div><div class="section" title="2.1.5.1. Queues"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-Queues"></a>2.1.5.1.
+ Queues
+ </h5></div></div></div><p>
+ A queue can be created in QPID using the following URL format.
+ </p><p>
+ direct://amq.direct/<Destination>/<Queue
+ Name>
+ </p><p>
+ For example:
+ direct://amq.direct/<Destination>/simpleQueue
+ </p><p>
+ Queue names may consist of any mixture of digits, letters, and
+ underscores.
+ </p><p>
+ The <a class="xref" href="#">???</a> is described in more
+ detail on it's own page.
+ </p></div><div class="section" title="2.1.5.2. Topics"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-Topics"></a>2.1.5.2.
+ Topics
+ </h5></div></div></div><p>
+ A topic can be created in QPID using the following URL format.
+ </p><p>
+ topic://amq.topic/<Topic Subscription>/
+ </p><p>
+ The topic subscription may only contain the letters A-Z and a-z
+ and digits 0-9.
+ </p><p>
+ The topic subscription is formed from a series of words that may
+ only contain the letters A-Z and a-z and digits 0-9.
+ The words are delimited by dots. Each dot represents a new level.
+ </p><p>
+ For example: stocks.nyse.ibm
+ </p><p>
+ Wildcards can be used on subscription with the following meaning.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>match a single level
+ # match zero or more levels
+ </p></li></ul></div><p>
+ For example:
+ With two clients
+ 1 - stocks.*.ibm
+ 2 - stocks.#.ibm
+ </p><p>
+ Publishing stocks.nyse.ibm will be received by both
+ clients but stocks.ibm and stocks.world.us.ibm
+ will only be received by client 2.
+ </p><p>
+ The topic currently does not support wild cards.
+ </p></div></div><div class="section" title="2.1.6. How do I connect to the broker using JNDI ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIconnecttothebrokerusingJNDI-3F"></a>2.1.6.
+ How do I
+ connect to the broker using JNDI ?
+ </h4></div></div></div><p>
+ see <a class="xref" href="#">???</a>
+ </p></div><div class="section" title="2.1.7. I'm using Spring and Weblogic - can you help me with the configuration for moving over to Qpid ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-I-27musingSpringandWeblogiccanyouhelpmewiththeconfigurationformovingovertoQpid-3F"></a>2.1.7.
+ I'm using Spring and Weblogic - can you help me with the
+ configuration for moving over to Qpid ?
+ </h4></div></div></div><p>
+ Here is a donated Spring configuration file <a class="ulink" href="http://qpid.apache.org/qpid-java-faq.data/appContext.zip" target="_top">appContext.zip</a>
+ which shows the config for Qpid side by side with
+ Weblogic. HtH !
+ </p></div><div class="section" title="2.1.8. How do I configure the logging level for Qpid ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIconfigurethelogginglevelforQpid-3F"></a>2.1.8.
+ How do
+ I configure the logging level for Qpid ?
+ </h4></div></div></div><p>
+ The system property
+ </p><pre class="programlisting">
+amqj.logging.level
+</pre><p>
+ can be used to configure the logging level.
+ For the broker, you can use the environment variable
+ AMQJ_LOGGING_LEVEL which is picked up by the qpid-run script
+ (called by qpid-server to start the broker) at runtime.
+ </p><p>
+ For client code that you've written, simply pass in a system
+ property to your command line to set it to the level you'd like
+ i.e.
+ </p><pre class="programlisting">
+-Damqj.logging.level=INFO
+</pre><p>
+ The log level for the broker defaults to INFO if the env variable
+ is not set, but you may find that your log4j properties affect
+ this. Setting the property noted above should address this.
+ </p></div><div class="section" title="2.1.9. How can I configure my application to use Qpid client logging?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIconfiguremyapplicationtouseQpidclientlogging-3F"></a>2.1.9.
+ How can I configure my application to use Qpid client
+ logging?
+ </h4></div></div></div><p>
+ If you don't already have a logging implementation in your
+ classpath you should add slf4-log4j12-1.4.0.jar and
+ log4j-1.2.12.jar.
+ </p></div><div class="section" title="2.1.10. How can I configure the broker ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIconfigurethebroker-3F"></a>2.1.10.
+ How can I
+ configure the broker ?
+ </h4></div></div></div><p>
+ The broker configuration is contained in the
+ <installed-dir>/etc/config.xml file. You can copy and edit
+ this file and then specify your own configuration file as a
+ parameter to the startup script using the -c flag i.e.
+ qpid-server -c <your_config_file's_path>
+ </p><p>
+ For more detailed information on configuration, please see
+ <a class="xref" href="#">???</a>
+ </p><p>
+
+ </p></div><div class="section" title="2.1.11. What ports does the broker use?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Whatportsdoesthebrokeruse"></a>2.1.11.
+ What ports
+ does the broker use?
+ </h4></div></div></div><p>
+ The broker defaults to use port 5672 at startup for AMQP
+ traffic.
+ If the management interface is enabled it starts on port 8999 by
+ default.
+ </p><p>
+ The JMX management interface actually requires 2 ports to
+ operate, the second of which is indicated to the client
+ application during connection initiation to the main (default:
+ 8999) port. Previously this second port has been chosen at random
+ during broker startup, however since Qpid 0.5 this has been fixed
+ to a port 100 higher than the main port(ie Default:9099) in order
+ to ease firewall navigation.
+ </p></div><div class="section" title="2.1.12. How can I change the port the broker uses at runtime ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIchangetheportthebrokerusesatruntime-3F"></a>2.1.12.
+ How
+ can I change the port the broker uses at runtime ?
+ </h4></div></div></div><p>
+ The broker defaults to use port 5672 at startup for AMQP
+ traffic.
+ The broker also uses port 8999 for the JMX Management interface.
+ </p><p>
+ To change the AMQP traffic port use the -p flag at startup. To
+ change the management port use -m
+ i.e. qpid-server -p <port_number_to_use> -m
+ <port_number_to_use>
+ </p><p>
+ Use this to get round any issues on your host server with port
+ 5672/8999 being in use/unavailable.
+ </p><p>
+ For additional details on what ports the broker uses see <a class="xref" href="#QpidJavaFAQ-Whatportsdoesthebrokeruse" title="2.1.11. What ports does the broker use?">Section 2.1.11, “
+ What ports
+ does the broker use?
+ ”</a> FAQ
+ entry.
+ For more detailed information on configuration, please see
+ <a class="xref" href="#">???</a>
+ </p></div><div class="section" title="2.1.13. What command line options can I pass into the qpid-server script ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-WhatcommandlineoptionscanIpassintotheqpidserverscript-3F"></a>2.1.13.
+ What command line options can I pass into the qpid-server
+ script ?
+ </h4></div></div></div><p>
+ The following command line options are available:
+ </p><p>
+ The following options are available:
+ </p><div class="table"><a name="id2530697"></a><p class="title"><b>Table 1.1.
+ Command Line Options
+ </b></p><div class="table-contents"><table summary="
+ Command Line Options
+ " border="1"><colgroup><col><col><col></colgroup><tbody><tr><td>
+ Option
+ </td><td>
+ Long Option
+ </td><td>
+ Description
+ </td></tr><tr><td>
+ b
+ </td><td>
+ bind
+ </td><td>
+ Bind to the specified address overriding any value in the
+ config file
+ </td></tr><tr><td>
+ c
+ </td><td>
+ config
+ </td><td>
+ Use the given configuration file
+ </td></tr><tr><td>
+ h
+ </td><td>
+ help
+ </td><td>
+ Prints list of options
+ </td></tr><tr><td>
+ l
+ </td><td>
+ logconfig
+ </td><td>
+ Use the specified log4j.xml file rather than that in the
+ etc directory
+ </td></tr><tr><td>
+ m
+ </td><td>
+ mport
+ </td><td>
+ Specify port to listen on for the JMX Management. Overrides
+ value in config file
+ </td></tr><tr><td>
+ p
+ </td><td>
+ port
+ </td><td>
+ Specify port to listen on. Overrides value in config file
+ </td></tr><tr><td>
+ v
+ </td><td>
+ version
+ </td><td>
+ Print version information and exit
+ </td></tr><tr><td>
+ w
+ </td><td>
+ logwatch
+ </td><td>
+ Specify interval for checking for logging config changes.
+ Zero means no checking
+ </td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="2.1.14. How do I authenticate with the broker ? What user id & password should I use ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIauthenticatewiththebroker-3FWhatuserid-26passwordshouldIuse-3F"></a>2.1.14.
+ How do I authenticate with the broker ? What user id &
+ password should I use ?
+ </h4></div></div></div><p>
+ You should login as user guest with password guest
+ </p></div><div class="section" title="2.1.15. How do I create queues that will always be instantiated at broker startup ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIcreatequeuesthatwillalwaysbeinstantiatedatbrokerstartup-3F"></a>2.1.15.
+ How do I create queues that will always be instantiated at
+ broker startup ?
+ </h4></div></div></div><p>
+ You can configure queues which will be created at broker startup
+ by tailoring a copy of the virtualhosts.xml file provided in the
+ installed qpid-version/etc directory.
+ </p><p>
+ So, if you're using a queue called 'devqueue' you can ensure that
+ it is created at startup by using an entry something like this:
+ </p><pre class="programlisting">
+<virtualhosts>
+ <default>test</default>
+ <virtualhost>
+ <name>test</name>
+ <test>
+ <queue>
+ <name>devqueue</name>
+ <devqueue>
+ <exchange>amq.direct</exchange>
+ <maximumQueueDepth>4235264</maximumQueueDepth> <!-- 4Mb -->
+ <maximumMessageSize>2117632</maximumMessageSize> <!-- 2Mb -->
+ <maximumMessageAge>600000</maximumMessageAge> <!-- 10 mins -->
+ </devqueue>
+ </queue>
+ </test>
+ </virtualhost>
+</virtualhosts>
+</pre><p>
+ Note that the name (in thie example above the name is 'test')
+ element should match the virtualhost that you're using to create
+ connections to the broker. This is effectively a namespace used
+ to prevent queue name clashes etc. You can also see that we've
+ set the 'test' virtual host to be the default for any connections
+ which do not specify a virtual host (in the <default> tag).
+ </p><p>
+ You can amend the config.xml to point at a different
+ virtualhosts.xml file by editing the <virtualhosts/>
+ element.
+ </p><p>
+ So, for example, you could tell the broker to use a file in your
+ home directory by creating a new config.xml file with the
+ following entry:
+ </p><p>
+ <virtualhosts>/home/myhomedir/virtualhosts.xml</virtualhosts>
+ </p><p>
+ You can then pass this amended config.xml into the broker at
+ startup using the -c flag i.e.
+ qpid-server -c <path>/config.xml
+ </p></div><div class="section" title="2.1.16. How do I create queues at runtime?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIcreatequeuesatruntime-3F"></a>2.1.16.
+ How do I
+ create queues at runtime?
+ </h4></div></div></div><p>
+ Queues can be dynamically created at runtime by creating a
+ consumer for them. After they have been created and bound (which
+ happens automatically when a JMS Consumer is created) a publisher
+ can send messages to them.
+ </p></div><div class="section" title="2.1.17. How do I tune the broker?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoItunethebroker-3F"></a>2.1.17.
+ How do I tune
+ the broker?
+ </h4></div></div></div><p>
+ There are a number of tuning options available, please see the
+ <a class="xref" href="#How-to-Tune-M3-Java-Broker-Performance" title="8. How to Tune M3 Java Broker Performance">Section 8, “
+ How to Tune M3 Java Broker Performance
+ ”</a> page for more information.
+ </p></div><div class="section" title="2.1.18. Where do undeliverable messages end up ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Wheredoundeliverablemessagesendup-3F"></a>2.1.18.
+ Where do
+ undeliverable messages end up ?
+ </h4></div></div></div><p>
+ At present, messages with an invalid routing key will be returned
+ to the sender. If you register an exception listener for your
+ publisher (easiest to do by making your publisher implement the
+ ExceptionListener interface and coding the onException method)
+ you'll see that you end up in onException in this case. You can
+ expect to be catching a subclass of
+ org.apache.qpid.AMQUndeliveredException.
+ </p></div><div class="section" title="2.1.19. Can I configure the name of the Qpid broker log file at runtime ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-CanIconfigurethenameoftheQpidbrokerlogfileatruntime-3F"></a>2.1.19.
+ Can I configure the name of the Qpid broker log file at
+ runtime ?
+ </h4></div></div></div><p>
+ If you simply start the Qpid broker using the default
+ configuration, then the log file is written to
+ $QPID_WORK/log/qpid.log
+ </p><p>
+ This is not ideal if you want to run several instances from one
+ install, or acrhive logs to a shared drive from several hosts.
+ </p><p>
+ To make life easier, there are two optional ways to configure the
+ naming convention used for the broker log.
+ </p><div class="section" title="2.1.19.1. Setting a prefix or suffix"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-Settingaprefixorsuffix"></a>2.1.19.1.
+ Setting a prefix
+ or suffix
+ </h5></div></div></div><p>
+ Users should set the following environment variables before
+ running qpid-server:
+ </p><p>
+ QPID_LOG_PREFIX - will prefix the log file name with the
+ specified value e.g. if you set this value to be the name of your
+ host (for example) it could look something like host123qpid.log
+ </p><p>
+ QPID_LOG_SUFFIX - will suffix the file name with the specified
+ value e.g. if you set this value to be the name of your
+ application (for example) if could look something like
+ qpidMyApp.log
+ </p></div><div class="section" title="2.1.19.2. Including the PID"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJavaFAQ-IncludingthePID"></a>2.1.19.2.
+ Including the PID
+ </h5></div></div></div><p>
+ Setting either of these variables to the special value PID will
+ introduce the process id of the java process into the file name
+ as a prefix or suffix as specified**
+ </p></div></div><div class="section" title="2.1.20. My client application appears to have hung?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Myclientapplicationappearstohavehung-3F"></a>2.1.20.
+ My
+ client application appears to have hung?
+ </h4></div></div></div><p>
+ The client code currently has various timeouts scattered
+ throughout the code. These can cause your client to appear like
+ it has hung when it is actually waiting for the timeout ot
+ compelete. One example is when the broker becomes non-responsive,
+ the client code has a hard coded 2 minute timeout that it will
+ wait when closing a connection. These timeouts need to be
+ consolidated and exposed. see <a class="xref" href="#">???</a>
+ </p></div><div class="section" title="2.1.21. How do I contact the Qpid team ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIcontacttheQpidteam-3F"></a>2.1.21.
+ How do I
+ contact the Qpid team ?
+ </h4></div></div></div><p>
+ For general questions, please subscribe to the
+ <a class="ulink" href="mailto:users@qpid.apache.org" target="_top">users@qpid.apache.org</a> mailing list.
+ </p><p>
+ For development questions, please subscribe to the
+ <a class="ulink" href="mailto:dev@qpid.apache.org" target="_top">dev@qpid.apache.org</a> mailing list.
+ </p><p>
+ More details on these lists are available on our <a class="xref" href="#">???</a>
+ page.
+ </p></div><div class="section" title="2.1.22. How can I change a user's password while the broker is up ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIchangeauser-27spasswordwhilethebrokerisup-3F"></a>2.1.22.
+ How can I change a user's password while the broker is up ?
+ </h4></div></div></div><p>
+ You can do this via the <a class="xref" href="#">???</a>. To
+ do this simply log in to the management console as an admin user
+ (you need to have created an admin account in the
+ jmxremote.access file first) and then select the 'UserManagement'
+ mbean. Select the user in the table and click the Set Password
+ button. Alternatively, update the password file and use the
+ management console to reload the file with the button at the
+ bottom of the 'UserManagement' view. In both cases, this will
+ take effect when the user next logs in i.e. will not cause them
+ to be disconnected if they are already connected.
+ </p><p>
+ For more information on the Management Console please see our
+ <a class="xref" href="#Qpid-JMX-Management-Console-User-Guide" title="1.1.5. Qpid JMX Management Console User Guide">Section 1.1.5, “
+ Qpid JMX Management Console User Guide
+ ”</a>
+ </p></div><div class="section" title="2.1.23. How do I know if there is a consumer for a message I am going to send?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIknowifthereisaconsumerforamessageIamgoingtosend-3F"></a>2.1.23.
+ How do I know if there is a consumer for a message I am going
+ to send?
+ </h4></div></div></div><p>
+ Knowing that there is a consumer for a message is quite tricky.
+ That said using the qpid.jms.Session#createProducer with
+ immediate and mandatory set to true will get you part of the way
+ there.
+ </p><p>
+ If you are publishing to a well known queue then immediate will
+ let you know if there is any consumer able to pre-fetch that
+ message at the time you send it. If not it will be returned to
+ you on your connection listener.
+ </p><p>
+ If you are sending to a queue that the consumer creates then the
+ mandatory flag will let you know if they have not yet created
+ that queue.
+ </p><p>
+ These flags will not be able to tell you if the consuming
+ application has received the message and is able to process it.
+ </p></div><div class="section" title="2.1.24. How do I use an InVM Broker for my own tests?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowdoIuseanInVMBrokerformyowntests-3F"></a>2.1.24.
+ How do I
+ use an InVM Broker for my own tests?
+ </h4></div></div></div><p>
+ I would take a look at the testPassiveTTL in
+ <a class="ulink" href="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/systests/src/main/java/org/apache/qpid/server/queue/TimeToLiveTest.java" target="_top">TimeToLiveTest.java</a>
+ </p><p>
+ The setUp and tearDown methods show how to correctly start up a
+ broker for InVM testing. If you write your tests using a file for
+ the JNDI you can then very easily swap between running your tests
+ InVM and against a real broker.
+ </p><p>
+ See our <a class="xref" href="#">???</a> on how to confgure it
+ </p><p>
+ Basically though you just need to set two System Properites:
+ </p><p>
+ java.naming.factory.initial =
+ org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+ java.naming.provider.url = <your JNDI file>
+ </p><p>
+ and call getInitialContext() in your code.
+ </p><p>
+ You will of course need to have the broker libraries on your
+ class path for this to run.
+ </p></div><div class="section" title="2.1.25. How can I inspect the contents of my MessageStore?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-HowcanIinspectthecontentsofmyMessageStore-3F"></a>2.1.25.
+ How
+ can I inspect the contents of my MessageStore?
+ </h4></div></div></div><p>
+ There are two possibilities here:
+ </p><p>
+ 1) The management console can be used to interogate an active
+ broker and browse the contents of a queue.See the <a class="xref" href="#">???</a>
+ page for further details.
+ </p><p>
+ 2) The <a class="xref" href="#">???</a> can be used to inspect
+ the contents of a persistent message store. Note: this can
+ currently only be used when the broker is offline.
+ </p></div><div class="section" title="2.1.26. Why are my transient messages being so slow?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Whyaremytransientmessagesbeingsoslow-3F"></a>2.1.26.
+ Why are
+ my transient messages being so slow?
+ </h4></div></div></div><p>
+ You should check that you aren't sending persistent messages,
+ this is the default. If you want to send transient messages you
+ must explicitly set this option when instantiating your
+ MessageProducer or on the send() method.
+ </p></div><div class="section" title="2.1.27. Why does my producer fill up the broker with messages?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Whydoesmyproducerfillupthebrokerwithmessages-3F"></a>2.1.27.
+ Why
+ does my producer fill up the broker with messages?
+ </h4></div></div></div><p>
+ The Java broker does not currently implement producer flow
+ control. Publishes are currently asynchronous, so there is no
+ ability to rate limit this automatically. While this is something
+ which will be addressed in the future, it is currently up to
+ applications to ensure that they do not publish faster than the
+ messages are being consumed for signifcant periods of time.
+ </p></div><div class="section" title="2.1.28. The broker keeps throwing an OutOfMemory exception?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-ThebrokerkeepsthrowinganOutOfMemoryexception-3F"></a>2.1.28.
+ The
+ broker keeps throwing an OutOfMemory exception?
+ </h4></div></div></div><p>
+ The broker can no longer store any more messages in memory. This
+ is particular evident if you are using the MemoryMessageStore. To
+ alleviate this issue you should ensure that your clients are
+ consuming all the messages from the broker.
+ </p><p>
+ You may also want to increase the memory allowance to the broker
+ though this will only delay the exception if you are publishing
+ messages faster than you are consuming. See <a class="xref" href="#">???</a> for
+ details of changing the memory settings.
+ </p></div><div class="section" title="2.1.29. Why am I getting a broker side exception when I try to publish to a queue or a topic ?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-WhyamIgettingabrokersideexceptionwhenItrytopublishtoaqueueoratopic-3F"></a>2.1.29.
+ Why am I getting a broker side exception when I try to
+ publish to a queue or a topic ?
+ </h4></div></div></div><p>
+ If you get a stack trace like this when you try to publish, then
+ you may have typo'd the exchange type in your queue or topic
+ declaration. Open your virtualhosts.xml and check that the
+ </p><pre class="programlisting">
+<exchange>amq.direct</exchange>
+</pre><pre class="programlisting">
+2009-01-12 15:26:27,957 ERROR [pool-11-thread-2] protocol.AMQMinaProtocolSession (AMQMinaProtocolSession.java:365) - Unexpected exception while processing frame. Closing connection.
+java.lang.NullPointerException
+ at org.apache.qpid.server.security.access.PrincipalPermissions.authorise(PrincipalPermissions.java:398)
+ at org.apache.qpid.server.security.access.plugins.SimpleXML.authorise(SimpleXML.java:302)
+ at org.apache.qpid.server.handler.QueueBindHandler.methodReceived(QueueBindHandler.java:111)
+ at org.apache.qpid.server.handler.ServerMethodDispatcherImpl.dispatchQueueBind(ServerMethodDispatcherImpl.java:498)
+ at org.apache.qpid.framing.amqp_8_0.QueueBindBodyImpl.execute(QueueBindBodyImpl.java:167)
+ at org.apache.qpid.server.state.AMQStateManager.methodReceived(AMQStateManager.java:204)
+ at org.apache.qpid.server.protocol.AMQMinaProtocolSession.methodFrameReceived(AMQMinaProtocolSession.java:295)
+ at org.apache.qpid.framing.AMQMethodBodyImpl.handle(AMQMethodBodyImpl.java:93)
+ at org.apache.qpid.server.protocol.AMQMinaProtocolSession.frameReceived(AMQMinaProtocolSession.java:235)
+ at org.apache.qpid.server.protocol.AMQMinaProtocolSession.dataBlockReceived(AMQMinaProtocolSession.java:191)
+ at org.apache.qpid.server.protocol.AMQPFastProtocolHandler.messageReceived(AMQPFastProtocolHandler.java:244)
+ at org.apache.mina.common.support.AbstractIoFilterChain$TailFilter.messageReceived(AbstractIoFilterChain.java:703)
+ at org.apache.mina.common.support.AbstractIoFilterChain.callNextMessageReceived(AbstractIoFilterChain.java:362)
+ at org.apache.mina.common.support.AbstractIoFilterChain.access$1200(AbstractIoFilterChain.java:54)
+ at org.apache.mina.common.support.AbstractIoFilterChain$EntryImpl$1.messageReceived(AbstractIoFilterChain.java:800)
+ at org.apache.qpid.pool.PoolingFilter.messageReceived(PoolingFilter.java:371)
+ at org.apache.mina.filter.ReferenceCountingIoFilter.messageReceived(ReferenceCountingIoFilter.java:96)
+ at org.apache.mina.common.support.AbstractIoFilterChain.callNextMessageReceived(AbstractIoFilterChain.java:362)
+ at org.apache.mina.common.support.AbstractIoFilterChain.access$1200(AbstractIoFilterChain.java:54)
+ at org.apache.mina.common.support.AbstractIoFilterChain$EntryImpl$1.messageReceived(AbstractIoFilterChain.java:800)
+ at org.apache.mina.filter.codec.support.SimpleProtocolDecoderOutput.flush(SimpleProtocolDecoderOutput.java:60)
+ at org.apache.mina.filter.codec.QpidProtocolCodecFilter.messageReceived(QpidProtocolCodecFilter.java:174)
+ at org.apache.mina.common.support.AbstractIoFilterChain.callNextMessageReceived(AbstractIoFilterChain.java:362)
+ at org.apache.mina.common.support.AbstractIoFilterChain.access$1200(AbstractIoFilterChain.java:54)
+ at org.apache.mina.common.support.AbstractIoFilterChain$EntryImpl$1.messageReceived(AbstractIoFilterChain.java:800)
+ at org.apache.qpid.pool.Event$ReceivedEvent.process(Event.java:86)
+ at org.apache.qpid.pool.Job.processAll(Job.java:110)
+ at org.apache.qpid.pool.Job.run(Job.java:149)
+ at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:885)
+ at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:907)
+ at java.lang.Thread.run(Thread.java:619)
+</pre></div><div class="section" title="2.1.30. Why is there a lot of AnonymousIoService threads"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-WhyistherealotofAnonymousIoServicethreads"></a>2.1.30.
+ Why
+ is there a lot of AnonymousIoService threads
+ </h4></div></div></div><p>
+ These threads are part of the thread pool used by Mina to process
+ the socket. In the future we may provide tuning guidelines but at
+ this point we have seen no performance implications from the
+ current configuration. As the threads are part of a pool they
+ should remain inactive until required.
+ </p></div><div class="section" title='2.1.31. "unable to certify the provided SSL certificate using the current SSL trust store" when connecting the Management Console to the broker.'><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ--22unabletocertifytheprovidedSSLcertificateusingthecurrentSSLtruststore-22whenconnectingtheManagementConsoletothebroker."></a>2.1.31.
+ "unable to certify the provided SSL certificate using the
+ current SSL trust store" when connecting the Management Console
+ to the broker.
+ </h4></div></div></div><p>
+ You have not configured the console's SSL trust store properly,
+ see <a class="xref" href="#">???</a> for
+ more details.
+ </p></div><div class="section" title="2.1.32. Client keeps throwing 'Server did not respond in a timely fashion' [error code 408: Request Timeout]."><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-Clientkeepsthrowing-27Serverdidnotrespondinatimelyfashion-27-5Cerrorcode408-3ARequestTimeout-5C."></a>2.1.32.
+ Client keeps throwing 'Server did not respond in a timely
+ fashion' [error code 408: Request Timeout].
+ </h4></div></div></div><p>
+ Certain operations wait for a response from the Server. One such
+ operations is commit. If the server does not respond to the
+ commit request within a set time a Request Timeout [error code:
+ 408] exception is thrown (Server did not respond in a timely
+ fashion). This is to ensure that a server that has hung does not
+ cause the client process to be come unresponsive.
+ </p><p>
+ However, it is possible that the server just needs a long time to
+ process a give request. For example, sending a large persistent
+ message when using a persistent store will take some time to a)
+ Transfer accross the network and b) to be fully written to disk.
+ </p><p>
+ These situations require that the default timeout value be
+ increased. A cilent <a class="xref" href="#">???</a> 'amqj.default_syncwrite_timeout' can be set
+ on the client to increase the wait time. The default in 0.5 is
+ 30000 (30s).
+ </p></div><div class="section" title="2.1.33. Can a use TCP_KEEPALIVE or AMQP heartbeating to keep my connection open?"><div class="titlepage"><div><div><h4 class="title"><a name="QpidJavaFAQ-CanauseTCPKEEPALIVEorAMQPheartbeatingtokeepmyconnectionopen-3F"></a>2.1.33.
+ Can a use TCP_KEEPALIVE or AMQP heartbeating to keep my
+ connection open?
+ </h4></div></div></div><p>
+ See <a class="xref" href="#">???</a>
+ </p></div></div></div><div class="section" title="3. Java Environment Variables"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2530604"></a>3.
+ Java Environment Variables
+ </h2></div></div></div><div class="section" title="3.1. Setting Qpid Environment Variables"><div class="titlepage"><div><div><h3 class="title"><a name="JavaEnvironmentVariables-SettingQpidEnvironmentVariables"></a>3.1.
+ Setting
+ Qpid Environment Variables
+ </h3></div></div></div><div class="section" title="3.1.1. Qpid Deployment Path Variables"><div class="titlepage"><div><div><h4 class="title"><a name="JavaEnvironmentVariables-QpidDeploymentPathVariables"></a>3.1.1.
+ Qpid
+ Deployment Path Variables
+ </h4></div></div></div><p>
+ There are two main Qpid environment variables which are required
+ to be set for Qpid deployments, QPID_HOME and QPID_WORK.
+ </p><p>
+ QPID_HOME - This variable is used to tell the Qpid broker where
+ it's installed home is, which is in turn used to find dependency
+ JARs which Qpid uses.
+ </p><p>
+ QPID_WORK - This variable is used by Qpid when creating all
+ 'writeable' directories that it uses. This includes the log
+ directory and the storage location for any BDB instances in use
+ by your deployment (if you're using persistence with BDB). If you
+ do not set this variable, then the broker will default (in the
+ qpid-server script) to use the current user's homedir as the root
+ directory for creating the writeable locations that it uses.
+ </p></div><div class="section" title="3.1.2. Setting Max Memory for the broker"><div class="titlepage"><div><div><h4 class="title"><a name="JavaEnvironmentVariables-SettingMaxMemoryforthebroker"></a>3.1.2.
+ Setting
+ Max Memory for the broker
+ </h4></div></div></div><p>
+ If you simply start the Qpid broker, it will default to use a
+ -Xmx setting of 1024M for the broker JVM. However, we would
+ recommend that you make the maximum -Xmx heap size available, if
+ possible, of 3Gb (for 32-bit platforms).
+ </p><p>
+ You can control the memory setting for your broker by setting the
+ QPID_JAVA_MEM variable before starting the broker e.g. -Xmx3668m
+ . Enclose your value within quotes if you also specify a -Xms
+ value. The value in use is echo'd by the qpid-server script on
+ startup.
+ </p></div></div></div><div class="section" title="4. Qpid Troubleshooting Guide"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2530607"></a>4.
+ Qpid Troubleshooting Guide
+ </h2></div></div></div><div class="section" title="4.1. I'm getting a java.lang.UnsupportedClassVersionError when I try to start the broker. What does this mean ?"><div class="titlepage"><div><div><h3 class="title"><a name="QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F"></a>4.1.
+ I'm getting a java.lang.UnsupportedClassVersionError when I
+ try to start the broker. What does this mean ?
+ </h3></div></div></div><p>
+ The QPID broker requires JDK 1.5 or later. If you're seeing this
+ exception you don't have that version in your path. Set JAVA_HOME
+ to the correct version and ensure the bin directory is on your
+ path.
+ </p><p>
+ java.lang.UnsupportedClassVersionError:
+ org/apache/qpid/server/Main (Unsupported major.minor version
+ 49.0)
+ at
+ java.lang.ClassLoader.defineClass(Ljava.lang.String;[BIILjava.security.ProtectionDomain;)Ljava.lang.Class;(Unknown
+ Source)
+ at
+ java.security.SecureClassLoader.defineClass(Ljava.lang.String;[BIILjava.security.CodeSource;)Ljava.lang.Class;(SecureClassLoader.java:123)
+
+ at
+ java.net.URLClassLoader.defineClass(Ljava.lang.String;Lsun.misc.Resource;)Ljava.lang.Class;(URLClassLoader.java:251)
+
+ at
+ java.net.URLClassLoader.access$100(Ljava.net.URLClassLoader;Ljava.lang.String;Lsun.misc.Resource;)Ljava.lang.Class;(URLClassLoader.java:55)
+
+ at java.net.URLClassLoader$1.run()Ljava.lang.Object;
+ (URLClassLoader.java:194)
+ at
+ jrockit.vm.AccessController.do_privileged_exc(Ljava.security.PrivilegedExceptionAction;Ljava.security.AccessControlContext;I)Ljava.lang.Object;(Unknown
+ Source)
+ at
+ jrockit.vm.AccessController.doPrivileged(Ljava.security.PrivilegedExceptionAction;Ljava.security.AccessControlContext;)Ljava.lang.Object;(Unknown
+ Source)
+ at
+ java.net.URLClassLoader.findClass(Ljava.lang.String;)Ljava.lang.Class;(URLClassLoader.java:187)
+
+ at
+ java.lang.ClassLoader.loadClass(Ljava.lang.String;Z)Ljava.lang.Class;
+ (Unknown Source)
+ at
+ sun.misc.Launcher$AppClassLoader.loadClass(Ljava.lang.String;Z)Ljava.lang.Class;(Launcher.java:274)
+
+ at
+ java.lang.ClassLoader.loadClass(Ljava.lang.String;)Ljava.lang.Class;
+
+ (Unknown Source)
+ at
+ java.lang.ClassLoader.loadClassFromNative(II)Ljava.lang.Class;
+
+ (Unknown Source)
+ </p></div><div class="section" title="4.2. I'm having a problem binding to the required host:port at broker startup ?"><div class="titlepage"><div><div><h3 class="title"><a name="QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F"></a>4.2.
+ I'm having a problem binding to the required host:port at
+ broker startup ?
+ </h3></div></div></div><p>
+ This error probably indicates that another process is using the
+ port you the broker is trying to listen on. If you haven't
+ amended the default configuration this will be 5672. To check
+ what process is using the port you can use 'netstat -an |grep
+ 5672'.
+ </p><p>
+ To change the port your broker uses, either edit the config.xml
+ you are using. You can specify an alternative config.xml from the
+ one provided in /etc by using the -c flag i.e. qpid-server -c
+ <my config file path>.
+ </p><p>
+ You can also amend the port more simply using the -p option to
+ qpid-server i.e. qpid-server -p <my port number'
+ </p></div><div class="section" title="4.3. I'm having problems with my classpath. How can I ensure that my classpath is ok ?"><div class="titlepage"><div><div><h3 class="title"><a name="QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F"></a>4.3.
+ I'm having problems with my classpath. How can I ensure that
+ my classpath is ok ?
+ </h3></div></div></div><p>
+ When you are running the broker the classpath is taken care of
+ for you, via the manifest entries in the launch jars that the
+ qpid-server configuration file adds to the classpath.
+ </p><p>
+ However, if you are running your own client code and experiencing
+ classspath errors you need to ensure that the client-launch.jar
+ from the installed Qpid lib directory is on your classpath. The
+ manifest for this jar includes the common-launch.jar, and thus
+ all the code you need to run a client application.
+ </p></div><div class="section" title="4.4. I can't get the broker to start. How can I diagnose the problem ?"><div class="titlepage"><div><div><h3 class="title"><a name="QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F"></a>4.4.
+ I can't get the broker to start. How can I diagnose the
+ problem ?
+ </h3></div></div></div><p>
+ Firstly have a look at the broker log file - either on stdout or
+ in $QPID_WORK/log/qpid.log or in $HOME/log/qpid.log if you
+ haven't set QPID_WORK.
+ </p><p>
+ You should see the problem logged in here via log4j and a stack
+ trace. Have a look at the other entries on this page for common
+ problems. If the log file includes a line like:
+ </p><p>
+ "2006-10-13 09:58:14,672 INFO [main] server.Main (Main.java:343)
+ - Qpid.AMQP listening on non-SSL address 0.0.0.0/0.0.0.0:5672"
+ </p><p>
+ ... then you know the broker started up. If not, then it didn't.
+ </p></div><div class="section" title="4.5. When I try to send messages to a queue I'm getting a error as the queue does not exist. What can I do ?"><div class="titlepage"><div><div><h3 class="title"><a name="QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F"></a>4.5.
+ When I try to send messages to a queue I'm getting a error as
+ the queue does not exist. What can I do ?
+ </h3></div></div></div><p>
+ In Qpid queues need a consumer before they really exist, unless
+ you have used the virtualhosts.xml file to specify queues which
+ should always be created at broker startup. If you don't want to
+ use this config, then simply ensure that you consume first from
+ queue before staring to publish to it. See the entry on our
+ <a class="xref" href="#">???</a> for more details of using the virtualhosts.xml route.
+ </p></div></div></div><div class="chapter" title="Chapter 2. How Tos"><div class="titlepage"><div><div><h2 class="title"><a name="Qpid-Java-Broker-HowTos"></a>Chapter 2. How Tos</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2528262">1.
+ Add New Users
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#AddNewUsers-AvailablePasswordfileformats">1.1.
+ Available
+ Password file formats
+ </a></span></dt><dt><span class="section"><a href="#AddNewUsers-Dynamicchangestopasswordfiles.">1.2.
+ Dynamic
+ changes to password files.
+ </a></span></dt><dt><span class="section"><a href="#AddNewUsers-HowpasswordfilesandPrincipalDatabasesrelatetoauthenticationmechanisms">1.3.
+ How password files and PrincipalDatabases relate to
+ authentication mechanisms
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2527674">2.
+ Configure ACLs
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureACLs-ConfigureACLs">2.1.
+ Configure ACLs
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528192">3.
+ Configure Java Qpid to use a SSL connection.
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-UsingSSLconnectionwithQpidJava.">3.1.
+ Using SSL connection with Qpid Java.
+ </a></span></dt><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-Setup">3.2.
+ Setup
+ </a></span></dt><dt><span class="section"><a href="#ConfigureJavaQpidtouseaSSLconnection.-Performingtheconnection.">3.3.
+ Performing
+ the connection.
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2530096">4.
+ Configure Log4j CompositeRolling Appender
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfigureLog4jCompositeRollingAppender-HowtoconfiguretheCompositeRollinglog4jAppender">4.1.
+ How to configure the CompositeRolling log4j Appender
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528191">5.
+ Configure the Broker via config.xml
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfiguretheBrokerviaconfig.xml-Brokerconfig.xmlOverview">5.1.
+ Broker config.xml Overview
+ </a></span></dt><dt><span class="section"><a href="#ConfiguretheBrokerviaconfig.xml-QpidVersion">5.2.
+ Qpid
+ Version
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528927">6.
+ Configure the Virtual Hosts via virtualhosts.xml
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#ConfiguretheVirtualHostsviavirtualhosts.xml-virtualhosts.xmlOverview">6.1.
+ virtualhosts.xml Overview
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528256">7.
+ Debug using log4j
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#Debugusinglog4j-Debuggingwithlog4jconfigurations">7.1.
+ Debugging
+ with log4j configurations
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#How-to-Tune-M3-Java-Broker-Performance">8.
+ How to Tune M3 Java Broker Performance
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-ProblemStatement">8.1.
+ Problem
+ Statement
+ </a></span></dt><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-SuccessfulTuningOptions">8.2.
+ Successful
+ Tuning Options
+ </a></span></dt><dt><span class="section"><a href="#HowtoTuneM3JavaBrokerPerformance-NextSteps">8.3.
+ Next
+ Steps
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2528243">9.
+ Qpid Java Build How To
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#QpidJavaBuildHowTo-BuildInstructionsGeneral">9.1.
+ Build
+ Instructions - General
+ </a></span></dt><dt><span class="section"><a href="#QpidJavaBuildHowTo-BuildInstructionsTrunk">9.2.
+ Build
+ Instructions - Trunk
+ </a></span></dt></dl></dd><dt><span class="section"><a href="#id2532013">10.
+ Use Priority Queues
+ </a></span></dt><dd><dl><dt><span class="section"><a href="#UsePriorityQueues-GeneralInformation">10.1.
+ General
+ Information
+ </a></span></dt><dt><span class="section"><a href="#UsePriorityQueues-DefiningPriorityQueues">10.2.
+ Defining
+ Priority Queues
+ </a></span></dt><dt><span class="section"><a href="#UsePriorityQueues-Clientconfiguration-2Fmessagingmodelforpriorityqueues">10.3.
+ Client configuration/messaging model for priority queues
+ </a></span></dt></dl></dd></dl></div><div class="section" title="1. Add New Users"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2528262"></a>1.
+ Add New Users
+ </h2></div></div></div><p>
+ The Qpid Java Broker has a single reference source (<a class="xref" href="#">???</a>) that
+ defines all the users in the system.
+ </p><p>
+ To add a new user to the broker the password file must be
+ updated. The details about adding entries and when these updates
+ take effect are dependent on the file format each of which are
+ described below.
+ </p><div class="section" title="1.1. Available Password file formats"><div class="titlepage"><div><div><h3 class="title"><a name="AddNewUsers-AvailablePasswordfileformats"></a>1.1.
+ Available
+ Password file formats
+ </h3></div></div></div><p>
+ There are currently two different file formats available for use
+ depending on the PrincipalDatabase that is desired. In all cases
+ the clients need not be aware of the type of PrincipalDatabase in
+ use they only need support the SASL mechanisms they provide.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <a class="xref" href="#AddNewUsers-Plain" title="1.1.1. Plain">Section 1.1.1, “
+ Plain
+ ”</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#AddNewUsers-Base64MD5PasswordFileFormat" title="1.1.3. Base64MD5 Password File Format">Section 1.1.3, “
+ Base64MD5
+ Password File Format
+ ”</a>
+ </p></li></ul></div><p>
+
+ </p><div class="section" title="1.1.1. Plain"><div class="titlepage"><div><div><h4 class="title"><a name="AddNewUsers-Plain"></a>1.1.1.
+ Plain
+ </h4></div></div></div><p>
+ The plain file has the following format:
+ </p><pre class="programlisting">
+# Plain password authentication file.
+# default name : passwd
+# Format <username>:<password>
+#e.g.
+martin:password
+</pre><p>
+ As the contents of the file are plain text and the password is
+ taken to be everything to the right of the ':'(colon). The
+ password, therefore, cannot contain a ':' colon, but this can be
+ used to delimit the password.
+ </p><p>
+ Lines starting with a '#' are treated as comments.
+ </p></div><div class="section" title="1.1.2. Where is the password file for my broker ?"><div class="titlepage"><div><div><h4 class="title"><a name="AddNewUsers-Whereisthepasswordfileformybroker-3F"></a>1.1.2.
+ Where is
+ the password file for my broker ?
+ </h4></div></div></div><p>
+ The location of the password file in use for your broker is as
+ configured in your config.xml file.
+ </p><pre class="programlisting">
+<principal-databases>
+ <principal-database>
+ <name>passwordfile</name>
+ <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
+ <attributes>
+ <attribute>
+ <name>passwordFile</name>
+ <value>${conf}/passwd</value>
+ </attribute>
+ </attributes>
+ </principal-database>
+ </principal-databases>
+</pre><p>
+ So in the example config.xml file this password file lives in the
+ directory specified as the conf directory (at the top of your
+ config.xml file).
+ </p><p>
+ If you wish to use Base64 encoding for your password file, then
+ in the <class> element above you should specify
+ org.apache.qpid.server.security.auth.database.Base64MD5PasswordFilePrincipalDatabase
+ </p><p>
+ The default is:
+ </p><pre class="programlisting">
+ <conf>${prefix}/etc</conf>
+</pre></div><div class="section" title="1.1.3. Base64MD5 Password File Format"><div class="titlepage"><div><div><h4 class="title"><a name="AddNewUsers-Base64MD5PasswordFileFormat"></a>1.1.3.
+ Base64MD5
+ Password File Format
+ </h4></div></div></div><p>
+ This format can be used to ensure that SAs cannot read the plain
+ text password values from your password file on disk.
+ </p><p>
+ The Base64MD5 file uses the following format:
+ </p><pre class="programlisting">
+# Base64MD5 password authentication file
+# default name : qpid.passwd
+# Format <username>:<Base64 Encoded MD5 hash of the users password>
+#e.g.
+martin:X03MO1qnZdYdgyfeuILPmQ==
+</pre><p>
+ As with the Plain format the line is delimited by a ':'(colon).
+ The password field contains the MD5 Hash of the users password
+ encoded in Base64.
+ </p><p>
+ This file is read on broker start-up and is not re-read.
+ </p></div><div class="section" title="1.1.4. How can I update a Base64MD5 password file ?"><div class="titlepage"><div><div><h4 class="title"><a name="AddNewUsers-HowcanIupdateaBase64MD5passwordfile-3F"></a>1.1.4.
+ How can
+ I update a Base64MD5 password file ?
+ </h4></div></div></div><p>
+ To update the file there are two options:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Edit the file by hand using the <span class="emphasis"><em>qpid-passwd</em></span> tool
+ that will generate the required lines. The output from the tool
+ is the text that needs to be copied in to your active password
+ file. This tool is located in the broker bin directory.
+ Eventually it is planned for this tool to emulate the
+ functionality of <a class="xref" href="#">???</a>
+ for qpid passwd files.
+ <span class="emphasis"><em>NOTE:</em></span> For the changes to be seen by the broker you must
+ either restart the broker or reload the data with the
+ management tools (see <a class="xref" href="#Qpid-JMX-Management-Console-User-Guide" title="1.1.5. Qpid JMX Management Console User Guide">Section 1.1.5, “
+ Qpid JMX Management Console User Guide
+ ”</a>)
+ </p></li><li class="listitem"><p>Use the management tools to create a new user. The changes
+ will be made by the broker to the password file and the new user
+ will be immediately available to the system (see <a class="xref" href="#Qpid-JMX-Management-Console-User-Guide" title="1.1.5. Qpid JMX Management Console User Guide">Section 1.1.5, “
+ Qpid JMX Management Console User Guide
+ ”</a>).
+ </p></li></ol></div></div></div><div class="section" title="1.2. Dynamic changes to password files."><div class="titlepage"><div><div><h3 class="title"><a name="AddNewUsers-Dynamicchangestopasswordfiles."></a>1.2.
+ Dynamic
+ changes to password files.
+ </h3></div></div></div><p>
+ The Plain password file and the Base64MD5 format file are both
+ only read once on start up.
+ </p><p>
+ To make changes dynamically there are two options, both require
+ administrator access via the Management Console (see <a class="xref" href="#Qpid-JMX-Management-Console-User-Guide" title="1.1.5. Qpid JMX Management Console User Guide">Section 1.1.5, “
+ Qpid JMX Management Console User Guide
+ ”</a>)
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>You can replace the file and use the console to reload its
+ contents.
+ </p></li><li class="listitem"><p>The management console provides an interface to create,
+ delete and amend the users. These changes are written back to the
+ active password file.
+ </p></li></ol></div></div><div class="section" title="1.3. How password files and PrincipalDatabases relate to authentication mechanisms"><div class="titlepage"><div><div><h3 class="title"><a name="AddNewUsers-HowpasswordfilesandPrincipalDatabasesrelatetoauthenticationmechanisms"></a>1.3.
+ How password files and PrincipalDatabases relate to
+ authentication mechanisms
+ </h3></div></div></div><p>
+ For each type of password file a PrincipalDatabase exists that
+ parses the contents. These PrincipalDatabases load various SASL
+ mechanism based on their supportability. e.g. the Base64MD5 file
+ format can't support Plain authentication as the plain password
+ is not available. Any client connecting need only be concerned
+ about the SASL module they support and not the type of
+ PrincipalDatabase. So I client that understands CRAM-MD5 will
+ work correctly with a Plain and Base64MD5 PrincipalDatabase.
+ </p><div class="table"><a name="id2529715"></a><p class="title"><b>Table 2.1. </b></p><div class="table-contents"><table summary="" border="1"><colgroup><col><col></colgroup><tbody><tr><td>
+ FileFormat/PrincipalDatabase
+ </td><td>
+ SASL
+ </td></tr><tr><td>
+ Plain
+ </td><td>
+ AMQPLAIN PLAIN CRAM-MD5
+ </td></tr><tr><td>
+ Base64MD5
+ </td><td>
+ CRAM-MD5 CRAM-MD5-HASHED
+ </td></tr></tbody></table></div></div><br class="table-break"><p>
+ For details of SASL support see <a class="xref" href="#">???</a>
+ </p></div></div><div class="section" title="2. Configure ACLs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2527674"></a>2.
+ Configure ACLs
+ </h2></div></div></div><div class="section" title="2.1. Configure ACLs"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureACLs-ConfigureACLs"></a>2.1.
+ Configure ACLs
+ </h3></div></div></div><div class="section" title="2.1.1. Specification"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-Specification"></a>2.1.1.
+ Specification
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <a class="xref" href="#">???</a>
+ </p></li><li class="listitem"><p>
+ <a class="xref" href="#">???</a>
+ </p></li></ul></div></div><div class="section" title="2.1.2. C++ Broker"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-CBroker"></a>2.1.2.
+ C++ Broker
+ </h4></div></div></div><p>
+ The C++ broker supports <a class="xref" href="#">???</a> of the ACLs
+ </p></div><div class="section" title="2.1.3. Java Broker"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureACLs-JavaBroker"></a>2.1.3.
+ Java Broker
+ </h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <a class="xref" href="#">???</a>
+ </p></li><li class="listitem"><p>Support for Version 2 specification is in progress.
+ </p></li></ul></div></div></div></div><div class="section" title="3. Configure Java Qpid to use a SSL connection."><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2528192"></a>3.
+ Configure Java Qpid to use a SSL connection.
+ </h2></div></div></div><div class="section" title="3.1. Using SSL connection with Qpid Java."><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-UsingSSLconnectionwithQpidJava."></a>3.1.
+ Using SSL connection with Qpid Java.
+ </h3></div></div></div><p>
+ This section will show how to use SSL to enable secure
+ connections between a Java client and broker.
+ </p></div><div class="section" title="3.2. Setup"><div class="titlepage"><div><div><h3 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-Setup"></a>3.2.
+ Setup
+ </h3></div></div></div><div class="section" title="3.2.1. Broker Setup"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-BrokerSetup"></a>3.2.1.
+ Broker
+ Setup
+ </h4></div></div></div><p>
+ The broker configuration file (config.xml) needs to be updated to
+ include the SSL keystore location details.
+ </p><pre class="programlisting">
+<!-- Additions required to Connector Section -->
+
+<ssl>
+ <enabled>true</enabled>
+ <sslOnly>true</sslOnly>
+ <keystorePath>/path/to/keystore.ks</keystorePath>
+ <keystorePassword>keystorepass</keystorePassword>
+</ssl>
+</pre><p>
+ The sslOnly option is included here for completeness however this
+ will disable the unencrypted port and leave only the SSL port
+ listening for connections.
+ </p></div><div class="section" title="3.2.2. Client Setup"><div class="titlepage"><div><div><h4 class="title"><a name="ConfigureJavaQpidtouseaSSLconnection.-ClientSetup"></a>3.2.2.
+ Client
+ Setup
+ </h4></div></div></div><p>
[... 2159 lines stripped ...]
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org