doc(api) add comment and version for APIs

Author: 翊名

openmessaging-api/src/main/java/io/openmessaging/api/Constants.java

@@ -16,11 +16,41 @@
  */
 package io.openmessaging.api;
 
+/**
+ * Consumer interface.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public interface Consumer extends LifeCycle, Credentials {
 
+    /**
+     * Subscribe message in order.
+     *
+     * @param topic message topic.
+     * @param subExpression Subscribe to the filter expression string, which the broker filters based on this
+     * expression. <br> eg: "tag1 || tag2 || tag3"<br>, if subExpression is equal to null or *, it means subscribe all
+     * messages.
+     * @param listener The message callback listener, the consumer receives the message and then passes it to the
+     * message callback listener for consumption.
+     */
     void subscribe(final String topic, final String subExpression, final MessageListener listener);
 
+    /**
+     * Subscribe to messages, which can be filtered using SQL expressions.
+     *
+     * @param topic
+     * @param selector Subscribe to the message selector (can be empty, indicating no filtering), the ONS server filters
+     * according to the expression in this selector. Currently supports two expression syntax: {@link
+     * ExpressionType#TAG}, {@link ExpressionType#SQL92} Among them, the effect of TAG filtering is consistent with the
+     * above interface.
+     * @param listener Message callback listener
+     */
     void subscribe(final String topic, final MessageSelector selector, final MessageListener listener);
 
+    /**
+     * Unsubscribe message
+     * @param topic
+     */
     void unsubscribe(final String topic);
 }

openmessaging-api/src/main/java/io/openmessaging/api/Consumer.java

@@ -15,8 +15,20 @@
  * limitations under the License.
  */
 package io.openmessaging.api;
+
 import java.util.Properties;
 
+/**
+ *
+ * Used for update credentials.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public interface Credentials {
+    /**
+     * Update credentials for instance, properties can be found in {@link OMSBuiltinKeys}
+     * @param credentialProperties
+     */
     void updateCredential(Properties credentialProperties);
 }

openmessaging-api/src/main/java/io/openmessaging/api/Credentials.java

@@ -16,6 +16,12 @@
  */
 package io.openmessaging.api;
 
+/**
+ * Message filter expression type.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public enum ExpressionType {
 
     SQL92,

openmessaging-api/src/main/java/io/openmessaging/api/ExpressionType.java

@@ -16,12 +16,42 @@
  */
 package io.openmessaging.api;
 
+/**
+ * The {@code LifeCycle} defines a lifecycle interface for a OMS related service endpoint, like {@link Producer}, {@link
+ * Consumer}, and so on.
+ * <p>
+ * If the service endpoint class implements the {@code ServiceLifecycle} interface, most of the containers can manage
+ * the lifecycle of the corresponding service endpoint objects easily.
+ * <p>
+ * Any service endpoint should support repeated restart if it implements the {@code ServiceLifecycle} interface.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public interface LifeCycle {
+    /**
+     * Used to determine whether the current instance is started.
+     *
+     * @return if this instance has been started success, this method will return true, otherwise false.
+     */
     boolean isStarted();
 
+    /**
+     * Used to determine whether the current instance is closed.
+     *
+     * @return if this instance has been stopped, this method will return true, otherwise false.
+     */
     boolean isClosed();
 
+    /**
+     * Used for startup or initialization of a service endpoint. A service endpoint instance will be in a ready state
+     * after this method has been completed.
+     */
     void start();
 
+    /**
+     * Notify a service instance of the end of its life cycle. Once this method completes, the service endpoint could be
+     * destroyed and eligible for garbage collection.
+     */
     void shutdown();
 }

openmessaging-api/src/main/java/io/openmessaging/api/LifeCycle.java

@@ -19,28 +19,57 @@
 import java.io.Serializable;
 import java.util.Properties;
 
