Merging default into bug21673

Author: Matthew Sackman

Makefile

@@ -7,7 +7,7 @@ SRC_ARCHIVE=$(PACKAGE_NAME)-$(VERSION)
 SIGNING_KEY=056E8E56
 GNUPG_PATH=~
 
-WEB_URL=http://stage.rabbitmq.com/
+WEB_URL=http://www.rabbitmq.com/
 NEXUS_STAGE_URL=http://oss.sonatype.org/service/local/staging/deploy/maven2
 
 AMQP_CODEGEN_DIR=$(shell fgrep sibling.codegen.dir build.properties | sed -e 's:sibling\.codegen\.dir=::')

README-EXAMPLES

@@ -0,0 +1,84 @@
+Overview
+========
+
+A number of examples are packaged with the source distribution and
+with the tests jar in the binary distribution. These examples vary in
+complexity from simple clients and servers through to complex test
+harnesses that are used for testing the RabbitMQ server.
+
+The source code for the examples can be found in the
+test/src/com/rabbitmq/examples directory of the source distribution.
+
+
+Running the Examples
+====================
+
+The script runjava.sh or runjava.bat can be found in the top level
+directory of the binary distribution or in the scripts directory of
+the source distribution.
+
+This script can be used to run the examples.  For instance, if you are
+using the binary distribution and if you have a RabbitMQ broker
+running and you open two shell or console windows you can test basic
+connectivity like this:
+
+shell-1$ ./runjava.sh com.rabbitmq.examples.SimpleConsumer
+
+shell-2$ ./runjava.sh com.rabbitmq.examples.SimpleProducer
+
+shell-1$ ./runjava.sh com.rabbitmq.examples.SimpleConsumer
+Message: the time is Fri Feb 26 08:28:58 GMT 2010
+
+Running the examples from the source distribution requries two more
+preliminary steps:
+
+shell-1$ ant dist
+
+shell-1$ cd build/dist/
+
+Now, the examples can be run exactly as detailed above.
+
+The more complex examples will require additional command line
+arguments and it is best to examine the source of the examples to
+determine what arguments are available.
+
+All examples live in the com.rabbitmq.examples package, so just add
+that package name to the examples described below to produce the full
+classname that is required as the first argument to the runjava
+script.
+
+
+Simple Examples
+===============
+
+SimpleProducer - Sends a message to an exchange.
+SimpleConsumer - Reads a message from a queue.
+SimpleTopicProducer - Sends a message to a topic exchange.
+SimpleTopicConsumer - Reads a message from a topic queue.
+SendString - Send a string to an exchange.
+FileProducer - Sends a file to an exchange.
+FileConsumer - Reads a file from a queue.
+HelloClient - Performs a simple RPC call over AMQP.
+HelloServer - Acts as an RPC server over AMQP.
+HelloJsonClient - Performs a simple JSON-RPC call over AMQP.
+HelloJsonServer - Acts as a JSON-RPC server over AMQP.
+LogTail - Tails the server logs.
+SendString - Sends a user supplied message over AMQP.
+
+
+More Complex Examples
+=====================
+
+Most of these examples are used in testing and tuning the RabbitMQ
+server.
+
+BufferPerformanceMetrics - Tests buffer sizing.
+ChannelCreationPerformance - Test different Channel creation strategies.
+ConsumerMain - Measures performance of Consumers.
+ManyConnections - Tests many connections.
+MulticastMain - Measures performance of multiple consumers and producers.
+ProducerMain - Measures performance of Producers.
+SpammyTopicProducer - Sends lots of different topic messages over AMQP.
+StressPersister - Stress test for persister.
+TestMain - RabbitMQ server regression tests.
+TracerConcurrencyTest - Tests correct concurrency behaviour of RabbitMQ tracer.

README-TESTS

@@ -0,0 +1,68 @@
+Overview
+========
+
+There are multiple test suites in the RabbitMQ Java client library;
+the source for all of the suites can be found in the test/src
+directory.
+
+The suites are:
+
+  Client tests
+  Functional tests
+  Server tests
+  SSL tests
+
+All the tests require a conforming server listening on localhost:5672
+(the default settings).  For details on running specific tests, see
+below.
+
+All the test suites can be run with the command ant test-suite. To run
+specific test suites see the instructions below.
+
+
+Running a Specific Test Suite
+=============================
+
+To run a specific test suite, but not the others, you should execute
+one of the following in the top-level directory of the source tree:
+
+  ant test-client
+  ant test-functional
+  ant test-server
+  ant test-ssl
+
+Note that to run the SSL tests, the RabbitMQ server should be
+configured to use SSL as per the SSL with RabbitMQ guide.
+
+The server tests are meant to test a RabbitMQ broker.  Broadly, they
+require a running RabbitMQ broker on the default host/port, the source
+code for rabbitmq-server in ../rabbitmq-server, and a test directory
+../rabbitmq-test.  Running them manually is a tricky business.
+
+For example, to run the client tests:
+
+----------------- Example shell session -------------------------------------
+rabbitmq-java-client$ ant test-client
+Buildfile: build.xml
+
+test-prepare:
+
+test-build:
+
+amqp-generate-check:
+
+amqp-generate:
+
+build:
+
+test-build-param:
+
+test-client:
+    [junit] Running com.rabbitmq.client.test.ClientTests
+    [junit] Tests run: 31, Failures: 0, Errors: 0, Time elapsed: 2.388 sec
+
+BUILD SUCCESSFUL
+-----------------------------------------------------------------------------
+
+If any tests are broken details can be found by viewing this file:
+	build/TEST-com.rabbitmq.client.test.ClientTests.txt

