Merging default into bug22956

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.properties

@@ -13,7 +13,7 @@ test.javac.out=${build.out}/test/classes
 test.src.home=test/src
 java-jvm-1.4=c:/Program Files/java/j2re1.4.2_14/bin/java
 sibling.codegen.dir=../rabbitmq-codegen/
-spec.version=0.8
+spec.version=0.9.1
 bundle.out=${build.out}/bundle
 javadoc.out=build/doc/api
 python.bin=python

build.xml

@@ -26,8 +26,8 @@
     <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">
       <srcfiles file="codegen.py"/>
@@ -40,7 +40,7 @@
       </compositemapper>
     </uptodate>
   </target>
-  
+
   <target name="amqp-generate" depends="amqp-generate-check"
     unless="amqp.generate.notRequired" description="generate AMQP.java and AMQImpl.java from AMQP spec">
     <mkdir dir="${src.generated}/com/rabbitmq/client/"/>
@@ -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">
@@ -167,12 +171,12 @@
       <arg value="${CLIENT_KEYSTORE_PHRASE}"/>
     </exec>
   </target>
-  
+
   <target name="remove-client-keystore" if="SSL_AVAILABLE">
     <delete file="${CLIENT_KEYSTORE}" failonerror="false"/>
     <delete file="${CLIENT_KEYSTORE_EMPTY}" failonerror="false"/>
   </target>
-  
+
   <target name="test-prepare">
 	<property name="haltOnFailureJunit" value="yes" />
   	<property name="haltOnFailureJava" value="true" />
@@ -314,10 +318,10 @@
 
   <target name="test-suite-prepare">
   	<property name="haltOnFailureJunit" value="no" />
-  	<property name="haltOnFailureJava" value="false" />	
+  	<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>
@@ -328,8 +332,8 @@
   </target>
 
   <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"
@@ -351,7 +355,7 @@
       <jvmarg value="-Dkeystore.path=${CLIENT_KEYSTORE}"/>
       <jvmarg value="-Dkeystore.empty.path=${CLIENT_KEYSTORE_EMPTY}"/>
       <jvmarg value="-Dkeystore.passwd=${CLIENT_KEYSTORE_PHRASE}"/>
-      
+
       <jvmarg value="-Dp12.path=${SSL_CERTS_DIR}/client/keycert.p12"/>
       <jvmarg value="-Dp12.passwd=${SSL_P12_PASSWORD}"/>
 
@@ -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"
@@ -475,16 +479,16 @@
       <fileset dir="lib">
         <include name="**/*.jar"/>
       </fileset>
-      
+
       <fileset dir="${lib.out}">
         <include name="**/*.jar"/>
       </fileset>
-      
+
       <fileset dir="scripts">
         <include name="**/*.sh"/>
         <include name="**/*.bat"/>
       </fileset>
-      
+
       <fileset file="${retrotranslator}/retrotranslator-runtime-1.2.1.jar"/>
       <fileset file="${retrotranslator}/backport-util-concurrent-3.0.jar"/>
     </copy>

codegen.py

@@ -150,6 +150,7 @@ def printHeader():
     public static class PROTOCOL {"""
         print "        public static final int MAJOR = %i;" % spec.major
         print "        public static final int MINOR = %i;" % spec.minor
+        print "        public static final int REVISION = %i;" % spec.revision
         print "        public static final int PORT = %i;" % spec.port
         print "    }"
 

src/com/rabbitmq/client/BasicProperties.java

@@ -114,12 +114,6 @@ public interface BasicProperties {
      */
     public abstract String getAppId();
 
-    /**
-     * Retrieve the value in the clusterId field.
-     * @return clusterId field, or null if the field has not been set.
-     */
-    public abstract String getClusterId();
-
     /**
      * Set the contentType field, or null indicating the field is not set
      * @param contentType the value to set the field to
@@ -198,9 +192,4 @@ public interface BasicProperties {
      */
     public abstract void setAppId(String appId);
 
-    /**
-     * Set the clusterId field, or null indicating the field is not set
-     * @param clusterId the value to set the field to
-     */
-    public abstract void setClusterId(String clusterId);
 }

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.
@@ -467,7 +478,7 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      * @see com.rabbitmq.client.AMQP.Basic.Consume
      * @see com.rabbitmq.client.AMQP.Basic.ConsumeOk
      * @see #basicAck
-     * @see #basicConsume(String,boolean, String,boolean,boolean, Consumer)
+     * @see #basicConsume(String,boolean, String,boolean,boolean, Map, Consumer)
      */
     String basicConsume(String queue, Consumer callback) throws IOException;
 
@@ -481,7 +492,7 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      * @throws java.io.IOException if an error is encountered
      * @see com.rabbitmq.client.AMQP.Basic.Consume
      * @see com.rabbitmq.client.AMQP.Basic.ConsumeOk
-     * @see #basicConsume(String,boolean, String,boolean,boolean, Consumer)
+     * @see #basicConsume(String,boolean, String,boolean,boolean, Map, Consumer)
      */
     String basicConsume(String queue, boolean noAck, Consumer callback) throws IOException;
 
@@ -495,7 +506,7 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      * @throws java.io.IOException if an error is encountered
      * @see com.rabbitmq.client.AMQP.Basic.Consume
      * @see com.rabbitmq.client.AMQP.Basic.ConsumeOk
-     * @see #basicConsume(String,boolean, String,boolean,boolean, Consumer)
+     * @see #basicConsume(String,boolean, String,boolean,boolean, Map, Consumer)
      */
     String basicConsume(String queue, boolean noAck, String consumerTag, Consumer callback) throws IOException;
 
@@ -513,7 +524,7 @@ Queue.DeclareOk queueDeclare(String queue, boolean durable, boolean exclusive, b
      * @see com.rabbitmq.client.AMQP.Basic.Consume
      * @see com.rabbitmq.client.AMQP.Basic.ConsumeOk
      */
-    String basicConsume(String queue, boolean noAck, String consumerTag, boolean noLocal, boolean exclusive, Consumer callback) throws IOException;
+    String basicConsume(String queue, boolean noAck, String consumerTag, boolean noLocal, boolean exclusive, Map<String, Object> filter, Consumer callback) throws IOException;
 
     /**
      * Cancel a consumer. Calls the consumer's {@link Consumer#handleCancelOk}

src/com/rabbitmq/client/Connection.java

@@ -98,12 +98,6 @@ public interface Connection extends ShutdownNotifier { // rename to AMQPConnecti
      */
     Map<String, Object> getClientProperties();
 
-    /**
-     * Retrieve the known hosts.
-     * @return an array of addresses for all hosts that came back in the initial {@link com.rabbitmq.client.AMQP.Connection.OpenOk} open-ok method
-     */
-    Address[] getKnownHosts();
-
     /**
      * Retrieve the server properties.
      * @return a map of the server properties. This typically includes the product name and version of the server.