Merge default into bug22964.

Author: Simon MacMullen

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 ${codegen.dir}/rabbitmq-0.8-extensions.json"/>
+  <property name="AMQP_SPEC_JSON_PATH" value="${codegen.dir}/amqp-rabbitmq-${spec.version}.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

@@ -457,6 +457,17 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      */
     void basicAck(long deliveryTag, boolean multiple) throws IOException;
 
+    /**
+     * Reject a message. Supply the deliveryTag from the {@link com.rabbitmq.client.AMQP.Basic.GetOk}
+     * or {@link com.rabbitmq.client.AMQP.Basic.Deliver} method
+     * containing the received message being rejected.
+     * @see com.rabbitmq.client.AMQP.Basic.Reject
+     * @param deliveryTag the tag from the received {@link com.rabbitmq.client.AMQP.Basic.GetOk} or {@link com.rabbitmq.client.AMQP.Basic.Deliver}
+     * @param requeue true if the rejected message should be requeued rather than discarded/dead-lettered
+     * @throws java.io.IOException if an error is encountered
+     */
+    void basicReject(long deliveryTag, boolean requeue) throws IOException;
+
     /**
      * Start a non-nolocal, non-exclusive consumer, with
      * explicit acknowledgements required and a server-generated consumerTag.

src/com/rabbitmq/client/ConnectionFactory.java

@@ -346,13 +346,13 @@ protected FrameHandler createFrameHandler(Socket sock)
     }
 
     /**
-     *  Provides a hook to insert custom configuration of the sockets used
-     *  to connect to an AMQP server before they connect. 
+     *  Provides a hook to insert custom configuration of the sockets
+     *  used to connect to an AMQP server before they connect.
      *
-     *  The default behaviour of this method is to disable Nagle's algorithm to get
-     *  more consistently low latency.
-     *  However it may be overridden freely and there is no requirement to retain
-     *  this behaviour. 
+     *  The default behaviour of this method is to disable Nagle's
+     *  algorithm to get more consistently low latency.  However it
+     *  may be overridden freely and there is no requirement to retain
+     *  this behaviour.
      *
      *  @param socket The socket that is to be used for the Connection
      */

src/com/rabbitmq/client/DefaultConsumer.java

@@ -45,7 +45,7 @@ public class DefaultConsumer implements Consumer {
 
     /**
      * Constructs a new instance and records its association to the passed-in channel.
-     * @param channel the channel on which the
+     * @param channel the channel to which this consumer is attached
      */
     public DefaultConsumer(Channel channel) {
         _channel = channel;

src/com/rabbitmq/client/QueueingConsumer.java

@@ -40,7 +40,37 @@
 import com.rabbitmq.utility.Utility;
 
 /**
- * Convenience class: an implementation of {@link Consumer} with straightforward blocking semantics
+ * Convenience class: an implementation of {@link Consumer} with
+ * straightforward blocking semantics.
+ *
+ * The general pattern for using QueueingConsumer is as follows:
+ *
+ * <pre>
+ * // Create connection and channel.
+ * {@link ConnectionFactory} factory = new ConnectionFactory();
+ * Connection conn = factory.newConnection();
+ * {@link Channel} ch1 = conn.createChannel();
+ *
+ * // Declare a queue and bind it to an exchange.
+ * String queueName = ch1.queueDeclare().{@link AMQP.Queue.DeclareOk#getQueue getQueue}();
+ * ch1.{@link Channel#queueBind queueBind}(queueName, exchangeName, queueName);
+ *
+ * // Create the QueueingConsumer and have it consume from the queue
+ * QueueingConsumer consumer = new {@link QueueingConsumer#QueueingConsumer QueueingConsumer}(ch1);
+ * ch1.{@link Channel#basicConsume basicConsume}(queueName, false, consumer);
+ *
+ * // Process deliveries
+ * while (/* some condition * /) {
+ *     {@link QueueingConsumer.Delivery} delivery = consumer.{@link QueueingConsumer#nextDelivery nextDelivery}();
+ *     // process delivery
+ *     ch1.{@link Channel#basicAck basicAck}(delivery.{@link QueueingConsumer.Delivery#getEnvelope getEnvelope}().{@link Envelope#getDeliveryTag getDeliveryTag}(), false);
+ * }
+ * </pre>
+ *
+ * <p>For a more detailed explanation, see <a href="http://www.rabbitmq.com/api-guide.html#consuming">the java api guide</a>.</p>
+ *
+ * <p>For a more complete example, see LogTail in the test/src/com/rabbitmq/examples
+ * directory of the source distribution.</p>
  */
 public class QueueingConsumer extends DefaultConsumer {
     private final BlockingQueue<Delivery> _queue;

src/com/rabbitmq/client/impl/ChannelN.java

@@ -646,6 +646,13 @@ public void basicAck(long deliveryTag, boolean multiple)
         transmit(new Basic.Ack(deliveryTag, multiple));
     }
 
+    /** Public API - {@inheritDoc} */
+    public void basicReject(long deliveryTag, boolean requeue)
+        throws IOException
+    {
+        transmit(new Basic.Reject(deliveryTag, requeue));
+    }
+
     /** Public API - {@inheritDoc} */
     public String basicConsume(String queue, Consumer callback)
         throws IOException

test/src/com/rabbitmq/client/test/BrokerTestCase.java

@@ -42,7 +42,8 @@
 import com.rabbitmq.client.GetResponse;
 import com.rabbitmq.client.MessageProperties;
 import com.rabbitmq.client.ShutdownSignalException;
-
+import com.rabbitmq.client.AlreadyClosedException;
+import com.rabbitmq.client.impl.ShutdownNotifierComponent;
 import com.rabbitmq.client.AMQP;
 
 public class BrokerTestCase extends TestCase
@@ -128,6 +129,16 @@ public void closeChannel()
 
     public void checkShutdownSignal(int expectedCode, IOException ioe) {
         ShutdownSignalException sse = (ShutdownSignalException) ioe.getCause();
+        checkShutdownSignal(expectedCode, sse);
+    }
+
+    public void checkShutdownSignal(int expectedCode, AlreadyClosedException ace) {
+        ShutdownNotifierComponent snc = (ShutdownNotifierComponent) ace.getReference();
+        ShutdownSignalException sse = snc.getCloseReason();
+        checkShutdownSignal(expectedCode, sse);
+    }
+
+    public void checkShutdownSignal(int expectedCode, ShutdownSignalException sse) {
         Command closeCommand = (Command) sse.getReason();
         channel = null;
         if (sse.isHardError()) {
@@ -140,6 +151,20 @@ public void checkShutdownSignal(int expectedCode, IOException ioe) {
         }
     }
 
+    public void expectChannelError(int error) {
+        try {
+            channel.basicQos(0);
+            fail("Expected channel error " + error);
+        } catch (IOException ioe) {
+            // If we get a channel close back when flushing it with the
+            // synchronous basicQos above.
+            checkShutdownSignal(error, ioe);
+        } catch (AlreadyClosedException ace) {
+            // If it has already closed of its own accord before we got there.
+            checkShutdownSignal(error, ace);
+        }
+    }
+
   protected void assertDelivered(String q, int count) throws IOException {
     assertDelivered(q, count, false);
   }