Add Javadoc for compression

Author: acogoluegnes

src/main/java/com/rabbitmq/stream/Codec.java

@@ -18,6 +18,8 @@
  * Codec to encode and decode messages.
  *
  * <p>The codec is expected to use the AMQP 1.0 message format.
+ *
+ * <p>This is considered a SPI and is susceptible to change at any time.
  */
 public interface Codec {
 

src/main/java/com/rabbitmq/stream/codec/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Implementations of AMQP 1.0 {@link com.rabbitmq.stream.Codec}.
+ *
+ * <p>Classes and interfaces in this package are considered SPI and are susceptible to change at any
+ * time.
+ */
+package com.rabbitmq.stream.codec;

src/main/java/com/rabbitmq/stream/compression/CommonsCompressCompressionCodecFactory.java

@@ -19,6 +19,16 @@
 import com.rabbitmq.stream.compression.CompressionUtils.CommonsCompressSnappyCompressionCodec;
 import com.rabbitmq.stream.compression.CompressionUtils.CommonsCompressZstdCompressionCodec;
 
+/**
+ * {@link CompressionCodecFactory} creating codecs using <a
+ * href="https://commons.apache.org/proper/commons-compress/">Apache Commons Compress</a>
+ * implementations.
+ *
+ * The framed format is used for SNAPPY and LZ4.
+ *
+ * All but ZSTD compression codecs are implemented in Commons Compress. The ZSTD codec
+ * uses the <a href="https://github.com/luben/zstd-jni/">zstd-jni</a> library.
+ */
 public class CommonsCompressCompressionCodecFactory implements CompressionCodecFactory {
   private final CompressionCodec[] codecs = new CompressionCodec[5];
 

src/main/java/com/rabbitmq/stream/compression/Compression.java

@@ -14,6 +14,7 @@
 
 package com.rabbitmq.stream.compression;
 
+/** Enum to define types of compression codecs. */
 public enum Compression {
   NONE((byte) 0),
   GZIP((byte) 1),
@@ -29,11 +30,11 @@ public enum Compression {
     this.code = code;
   }
 
-  public byte code() {
-    return this.code;
-  }
-
   public static Compression get(byte code) {
     return COMPRESSIONS[code];
   }
+
+  public byte code() {
+    return this.code;
+  }
 }

src/main/java/com/rabbitmq/stream/compression/CompressionCodec.java

@@ -18,13 +18,37 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/** Codec to compress and decompress sub-entries. */
 public interface CompressionCodec {
 
+  /**
+   * Provides the maximum compressed size from the source length.
+   *
+   * @param sourceLength size of plain, uncompressed data
+   * @return maximum compressed size
+   */
   int maxCompressedLength(int sourceLength);
 
-  OutputStream compress(ByteBuf byteBuf);
+  /**
+   * Creates an {@link OutputStream} to compress data.
+   *
+   * @param target {@link ByteBuf} to write compressed data to
+   * @return output stream to write plain data to
+   */
+  OutputStream compress(ByteBuf target);
 
-  InputStream decompress(ByteBuf byteBuf);
+  /**
+   * Creates an {@link InputStream} to read decompressed data from.
+   *
+   * @param source the {@link ByteBuf} to read compressed from
+   * @return input stream to read decompressed from
+   */
+  InputStream decompress(ByteBuf source);
 
+  /**
+   * Return the code for this type of codec.
+   *
+   * @return compression code
+   */
   byte code();
 }

src/main/java/com/rabbitmq/stream/compression/CompressionCodecFactory.java

@@ -14,7 +14,15 @@
 
 package com.rabbitmq.stream.compression;
 
+/**
+ * Factory to create {@link CompressionCodec} instances.
+ */
 public interface CompressionCodecFactory {
 
+  /**
+   * Get a compression codec for a given type of compression.
+   * @param compression the type of compression codec
+   * @return the appropriate compression codec
+   */
   CompressionCodec get(Compression compression);
-}
+}

src/main/java/com/rabbitmq/stream/compression/CompressionUtils.java

@@ -30,6 +30,9 @@
 import org.xerial.snappy.SnappyFramedInputStream;
 import org.xerial.snappy.SnappyFramedOutputStream;
 
+/**
+ * Implementation of {@link CompressionCodec}s.
+ */
 public final class CompressionUtils {
 
   private CompressionUtils() {}

src/main/java/com/rabbitmq/stream/compression/DefaultCompressionCodecFactory.java

@@ -19,6 +19,14 @@
 import com.rabbitmq.stream.compression.CompressionUtils.XerialSnappyCompressionCodec;
 import com.rabbitmq.stream.compression.CompressionUtils.ZstdJniCompressionCodec;
 
+/**
+ * {@link CompressionCodecFactory} implementation using various compression libraries.
+ *
+ * <p>The GZIP codec is based on the JDK implementation, the SNAPPY codec uses <a
+ * href="https://github.com/xerial/snappy-java">Xerial Snappy</a> (framed), the LZ4 codec uses <a
+ * href="https://github.com/lz4/lz4-java">LZ4 Java</a> (framed), the ZSTD codec uses <a
+ * href="https://github.com/luben/zstd-jni/">zstd-jni</a>.
+ */
 public class DefaultCompressionCodecFactory implements CompressionCodecFactory {
 
   private final CompressionCodec[] codecs = new CompressionCodec[5];

src/main/java/com/rabbitmq/stream/compression/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Compression codec utilities to compress and decompress sub-entries.
+ *
+ * <p>Classes and interfaces in this package are considered SPI and are susceptible to change at any
+ * time.
+ */
+package com.rabbitmq.stream.compression;

src/main/java/com/rabbitmq/stream/metrics/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Package for metrics collection utilities.
+ *
+ * <p>Classes and interfaces in this package are considered SPI and are susceptible to change at any
+ * time.
+ */
+package com.rabbitmq.stream.metrics;