Merge default into bug 22889.

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

@@ -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/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;
@@ -345,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/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/AMQConnection.java

@@ -54,17 +54,8 @@
 /**
  * Concrete class representing and managing an AMQP connection to a broker.
  * <p>
- * To connect to a broker,
- *
- * <pre>
- * AMQConnection conn = new AMQConnection(hostName, portNumber);
- * conn.open(username, portNumber, virtualHost);
- * </pre>
- *
- * <pre>
- * ChannelN ch1 = conn.createChannel(1);
- * ch1.open(&quot;&quot;);
- * </pre>
+ * To create a broker connection, use {@link ConnectionFactory}.  See {@link Connection}
+ * for an example.
  */
 public class AMQConnection extends ShutdownNotifierComponent implements Connection {
     /** Timeout used while waiting for AMQP handshaking to complete (milliseconds) */
@@ -79,7 +70,7 @@ public class AMQConnection extends ShutdownNotifierComponent implements Connecti
      * method is called when each new ConnectionFactory instance is
      * constructed.
      * @return a map of client properties
-     * @see Connection.getClientProperties()
+     * @see Connection#getClientProperties
      */
     public static Map<String, Object> defaultClientProperties() {
         return Frame.buildTable(new Object[] {
@@ -134,7 +125,7 @@ public static Map<String, Object> defaultClientProperties() {
 
     /**
      * Protected API - respond, in the driver thread, to a ShutdownSignal.
-     * @param channelNumber the number of the channel to disconnect
+     * @param channel the channel to disconnect
      */
     public final void disconnectChannel(ChannelN channel) {
         _channelManager.disconnectChannel(channel);

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

@@ -64,8 +64,8 @@
  * To open a channel,
  * <pre>
  * {@link Connection} conn = ...;
- * {@link ChannelN} ch1 = conn.{@link Connection#createChannel createChannel}(1);
- * ch1.{@link ChannelN#open open}("");
+ * {@link ChannelN} ch1 = conn.{@link Connection#createChannel createChannel}();
+ * ch1.{@link ChannelN#open open}();
  * </pre>
  */
 public class ChannelN extends AMQChannel implements com.rabbitmq.client.Channel {