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

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

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;

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

@@ -25,6 +25,13 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * FastJson serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="fastjson" /&gt;
+ * </pre>
+ */
 public class FastJsonSerialization implements Serialization {
 
     @Override

dubbo-serialization/dubbo-serialization-fst/src/main/java/org/apache/dubbo/common/serialize/fst/FstFactory.java

@@ -25,6 +25,9 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Fst object input/output factory
+ */
 public class FstFactory {
 
     private static final FstFactory factory = new FstFactory();

dubbo-serialization/dubbo-serialization-fst/src/main/java/org/apache/dubbo/common/serialize/fst/FstObjectInput.java

@@ -24,7 +24,9 @@
 import java.io.InputStream;
 import java.lang.reflect.Type;
 
-
+/**
+ * Fst object input implementation
+ */
 public class FstObjectInput implements ObjectInput {
 
     private FSTObjectInput input;

dubbo-serialization/dubbo-serialization-fst/src/main/java/org/apache/dubbo/common/serialize/fst/FstObjectOutput.java

@@ -23,7 +23,9 @@
 import java.io.IOException;
 import java.io.OutputStream;
 
-
+/**
+ * Fst object output implementation
+ */
 public class FstObjectOutput implements ObjectOutput {
 
     private FSTObjectOutput output;

dubbo-serialization/dubbo-serialization-fst/src/main/java/org/apache/dubbo/common/serialize/fst/FstSerialization.java

@@ -25,6 +25,13 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Fst serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="fst" /&gt;
+ * </pre>
+ */
 public class FstSerialization implements Serialization {
 
     @Override

dubbo-serialization/dubbo-serialization-hessian2/src/main/java/org/apache/dubbo/common/serialize/hessian2/Hessian2ObjectInput.java

@@ -25,7 +25,7 @@
 import java.lang.reflect.Type;
 
 /**
- * Hessian2 Object input.
+ * Hessian2 object input implementation
  */
 public class Hessian2ObjectInput implements ObjectInput {
     private final Hessian2Input mH2i;

dubbo-serialization/dubbo-serialization-hessian2/src/main/java/org/apache/dubbo/common/serialize/hessian2/Hessian2ObjectOutput.java

@@ -24,7 +24,7 @@
 import java.io.OutputStream;
 
 /**
- * Hessian2 Object output.
+ * Hessian2 object output implementation
  */
 public class Hessian2ObjectOutput implements ObjectOutput {
     private final Hessian2Output mH2o;

dubbo-serialization/dubbo-serialization-hessian2/src/main/java/org/apache/dubbo/common/serialize/hessian2/Hessian2Serialization.java

@@ -25,6 +25,13 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Hessian2 serialization implementation, hessian2 is the default serialization protocol for dubbo
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="hessian2" /&gt;
+ * </pre>
+ */
 public class Hessian2Serialization implements Serialization {
 
     public static final byte ID = 2;

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/CompactedJavaSerialization.java

@@ -25,6 +25,13 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Compacted java serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="compactedjava" /&gt;
+ * </pre>
+ */
 public class CompactedJavaSerialization implements Serialization {
 
     @Override

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/CompactedObjectInputStream.java

@@ -26,7 +26,7 @@
 import java.io.StreamCorruptedException;
 
 /**
- * Compacted java object input stream.
+ * Compacted java object input implementation
  */
 public class CompactedObjectInputStream extends ObjectInputStream {
     private ClassLoader mClassLoader;

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/CompactedObjectOutputStream.java

@@ -22,7 +22,7 @@
 import java.io.OutputStream;
 
 /**
- * Compacted java object output stream.
+ * Compacted java object output implementation
  */
 public class CompactedObjectOutputStream extends ObjectOutputStream {
     public CompactedObjectOutputStream(OutputStream out) throws IOException {

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/JavaObjectInput.java

@@ -24,7 +24,7 @@
 import java.lang.reflect.Type;
 
 /**
- * Java Object input.
+ * Java object input implementation
  */
 public class JavaObjectInput extends NativeJavaObjectInput {
     public final static int MAX_BYTE_ARRAY_LENGTH = 8 * 1024 * 1024;

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/JavaObjectOutput.java

@@ -23,7 +23,7 @@
 import java.io.OutputStream;
 
 /**
- * Java Object output.
+ * Java object output implementation
  */
 public class JavaObjectOutput extends NativeJavaObjectOutput {
     public JavaObjectOutput(OutputStream os) throws IOException {

dubbo-serialization/dubbo-serialization-jdk/src/main/java/org/apache/dubbo/common/serialize/java/JavaSerialization.java

@@ -25,6 +25,13 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Java serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="java" /&gt;
+ * </pre>
+ */
 public class JavaSerialization implements Serialization {
 
     @Override