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/01/14 17:55:57 UTC
svn commit: r899299 [3/3] - /qpid/trunk/qpid/doc/book/src/
Added: qpid/trunk/qpid/doc/book/src/Qpid Java FAQ.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Qpid%20Java%20FAQ.xml?rev=899299&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Qpid Java FAQ.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Qpid Java FAQ.xml Thu Jan 14 16:55:54 2010
@@ -0,0 +1,925 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : Qpid Java FAQ
+ </title>
+
+ <section role="h2" id="QpidJavaFAQ-Purpose">
+ <title>Purpose</title>
+ <para>
+ 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.
+ </para>
+
+ <section role="h3" id="QpidJavaFAQ-WhatisQpid-3F"><title>
+ What is Qpid ?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ It currently supports the following features:
+ </para><itemizedlist>
+ <listitem><para>High performance header-based routing for messages
+ </para></listitem>
+ <listitem><para>All features required by the JMS 1.1 specification. Qpid
+ passes all tests in the Sun JMS compliance test suite
+ </para></listitem>
+ <listitem><para>Transaction support
+ </para></listitem>
+ <listitem><para>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 <xref linkend="qpid_3rd-20Party-20Libraries"/> page
+ </para></listitem>
+ <listitem><para>Pluggable security using SASL. Any Java SASL provider can be
+ used
+ </para></listitem>
+ <listitem><para>Management using JMX and a custom management console built
+ using Eclipse RCP
+ </para></listitem>
+ <listitem><para>Naturally, interoperability with other clients including the
+ Qpid .NET, Python, Ruby and C++ implementations
+ </para></listitem>
+ </itemizedlist>
+ <!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-WhyamIgettingaConfigurationExceptionatbrokerstartup-3F"><title>
+ Why am I getting a ConfigurationException at broker startup ?
+ </title>
+
+ <section role="h4" id="QpidJavaFAQ-InvocationTargetException"><title>
+ InvocationTargetException
+ </title>
+ <para>
+ If you get a java.lang.reflect.InvocationTargetException on
+ startup, wrapped as ConfigurationException like this:
+ </para>
+ <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)
+</programlisting>
+ <para>
+ .. then it means you have a missing password file.
+ </para><para>
+ 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.
+ </para><para>
+ The config.xml can be a little confusing in terms of element
+ names and file names for passwords.
+ </para><para>
+ To do this, you need to edit the passwordDir element for the
+ broker, which may have a comment to that effect:
+ </para>
+ <programlisting>
+<passwordDir><!-- Change to the location --></passwordDir>
+</programlisting>
+ <para>
+ The file should be named passwd by default but if you want to you
+ can change this by editing this element:
+ </para>
+ <programlisting>
+<value>${passwordDir}/passwd</value>
+</programlisting>
+ <!--h4--></section>
+
+
+ <section role="h4" id="QpidJavaFAQ-Cannotlocateconfigurationsourcenull-2Fvirtualhosts.xml"><title>
+ Cannot locate configuration source null/virtualhosts.xml
+ </title>
+
+ <para>
+ If you get this message, wrapped inside a ConfigurationException
+ then you've come across a known issue, see JIRA <xref linkend="qpid_QPID-431"/>
+ </para><para>
+ 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
+ </para>
+<!--h4--></section>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIruntheQpidbroker-3F"><title>
+ How do I run
+ the Qpid broker ?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ For the Windows OS, please use qpid-server.bat.
+ </para><para>
+ 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.
+ </para><para>
+ For more information on running the broker please see our
+ <xref linkend="qpid_Getting-20Started"/> page.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIcreateaconnectionusingaURL-3F"><title>
+ How can I
+ create a connection using a URL ?
+ </title>
+
+ <para>
+ Please see the <xref linkend="qpid_Connection-20URL-20Format"/> documentation.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIrepresentaJMSDestinationstringwithQPID-3F"><title>
+ How
+ do I represent a JMS Destination string with QPID ?
+ </title>
+
+ <section role="h4" id="QpidJavaFAQ-Queues"><title>
+ Queues
+ </title>
+
+ <para>
+ A queue can be created in QPID using the following URL format.
+ </para><para>
+ direct://amq.direct/<Destination>/<Queue
+ Name>
+ </para><para>
+ For example:
+ direct://amq.direct/<Destination>/simpleQueue
+ </para><para>
+ Queue names may consist of any mixture of digits, letters, and
+ underscores.
+ </para><para>
+ The <xref linkend="qpid_BindingURLFormat"/> is described in more
+ detail on it's own page.
+ </para>
+<!--h4--></section>
+
+ <section role="h4" id="QpidJavaFAQ-Topics"><title>
+ Topics
+ </title>
+
+ <para>
+ A topic can be created in QPID using the following URL format.
+ </para><para>
+ topic://amq.topic/<Topic Subscription>/
+ </para><para>
+ The topic subscription may only contain the letters A-Z and a-z
+ and digits 0-9.
+ </para><para>
+ 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.
+ </para><para>
+ For example: stocks.nyse.ibm
+ </para><para>
+ Wildcards can be used on subscription with the following meaning.
+ </para><itemizedlist>
+ <listitem><para>match a single level
+ # match zero or more levels
+ </para></listitem>
+ </itemizedlist><para>
+ For example:
+ With two clients
+ 1 - stocks.*.ibm
+ 2 - stocks.#.ibm
+ </para><para>
+ 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.
+ </para><para>
+ The topic currently does not support wild cards.
+ </para>
+<!--h4--></section>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIconnecttothebrokerusingJNDI-3F"><title>
+ How do I
+ connect to the broker using JNDI ?
+ </title>
+
+ <para>
+ see <xref linkend="qpid_How-20to-20Use-20JNDI"/>
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-I-27musingSpringandWeblogiccanyouhelpmewiththeconfigurationformovingovertoQpid-3F"><title>
+ I'm using Spring and Weblogic - can you help me with the
+ configuration for moving over to Qpid ?
+ </title>
+
+ <para>
+ Here is a donated Spring configuration file <xref linkend="qpid_2264.zip"/> which shows the
+ config for Qpid side by side with Weblogic. HtH !
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIconfigurethelogginglevelforQpid-3F"><title>
+ How do
+ I configure the logging level for Qpid ?
+ </title>
+
+ <para>
+ The system property
+ </para>
+ <programlisting>
+amqj.logging.level
+</programlisting>
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para>
+ <programlisting>
+-Damqj.logging.level=INFO
+</programlisting>
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIconfiguremyapplicationtouseQpidclientlogging-3F"><title>
+ How can I configure my application to use Qpid client
+ logging?
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIconfigurethebroker-3F"><title>
+ How can I
+ configure the broker ?
+ </title>
+
+ <para>
+ 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>
+ </para><para>
+ For more detailed information on configuration, please see
+ <xref linkend="qpid_Qpid-20Design-20--20Configuration"/>
+ </para><para>
+
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Whatportsdoesthebrokeruse-3F"><title>
+ What ports
+ does the broker use?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIchangetheportthebrokerusesatruntime-3F"><title>
+ How
+ can I change the port the broker uses at runtime ?
+ </title>
+
+ <para>
+ The broker defaults to use port 5672 at startup for AMQP
+ traffic.
+ The broker also uses port 8999 for the JMX Management interface.
+ </para><para>
+ 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>
+ </para><para>
+ Use this to get round any issues on your host server with port
+ 5672/8999 being in use/unavailable.
+ </para><para>
+ For additional details on what ports the broker uses see <xref linkend="QpidJavaFAQ-Whatportsdoesthebrokeruse"/> FAQ
+ entry.
+ For more detailed information on configuration, please see
+ <xref linkend="qpid_Qpid-20Design-20--20Configuration"/>
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-WhatcommandlineoptionscanIpassintotheqpidserverscript-3F"><title>
+ What command line options can I pass into the qpid-server
+ script ?
+ </title>
+
+ <para>
+ The following command line options are available:
+ </para>
+
+ <para>
+ The following options are available:
+ </para><table>
+ <title>
+ Command Line Options
+ </title>
+
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ Option
+ </entry>
+ <entry>
+ Long Option
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ b
+ </entry>
+ <entry>
+ bind
+ </entry>
+ <entry>
+ Bind to the specified address overriding any value in the
+ config file
+ </entry>
+ </row>
+ <row>
+ <entry>
+ c
+ </entry>
+ <entry>
+ config
+ </entry>
+ <entry>
+ Use the given configuration file
+ </entry>
+ </row>
+ <row>
+ <entry>
+ h
+ </entry>
+ <entry>
+ help
+ </entry>
+ <entry>
+ Prints list of options
+ </entry>
+ </row>
+ <row>
+ <entry>
+ l
+ </entry>
+ <entry>
+ logconfig
+ </entry>
+ <entry>
+ Use the specified log4j.xml file rather than that in the
+ etc directory
+ </entry>
+ </row>
+ <row>
+ <entry>
+ m
+ </entry>
+ <entry>
+ mport
+ </entry>
+ <entry>
+ Specify port to listen on for the JMX Management. Overrides
+ value in config file
+ </entry>
+ </row>
+ <row>
+ <entry>
+ p
+ </entry>
+ <entry>
+ port
+ </entry>
+ <entry>
+ Specify port to listen on. Overrides value in config file
+ </entry>
+ </row>
+ <row>
+ <entry>
+ v
+ </entry>
+ <entry>
+ version
+ </entry>
+ <entry>
+ Print version information and exit
+ </entry>
+ </row>
+ <row>
+ <entry>
+ w
+ </entry>
+ <entry>
+ logwatch
+ </entry>
+ <entry>
+ Specify interval for checking for logging config changes.
+ Zero means no checking
+ </entry>
+ </row>
+ </tbody>
+ </tgroup></table>
+ </section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIauthenticatewiththebroker-3FWhatuserid-26passwordshouldIuse-3F"><title>
+ How do I authenticate with the broker ? What user id &
+ password should I use ?
+ </title>
+
+ <para>
+ You should login as user guest with password guest
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIcreatequeuesthatwillalwaysbeinstantiatedatbrokerstartup-3F"><title>
+ How do I create queues that will always be instantiated at
+ broker startup ?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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:
+ </para>
+ <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>
+</programlisting>
+ <para>
+ 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).
+ </para><para>
+ You can amend the config.xml to point at a different
+ virtualhosts.xml file by editing the <virtualhosts/>
+ element.
+ </para><para>
+ 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:
+ </para><para>
+ <virtualhosts>/home/myhomedir/virtualhosts.xml</virtualhosts>
+ </para><para>
+ 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
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIcreatequeuesatruntime-3F"><title>
+ How do I
+ create queues at runtime?
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoItunethebroker-3F"><title>
+ How do I tune
+ the broker?
+ </title>
+
+ <para>
+ There are a number of tuning options available, please see the
+ <xref linkend="qpid_How-20to-20Tune-20M3-20Java-20Broker-20Performance"/> page for more information.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Wheredoundeliverablemessagesendup-3F"><title>
+ Where do
+ undeliverable messages end up ?
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-CanIconfigurethenameoftheQpidbrokerlogfileatruntime-3F"><title>
+ Can I configure the name of the Qpid broker log file at
+ runtime ?
+ </title>
+
+ <para>
+ If you simply start the Qpid broker using the default
+ configuration, then the log file is written to
+ $QPID_WORK/log/qpid.log
+ </para><para>
+ This is not ideal if you want to run several instances from one
+ install, or acrhive logs to a shared drive from several hosts.
+ </para><para>
+ To make life easier, there are two optional ways to configure the
+ naming convention used for the broker log.
+ </para>
+
+ <section role="h4" id="QpidJavaFAQ-Settingaprefixorsuffix"><title>
+ Setting a prefix
+ or suffix
+ </title>
+
+ <para>
+ Users should set the following environment variables before
+ running qpid-server:
+ </para><para>
+ 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
+ </para><para>
+ 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
+ </para>
+<!--h4--></section>
+
+ <section role="h4" id="QpidJavaFAQ-IncludingthePID"><title>
+ Including the PID
+ </title>
+
+ <para>
+ 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**
+ </para>
+<!--h4--></section>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Myclientapplicationappearstohavehung-3F"><title>
+ My
+ client application appears to have hung?
+ </title>
+
+ <para>
+ 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 <xref linkend="qpid_QPID-429"/>
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIcontacttheQpidteam-3F"><title>
+ How do I
+ contact the Qpid team ?
+ </title>
+
+ <para>
+ For general questions, please subscribe to the
+ users@qpid.apache.org mailing list (<xref linkend="qpid_"/>).
+ </para><para>
+ For development questions, please subscribe to the
+ dev@qpid.apache.org mailing list (<xref linkend="qpid_"/>).
+ </para><para>
+ More details on these lists are available on our <xref linkend="qpid_Mailing-20Lists"/>
+ page.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIchangeauser-27spasswordwhilethebrokerisup-3F"><title>
+ How can I change a user's password while the broker is up ?
+ </title>
+
+ <para>
+ You can do this via the <xref linkend="qpid_Qpid-20JMX-20Management-20Console"/>. 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.
+ </para><para>
+ For more information on the Management Console please see our
+ <xref linkend="qpid_Qpid-20JMX-20Management-20Console-20User-20Guide"/>
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIknowifthereisaconsumerforamessageIamgoingtosend-3F"><title>
+ How do I know if there is a consumer for a message I am going
+ to send?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para><para>
+ 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.
+ </para><para>
+ These flags will not be able to tell you if the consuming
+ application has received the message and is able to process it.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowdoIuseanInVMBrokerformyowntests-3F"><title>
+ How do I
+ use an InVM Broker for my own tests?
+ </title>
+
+ <para>
+ I would take a look at the testPassiveTTL in <xref linkend="qpid_TimeToLiveTest.java?revision=683950&view=markup"/>
+ </para><para>
+ 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.
+ </para><para>
+ See our <xref linkend="qpid_How-20to-20Use-20JNDI"/> on how to confgure it
+ </para><para>
+ Basically though you just need to set two System Properites:
+ </para><para>
+ java.naming.factory.initial =
+ org.apache.qpid.jndi.PropertiesFileInitialContextFactory
+ java.naming.provider.url = <your JNDI file>
+ </para><para>
+ and call getInitialContext() in your code.
+ </para><para>
+ You will of course need to have the broker libraries on your
+ class path for this to run.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-HowcanIinspectthecontentsofmyMessageStore-3F"><title>
+ How
+ can I inspect the contents of my MessageStore?
+ </title>
+
+ <para>
+ There are two possibilities here:
+ </para><para>
+ 1) The management console can be used to interogate an active
+ broker and browse the contents of a queue.See the <xref linkend="qpid_Qpid-20JMX-20Management-20Console"/>
+ page for further details.
+ </para><para>
+ 2) The <xref linkend="qpid_MessageStore-20Tool"/> can be used to inspect
+ the contents of a persistent message store. Note: this can
+ currently only be used when the broker is offline.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Whyaremytransientmessagesbeingsoslow-3F"><title>
+ Why are
+ my transient messages being so slow?
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Whydoesmyproducerfillupthebrokerwithmessages-3F"><title>
+ Why
+ does my producer fill up the broker with messages?
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-ThebrokerkeepsthrowinganOutOfMemoryexception-3F"><title>
+ The
+ broker keeps throwing an OutOfMemory exception?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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 <xref linkend="qpid_Java-20Environment-20Variables"/> for
+ details of changing the memory settings.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-WhyamIgettingabrokersideexceptionwhenItrytopublishtoaqueueoratopic-3F"><title>
+ Why am I getting a broker side exception when I try to
+ publish to a queue or a topic ?
+ </title>
+
+ <para>
+ 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
+ </para>
+ <programlisting>
+<exchange>amq.direct</exchange>
+</programlisting>
+
+ <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)
+</programlisting>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-WhyistherealotofAnonymousIoServicethreads"><title>
+ Why
+ is there a lot of AnonymousIoService threads
+ </title>
+
+ <para>
+ 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.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ--22unabletocertifytheprovidedSSLcertificateusingthecurrentSSLtruststore-22whenconnectingtheManagementConsoletothebroker."><title>
+ "unable to certify the provided SSL certificate using the
+ current SSL trust store" when connecting the Management Console
+ to the broker.
+ </title>
+
+ <para>
+ You have not configured the console's SSL trust store properly,
+ see <xref linkend="qpid_Management-20Console-20Security"/> for
+ more details.
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-Clientkeepsthrowing-27Serverdidnotrespondinatimelyfashion-27-5Cerrorcode408-3ARequestTimeout-5C."><title>
+ Client keeps throwing 'Server did not respond in a timely
+ fashion' [error code 408: Request Timeout].
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para><para>
+ These situations require that the default timeout value be
+ increased. A cilent <xref linkend="qpid_System-20Properties"/> 'amqj.default_syncwrite_timeout' can be set
+ on the client to increase the wait time. The default in 0.5 is
+ 30000 (30s).
+ </para>
+<!--h3--></section>
+
+ <section role="h3" id="QpidJavaFAQ-CanauseTCPKEEPALIVEorAMQPheartbeatingtokeepmyconnectionopen-3F"><title>
+ Can a use TCP_KEEPALIVE or AMQP heartbeating to keep my
+ connection open?
+ </title>
+
+ <para>
+ See <xref linkend="qpid_Configure-20Broker-20and-20Client-20Heartbeating"/>
+ </para>
+
+<!--h3--></section>
+<!--h2--></section>
+
+
+
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/Qpid Management Features.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Qpid%20Management%20Features.xml?rev=899299&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Qpid Management Features.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Qpid Management Features.xml Thu Jan 14 16:55:54 2010
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml">
+ <title>
+ Apache Qpid : Qpid Management Features
+ </title>
+ <para>
+ <emphasis>Management tool:</emphasis> See our <xref linkend="qpid_Qpid-20JMX-20Management-20Console"/> for
+ details of how to use various console options with the Qpid
+ management features.
+ </para>
+ <para>
+ The management of QPID is categorised into following types-
+ </para>
+ <orderedlist>
+ <listitem><para>Exchange
+ </para></listitem>
+ <listitem><para>Queue
+ </para></listitem>
+ <listitem><para>Connection
+ </para></listitem>
+ <listitem><para>Broker
+ </para></listitem>
+ </orderedlist>
+ <para>
+ Â <emphasis>1) Managing and Monitoring Exchanges</emphasis>: Following is
+ the list of features, which we can have available for managing
+ and monitoring an Exchange running on a Qpid Server Domain-
+ </para>
+ <orderedlist>
+ <listitem><para>Displaying the following information for monitoring purpose-
+ <orderedlist>
+ <listitem><para>The list of queues bound to the exchange along with the
+ routing keys.
+ </para></listitem>
+ <listitem><para>
+ General Exchange properties(like name,
+ durable etc).
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ <listitem><para>
+ Binding an existing queue with the
+ exchange.
+ </para></listitem>
+ </orderedlist>
+ <para>
+ <emphasis>2) Managing and Monitoring
+ Queues</emphasis>:Â Following are the
+ features, which we can have for a Queue on a Qpid Server
+ Domain-
+ </para>
+ <orderedlist>
+ <listitem><para>
+ Displaying the following information about
+ the queue for monitoring purpose-
+ <orderedlist>
+ <listitem><para>
+ General Queue properties(like name,
+ durable, etc.)
+ </para></listitem>
+ <listitem><para>
+ The maximum size of a message that can
+ be accepted from the message producer.
+ </para></listitem>
+ <listitem><para>
+ The number of the active consumers
+ accessing the Queue.
+ </para></listitem>
+ <listitem><para>
+ The total number of
+ consumers (Active and Suspended).
+ </para></listitem>
+ <listitem><para>
+ The number of undelivered messages
+ in the Queue.
+ </para></listitem>
+ <listitem><para>
+ The total number of messages received
+ on the Queue since startup.
+ </para></listitem>
+ <listitem><para>
+ The maximum number of bytes for
+ the Queue that can be stored on the Server.
+ </para></listitem>
+ <listitem><para>The maximum number of messages for the Queue that can be
+ stored on the Server.
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ <listitem><para>
+ Viewing the messages on the Queue.
+ </para></listitem>
+ <listitem><para>
+ Deleting message from top of the
+ Queue.
+ </para></listitem>
+ <listitem><para>
+ Clearing the Queue.
+ </para></listitem>
+ <listitem><para>
+ Browsing the DeadMessageQueue - Messages
+ which are expired or undelivered because of some reason are
+ routed to the DeadMessageQueue. This queue can not be
+ deleted. [Note: The is open because it depends on how
+ these kind of messages will be handeled?]
+ </para></listitem>
+ </orderedlist>
+ <para>
+ <emphasis>3) Managing and Monitoring
+ Connections</emphasis>: Following are the
+ features, which we can have for a connection on a QPID
+ Server Domain-
+ </para>
+ <orderedlist>
+ <listitem><para>
+ Displaying general connection
+ properties(like remote address, etc.).
+ </para></listitem>
+ <listitem><para>Setting maximum number of channels allowed for a
+ connection.
+ </para></listitem>
+ <listitem><para>View all related channels and channel properties.
+ </para></listitem>
+ <listitem><para>Closing a channel.
+ </para></listitem>
+ <listitem><para>Commit or Rollback transactions of a channel, if the channel
+ is transactional.
+ </para></listitem>
+ <listitem><para>Notification for exceeding the maximum number of
+ channels.
+ </para></listitem>
+ <listitem><para>Dropping a connection.
+ </para></listitem>
+ <listitem><para>The work for <xref linkend="qpid_Network-20IO-20Interface"/> implies that
+ there are potentially some additional requirements
+ <orderedlist>
+ <listitem><para>Alert when tcp flow control kicks in
+ </para></listitem>
+ <listitem><para>Information available about current memory usage
+ available through JMX interface
+ </para></listitem>
+ <listitem><para>Dynamic removal of buffer bounds? (fundamentally not
+ possible with TransportIO)
+ </para></listitem>
+ <listitem><para>Management functionality added to JMX interface - UI
+ changes?
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ </orderedlist>
+ <para>
+ <emphasis>4) Managing the Broker</emphasis>: Features for the Broker-
+ </para>
+ <orderedlist>
+ <listitem><para>Creating an Exchange.
+ </para></listitem>
+ <listitem><para>Unregistering an Exchange.
+ </para></listitem>
+ <listitem><para>Creating a Queue.
+ </para></listitem>
+ <listitem><para>Deleting a
+ Queue.       Â
+ </para></listitem>
+ </orderedlist>
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/Qpid Troubleshooting Guide.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Qpid%20Troubleshooting%20Guide.xml?rev=899299&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Qpid Troubleshooting Guide.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Qpid Troubleshooting Guide.xml Thu Jan 14 16:55:54 2010
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : Qpid Troubleshooting Guide
+ </title><para>
+ Contents
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F"/>
+ </para></listitem>
+ <listitem><para>
+ <xref linkend="QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F"/>
+ </para></listitem>
+ </itemizedlist>
+ <section role="h2" id="QpidTroubleshootingGuide-I-27mgettingajava.lang.UnsupportedClassVersionErrorwhenItrytostartthebroker.Whatdoesthismean-3F"><title>
+ I'm getting a java.lang.UnsupportedClassVersionError when I
+ try to start the broker. What does this mean ?
+ </title>
+
+ <para>
+ 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.
+ </para><para>
+ 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)
+ </para>
+
+<!--h2--></section>
+
+ <section role="h2" id="QpidTroubleshootingGuide-I-27mhavingaproblembindingtotherequiredhost-3Aportatbrokerstartup-3F"><title>
+ I'm having a problem binding to the required host:port at
+ broker startup ?
+ </title>
+ <para>
+ 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'.
+ </para><para>
+ 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>.
+ </para><para>
+ You can also amend the port more simply using the -p option to
+ qpid-server i.e. qpid-server -p <my port number'
+ </para>
+<!--h2--></section>
+
+ <section role="h2" id="QpidTroubleshootingGuide-I-27mhavingproblemswithmyclasspath.HowcanIensurethatmyclasspathisok-3F"><title>
+ I'm having problems with my classpath. How can I ensure that
+ my classpath is ok ?
+ </title>
+ <para>
+ 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.
+ </para><para>
+ 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.
+ </para>
+
+ <section role="h2" id="QpidTroubleshootingGuide-Ican-27tgetthebrokertostart.HowcanIdiagnosetheproblem-3F"><title>
+ I can't get the broker to start. How can I diagnose the
+ problem ?
+ </title>
+ <para>
+ 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.
+ </para><para>
+ 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:
+ </para><para>
+ "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"
+ </para><para>
+ ... then you know the broker started up. If not, then it didn't.
+ </para>
+<!--h2--></section>
+
+ <section role="h2" id="QpidTroubleshootingGuide-WhenItrytosendmessagestoaqueueI-27mgettingaerrorasthequeuedoesnotexist.WhatcanIdo-3F"><title>
+ When I try to send messages to a queue I'm getting a error as
+ the queue does not exist. What can I do ?
+ </title>
+ <para>
+ 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
+ <xref linkend="qpid_Qpid-20Java-20FAQ"/> for more details of using the virtualhosts.xml route.
+ </para>
+<!--h2--></section>
+</chapter>
Added: qpid/trunk/qpid/doc/book/src/Use Priority Queues.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Use%20Priority%20Queues.xml?rev=899299&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Use Priority Queues.xml (added)
+++ qpid/trunk/qpid/doc/book/src/Use Priority Queues.xml Thu Jan 14 16:55:54 2010
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter xmlns:html="http://www.w3.org/1999/xhtml"><title>
+ Apache Qpid : Use Priority Queues
+ </title>
+
+
+ <section role="h2" id="UsePriorityQueues-GeneralInformation"><title>
+ General
+ Information
+ </title>
+ <para>
+ The Qpid M3 release introduces priority queues into the Java
+ Messaging Broker, supporting JMS clients who wish to make use of
+ priorities in their messaging implementation.
+ </para><para>
+ There are some key points around the use of priority queues in
+ Qpid, discussed in the sections below.
+ </para>
+<!--h2--></section>
+ <section role="h2" id="UsePriorityQueues-DefiningPriorityQueues"><title>
+ Defining
+ Priority Queues
+ </title>
+ <para>
+ You must define a priority queue specifically before you start to
+ use it. You cannot subsequently change a queue to/from a priority
+ queue (without deleting it and re-creating).
+ </para><para>
+ You define a queue as a priority queue in the virtualhost
+ configuration file, which the broker loads at startup. When
+ defining the queue, add a <priority>true</priority>
+ element. This will ensure that the queue has 10 distinct
+ priorities, which is the number supported by JMS.
+ </para><para>
+ If you require fewer priorities, it is possible to specify a
+ <priorities>int</priorities> element (where int is a
+ valid integer value between 2 and 10 inclusive) which will give
+ the queue that number of distinct priorities. When messages are
+ sent to that queue, their effective priority will be calculated
+ by partitioning the priority space. If the number of effective
+ priorities is 2, then messages with priority 0-4 are treated the
+ same as "lower priority" and messages with priority 5-9 are
+ treated equivalently as "higher priority".
+ </para>
+ <programlisting>
+<queue>
+ <name>test</name>
+ <test>
+ <exchange>amq.direct</exchange>
+ <priority>true</priority>
+ </test>
+</queue>
+</programlisting>
+<!--h2--></section>
+
+ <section role="h2" id="UsePriorityQueues-Clientconfiguration-2Fmessagingmodelforpriorityqueues"><title>
+ Client configuration/messaging model for priority queues
+ </title>
+ <para>
+ There are some other configuration & paradigm changes which
+ are required in order that priority queues work as expected.
+ </para>
+ <section role="h3" id="UsePriorityQueues-Setlowprefetch"><title>
+ Set low pre-fetch
+ </title>
+ <para>
+ Qpid clients receive buffered messages in batches, sized
+ according to the pre-fetch value. The current default is 5000.
+ </para><para>
+ However, if you use the default value you will probably
+ <emphasis>not</emphasis> see desirable behaviour with messages of different
+ priority. This is because a message arriving after the pre-fetch
+ buffer has filled will not leap frog messages of lower priority.
+ It will be delivered at the front of the next batch of buffered
+ messages (if that is appropriate), but this is most likely NOT
+ what you need.
+ </para><para>
+ So, you need to set the prefetch values for your client
+ (consumer) to make this sensible. To do this set the java system
+ property max_prefetch on the client environment (using -D) before
+ creating your consumer.
+ </para><para>
+ Setting the Qpid pre-fetch to 1 for your client means that
+ message priority will be honoured by the Qpid broker as it
+ dispatches messages to your client. A default for all client
+ connections can be set via a system property:
+ </para>
+ <programlisting>
+-Dmax_prefetch=1
+</programlisting>
+ <para>
+ The prefetch can be also be adjusted on a per connection basis by
+ adding a 'maxprefetch' value to the <xref linkend="qpid_Connection-20URL-20Format"/>
+ </para>
+ <programlisting>
+amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672'
+</programlisting>
+ <para>
+ There is a slight performance cost here if using the receive()
+ method and you could test with a slightly higher pre-fetch (up to
+ 10) if the trade-off between throughput and prioritisation is
+ weighted towards the former for your application. (If you're
+ using OnMessage() then this is not a concern.)
+ </para>
+<!--h3--></section>
+ <section role="h3" id="UsePriorityQueues-Singleconsumerpersession"><title>
+ Single
+ consumer per session
+ </title>
+ <para>
+ If you are using the receive() method to consume messages then
+ you should also only use one consumer per session with priority
+ queues. If you're using OnMessage() then this is not a concern.
+ </para>
+<!--h3--></section>
+<!--h2--></section>
+</chapter>
Modified: qpid/trunk/qpid/doc/book/src/schemas.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/schemas.xml?rev=899299&r1=899298&r2=899299&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/schemas.xml (original)
+++ qpid/trunk/qpid/doc/book/src/schemas.xml Thu Jan 14 16:55:54 2010
@@ -1,5 +1,6 @@
<?xml version="1.0"?>
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
+ <uri resource="Configure the Broker via config.xml.xml" typeId="DocBook"/>
<uri resource="SSL.xml" typeId="DocBook"/>
<uri resource="Using Broker Federation.xml" typeId="DocBook"/>
<uri resource="Cheat Sheet for configuring Exchange Options.xml" typeId="DocBook"/>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org