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 @@ package org.apache.dubbo.common.serialize;
 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 @@ package org.apache.dubbo.common.serialize;
 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.io.IOException;
 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 @@ package org.apache.dubbo.common.serialize;
 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,30 +25,35 @@ import java.io.InputStream;
 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
      */
@@ -56,10 +61,10 @@ public interface Serialization {
     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,6 +21,10 @@ import com.esotericsoftware.kryo.Serializer;
 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 {
 
 
@@ -28,6 +32,8 @@ public abstract class SerializableClassRegistry {
 
     /**
      * only supposed to be called at startup time
+     *
+     * @param clazz object type
      */
     public static void registerClass(Class clazz) {
         registerClass(clazz, null);
@@ -35,6 +41,9 @@ public abstract class SerializableClassRegistry {
 
     /**
      * 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 abstract class SerializableClassRegistry {
         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 @@ package org.apache.dubbo.common.serialize.support;
 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.InputStreamReader;
 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.OutputStreamWriter;
 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.IOException;
 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 org.nustaq.serialization.FSTObjectOutput;
 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.IOException;
 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 org.nustaq.serialization.FSTObjectOutput;
 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.IOException;
 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.io.InputStream;
 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.IOException;
 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.IOException;
 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.IOException;
 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.ObjectStreamClass;
 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.ObjectStreamClass;
 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.io.ObjectInputStream;
 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.ObjectOutputStream;
 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.IOException;
 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

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

@@ -25,6 +25,9 @@ import java.io.InputStream;
 import java.io.ObjectInputStream;
 import java.lang.reflect.Type;
 
+/**
+ * Native java object input implementation
+ */
 public class NativeJavaObjectInput implements ObjectInput {
 
     private final ObjectInputStream inputStream;

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

@@ -24,6 +24,9 @@ import java.io.IOException;
 import java.io.ObjectOutputStream;
 import java.io.OutputStream;
 
+/**
+ * Native java object output implementation
+ */
 public class NativeJavaObjectOutput implements ObjectOutput {
 
     private final ObjectOutputStream outputStream;

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

@@ -26,6 +26,13 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Native java serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="nativejava" /&gt;
+ * </pre>
+ */
 public class NativeJavaSerialization implements Serialization {
 
     public static final String NAME = "nativejava";

dubbo-serialization/dubbo-serialization-kryo/src/main/java/org/apache/dubbo/common/serialize/kryo/KryoObjectInput.java

@@ -28,6 +28,9 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.lang.reflect.Type;
 
+/**
+ * Kryo object input implementation, kryo object can be clean
+ */
 public class KryoObjectInput implements ObjectInput, Cleanable {
 
     private Kryo kryo;

dubbo-serialization/dubbo-serialization-kryo/src/main/java/org/apache/dubbo/common/serialize/kryo/KryoObjectOutput.java

@@ -26,6 +26,9 @@ import com.esotericsoftware.kryo.io.Output;
 import java.io.IOException;
 import java.io.OutputStream;
 
+/**
+ * Kryo object output implementation, kryo object can be clean
+ */
 public class KryoObjectOutput implements ObjectOutput, Cleanable {
 
     private Output output;

dubbo-serialization/dubbo-serialization-kryo/src/main/java/org/apache/dubbo/common/serialize/kryo/KryoSerialization.java

@@ -28,6 +28,9 @@ import java.io.OutputStream;
 /**
  * TODO for now kryo serialization doesn't deny classes that don't implement the serializable interface
  *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="kryo" /&gt;
+ * </pre>
  */
 public class KryoSerialization implements Serialization {
 

dubbo-serialization/dubbo-serialization-protostuff/src/main/java/org/apache/dubbo/common/serialize/protostuff/ProtostuffObjectInput.java

@@ -29,6 +29,9 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.lang.reflect.Type;
 
+/**
+ * Protostuff object input implementation
+ */
 public class ProtostuffObjectInput implements ObjectInput {
 
     private DataInputStream dis;

dubbo-serialization/dubbo-serialization-protostuff/src/main/java/org/apache/dubbo/common/serialize/protostuff/ProtostuffObjectOutput.java

@@ -29,6 +29,9 @@ import java.io.DataOutputStream;
 import java.io.IOException;
 import java.io.OutputStream;
 
+/**
+ * Protostuff object output implementation
+ */
 public class ProtostuffObjectOutput implements ObjectOutput {
 
     private LinkedBuffer buffer = LinkedBuffer.allocate();

dubbo-serialization/dubbo-serialization-protostuff/src/main/java/org/apache/dubbo/common/serialize/protostuff/ProtostuffSerialization.java

@@ -26,6 +26,13 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Protostuff serialization implementation
+ *
+ * <pre>
+ *     e.g. &lt;dubbo:protocol serialization="protostuff" /&gt;
+ * </pre>
+ */
 public class ProtostuffSerialization implements Serialization {
     @Override
     public byte getContentTypeId() {

dubbo-serialization/dubbo-serialization-protostuff/src/main/java/org/apache/dubbo/common/serialize/protostuff/delegate/TimeDelegate.java

@@ -26,6 +26,9 @@ import io.protostuff.runtime.Delegate;
 import java.io.IOException;
 import java.sql.Time;
 
+/**
+ * Custom {@link Time} delegate
+ */
 public class TimeDelegate implements Delegate<Time> {
     @Override
     public WireFormat.FieldType getFieldType() {

dubbo-serialization/dubbo-serialization-protostuff/src/main/java/org/apache/dubbo/common/serialize/protostuff/utils/WrapperUtils.java

@@ -43,6 +43,9 @@ import java.util.TreeSet;
 import java.util.Vector;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Use WrapperUtils to wrap object to {@link Wrapper}
+ */
 public class WrapperUtils {
     private static final Set<Class<?>> WRAPPER_SET = new HashSet<>();
 
@@ -82,10 +85,22 @@ public class WrapperUtils {
 
     }
 
+    /**
+     * Determine if the object needs wrap
+     *
+     * @param clazz object type
+     * @return need wrap
+     */
     public static boolean needWrapper(Class<?> clazz) {
         return WrapperUtils.WRAPPER_SET.contains(clazz) || clazz.isArray() || clazz.isEnum();
     }
 
+    /**
+     * Determine if the object needs wrap
+     *
+     * @param obj object
+     * @return need wrap
+     */
     public static boolean needWrapper(Object obj) {
         return needWrapper(obj.getClass());
     }