Merge pull request #7 from LuminiaDev/docs

docs: written javadoc for all classes

Author: MEFRREEX

README.md

@@ -16,22 +16,24 @@ import com.luminiadev.bridge.network.codec.packet.BridgePacketDirection;
 BridgeRabbitMQNetwork network = new BridgeRabbitMQNetwork(BridgeRabbitMQConfig.builder()
         .host("localhost")
         .credentials(new BridgeRabbitMQCredentials("guest", "guest"))
+        .serviceId("my-service-id") // You can remove this parameter and the id will be generated automatically
         .build());
 
-// Creating a codec with an example packet
-BridgeCodec codec = BridgeCodec.builder()
-        .registerPacket("example_packet", ExamplePacket::new, new ExamplePacketSerializer())
-        .build();
+        // Creating a codec with an example packet
+// If any packet is not found in the codec, it will be handled as BridgeUnknownPacket.
+        BridgeCodec codec = BridgeCodec.builder()
+                .registerPacket("example_packet", ExamplePacket::new, new ExamplePacketSerializer())
+                .build();
 
 network.setCodec(codec); // Set codec to network
 network.start(); // Start network
 
 // Adding packet handler
 network.addPacketHandler((packet, direction, serviceId) -> {
-    if (direction == BridgePacketDirection.TO_SERVICE) {
+        if (direction == BridgePacketDirection.TO_SERVICE) {
         System.out.println("Received packet " + packet + " from service " + serviceId);
     } else {
-        System.out.println("Sent packet: " + packet);
+            System.out.println("Sent packet: " + packet);
     }
-});
+            });
 ```

bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeCodecException.java

@@ -1,15 +1,34 @@
 package com.luminiadev.bridge.exception;
 
+/**
+ * Custom exception for bridge codec errors.
+ */
 public class BridgeCodecException extends BridgeException {
 
+    /**
+     * Creates a new BridgeCodecException with the specified message.
+     *
+     * @param message The detail message
+     */
     public BridgeCodecException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new BridgeCodecException with the specified message and cause.
+     *
+     * @param message The detail message
+     * @param cause The cause of the exception
+     */
     public BridgeCodecException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a new BridgeCodecException with the specified cause.
+     *
+     * @param cause The cause of the exception
+     */
     public BridgeCodecException(Throwable cause) {
         super(cause);
     }

bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeException.java

@@ -1,15 +1,34 @@
 package com.luminiadev.bridge.exception;
 
+/**
+ * Custom exception for bridge errors.
+ */
 public class BridgeException extends RuntimeException {
 
+    /**
+     * Creates a new BridgeException with the specified message.
+     *
+     * @param message The detail message
+     */
     public BridgeException(String message) {
         super(message);
     }
 
+    /**
+     * Creates a new BridgeException with the specified message and cause.
+     *
+     * @param message The detail message
+     * @param cause The cause of the exception
+     */
     public BridgeException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * Creates a new BridgeException with the specified cause.
+     *
+     * @param cause The cause of the exception
+     */
     public BridgeException(Throwable cause) {
         super(cause);
     }

bridge-common/src/main/java/com/luminiadev/bridge/network/AbstractBridgeNetwork.java

@@ -12,6 +12,9 @@
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * Bridge network interface abstract class with basic methods implementation.
+ */
 public abstract class AbstractBridgeNetwork implements BridgeNetwork {
 
     private BridgeCodec codec;

bridge-common/src/main/java/com/luminiadev/bridge/network/BridgeNetwork.java

@@ -1,35 +1,98 @@
 package com.luminiadev.bridge.network;
 
+import com.luminiadev.bridge.exception.BridgeCodecException;
 import com.luminiadev.bridge.network.codec.BridgeCodec;
 import com.luminiadev.bridge.network.codec.packet.BridgePacket;
 import com.luminiadev.bridge.network.codec.packet.handler.BridgePacketHandler;
 import io.netty.buffer.ByteBuf;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.UnmodifiableView;
 
 import java.util.Set;
 
+/**
+ * Bridge network interface.
+ */
 public interface BridgeNetwork {
 
-    String getServiceId();
+    /**
+     * Get service id.
+     *
+     * @return Service id
+     */
+    @NotNull String getServiceId();
 
+    /**
+     * Set up codec.
+     *
+     * @param codec The BridgeCodec
+     */
     void setCodec(BridgeCodec codec);
 
+    /**
+     * Get set codec.
+     *
+     * @return Set codec or null, if not set
+     */
     @Nullable BridgeCodec getCodec();
 
-    @UnmodifiableView Set<BridgePacketHandler> getPacketHandlers();
+    /**
+     * Get an immutable set of packet handlers.
+     *
+     * @return Set of packet handlers
+     */
+    @UnmodifiableView
+    Set<BridgePacketHandler> getPacketHandlers();
 
+    /**
+     * Add a packet handler.
+     *
+     * @param handler The BridgePacketHandler
+     */
     void addPacketHandler(BridgePacketHandler handler);
 
+    /**
+     * Remove a packet handler.
+     *
+     * @param handler The BridgePacketHandler
+     */
     void removePacketHandler(BridgePacketHandler handler);
 
+    /**
+     * Send a bridge packet.
+     *
+     * @param packet The BridgePacket
+     * @param <T>    The packet type
+     */
     <T extends BridgePacket> void sendPacket(T packet);
 
+    /**
+     * Decodes the byte buffer in BridgePacket.
+     *
+     * @param buffer   Netty ByteBuf
+     * @param packetId Packet id
+     * @return The decoded BridgePacket
+     * @throws BridgeCodecException If the codec is not set
+     */
     BridgePacket tryDecode(ByteBuf buffer, String packetId);
 
+    /**
+     * Encodes the BridgePacket to byte buffer.
+     *
+     * @param buffer Netty ByteBuf
+     * @param packet Packet object
+     * @throws BridgeCodecException If the codec is not set
+     */
     <T extends BridgePacket> void tryEncode(ByteBuf buffer, T packet);
 
+    /**
+     * Starts the Bridge network interface.
+     */
     void start();
 
+    /**
+     * Closes the Bridge network interface.
+     */
     void close();
 }

bridge-common/src/main/java/com/luminiadev/bridge/network/codec/BridgeCodec.java

@@ -13,33 +13,66 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Bridge packet codec for registering and encoding packets.
+ */
 public final class BridgeCodec {
 
     private final Map<String, BridgePacketDefinition<? extends BridgePacket>> packetsById = new HashMap<>();
     private final Map<Class<?>, BridgePacketDefinition<? extends BridgePacket>> packetsByClass = new HashMap<>();
 
+    /**
+     * Creates an empty codec builder.
+     *
+     * @return Builder
+     */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Gets the bridge packet definition by the id.
+     *
+     * @param id Packet id
+     * @return BridgePacketDefinition or null
+     */
     public @Nullable BridgePacketDefinition<? extends BridgePacket> getPacketDefinition(String id) {
         return packetsById.get(id);
     }
 
+    /**
+     * Gets the bridge packet definition by the id.
+     * @param classOf Packet class
+     * @param <T> Packet type
+     * @return BridgePacketDefinition or null
+     */
     @SuppressWarnings("unchecked")
     public @Nullable <T extends BridgePacket> BridgePacketDefinition<T> getPacketDefinition(Class<T> classOf) {
         return (BridgePacketDefinition<T>) packetsByClass.get(classOf);
     }
 
+    /**
+     * Register the packet definition.
+     *
+     * @param definition BridgePacketDefinition
+     * @param <T> Packet type
+     * @throws BridgeCodecException If the packet is already registered
+     */
     public <T extends BridgePacket> void registerPacket(BridgePacketDefinition<T> definition) {
         if (!packetsById.containsKey(definition.getId())) {
             packetsById.put(definition.getId(), definition);
-            packetsByClass.put(definition.getClass(), definition);
+            packetsByClass.put(definition.getFactory().getClass(), definition);
         } else {
             throw new BridgeCodecException("Packet with id " + definition.getId() + " is already registered");
         }
     }
 
+    /**
+     * Deregister packet definition by packet id.
+     *
+     * @param packetId Packet id
+     * @throws BridgeCodecException If the packet is not registered
+     */
     public void unregisterPacket(String packetId) {
         BridgePacketDefinition<? extends BridgePacket> definition = packetsById.remove(packetId);
         if (definition != null) {
@@ -49,6 +82,14 @@ public void unregisterPacket(String packetId) {
         }
     }
 
+    /**
+     * Decodes the byte buffer in BridgePacket.
+     *
+     * @param buffer   Netty ByteBuf
+     * @param packetId Packet id
+     * @return The decoded BridgePacket
+     * @throws BridgeCodecException If the codec is not set
+     */
     @SuppressWarnings({"unchecked", "rawtypes"})
     public BridgePacket tryDecode(ByteBuf buffer, String packetId) {
         BridgePacketDefinition<? extends BridgePacket> definition = this.getPacketDefinition(packetId);
@@ -71,6 +112,13 @@ public BridgePacket tryDecode(ByteBuf buffer, String packetId) {
         return packet;
     }
 
+    /**
+     * Encodes the BridgePacket to byte buffer.
+     *
+     * @param buffer Netty ByteBuf
+     * @param packet Packet object
+     * @throws BridgeCodecException If the codec is not set
+     */
     @SuppressWarnings("unchecked")
     public <T extends BridgePacket> void tryEncode(ByteBuf buffer, T packet) {
         BridgePacketSerializerHelper helper = new BridgePacketSerializerHelper(buffer);
@@ -89,6 +137,11 @@ public <T extends BridgePacket> void tryEncode(ByteBuf buffer, T packet) {
         serializer.serialize(buffer, helper, packet);
     }
 
+    /**
+     * Creates Builder from codec with all codec parameters.
+     *
+     * @return Builder
+     */
     public Builder toBuilder() {
         Builder builder = new Builder();
         builder.definitions.putAll(packetsById);

bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacket.java

@@ -2,7 +2,15 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * A bridge packet.
+ */
 public interface BridgePacket {
 
+    /**
+     * Gets packet id.
+     *
+     * @return Packet id
+     */
     @NotNull String getId();
 }

bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDefinition.java

@@ -3,6 +3,11 @@
 import com.luminiadev.bridge.network.codec.packet.serializer.BridgePacketSerializer;
 import lombok.Value;
 
+/**
+ * Bridge packet definition, contains id, factory and serializer of the packet.
+ *
+ * @param <T> Packet type
+ */
 @Value
 public class BridgePacketDefinition<T extends BridgePacket> {
     String id;

bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDirection.java

@@ -1,6 +1,15 @@
 package com.luminiadev.bridge.network.codec.packet;
 
+/**
+ * Bridge packet direction.
+ */
 public enum BridgePacketDirection {
+    /**
+     * The packet sent by the current service to other services.
+     */
     FROM_SERVICE,
+    /**
+     * The packet was sent from another service to the current service.
+     */
     TO_SERVICE
 }

bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketFactory.java

@@ -1,6 +1,17 @@
 package com.luminiadev.bridge.network.codec.packet;
 
+/**
+ * Bridge packet factory.
+ *
+ * @param <T> Packet type
+ */
 @FunctionalInterface
 public interface BridgePacketFactory<T extends BridgePacket> {
+
+    /**
+     * Creates a new bridge packet instance.
+     *
+     * @return A new bridge packet instance
+     */
     T create();
 }