+/**
+ * The {@code Message} interface is the root interface of all OMS messages, and the most commonly used OMS message is
+ * {@link Message}.
+ * <p>
+ * Most message-oriented middleware (MOM) products treat messages as lightweight entities that consist of header and
+ * body and is used by separate applications to exchange a piece of information, like <a
+ * href="http://rocketmq.apache.org/">Apache RocketMQ</a>.
+ * <p>
+ * The header contains fields used by the messaging system that describes the message's meta information, while the body
+ * contains the application data being transmitted.
+ * <p>
+ * As for the message header, OMS defines two kinds types: userProperties and systemProperties with respect to
+ * flexibility in vendor implementation and user usage.
+ * <ul>
+ * <li>
+ * System Properties, OMS defines some standard attributes in {@link SystemPropKey} that represent the characteristics
+ * of the message.
+ * </li>
+ * <li>
+ * User properties, some OMS vendors may require enhanced extra attributes of the message or some users may want to
+ * clarify some customized attributes to draw the body. OMS provides the improved scalability for these scenarios.
+ * </li>
+ * </ul>
+ * The body contains the application data being transmitted, which is generally ignored by the messaging system and
+ * simply transmitted to its destination.
+ * <p>
+ * In BytesMessage, the body is just a byte array, may be compressed and uncompressed in the transmitting process by the
+ * messaging system. The application is responsible for explaining the concrete content and format of the message body,
+ * OMS is never aware of that.
+ *
+ * The body part is placed in the implementation classes of {@code Message}.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public class Message implements Serializable {
 
     private static final long serialVersionUID = -1385924226856188094L;
 
-
     protected Properties systemProperties;
 
-
     private String topic;
 
-
     private Properties userProperties;
 
-
     private byte[] body;
 
-
     public Message() {
         this(null, null, "", null);
     }
 
-
     public Message(String topic, String tag, String key, byte[] body) {
         this.topic = topic;
         this.body = body;
@@ -49,7 +78,6 @@ public Message(String topic, String tag, String key, byte[] body) {
         this.putSystemProperties(SystemPropKey.KEY, key);
     }
 
-
     public void putSystemProperties(final String key, final String value) {
         if (null == this.systemProperties) {
             this.systemProperties = new Properties();
@@ -60,12 +88,10 @@ public void putSystemProperties(final String key, final String value) {
         }
     }
 
-
     public Message(String topic, String tags, byte[] body) {
         this(topic, tags, "", body);
     }
 
-
     public void putUserProperties(final String key, final String value) {
         if (null == this.userProperties) {
             this.userProperties = new Properties();
@@ -76,7 +102,6 @@ public void putUserProperties(final String key, final String value) {
         }
     }
 
-
     public String getUserProperties(final String key) {
         if (null != this.userProperties) {
             return (String) this.userProperties.get(key);
@@ -85,22 +110,18 @@ public String getUserProperties(final String key) {
         return null;
     }
 
-
     public String getTopic() {
         return topic;
     }
 
-
     public void setTopic(String topic) {
         this.topic = topic;
     }
 
-
     public String getTag() {
         return this.getSystemProperties(SystemPropKey.TAG);
     }
 
-
     public String getSystemProperties(final String key) {
         if (null != this.systemProperties) {
             return this.systemProperties.getProperty(key);
@@ -109,27 +130,22 @@ public String getSystemProperties(final String key) {
         return null;
     }
 
-
     public void setTag(String tag) {
         this.putSystemProperties(SystemPropKey.TAG, tag);
     }
 
-
     public String getKey() {
         return this.getSystemProperties(SystemPropKey.KEY);
     }
 
-
     public void setKey(String key) {
         this.putSystemProperties(SystemPropKey.KEY, key);
     }
 
-
     public String getMsgID() {
         return this.getSystemProperties(SystemPropKey.MSGID);
     }
 
-
     public void setMsgID(String msgid) {
         this.putSystemProperties(SystemPropKey.MSGID, msgid);
     }
@@ -164,7 +180,6 @@ public void setBody(byte[] body) {
         this.body = body;
     }
 
-
     public int getReconsumeTimes() {
         String pro = this.getSystemProperties(SystemPropKey.RECONSUMETIMES);
         if (pro != null) {
@@ -174,12 +189,10 @@ public int getReconsumeTimes() {
         return 0;
     }
 
-
     public void setReconsumeTimes(final int value) {
         putSystemProperties(SystemPropKey.RECONSUMETIMES, String.valueOf(value));
     }
 
-
     public long getBornTimestamp() {
         String pro = this.getSystemProperties(SystemPropKey.BORNTIMESTAMP);
         if (pro != null) {
@@ -189,23 +202,19 @@ public long getBornTimestamp() {
         return 0L;
     }
 
-
     public void setBornTimestamp(final long value) {
         putSystemProperties(SystemPropKey.BORNTIMESTAMP, String.valueOf(value));
     }
 
-
     public String getBornHost() {
         String pro = this.getSystemProperties(SystemPropKey.BORNHOST);
         return pro == null ? "" : pro;
     }
 
-
     public void setBornHost(final String value) {
         putSystemProperties(SystemPropKey.BORNHOST, value);
     }
 
-
     public long getStartDeliverTime() {
         String pro = this.getSystemProperties(SystemPropKey.STARTDELIVERTIME);
         if (pro != null) {
@@ -224,7 +233,6 @@ public void setShardingKey(final String value) {
         putSystemProperties(SystemPropKey.SHARDINGKEY, value);
     }
 
-
     public void setStartDeliverTime(final long value) {
         putSystemProperties(SystemPropKey.STARTDELIVERTIME, String.valueOf(value));
     }
@@ -235,7 +243,6 @@ public String toString() {
             + (body != null ? body.length : 0) + "]";
     }
 
-
     static public class SystemPropKey {
         public static final String TAG = "__TAG";
         public static final String KEY = "__KEY";

openmessaging-api/src/main/java/io/openmessaging/api/Message.java

@@ -18,22 +18,50 @@
 
 import java.util.Properties;
 
+/**
+ * Used for set or get the relevant properties of a message.
+ *
+ * @version OMS 1.2.0
+ * @since OMS 1.2.0
+ */
 public class MessageAccessor {
+    /**
+     * Used for get all system properties.
+     *
+     * @param msg
+     * @return system properties
+     */
     public static Properties getSystemProperties(final Message msg) {
         return msg.systemProperties;
     }
 
-
+    /**
+     * Used for set system properties, will used new systemProperties to override current systemProperties.
+     *
+     * @param msg
+     * @return system properties
+     */
     public static void setSystemProperties(final Message msg, Properties systemProperties) {
         msg.systemProperties = systemProperties;
     }
 
-
+    /**
+     * Used for set system property for a specified key, will used new value to replace origin system property of a
+     * specified key.
+     *
+     * @param msg
+     * @return
+     */
     public static void putSystemProperties(final Message msg, final String key, final String value) {
         msg.putSystemProperties(key, value);
     }
 
-
+    /**
+     * Used for get a system property value for a specified key.
+     *
+     * @param msg
+     * @return system property value of specified key
+     */
     public static String getSystemProperties(final Message msg, final String key) {
         return msg.getSystemProperties(key);
     }