build.xml

@@ -26,7 +26,7 @@
     <pathelement path="${test.javac.out}"/>
   </path>
 
-  <property name="AMQP_SPEC_JSON_PATH" value="${codegen.dir}/amqp-${spec.version}.json"/>
+  <property name="AMQP_SPEC_JSON_PATH" value="${codegen.dir}/amqp-${spec.version}.json ${codegen.dir}/rabbitmq-0.8-extensions.json"/>
 
   <target name="amqp-generate-check" description="check if codegen needs to be run">
     <uptodate property="amqp.generate.notRequired">
@@ -77,7 +77,7 @@
   	</fail>
   </target>
 
-  <target name="build" depends="amqp-generate">
+  <target name="build" depends="amqp-generate" description="Build the client library.">
     <mkdir dir="${javac.out}"/>
     <copy file="src/com/rabbitmq/client/impl/ClientVersion.java.in"
 	  tofile="${src.generated}/com/rabbitmq/client/impl/ClientVersion.java">
@@ -116,6 +116,10 @@
     <property name="SSL_P12_PASSWORD" value="${env.PASSWORD}"/>
   </target>
 
+  <target  name="detect-umbrella">
+    <available property="UMBRELLA_AVAILABLE" file="../rabbitmq-test"/>
+  </target>
+
   <target name="detect-tmpdir">
     <property environment="env"/>
     <condition property="TMPDIR" value="${env.TMPDIR}" else="/tmp">
@@ -317,7 +321,7 @@
   	<property name="haltOnFailureJava" value="false" />	
   </target>
 
-  <target name="test-suite" depends="test-suite-prepare, test-suite-run">
+  <target name="test-suite" depends="test-suite-prepare, test-suite-run" description="Run all test suites.">
   	<fail message="Errors occured in tests">
   	    <condition>
             <not>
@@ -329,7 +333,7 @@
 
   <target name="test-suite-run" depends="test-client, test-ssl, test-server, test-functional, test-main-silent"/>
 
-  <target name="test-client" depends="test-build">
+  <target name="test-client" depends="test-build" description="Run the client test suites.">
     <junit printSummary="withOutAndErr"
         haltOnFailure="${haltOnFailureJunit}"
         failureproperty="test.failure"
@@ -362,7 +366,7 @@
     <antcall target="remove-client-keystore"/>
   </target>
 
-  <target name="test-functional" depends="test-build">
+  <target name="test-functional" depends="test-build" description="Run the functional test suite.">
     <junit printSummary="withOutAndErr"
         haltOnFailure="${haltOnFailureJunit}"
         failureproperty="test.failure"
@@ -375,7 +379,7 @@
     </junit>
   </target>
 
-  <target name="test-server" depends="test-build">
+  <target name="test-server" depends="detect-umbrella, test-build" if="UMBRELLA_AVAILABLE">
     <junit printSummary="withOutAndErr"
         haltOnFailure="${haltOnFailureJunit}"
         failureproperty="test.failure"

src/com/rabbitmq/client/Channel.java

