Fixed javadoc and null checks.

Signed-off-by: pellmann <marc.pellmann@bosch-si.com>
eclipse-hono · May 22, 2018 · 4cee1c5 · 4cee1c5
1 parent e0676e7
commit 4cee1c5
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 40 deletions.
diff --git a/service-base/src/main/java/org/eclipse/hono/service/command/CommandConnection.java b/service-base/src/main/java/org/eclipse/hono/service/command/CommandConnection.java
@@ -29,27 +29,30 @@
 public interface CommandConnection extends HonoClient {
 
     /**
-     * Creates a receiver link in the CommandConsumer and a message handler for Commands.
+     *
+     * Creates a new consumer of commands for a tenants device.
      * 
      * @param tenantId The tenant to consume commands from.
-     * @param deviceId The device for which the receiver will be created.
-     * @param messageConsumer The message handler for the received commands.
-     * @param closeHandler The close handler for the receiver.
-     * @return A future, with a MessageConsumer.
-     * @throws NullPointerException if tenantId, deviceId or messageConsumer is {@code null};
+     * @param deviceId The device for which the consumer will be created.
+     * @param commandConsumer The handler to invoke with every command received.
+     * @param closeHandler The handler invoked when the peer detaches the link.
+     * @return A future that will complete with the consumer once the link has been established. The future will fail if
+     *         the link cannot be established, e.g. because this client is not connected.
+     * @throws NullPointerException if tenantId, deviceId or messageConsumer is {@code null}.
      */
     Future<MessageConsumer> createCommandConsumer(String tenantId, String deviceId,
-            BiConsumer<ProtonDelivery, Message> messageConsumer,
+            BiConsumer<ProtonDelivery, Message> commandConsumer,
             Handler<Void> closeHandler);
 
     /**
-     * Send back a response for a command to the business application.
+     * Gets a sender for sending command responses back to the business application.
      * 
-     * @param tenantId The data to send back or {@code null}.
-     * @param deviceId The data to send back or {@code null}.
-     * @param replyId The data to send back or {@code null}.
-     * @return A ProtonDelivery indicating the success
-     * @throws NullPointerException if commandToResponse is {@code null};
+     * @param tenantId The ID of the tenant to send the command responses for.
+     * @param deviceId The ID of the device to send the command responses for.
+     * @param replyId The ID used to build the reply address as {@code control/tenantId/deviceId/replyId}.
+     * @return A future that will complete with the sender once the link has been established. The future will fail if
+     *         the link cannot be established, e.g. because this client is not connected.
+     * @throws NullPointerException if tenantId, deviceId or replyId is {@code null}.
      */
     Future<CommandResponseSender> getOrCreateCommandResponseSender(String tenantId, String deviceId, String replyId);
 }
