From 8d32f064dd2a6998e68345a8fc97a6a218aef1fd Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Fri, 5 Oct 2012 16:38:51 +0000 Subject: QPID-4358: Restructure Java Broker docbook Introduce a new document structure Migrate useful content from old book to the new structure, rationalising the id's Remove out-of-date content git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1394629 13f79535-47bb-0310-9956-ffa450edef68 --- qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml | 890 ------------------------ 1 file changed, 890 deletions(-) delete mode 100644 qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml (limited to 'qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml') diff --git a/qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml b/qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml deleted file mode 100644 index 2940e58138..0000000000 --- a/qpid/doc/book/src/java-broker/Qpid-Java-FAQ.xml +++ /dev/null @@ -1,890 +0,0 @@ - - - -
- Qpid Java FAQ - - -
- Purpose - - 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. - - -
- What is Qpid ? - - - - 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. - - It currently supports the following features: - - High performance header-based routing for messages - - All features required by the JMS 1.1 specification. Qpid - passes all tests in the Sun JMS compliance test suite - - Transaction support - - 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 page - - Pluggable security using SASL. Any Java SASL provider can be - used - - Management using JMX and a custom management console built - using Eclipse RCP - - Naturally, interoperability with other clients including the - Qpid .NET, Python, Ruby and C++ implementations - - -
- -
- Why am I getting a ConfigurationException at broker startup ? - - -
- InvocationTargetException - - - If you get a java.lang.reflect.InvocationTargetException on - startup, wrapped as ConfigurationException like this: - - -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) - - - .. then it means you have a missing password file. - - 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. - - The config.xml can be a little confusing in terms of element - names and file names for passwords. - - To do this, you need to edit the passwordDir element for the - broker, which may have a comment to that effect: - - -<passwordDir><!-- Change to the location --></passwordDir> - - - The file should be named passwd by default but if you want to you - can change this by editing this element: - - -<value>${passwordDir}/passwd</value> - -
- - -
- Cannot locate configuration source null/virtualhosts.xml - - - - If you get this message, wrapped inside a ConfigurationException - then you've come across a known issue, see JIRA - - 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 - -
-
- -
- How do I run - the Qpid broker ? - - - - 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. - - For the Windows OS, please use qpid-server.bat. - - 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. - - For more information on running the broker please see our - page. - -
- -
- How can I - create a connection using a URL ? - - - - Please see the documentation. - -
- -
- How - do I represent a JMS Destination string with QPID ? - - -
- Queues - - - - A queue can be created in QPID using the following URL format. - - direct://amq.direct/<Destination>/<Queue - Name> - - For example: - direct://amq.direct/<Destination>/simpleQueue - - Queue names may consist of any mixture of digits, letters, and - underscores. - - The is described in more - detail on it's own page. - -
- -
- Topics - - - - A topic can be created in QPID using the following URL format. - - topic://amq.topic/<Topic Subscription>/ - - The topic subscription may only contain the letters A-Z and a-z - and digits 0-9. - - 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. - - For example: stocks.nyse.ibm - - Wildcards can be used on subscription with the following meaning. - - match a single level - # match zero or more levels - - - For example: - With two clients - 1 - stocks.*.ibm - 2 - stocks.#.ibm - - 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. - - The topic currently does not support wild cards. - -
-
- -
- How do I - connect to the broker using JNDI ? - - - - see - -
- -
- I'm using Spring and Weblogic - can you help me with the - configuration for moving over to Qpid ? - - - - Here is a donated Spring configuration file appContext.zip - which shows the config for Qpid side by side with - Weblogic. HtH ! - -
- -
- How do - I configure the logging level for Qpid ? - - - - The system property - - -amqj.logging.level - - - 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. - - 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. - - --Damqj.logging.level=INFO - - - 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. - -
- -
- How can I configure my application to use Qpid client - logging? - - - - 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. - -
- -
- How can I - configure the broker ? - - - - 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> - - For more detailed information on configuration, please see - - - - -
- -
- What ports - does the broker use? - - - - 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. - - 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. - -
- -
- How - can I change the port the broker uses at runtime ? - - - - The broker defaults to use port 5672 at startup for AMQP - traffic. - The broker also uses port 8999 for the JMX Management interface. - - 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> - - Use this to get round any issues on your host server with port - 5672/8999 being in use/unavailable. - - For additional details on what ports the broker uses see FAQ - entry. - For more detailed information on configuration, please see - - -
- -
- What command line options can I pass into the qpid-server - script ? - - - - The following command line options are available: - - - - The following options are available: - - - Command Line Options - - - - - - - Option - - - Long Option - - - Description - - - - - b - - - bind - - - Bind to the specified address overriding any value in the - config file - - - - - c - - - config - - - Use the given configuration file - - - - - h - - - help - - - Prints list of options - - - - - l - - - logconfig - - - Use the specified log4j.xml file rather than that in the - etc directory - - - - - m - - - mport - - - Specify port to listen on for the JMX Management. Overrides - value in config file - - - - - p - - - port - - - Specify port to listen on. Overrides value in config file - - - - - v - - - version - - - Print version information and exit - - - - - w - - - logwatch - - - Specify interval for checking for logging config changes. - Zero means no checking - - - -
-
- -
- How do I authenticate with the broker ? What user id & - password should I use ? - - - - You should login as user guest with password guest - -
- -
- How do I create queues that will always be instantiated at - broker startup ? - - - - 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. - - 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: - - -<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> - - - 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). - - You can amend the config.xml to point at a different - virtualhosts.xml file by editing the <virtualhosts/> - element. - - 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: - - <virtualhosts>/home/myhomedir/virtualhosts.xml</virtualhosts> - - 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 - -
- -
- How do I - create queues at runtime? - - - - 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. - -
- -
- How do I tune - the broker? - - - - There are a number of tuning options available, please see the - page for more information. - -
- -
- Where do - undeliverable messages end up ? - - - - 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. - -
- -
- Can I configure the name of the Qpid broker log file at - runtime ? - - - - If you simply start the Qpid broker using the default - configuration, then the log file is written to - $QPID_WORK/log/qpid.log - - This is not ideal if you want to run several instances from one - install, or acrhive logs to a shared drive from several hosts. - - To make life easier, there are two optional ways to configure the - naming convention used for the broker log. - - -
- Setting a prefix - or suffix - - - - Users should set the following environment variables before - running qpid-server: - - 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 - - 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 - -
- -
- Including the PID - - - - 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** - -
-
- -
- My - client application appears to have hung? - - - - 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 - -
- -
- How do I - contact the Qpid team ? - - - - For general questions, please subscribe to the - users@qpid.apache.org mailing list. - - For development questions, please subscribe to the - dev@qpid.apache.org mailing list. - - More details on these lists are available on our - page. - -
- -
- How can I change a user's password while the broker is up ? - - - - You can do this via the . 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. - - For more information on the Management Console please see our - - -
- -
- How do I know if there is a consumer for a message I am going - to send? - - - - 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. - - 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. - - 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. - - These flags will not be able to tell you if the consuming - application has received the message and is able to process it. - -
- -
- How - can I inspect the contents of my MessageStore? - - - - The management console can be used to interogate an active - broker and browse the contents of a queue.See the - page for further details. - -
- -
- Why are - my transient messages being so slow? - - - - 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. - -
- -
- Why - does my producer fill up the broker with messages? - - - - Switch on producer flow control to prevent temporary spikes in - message production over-filling the broker. - - Of course, if the long-term rate of message production exceeds - the rate of message - consumption then that is an architectural problem that can only - be temporarily mitigated by producer flow control. - -
- -
- The - broker keeps throwing an OutOfMemory exception? - - - - 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. - - 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 for - details of changing the memory settings. - -
- -
- Why am I getting a broker side exception when I try to - publish to a queue or a topic ? - - - - 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 - - -<exchange>amq.direct</exchange> - - - -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) - -
- -
- Why - is there a lot of AnonymousIoService threads - - - - 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. - -
- -
- "unable to certify the provided SSL certificate using the - current SSL trust store" when connecting the Management Console - to the broker. - - - - You have not configured the console's SSL trust store properly, - see for - more details. - -
- -
- Can a use TCP_KEEPALIVE or AMQP heartbeating to keep my - connection open? - - - - See - - -
-
- - - -
-- cgit v1.2.1