Add javadoc for dubbo-serialization module(#3002). (#3004)

Add javadoc for dubbo-serialization module(#3002).

Author: majinkai

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/Cleanable.java

@@ -16,7 +16,13 @@
  */
 package org.apache.dubbo.common.serialize;
 
+/**
+ * Interface defines that the object is cleanable.
+ */
 public interface Cleanable {
 
+    /**
+     * Implementations must implement this cleanup method
+     */
     void cleanup();
 }

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/DataInput.java

@@ -19,7 +19,7 @@
 import java.io.IOException;
 
 /**
- * Data input.
+ * Basic data type input interface.
  */
 public interface DataInput {
 

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/DataOutput.java

@@ -19,7 +19,7 @@
 import java.io.IOException;
 
 /**
- * Data output.
+ * Basic data type output interface.
  */
 public interface DataOutput {
 
@@ -98,9 +98,9 @@ public interface DataOutput {
     /**
      * Write byte array.
      *
-     * @param v   value.
-     * @param off offset.
-     * @param len length.
+     * @param v value.
+     * @param off the start offset in the data.
+     * @param len the number of bytes that are written.
      * @throws IOException
      */
     void writeBytes(byte[] v, int off, int len) throws IOException;

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/ObjectInput.java

@@ -20,30 +20,37 @@
 import java.lang.reflect.Type;
 
 /**
- * Object input.
+ * Object input interface.
  */
 public interface ObjectInput extends DataInput {
 
     /**
-     * read object.
+     * read object
      *
-     * @return object.
+     * @return object
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if an ClassNotFoundException occurs
      */
     Object readObject() throws IOException, ClassNotFoundException;
 
     /**
-     * read object.
+     * read object
      *
-     * @param cls object type.
-     * @return object.
+     * @param cls object class
+     * @return object
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if an ClassNotFoundException occurs
      */
     <T> T readObject(Class<T> cls) throws IOException, ClassNotFoundException;
 
     /**
-     * read object.
+     * read object
      *
-     * @param cls object type.
-     * @return object.
+     * @param cls object class
+     * @param type object type
+     * @return object
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if an ClassNotFoundException occurs
      */
     <T> T readObject(Class<T> cls, Type type) throws IOException, ClassNotFoundException;
 

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/ObjectOutput.java

@@ -19,7 +19,7 @@
 import java.io.IOException;
 
 /**
- * Object output.
+ * Object output interface.
  */
 public interface ObjectOutput extends DataOutput {
 

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/Serialization.java

@@ -25,41 +25,46 @@
 import java.io.OutputStream;
 
 /**
- * Serialization. (SPI, Singleton, ThreadSafe)
+ * Serialization strategy interface that specifies a serializer. (SPI, Singleton, ThreadSafe)
+ *
+ * The default extension is hessian2 and the default serialization implementation of the dubbo protocol.
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="xxx" /&gt;
+ * </pre>
  */
 @SPI("hessian2")
 public interface Serialization {
 
     /**
-     * get content type id
+     * Get content type unique id, recommended that custom implementations use values greater than 20.
      *
      * @return content type id
      */
     byte getContentTypeId();
 
     /**
-     * get content type
+     * Get content type
      *
      * @return content type
      */
     String getContentType();
 
     /**
-     * create serializer
+     * Get a serialization implementation instance
      *
-     * @param url
-     * @param output
+     * @param url URL address for the remote service
+     * @param output the underlying output stream
      * @return serializer
      * @throws IOException
      */
     @Adaptive
     ObjectOutput serialize(URL url, OutputStream output) throws IOException;
 
     /**
-     * create deserializer
+     * Get a deserialization implementation instance
      *
-     * @param url
-     * @param input
+     * @param url URL address for the remote service
+     * @param input the underlying input stream
      * @return deserializer
      * @throws IOException
      */

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/support/SerializableClassRegistry.java

@@ -21,20 +21,29 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * Provide a unified serialization registry, this class used for {@code dubbo-serialization-fst}
+ * and {@code dubbo-serialization-kryo}, it will register some classes at startup time (for example {@link AbstractKryoFactory#create})
+ */
 public abstract class SerializableClassRegistry {
 
 
     private static final Map<Class, Object> registrations = new LinkedHashMap<>();
 
     /**
      * only supposed to be called at startup time
+     *
+     * @param clazz object type
      */
     public static void registerClass(Class clazz) {
         registerClass(clazz, null);
     }
 
     /**
      * only supposed to be called at startup time
+     *
+     * @param clazz object type
+     * @param serializer object serializer
      */
     public static void registerClass(Class clazz, Serializer serializer) {
         if (clazz == null) {
@@ -43,6 +52,11 @@ public static void registerClass(Class clazz, Serializer serializer) {
         registrations.put(clazz, serializer);
     }
 
+    /**
+     * get registered classes
+     *
+     * @return class serializer
+     * */
     public static Map<Class, Object> getRegisteredClasses() {
         return registrations;
     }

dubbo-serialization/dubbo-serialization-api/src/main/java/org/apache/dubbo/common/serialize/support/SerializationOptimizer.java

@@ -19,10 +19,14 @@
 import java.util.Collection;
 
 /**
- * This class can be replaced with the contents in config file, but for now I think the class is easier to write
- *
+ * Interface defining serialization optimizer, there are nothing implementations for now.
  */
 public interface SerializationOptimizer {
 
+    /**
+     * Get serializable classes
+     *
+     * @return serializable classes
+     * */
     Collection<Class> getSerializableClasses();
 }

dubbo-serialization/dubbo-serialization-fastjson/src/main/java/org/apache/dubbo/common/serialize/fastjson/FastJsonObjectInput.java

@@ -29,6 +29,9 @@
 import java.io.Reader;
 import java.lang.reflect.Type;
 
+/**
+ * FastJson object input implementation
+ */
 public class FastJsonObjectInput implements ObjectInput {
 
     private final BufferedReader reader;

dubbo-serialization/dubbo-serialization-fastjson/src/main/java/org/apache/dubbo/common/serialize/fastjson/FastJsonObjectOutput.java

@@ -28,6 +28,9 @@
 import java.io.PrintWriter;
 import java.io.Writer;
 
+/**
+ * FastJson object output implementation
+ */
 public class FastJsonObjectOutput implements ObjectOutput {
 
     private final PrintWriter writer;