Add checkstyle validation and fix style violations in the common modu…

…le (apache#4989)

* Add checkstyle validation and fix style violations.

* Add the first batch of javadoc comments.

* Add javadoc comments in the pulsar common module

* Substitute the suppression warnings with javadoc comments in the pulsar common module

pulsar-common/pom.xml

@@ -156,6 +156,26 @@
         </execution>
       </executions>
     </plugin>
+
+    <plugin>
+      <groupId>org.apache.maven.plugins</groupId>
+      <artifactId>maven-checkstyle-plugin</artifactId>
+      <executions>
+        <execution>
+          <id>check-style</id>
+          <phase>verify</phase>
+          <configuration>
+            <configLocation>../buildtools/src/main/resources/pulsar/checkstyle.xml</configLocation>
+            <suppressionsLocation>../buildtools/src/main/resources/pulsar/suppressions.xml</suppressionsLocation>
+            <encoding>UTF-8</encoding>
+            <excludes>**/proto/*</excludes>
+          </configuration>
+          <goals>
+            <goal>check</goal>
+          </goals>
+        </execution>
+      </executions>
+    </plugin>
   </plugins>
   </build>
 </project>

pulsar-common/src/main/java/org/apache/pulsar/client/api/url/DataURLStreamHandler.java

@@ -31,8 +31,14 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Extension of the {@code URLStreamHandler} class to handle all stream protocol handlers.
+ */
 public class DataURLStreamHandler extends URLStreamHandler {
 
+    /**
+     * Representation of a communications link between the application and a URL.
+     */
     static class DataURLConnection extends URLConnection {
         private boolean parsed = false;
         private String contentType;

pulsar-common/src/main/java/org/apache/pulsar/client/api/url/PulsarURLStreamHandlerFactory.java

@@ -23,6 +23,10 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * This class defines a factory for {@code URL} stream
+ * protocol handlers.
+ */
 public class PulsarURLStreamHandlerFactory implements URLStreamHandlerFactory {
     private static final Map<String, Class<? extends URLStreamHandler>> handlers;
     static {

pulsar-common/src/main/java/org/apache/pulsar/client/api/url/URL.java

@@ -25,6 +25,9 @@
 import java.net.URLConnection;
 import java.net.URLStreamHandlerFactory;
 
+/**
+ * Wrapper around {@code java.net.URL} to improve usability.
+ */
 public class URL {
     private static final URLStreamHandlerFactory urlStreamHandlerFactory = new PulsarURLStreamHandlerFactory();
     private final java.net.URL url;

pulsar-common/src/main/java/org/apache/pulsar/client/api/url/package-info.java

@@ -0,0 +1,22 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Classes to work with URLs.
+ */
+package org.apache.pulsar.client.api.url;

pulsar-common/src/main/java/org/apache/pulsar/common/allocator/PulsarByteBufAllocator.java

@@ -32,6 +32,9 @@
 import org.apache.bookkeeper.common.allocator.LeakDetectionPolicy;
 import org.apache.bookkeeper.common.allocator.PoolingPolicy;
 
+/**
+ * Holder of a ByteBuf allocator.
+ */
 @UtilityClass
 @Slf4j
 public class PulsarByteBufAllocator {

pulsar-common/src/main/java/org/apache/pulsar/common/allocator/package-info.java

@@ -0,0 +1,22 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Classes implementing pulsar allocator.
+ */
+package org.apache.pulsar.common.allocator;

pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/MessageParser.java

@@ -24,22 +24,26 @@
 
 import io.netty.buffer.ByteBuf;
 import io.netty.util.ReferenceCountUtil;
-
 import java.io.IOException;
-
 import lombok.experimental.UtilityClass;
 import lombok.extern.slf4j.Slf4j;
-
-import org.apache.pulsar.common.protocol.Commands;
 import org.apache.pulsar.common.api.proto.PulsarApi;
 import org.apache.pulsar.common.api.proto.PulsarApi.MessageMetadata;
 import org.apache.pulsar.common.compression.CompressionCodec;
 import org.apache.pulsar.common.compression.CompressionCodecProvider;
 import org.apache.pulsar.common.naming.TopicName;
+import org.apache.pulsar.common.protocol.Commands;
 
+/**
+ * Helper class to work with a raw Pulsar entry payload.
+ */
 @UtilityClass
 @Slf4j
 public class MessageParser {
+
+    /**
+     * Definition of an interface to process a raw Pulsar entry payload.
+     */
     public interface MessageProcessor {
         void process(RawMessage message);
     }
@@ -64,7 +68,8 @@ public static void parseMessage(TopicName topicName, long ledgerId, long entryId
             try {
                 msgMetadata = Commands.parseMessageMetadata(payload);
             } catch (Throwable t) {
-                log.warn("[{}] Failed to deserialize metadata for message {}:{} - Ignoring", topicName, ledgerId, entryId);
+                log.warn("[{}] Failed to deserialize metadata for message {}:{} - Ignoring",
+                    topicName, ledgerId, entryId);
                 return;
             }
 
@@ -90,10 +95,11 @@ public static void parseMessage(TopicName topicName, long ledgerId, long entryId
 
             if (numMessages == 1 && !msgMetadata.hasNumMessagesInBatch()) {
                 processor.process(
-                        RawMessageImpl.get(refCntMsgMetadata, null, uncompressedPayload.retain(), ledgerId, entryId, 0));
+                    RawMessageImpl.get(refCntMsgMetadata, null, uncompressedPayload.retain(), ledgerId, entryId, 0));
             } else {
                 // handle batch message enqueuing; uncompressed payload has all messages in batch
-                receiveIndividualMessagesFromBatch(refCntMsgMetadata, uncompressedPayload, ledgerId, entryId, processor);
+                receiveIndividualMessagesFromBatch(
+                    refCntMsgMetadata, uncompressedPayload, ledgerId, entryId, processor);
             }
 
 

pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/RawMessage.java

@@ -26,26 +26,26 @@
 /**
  * View of a message that exposes the internal direct-memory buffer for more efficient processing.
  *
- * The message needs to be released when the processing is done.
+ * <p>The message needs to be released when the processing is done.
  */
 public interface RawMessage {
 
     /**
-     * Release all the resources associated with this raw message
+     * Release all the resources associated with this raw message.
      */
     void release();
 
     /**
      * Return the properties attached to the message.
      *
-     * Properties are application defined key/value pairs that will be attached to the message
+     * <p>Properties are application defined key/value pairs that will be attached to the message.
      *
      * @return an unmodifiable view of the properties map
      */
     Map<String, String> getProperties();
 
     /**
-     * Get the content of the message
+     * Get the content of the message.
      *
      * @return the byte array with the message payload
      */
@@ -54,9 +54,10 @@ public interface RawMessage {
     /**
      * Get the unique message ID associated with this message.
      *
-     * The message id can be used to univocally refer to a message without having the keep the entire payload in memory.
+     * <p>The message id can be used to univocally refer to a message
+     * without having the keep the entire payload in memory.
      *
-     * Only messages received from the consumer will have a message id assigned.
+     * <p>Only messages received from the consumer will have a message id assigned.
      *
      * @return the message id null if this message was not received by this client instance
      */
@@ -74,8 +75,7 @@ public interface RawMessage {
      * Get the event time associated with this message. It is typically set by the applications via
      * {@link MessageBuilder#setEventTime(long)}.
      *
-     * <p>
-     * If there isn't any event time associated with this event, it will return 0.
+     * <p>If there isn't any event time associated with this event, it will return 0.
      */
     long getEventTime();
 
@@ -96,7 +96,7 @@ public interface RawMessage {
     String getProducerName();
 
     /**
-     * Get the key of the message
+     * Get the key of the message.
      *
      * @return the key of the message
      */

pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/RawMessageId.java

@@ -18,6 +18,9 @@
  */
 package org.apache.pulsar.common.api.raw;
 
+/**
+ * Interface to uniquely identify an internal raw message.
+ */
 public interface RawMessageId {
 
 }

pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/ReferenceCountedObject.java

@@ -23,6 +23,11 @@
 
 import java.util.function.Consumer;
 
+/**
+ * Class representing a reference-counted object that requires explicit deallocation.
+ *
+ * @param <T> type of the object that requires explicit deallocation.
+ */
 public class ReferenceCountedObject<T> extends AbstractReferenceCounted {
 
     private final T object;

pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/package-info.java

@@ -0,0 +1,22 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Classes implementing raw API messages.
+ */
+package org.apache.pulsar.common.api.raw;

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodec.java

@@ -18,17 +18,16 @@
  */
 package org.apache.pulsar.common.compression;
 
-import java.io.IOException;
-
 import io.netty.buffer.ByteBuf;
+import java.io.IOException;
 
 /**
- * Generic compression codec interface
+ * Generic compression codec interface.
  */
 public interface CompressionCodec {
 
     /**
-     * Compress a buffer
+     * Compress a buffer.
      *
      * @param raw
      *            a buffer with the uncompressed content. The reader/writer indexes will not be modified
@@ -39,7 +38,7 @@ public interface CompressionCodec {
     /**
      * Decompress a buffer.
      *
-     * The buffer needs to have been compressed with the matching Encoder.
+     * <p>The buffer needs to have been compressed with the matching Encoder.
      *
      * @param encoded
      *            the compressed content

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodecLZ4.java

@@ -19,20 +19,16 @@
 package org.apache.pulsar.common.compression;
 
 import io.netty.buffer.ByteBuf;
-
 import java.io.IOException;
 import java.nio.ByteBuffer;
-
 import lombok.extern.slf4j.Slf4j;
-
-import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
-
 import net.jpountz.lz4.LZ4Compressor;
 import net.jpountz.lz4.LZ4Factory;
 import net.jpountz.lz4.LZ4FastDecompressor;
+import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
 
 /**
- * LZ4 Compression
+ * LZ4 Compression.
  */
 @Slf4j
 public class CompressionCodecLZ4 implements CompressionCodec {

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodecNone.java

@@ -18,10 +18,12 @@
  */
 package org.apache.pulsar.common.compression;
 
-import java.io.IOException;
-
 import io.netty.buffer.ByteBuf;
+import java.io.IOException;
 
+/**
+ * No compression.
+ */
 public class CompressionCodecNone implements CompressionCodec {
 
     @Override

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodecProvider.java

@@ -25,6 +25,15 @@
 import org.apache.pulsar.client.api.CompressionType;
 import org.apache.pulsar.common.api.proto.PulsarApi;
 
+/**
+ * Provider of compression codecs used in Pulsar.
+ *
+ * @see CompressionCodecNone
+ * @see CompressionCodecLZ4
+ * @see CompressionCodecZLib
+ * @see CompressionCodecZstd
+ * @see CompressionCodecSnappy
+ */
 @UtilityClass
 public class CompressionCodecProvider {
     private static final EnumMap<PulsarApi.CompressionType, CompressionCodec> codecs;

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodecSnappy.java

@@ -20,14 +20,13 @@
 
 import io.netty.buffer.ByteBuf;
 import io.netty.buffer.PooledByteBufAllocator;
-import lombok.extern.slf4j.Slf4j;
-import org.xerial.snappy.Snappy;
-
 import java.io.IOException;
 import java.nio.ByteBuffer;
+import lombok.extern.slf4j.Slf4j;
+import org.xerial.snappy.Snappy;
 
 /**
- * Snappy Compression
+ * Snappy Compression.
  */
 @Slf4j
 public class CompressionCodecSnappy implements CompressionCodec {

pulsar-common/src/main/java/org/apache/pulsar/common/compression/CompressionCodecZLib.java

@@ -31,7 +31,7 @@
 import org.apache.pulsar.common.allocator.PulsarByteBufAllocator;
 
 /**
- * ZLib Compression
+ * ZLib Compression.
  */
 public class CompressionCodecZLib implements CompressionCodec {