diff --git a/service-base/src/main/java/org/eclipse/hono/service/command/CommandConnectionImpl.java b/service-base/src/main/java/org/eclipse/hono/service/command/CommandConnectionImpl.java
@@ -57,12 +57,12 @@ public CommandConnectionImpl(final Vertx vertx, final ClientConfigProperties cli
     public final Future<MessageConsumer> createCommandConsumer(
             final String tenantId,
             final String deviceId,
-            final BiConsumer<ProtonDelivery, Message> messageConsumer,
+            final BiConsumer<ProtonDelivery, Message> commandConsumer,
             final Handler<Void> closeHandler) {
 
         return createConsumer(
                 tenantId,
-                () -> newCommandConsumer(tenantId, deviceId, messageConsumer, closeHandler));
+                () -> newCommandConsumer(tenantId, deviceId, commandConsumer, closeHandler));
     }
 
     private Future<MessageConsumer> newCommandConsumer(

diff --git a/service-base/src/main/java/org/eclipse/hono/service/command/CommandConsumer.java b/service-base/src/main/java/org/eclipse/hono/service/command/CommandConsumer.java
@@ -1,5 +1,6 @@
 package org.eclipse.hono.service.command;
 
+import java.util.Objects;
 import java.util.function.BiConsumer;
 
 import org.apache.qpid.proton.message.Message;
@@ -28,31 +29,23 @@ public class CommandConsumer extends AbstractConsumer implements MessageConsumer
 
     private static final Logger LOG = LoggerFactory.getLogger(CommandConsumer.class);
 
-    /**
-     * Creates a client for a vert.x context.
-     *
-     * @param context The context to run all interactions with the server on.
-     * @param config The configuration properties to use.
-     * @param protonReceiver The receiver for commands.
-     * @throws NullPointerException if any of the parameters is {@code null}.
-     */
     private CommandConsumer(final Context context, final ClientConfigProperties config,
             final ProtonReceiver protonReceiver) {
         super(context, config, protonReceiver);
     }
 
     /**
-     * Creates a new command adapter.
+     * Creates a new command consumer.
      *
      * @param context The vert.x context to run all interactions with the server on.
      * @param clientConfig The configuration properties to use.
      * @param con The AMQP connection to the server.
-     * @param tenantId The tenant.
-     * @param deviceId The device.
-     * @param messageConsumer Message consumer.
+     * @param tenantId The tenant to consume commands from.
+     * @param deviceId The device for wich the commands should be consumed.
+     * @param messageConsumer The consumer to invoke with each command received.
      * @param receiverCloseHook A handler to invoke if the peer closes the receiver link unexpectedly.
      * @param creationHandler The handler to invoke with the outcome of the creation attempt.
-     * @throws NullPointerException if any of the parameters other than cache manager is {@code null}.
+     * @throws NullPointerException if any of the parameters is {@code null}.
      */
     public static final void create(
             final Context context,
@@ -64,19 +57,28 @@ public static final void create(
             final Handler<String> receiverCloseHook,
             final Handler<AsyncResult<MessageConsumer>> creationHandler) {
 
-        LOG.debug("creating new command adapter for [{}, {}]", tenantId, deviceId);
+        Objects.requireNonNull(context);
+        Objects.requireNonNull(clientConfig);
+        Objects.requireNonNull(con);
+        Objects.requireNonNull(tenantId);
+        Objects.requireNonNull(deviceId);
+        Objects.requireNonNull(messageConsumer);
+        Objects.requireNonNull(receiverCloseHook);
+        Objects.requireNonNull(creationHandler);
+
+        LOG.debug("creating new command consumer for [{}, {}]", tenantId, deviceId);
 
         final String address = ResourceIdentifier.from(CommandConstants.COMMAND_ENDPOINT, tenantId, deviceId).toString();
         AbstractHonoClient
                 .createReceiver(context, clientConfig, con, address, ProtonQoS.AT_LEAST_ONCE, messageConsumer::accept,
                         receiverCloseHook)
                 .setHandler(s -> {
                     if (s.succeeded()) {
-                        LOG.debug("successfully created command adapter for [{}, {}]", tenantId, deviceId);
+                        LOG.debug("successfully created command consumer for [{}, {}]", tenantId, deviceId);
                         creationHandler
                                 .handle(Future.succeededFuture(new CommandConsumer(context, clientConfig, s.result())));
                     } else {
-                        LOG.debug("failed to create command adapter for [{}, {}]", tenantId, deviceId, s.cause());
+                        LOG.debug("failed to create command consumer for [{}, {}]", tenantId, deviceId, s.cause());
                         creationHandler.handle(Future.failedFuture(s.cause()));
                     }
                 });

diff --git a/service-base/src/main/java/org/eclipse/hono/service/command/CommandResponseSender.java b/service-base/src/main/java/org/eclipse/hono/service/command/CommandResponseSender.java
@@ -13,7 +13,7 @@
 public interface CommandResponseSender extends MessageSender {
 
     /**
-     * Creates the response message.
+     * Sends a response message to a command back to the business application.
      *
      * @param tenantId The tenant that the command response will be send for and the device belongs to.
      * @param deviceId The device that sends the command.
@@ -22,7 +22,7 @@ public interface CommandResponseSender extends MessageSender {
      * @param payload The payload or {@code null}.
      * @param properties The properties or {@code null}.
      * @param status The status of the command, which was send to the device.
-     * @return The response message to be send back to the command sender.
+     * @return A future indicating the outcome of the operation.
      * @throws NullPointerException if any of tenantId, deviceId, replyId or correlationId is {@code null}.
      */
     Future<ProtonDelivery> sendCommandResponse(

diff --git a/service-base/src/main/java/org/eclipse/hono/service/command/CommandResponseSenderImpl.java b/service-base/src/main/java/org/eclipse/hono/service/command/CommandResponseSenderImpl.java
@@ -103,19 +103,17 @@ private static Message createResponseMessage(
     }
 
     /**
-     * Creates a new sender for publishing events to a Hono server.
+     * Creates a new sender to send responses for commands back to the business application.
      *
      * @param context The vertx context to run all interactions with the server on.
      * @param clientConfig The configuration properties to use.
      * @param con The connection to the AMQP network.
      * @param tenantId The tenant that the command response will be send for and the device belongs to.
-     * @param deviceId The device that sends the command.
+     * @param deviceId The device that sends the command response.
      * @param replyId The reply id as the unique postfix of the replyTo address.
-     * @param closeHook The handler to invoke when the Hono server closes the sender. The sender's target address is
-     *            provided as an argument to the handler.
+     * @param closeHook A handler to invoke if the peer closes the link unexpectedly.
      * @param creationHandler The handler to invoke with the result of the creation attempt.
-     * @throws NullPointerException if any of context, connection, tenant or handler is {@code null}.
-     * @throws IllegalArgumentException if waitForInitialCredits is {@code < 1}.
+     * @throws NullPointerException if any of context, clientConfig, con, tenantId, deviceId or replyId  is {@code null}.
      */
     public static void create(
             final Context context,
@@ -128,9 +126,11 @@ public static void create(
             final Handler<AsyncResult<MessageSender>> creationHandler) {
 
         Objects.requireNonNull(context);
+        Objects.requireNonNull(clientConfig);
         Objects.requireNonNull(con);
         Objects.requireNonNull(tenantId);
-        Objects.requireNonNull(creationHandler);
+        Objects.requireNonNull(deviceId);
+        Objects.requireNonNull(replyId);
 
         final String targetAddress = CommandResponseSenderImpl.getTargetAddress(tenantId, deviceId, replyId);
         createSender(context, clientConfig, con, targetAddress, ProtonQoS.AT_LEAST_ONCE, closeHook).compose(sender -> {