Naming, docs, cosmetics

Author: michaelklishin

src/com/rabbitmq/client/Connection.java

@@ -19,6 +19,7 @@
 import java.io.IOException;
 import java.net.InetAddress;
 import java.util.Map;
+import java.util.concurrent.ExecutorService;
 
 /**
  * Public API: Interface to an AMQ connection. See the see the <a href="http://www.amqp.org/">spec</a> for details.
@@ -94,11 +95,17 @@ public interface Connection extends ShutdownNotifier { // rename to AMQPConnecti
  Map<String, Object> getClientProperties();
 
  /**
- * Get connection name client property value
+ * Returns client-provided connection name, if any. Note that the value
+ * returned does not uniquely identify a connection and cannot be used
+ * as a connection identifier in HTTP API requests.
  *
- * @return string connection name from client properties, or null if there is not such property.
+ *
+ *
+ * @return client-provided connection name, if any
+ * @see ConnectionFactory#newConnection(Address[], String)
+ * @see ConnectionFactory#newConnection(ExecutorService, Address[], String)
  */
- String getConnectionName();
+ String getClientProvidedName();
 
  /**
  * Retrieve the server properties.

src/com/rabbitmq/client/ConnectionFactory.java

@@ -650,20 +650,24 @@ public Connection newConnection(Address[] addrs) throws IOException, TimeoutExce
 
 
  /**
- * Create a new broker connection, picking the first available address from
+ * Create a new broker connection with a client-provided name, picking the first available address from
  * the list.
  *
  * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
  * is enabled, the connection returned by this method will be {@link Recoverable}. Future
  * reconnection attempts will pick a random accessible address from the provided list.
  *
  * @param addrs an array of known broker addresses (hostname/port pairs) to try in order
- * @param connectionName arbitrary sring for connection name client property
+ * @param clientProvidedName application-specific connection name, will be displayed
+ * in the management UI if RabbitMQ server supports it.
+ * This value doesn't have to be unique and cannot be used
+ * as a connection identifier e.g. in HTTP API requests.
+ * This value is supposed to be human-readable.
  * @return an interface to the connection
  * @throws IOException if it encounters a problem
  */
