Add comment for some method

duhengforever · duhengforever · commit 9402d976790e · 2018-08-28T11:32:37.000+08:00
diff --git a/openmessaging-api-samples/src/main/java/io/openmessaging/samples/consumer/PullConsumerApp.java b/openmessaging-api-samples/src/main/java/io/openmessaging/samples/consumer/PullConsumerApp.java
@@ -2,7 +2,7 @@
 
 import io.openmessaging.MessagingAccessPoint;
 import io.openmessaging.OMS;
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import io.openmessaging.consumer.BindResult;
 import io.openmessaging.consumer.Consumer;
 import io.openmessaging.consumer.ReceiveResult;
@@ -17,7 +17,7 @@ public static void main(String[] args) {
 
         //Fetch a ResourceManager to create Queue resource.
         ResourceManager resourceManager = messagingAccessPoint.resourceManager();
-        Response createQueueResult = resourceManager.createQueue("NS://HELLO_QUEUE", new QueueConfig() {
+        Result createQueueResult = resourceManager.createQueue("NS://HELLO_QUEUE", new QueueConfig() {
             @Override public void setFifo(boolean isFifo) {
 
             }
diff --git a/openmessaging-api-samples/src/main/java/io/openmessaging/samples/consumer/PushConsumerApp.java b/openmessaging-api-samples/src/main/java/io/openmessaging/samples/consumer/PushConsumerApp.java
@@ -20,7 +20,7 @@
 import io.openmessaging.Message;
 import io.openmessaging.MessagingAccessPoint;
 import io.openmessaging.OMS;
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import io.openmessaging.consumer.Consumer;
 import io.openmessaging.consumer.MessageListener;
 import io.openmessaging.exception.OMSResourceNotExistException;
@@ -48,7 +48,9 @@ public void run() {
 
         //Consume messages from a simple queue.
         String simpleQueue = "NS://HELLO_QUEUE";
-        Response result = resourceManager.createQueue(simpleQueue);
+        Result result = resourceManager.createQueue(simpleQueue);
+        //This queue doesn't has a source queue, so only the message delivered to the queue directly can
+        //be consumed by this consumer.
         if (result.isSuccess()){
             consumer.bindQueue(simpleQueue, new MessageListener() {
                 @Override
@@ -61,9 +63,6 @@ public void onReceived(Message message, Context context) {
         }else {
             System.out.println("error: " + result.getError().getErrorCode() + " error message: " + result );
         }
-        //This queue doesn't has a source queue, so only the message delivered to the queue directly can
-        //be consumed by this consumer.
-
 
         consumer.unbindQueue(simpleQueue);
 
diff --git a/openmessaging-api/src/main/java/io/openmessaging/MessagingAccessPoint.java b/openmessaging-api/src/main/java/io/openmessaging/MessagingAccessPoint.java
@@ -17,7 +17,7 @@
 
 package io.openmessaging;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import io.openmessaging.consumer.Consumer;
 import io.openmessaging.consumer.ConsumerConfig;
 import io.openmessaging.consumer.MessageListener;
@@ -26,7 +26,6 @@
 import io.openmessaging.manager.ResourceManager;
 import io.openmessaging.producer.Producer;
 import io.openmessaging.producer.ProducerConfig;
-import java.util.jar.Attributes;
 
 /**
  * An instance of {@code MessagingAccessPoint} may be obtained from {@link OMS}, which is capable of creating {@code
@@ -44,7 +43,7 @@
  * @version OMS 1.0.0
  * @since OMS 1.0.0
  */
-public interface MessagingAccessPoint extends Response {
+public interface MessagingAccessPoint extends Result {
 
     /**
      * Returns the target OMS specification version of the specified vendor implementation.
diff --git a/openmessaging-api/src/main/java/io/openmessaging/common/Result.java b/openmessaging-api/src/main/java/io/openmessaging/common/Result.java
@@ -3,7 +3,7 @@
 import jdk.nashorn.internal.ir.annotations.Immutable;
 
 @Immutable
-public interface Response {
+public interface Result {
 
     /**
      * Get execution error
diff --git a/openmessaging-api/src/main/java/io/openmessaging/consumer/AckResult.java b/openmessaging-api/src/main/java/io/openmessaging/consumer/AckResult.java
@@ -1,8 +1,8 @@
 package io.openmessaging.consumer;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 
-public interface AckResult extends Response {
+public interface AckResult extends Result {
     /**
      * The unique receiptHandle related to the {@link Consumer#ack(String)} instance.
      * @return the message id
diff --git a/openmessaging-api/src/main/java/io/openmessaging/consumer/BindResult.java b/openmessaging-api/src/main/java/io/openmessaging/consumer/BindResult.java
@@ -1,7 +1,7 @@
 package io.openmessaging.consumer;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 
-public interface BindResult extends Response {
+public interface BindResult extends Result {
     String queueName();
 }
diff --git a/openmessaging-api/src/main/java/io/openmessaging/consumer/Consumer.java b/openmessaging-api/src/main/java/io/openmessaging/consumer/Consumer.java
@@ -21,7 +21,7 @@
 import io.openmessaging.MessagingAccessPoint;
 import io.openmessaging.ServiceLifecycle;
 import io.openmessaging.common.Error;
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import io.openmessaging.exception.OMSRuntimeException;
 import io.openmessaging.interceptor.ConsumerInterceptor;
 
@@ -135,7 +135,7 @@ public interface Consumer extends ServiceLifecycle {
      *
      * @param timeout receive message will blocked at most <code>timeout</code> milliseconds
      * @return the next message received from the bind queues, or null if the consumer is concurrently shut down,if this
-     * operation is expire, {@link Response#getError()} will return {@link Error#ERROR_408} error
+     * operation is expire, {@link Result#getError()} will return {@link Error#ERROR_408} error
      * code
      */
     ReceiveResult receive(long timeout);
diff --git a/openmessaging-api/src/main/java/io/openmessaging/consumer/ConsumerConfig.java b/openmessaging-api/src/main/java/io/openmessaging/consumer/ConsumerConfig.java
@@ -66,8 +66,11 @@ enum ConsumeStartPoint {
     boolean isAutoAckMode();
 
     /**
-     * @param consumeStartPoint
-     * @param startTime
+     * When a consumer start to consume message, this method is used to specify the starting point of consumption.
+     *
+     * @param consumeStartPoint consume strategy
+     * @param startTime this parameter is used to specify a start time when {@link ConsumeStartPoint#SPECIFIED_TIME}
+     * strategy is set
      */
     void setConsumeStartPoint(ConsumeStartPoint consumeStartPoint, long startTime);
 }
diff --git a/openmessaging-api/src/main/java/io/openmessaging/consumer/ReceiveResult.java b/openmessaging-api/src/main/java/io/openmessaging/consumer/ReceiveResult.java
@@ -1,9 +1,9 @@
 package io.openmessaging.consumer;
 
 import io.openmessaging.Message;
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 
-public interface ReceiveResult extends Response {
+public interface ReceiveResult extends Result {
     /**
      * Received message from bind queue in pull model
      * @return {@link Message} received message
diff --git a/openmessaging-api/src/main/java/io/openmessaging/manager/ListQueueResult.java b/openmessaging-api/src/main/java/io/openmessaging/manager/ListQueueResult.java
@@ -1,8 +1,8 @@
 package io.openmessaging.manager;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import java.util.List;
 
-public interface ListQueueResult extends Response {
+public interface ListQueueResult extends Result {
     List<String> queues();
 }
diff --git a/openmessaging-api/src/main/java/io/openmessaging/manager/ListStreamResult.java b/openmessaging-api/src/main/java/io/openmessaging/manager/ListStreamResult.java
@@ -1,8 +1,8 @@
 package io.openmessaging.manager;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import java.util.List;
 
-public interface ListStreamResult extends Response {
+public interface ListStreamResult extends Result {
     List<String> streams();
 }
diff --git a/openmessaging-api/src/main/java/io/openmessaging/manager/ResourceManager.java b/openmessaging-api/src/main/java/io/openmessaging/manager/ResourceManager.java
@@ -19,7 +19,7 @@
 
 import io.openmessaging.MessagingAccessPoint;
 import io.openmessaging.common.Error;
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 import java.util.List;
 
 /**
@@ -46,15 +46,15 @@ public interface ResourceManager {
      *
      * @param nsName the name of the new namespace
      */
-    Response createNamespace(String nsName);
+    Result createNamespace(String nsName);
 
     /**
      * Deletes an existing namespace resource.
      *
      * @param nsName the namespace needs to be deleted
-     * @return {@link Response#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
      */
-    Response deleteNamespace(String nsName);
+    Result deleteNamespace(String nsName);
 
     /**
      * Gets the namespace list in the current {@code MessagingAccessPoint}.
@@ -71,9 +71,9 @@ public interface ResourceManager {
      * {@literal <namespace_name>://<queue_name>}
      *
      * @param queueName the name of the new queue
-     * @return {@link Response#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
      */
-    Response createQueue(String queueName);
+    Result createQueue(String queueName);
 
     /**
      * Creates a {@code Queue} resource in the configured namespace with some preset attributes.
@@ -84,41 +84,41 @@ public interface ResourceManager {
      *
      * @param queueName the name of the new queue
      * @param queueConfig the preset config
-     * @return {@link Response#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
      */
-    Response createQueue(String queueName, QueueConfig queueConfig);
+    Result createQueue(String queueName, QueueConfig queueConfig);
 
     /**
      * Sets the attributes of the specified queue, the old attributes will be replaced by the provided attributes, only
      * the provided key will be updated.
      *
      * @param queueName the queue name
      * @param queueConfig the new attributes
-     * @return {@link Response#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_402} if the specific namespace does not exist
      */
-    Response setQueueConfig(String queueName, QueueConfig queueConfig);
+    Result setQueueConfig(String queueName, QueueConfig queueConfig);
 
     /**
      * Gets the attributes of the specified queue.
      *
      * @param queueName the queue name
-     * @return {@link Response#getError()} will return {@link Error#ERROR_403} if the specific queue does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_403} if the specific queue does not exist
      */
     QueueConfig getQueueConfig(String queueName);
 
     /**
      * Deletes an existing queue resource.
      *
      * @param queueName the queue needs to be deleted
-     * @return {@link Response#getError()} will return {@link Error#ERROR_403} if the specific queue does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_403} if the specific queue does not exist
      */
-    Response deleteQueue(String queueName);
+    Result deleteQueue(String queueName);
 
     /**
      * Gets the queue list in the specific namespace.
      *
      * @param nsName the specific namespace
-     * @return the list of all queues, {@link Response#getError()}  will return {@link Error#ERROR_402} if the specific
+     * @return the list of all queues, {@link Result#getError()}  will return {@link Error#ERROR_402} if the specific
      * namespace does not exist
      */
     ListQueueResult listQueues(String nsName);
@@ -131,33 +131,33 @@ public interface ResourceManager {
      * @param targetQueueName target queue, only receives message from original queue
      * @return
      */
-    Response duplicate(String sourceQueueName, String targetQueueName);
+    Result duplicate(String sourceQueueName, String targetQueueName);
 
     /**
-     * Add filter to
+     * In order to enable consumers to get the message in the specified mode, OpenMessaging recommend  use SQL
+     * expression to filter out messages.
      *
-     * @param queueName
-     * @param consumerId
-     * @param filterString
+     * @param queueName queue name
+     * @param filterString SQL expression to filter out messages.
      * @return
      */
-    Response filter(String queueName, String consumerId, String filterString);
+    Result filter(String queueName, String filterString);
 
     /**
-     * Deduplicate current  queue from sourceQueue, after this operation, destinationQueue  will no longer receive
-     * messages sent to the source queue.
+     * Deduplicate current  queue from sourceQueue, after this operation, <code>targetQueue</code>  will no longer
+     * receive messages sent to the source queue.
      *
      * @param sourceQueue source queue, process messages received from producer and duplicate those to target queue
      * @param targetQueue receive messages from source queue.
      * @return
      */
-    Response deDuplicate(String sourceQueue, String targetQueue);
+    Result deDuplicate(String sourceQueue, String targetQueue);
 
     /**
      * Gets the stream list behind the specified queue.
      *
      * @param queueName the queue name
-     * @return {@link Response#getError()} will return {@link Error#ERROR_403} if the specific namespace does not exist
+     * @return {@link Result#getError()} will return {@link Error#ERROR_403} if the specific namespace does not exist
      */
     ListStreamResult listStreams(String queueName);
 
diff --git a/openmessaging-api/src/main/java/io/openmessaging/producer/SendResult.java b/openmessaging-api/src/main/java/io/openmessaging/producer/SendResult.java
@@ -17,15 +17,15 @@
 
 package io.openmessaging.producer;
 
-import io.openmessaging.common.Response;
+import io.openmessaging.common.Result;
 
 /**
  * The result of sending a OMS message to server with the message id and some attributes.
  *
  * @version OMS 1.0.0
  * @since OMS 1.0.0
  */
-public interface SendResult extends Response {
+public interface SendResult extends Result {
     /**
      * The unique message id related to the {@code SendResult} instance.
      *

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`package io.openmessaging.consumer;`
`2`	`2`
`3`		`-import io.openmessaging.common.Response;`
	`3`	`+import io.openmessaging.common.Result;`
`4`	`4`
`5`		`-public interface BindResult extends Response {`
	`5`	`+public interface BindResult extends Result {`
`6`	`6`	`String queueName();`
`7`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`package io.openmessaging.manager;`
`2`	`2`
`3`		`-import io.openmessaging.common.Response;`
	`3`	`+import io.openmessaging.common.Result;`
`4`	`4`	`import java.util.List;`
`5`	`5`
`6`		`-public interface ListQueueResult extends Response {`
	`6`	`+public interface ListQueueResult extends Result {`
`7`	`7`	`List<String> queues();`
`8`	`8`	`}`