[rocketmq] branch 5.0.0-beta updated: Rename ConsumeStatus to ConsumeResult and polish java docs wherever possible

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lizhanhui pushed a commit to branch 5.0.0-beta
in repository https://gitbox.apache.org/repos/asf/rocketmq.git


The following commit(s) were added to refs/heads/5.0.0-beta by this push:
     new 46da67d73 Rename ConsumeStatus to ConsumeResult and polish java docs wherever possible
46da67d73 is described below

commit 46da67d73ebd210f42a7556a8ad3fadd2b262f2d
Author: Li Zhanhui <li...@gmail.com>
AuthorDate: Tue Apr 19 19:49:47 2022 +0800

    Rename ConsumeStatus to ConsumeResult and polish java docs wherever possible
---
 .../{ConsumeStatus.java => ConsumeResult.java}     |  5 ++--
 .../rocketmq/apis/consumer/MessageListener.java    | 35 +++++++++++++++-------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeStatus.java b/apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeResult.java
similarity index 88%
rename from apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeStatus.java
rename to apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeResult.java
index 0f0d7684d..8dde6f6a2 100644
--- a/apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeStatus.java
+++ b/apis/src/main/java/org/apache/rocketmq/apis/consumer/ConsumeResult.java
@@ -18,13 +18,14 @@
 
 package org.apache.rocketmq.apis.consumer;
 
-public enum ConsumeStatus {
+public enum ConsumeResult {
     /**
      * Consume message success and need commit this message.
      */
     SUCCESS,
+
     /**
-     * Consume message failed and need reconsume later.
+     * Failed to consume the message, expecting potential delivery after configured backoff.
      */
     FAILURE
 }
diff --git a/apis/src/main/java/org/apache/rocketmq/apis/consumer/MessageListener.java b/apis/src/main/java/org/apache/rocketmq/apis/consumer/MessageListener.java
index 3bf17cce1..5d249f109 100644
--- a/apis/src/main/java/org/apache/rocketmq/apis/consumer/MessageListener.java
+++ b/apis/src/main/java/org/apache/rocketmq/apis/consumer/MessageListener.java
@@ -20,18 +20,31 @@ package org.apache.rocketmq.apis.consumer;
 import org.apache.rocketmq.apis.message.MessageView;
 
 /**
- * MessageListener is used only for push consumer to process message consumption synchronously.
+ * <p>MessageListener is used only by PushConsumer to process messages
+ * synchronously.
  *
- * <p> Refer to {@link PushConsumer}, push consumer will get message from server
- * and dispatch the message to backend thread pool which control by parameter threadCount to consumer message concurrently.
+ * <p>PushConsumer will fetch messages from brokers and dispatch them to an
+ * embedded thread pool in form of <code>Runnable</code> tasks to achieve
+ * desirable processing concurrency.
+ *
+ * <p>Refer to {@link PushConsumer} for more further specs.
  */
 public interface MessageListener {
-    /**
-     * The callback interface for consume message. Your should process the messageView and return consumeStatus.
-     * Push consumer will commit the message to server when return SUCCESS or reconsume later when return FAILED.
-     * When consume method throw unexpected exception, this consumeStatus will be treated as FAILED.
-     * @param messageView is message which need consume.
-     * @return ConsumeStatus which defined in {@link ConsumeStatus}
-     */
-    ConsumeStatus consume(MessageView messageView);
+
+  /**
+   * Callback interface to handle incoming messages.
+   *
+   * Application developers are expected to implement this interface to fulfill
+   * business requirements through processing <code>message</code> and return
+   * <code>ConsumeResult</code> accordingly.
+   *
+   * Push consumer will, on behalf of its group, acknowledge the message to
+   * broker on SUCCESS; In case of FAILURE returned or unexpected exceptions
+   * were raised, it will negatively acknowledge <code>message</code>, which
+   * would potentially get re-delivered after configured back off period.
+   *
+   * @param messageView is message which need consume.
+   * @return ConsumeResult which defined in {@link ConsumeResult}
+   */
+  ConsumeResult consume(MessageView message);
 }