- public Connection newConnection(Address[] addrs, String connectionName) throws IOException, TimeoutException {
- return newConnection(this.sharedExecutor, Arrays.asList(addrs), connectionName);
+ public Connection newConnection(Address[] addrs, String clientProvidedName) throws IOException, TimeoutException {
+ return newConnection(this.sharedExecutor, Arrays.asList(addrs), clientProvidedName);
  }
 
  /**
@@ -683,20 +687,24 @@ public Connection newConnection(List<Address> addrs) throws IOException, Timeout
  }
 
  /**
- * Create a new broker connection, picking the first available address from
+ * Create a new broker connection with a client-provided name, picking the first available address from
  * the list.
  *
  * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
  * is enabled, the connection returned by this method will be {@link Recoverable}. Future
  * reconnection attempts will pick a random accessible address from the provided list.
  *
  * @param addrs a List of known broker addresses (hostname/port pairs) to try in order
- * @param connectionName arbitrary sring for connection name client property
+ * @param clientProvidedName application-specific connection name, will be displayed
+ * in the management UI if RabbitMQ server supports it.
+ * This value doesn't have to be unique and cannot be used
+ * as a connection identifier e.g. in HTTP API requests.
+ * This value is supposed to be human-readable.
  * @return an interface to the connection
  * @throws IOException if it encounters a problem
  */
- public Connection newConnection(List<Address> addrs, String connectionName) throws IOException, TimeoutException {
- return newConnection(this.sharedExecutor, addrs, connectionName);
+ public Connection newConnection(List<Address> addrs, String clientProvidedName) throws IOException, TimeoutException {
+ return newConnection(this.sharedExecutor, addrs, clientProvidedName);
  }
 
  /**
@@ -719,7 +727,7 @@ public Connection newConnection(ExecutorService executor, Address[] addrs) throw
 
 
  /**
- * Create a new broker connection, picking the first available address from
+ * Create a new broker connection with a client-provided name, picking the first available address from
  * the list.
  *
  * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
@@ -728,13 +736,17 @@ public Connection newConnection(ExecutorService executor, Address[] addrs) throw
  *
  * @param executor thread execution service for consumers on the connection
  * @param addrs an array of known broker addresses (hostname/port pairs) to try in order
- * @param connectionName arbitrary sring for connection name client property
+ * @param clientProvidedName application-specific connection name, will be displayed
+ * in the management UI if RabbitMQ server supports it.
+ * This value doesn't have to be unique and cannot be used
+ * as a connection identifier e.g. in HTTP API requests.
+ * This value is supposed to be human-readable.
  * @return an interface to the connection
  * @throws java.io.IOException if it encounters a problem
  * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
  */
- public Connection newConnection(ExecutorService executor, Address[] addrs, String connectionName) throws IOException, TimeoutException {
- return newConnection(executor, Arrays.asList(addrs), connectionName);
+ public Connection newConnection(ExecutorService executor, Address[] addrs, String clientProvidedName) throws IOException, TimeoutException {
+ return newConnection(executor, Arrays.asList(addrs), clientProvidedName);
  }
 
  /**
@@ -756,7 +768,7 @@ public Connection newConnection(ExecutorService executor, List<Address> addrs) t
  }
 
  /**
- * Create a new broker connection, picking the first available address from
+ * Create a new broker connection with a client-provided name, picking the first available address from
  * the list.
  *
  * If <a href="http://www.rabbitmq.com/api-guide.html#recovery">automatic connection recovery</a>
@@ -765,20 +777,24 @@ public Connection newConnection(ExecutorService executor, List<Address> addrs) t
  *
  * @param executor thread execution service for consumers on the connection
  * @param addrs a List of known broker addrs (hostname/port pairs) to try in order
- * @param connectionName arbitrary sring for connection name client property
+ * @param clientProvidedName application-specific connection name, will be displayed
+ * in the management UI if RabbitMQ server supports it.
+ * This value doesn't have to be unique and cannot be used
+ * as a connection identifier e.g. in HTTP API requests.
+ * This value is supposed to be human-readable.
  * @return an interface to the connection
  * @throws java.io.IOException if it encounters a problem
  * @see <a href="http://www.rabbitmq.com/api-guide.html#recovery">Automatic Recovery</a>
  */
- public Connection newConnection(ExecutorService executor, List<Address> addrs, String connectionName)
+ public Connection newConnection(ExecutorService executor, List<Address> addrs, String clientProvidedName)
  throws IOException, TimeoutException {
  // make sure we respect the provided thread factory
  FrameHandlerFactory fhFactory = createFrameHandlerFactory();
  ConnectionParams params = params(executor);
- // set connection name client property
- if (connectionName != null) {
+ // set client-provided via a client property
+ if (clientProvidedName != null) {
  Map<String, Object> properties = new HashMap<String, Object>(params.getClientProperties());
- properties.put("connection_name", connectionName);
+ properties.put("connection_name", clientProvidedName);
  params.setClientProperties(properties);
  }
 

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

@@ -470,13 +470,8 @@ public Map<String, Object> getClientProperties() {
  return new HashMap<String, Object>(_clientProperties);
  }
 
- public String getConnectionName() {
- Object connectionName = _clientProperties.get("connection_name");
- if (connectionName == null){
- return null;
- } else {
- return connectionName.toString();
- }
+ public String getClientProvidedName() {
+ return (String) _clientProperties.get("connection_name");
  }
 
  /**

src/com/rabbitmq/client/impl/recovery/AutorecoveringConnection.java

@@ -5,6 +5,7 @@
 import com.rabbitmq.client.BlockedListener;
 import com.rabbitmq.client.Channel;
 import com.rabbitmq.client.Connection;
+import com.rabbitmq.client.ConnectionFactory;
 import com.rabbitmq.client.MissedHeartbeatException;
 import com.rabbitmq.client.Recoverable;
 import com.rabbitmq.client.RecoveryListener;
@@ -27,6 +28,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
 import java.util.concurrent.TimeoutException;
 
 /**
@@ -157,10 +159,12 @@ public Map<String, Object> getClientProperties() {
  }
 
  /**
- * @see com.rabbitmq.client.Connection#getConnectionName()
+ * @see com.rabbitmq.client.Connection#getClientProvidedName()
+ * @see ConnectionFactory#newConnection(Address[], String)
+ * @see ConnectionFactory#newConnection(ExecutorService, Address[], String)
  */
- public String getConnectionName() {
- return delegate.getConnectionName();
+ public String getClientProvidedName() {
+ return delegate.getClientProvidedName();
  }
 
  /**

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

@@ -177,33 +177,33 @@ public void testConnectionHangInNegotiation() {
  assertEquals("Wrong type of exception returned.", SocketTimeoutException.class, exceptionList.get(0).getClass());
  }
 
- public void testConnectionName() throws IOException, TimeoutException {
- String connectionName = "custom name";
- Connection connection = factory.newConnection(connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ public void testClientProvidedConnectionName() throws IOException, TimeoutException {
+ String providedName = "event consumers connection";
+ Connection connection = factory.newConnection(providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
 
- List<Address> addresses_list = Arrays.asList(new Address("127.0.0.1"), new Address("127.0.0.1", 5672));
- connection = factory.newConnection(addresses_list, connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ List<Address> addrs1 = Arrays.asList(new Address("127.0.0.1"), new Address("127.0.0.1", 5672));
+ connection = factory.newConnection(addrs1, providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
 
- Address[] addresses_arr = {new Address("127.0.0.1"), new Address("127.0.0.1", 5672)};
- connection = factory.newConnection(addresses_arr, connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ Address[] addrs2 = {new Address("127.0.0.1"), new Address("127.0.0.1", 5672)};
+ connection = factory.newConnection(addrs2, providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
 
- ExecutorService executor = Executors.newSingleThreadExecutor();
- connection = factory.newConnection(executor, connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ ExecutorService xs = Executors.newSingleThreadExecutor();
+ connection = factory.newConnection(xs, providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
 
- connection = factory.newConnection(executor, addresses_list, connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ connection = factory.newConnection(xs, addrs1, providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
 
- connection = factory.newConnection(executor, addresses_arr, connectionName);
- assertEquals(connectionName, connection.getConnectionName());
+ connection = factory.newConnection(xs, addrs2, providedName);
+ assertEquals(providedName, connection.getClientProvidedName());
  connection.close();
  }
 

test/src/com/rabbitmq/client/test/functional/ConnectionRecovery.java

@@ -36,10 +36,10 @@ public void testNamedConnectionRecovery()
  AutorecoveringConnection c = newRecoveringConnection(connectionName);
  try {
  assertTrue(c.isOpen());
- assertEquals(connectionName, c.getConnectionName());
+ assertEquals(connectionName, c.getClientProvidedName());
  closeAndWaitForRecovery(c);
  assertTrue(c.isOpen());
- assertEquals(connectionName, c.getConnectionName());
+ assertEquals(connectionName, c.getClientProvidedName());
  } finally {
  c.abort();
  }