@@ -147,6 +147,40 @@ public interface Channel extends ShutdownNotifier {
      */
     void setFlowListener(FlowListener listener);
 
+    /**
+     * Get the current default consumer. @see setDefaultConsumer for rationale.
+     * @return an interface to the current default consumer.
+     */
+    Consumer getDefaultConsumer();
+
+    /**
+     * Set the current default consumer.
+     *
+     * Under certain circumstances it is possible for a channel to receive a
+     * message delivery which does not match any consumer which is currently
+     * set up via basicConsume(). This will occur after the following sequence
+     * of events:
+     *
+     * ctag = basicConsume(queue, consumer); // i.e. with explicit acks
+     * // some deliveries take place but are not acked
+     * basicCancel(ctag);
+     * basicRecover(false);
+     *
+     * Since requeue is specified to be false in the basicRecover, the spec
+     * states that the message must be redelivered to "the original recipient"
+     * - i.e. the same channel / consumer-tag. But the consumer is no longer
+     * active.
+     *
+     * In these circumstances, you can register a default consumer to handle
+     * such deliveries. If no default consumer is registered an
+     * IllegalStateException will be thrown when such a delivery arrives.
+     *
+     * Most people will not need to use this.
+     *
+     * @param consumer the consumer to use, or null indicating "don't use one".
+     */
+    void setDefaultConsumer(Consumer consumer);
+
     /**
      * Request specific "quality of service" settings.
      *
@@ -495,12 +529,22 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      * Ask the broker to resend unacknowledged messages.  In 0-8
      * basic.recover is asynchronous; in 0-9-1 it is synchronous, and
      * the new, deprecated method basic.recover_async is asynchronous.
-     * To avoid this API changing, this is named for the latter, and
-     * will be deprecated.
      * @param requeue If true, messages will be requeued and possibly
      * delivered to a different consumer. If false, messages will be
      * redelivered to the same consumer.
      */
+    Basic.RecoverOk basicRecover(boolean requeue) throws IOException;
+
+    /**
+     * Ask the broker to resend unacknowledged messages.  In 0-8
+     * basic.recover is asynchronous; in 0-9-1 it is synchronous, and
+     * the new, deprecated method basic.recover_async is asynchronous
+     * and deprecated.
+     * @param requeue If true, messages will be requeued and possibly
+     * delivered to a different consumer. If false, messages will be
+     * redelivered to the same consumer.
+     */
+    @Deprecated
     void basicRecoverAsync(boolean requeue) throws IOException;
 
     /**

src/com/rabbitmq/client/Connection.java

@@ -40,7 +40,8 @@
  *
  * <pre>
  * ConnectionFactory factory = new ConnectionFactory();
- * factory.setHostName(hostName);
+ * factory.setHost(hostName);
+ * factory.setPort(portNumber);
  * factory.setVirtualHost(virtualHost);
  * factory.setUsername(username);
  * factory.setPassword(password);

src/com/rabbitmq/client/ConnectionFactory.java

@@ -135,7 +135,8 @@ public int getPort() {
     }
 
     /**
-     *  @return the default port to use for connections
+     * Set the target port.
+     * @param port the default port to use for connections
      */
     public void setPort(int port) {
         this.port = port;
@@ -244,7 +245,7 @@ public void setRequestedHeartbeat(int requestedHeartbeat) {
      * table. Such changes will take effect when the next new
      * connection is started using this factory.
      * @return the map of client properties
-     * @see setClientProperties()
+     * @see #setClientProperties
      */
     public Map<String, Object> getClientProperties() {
         return _clientProperties;
@@ -254,7 +255,7 @@ public Map<String, Object> getClientProperties() {
      * Replace the table of client properties that will be sent to the
      * server during subsequent connection startups.
      * @param clientProperties the map of extra client properties
-     * @see getClientProperties()
+     * @see #getClientProperties
      */
     public void setClientProperties(Map<String, Object> clientProperties) {
         _clientProperties = clientProperties;
@@ -335,7 +336,13 @@ protected FrameHandler createFrameHandler(Address addr)
         Socket socket = factory.createSocket();
         configureSocket(socket);
         socket.connect(new InetSocketAddress(hostName, portNumber));
-        return new SocketFrameHandler(socket);
+        return createFrameHandler(socket);
+    }
+
+    protected FrameHandler createFrameHandler(Socket sock)
+        throws IOException
+    {
+        return new SocketFrameHandler(sock);
     }
 
     /**

src/com/rabbitmq/client/Consumer.java

@@ -70,6 +70,19 @@ public interface Consumer {
      */
     void handleShutdownSignal(String consumerTag, ShutdownSignalException sig);
 
+    /**
+     * Called to notify the consumer that we've received a basic.recover-ok
+     * in reply to a basic.recover some other thread sent. All messages
+     * received before this is invoked that haven't been ack'ed will be
+     * redelivered. All messages received afterwards won't be.
+     *
+     * This method exists since all the Consumer callbacks are invoked by the
+     * connection main loop thread - so it's sometimes useful to allow that
+     * thread to know that the recover-ok has been received, rather than the
+     * thread which invoked basicRecover().
+     */
+    void handleRecoverOk();
+
     /**
      * Called when a delivery appears for this consumer.
      * @param consumerTag the defined consumerTag (either client- or server-generated)

src/com/rabbitmq/client/DefaultConsumer.java

@@ -74,6 +74,13 @@ public void handleShutdownSignal(String consumerTag, ShutdownSignalException sig
         // no work to do
     }
 
+     /**
+     * No-op implementation of {@link Consumer#handleRecoverOk}.
+     */
+    public void handleRecoverOk() {
+        // no work to do
+    }
+
     /**
      * No-op implementation of {@link Consumer#handleDelivery}.
      */