From d41141ce61182c9e7d5be1361159f275657a6fd0 Mon Sep 17 00:00:00 2001 From: Arkadiy Date: Sat, 12 Jul 2025 19:25:31 +0400 Subject: [PATCH] docs: written javadoc for all classes --- README.md | 16 +++-- .../exception/BridgeCodecException.java | 19 ++++++ .../bridge/exception/BridgeException.java | 19 ++++++ .../bridge/network/AbstractBridgeNetwork.java | 3 + .../bridge/network/BridgeNetwork.java | 67 ++++++++++++++++++- .../bridge/network/codec/BridgeCodec.java | 55 ++++++++++++++- .../network/codec/packet/BridgePacket.java | 8 +++ .../codec/packet/BridgePacketDefinition.java | 5 ++ .../codec/packet/BridgePacketDirection.java | 9 +++ .../codec/packet/BridgePacketFactory.java | 11 +++ .../codec/packet/BridgeUnknownPacket.java | 4 ++ .../packet/handler/BridgePacketHandler.java | 12 ++++ .../serializer/BridgePacketSerializer.java | 19 ++++++ .../BridgePacketSerializerHelper.java | 3 + .../exception/BridgeRabbitMQException.java | 19 ++++++ .../bridge/network/BridgeRabbitMQConfig.java | 1 + .../bridge/network/BridgeRabbitMQNetwork.java | 6 +- 17 files changed, 265 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 8f340f8..6f8e378 100644 --- a/README.md +++ b/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); } -}); + }); ``` \ No newline at end of file diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeCodecException.java b/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeCodecException.java index dc89bd6..ae3351f 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeCodecException.java +++ b/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); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeException.java b/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeException.java index 45eac32..98b61b2 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/exception/BridgeException.java +++ b/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); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/AbstractBridgeNetwork.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/AbstractBridgeNetwork.java index a968172..ebbdae2 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/AbstractBridgeNetwork.java +++ b/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; diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/BridgeNetwork.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/BridgeNetwork.java index 2f24f29..ed4e1de 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/BridgeNetwork.java +++ b/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 getPacketHandlers(); + /** + * Get an immutable set of packet handlers. + * + * @return Set of packet handlers + */ + @UnmodifiableView + Set 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 The packet type + */ 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 + */ void tryEncode(ByteBuf buffer, T packet); + /** + * Starts the Bridge network interface. + */ void start(); + /** + * Closes the Bridge network interface. + */ void close(); } \ No newline at end of file diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/BridgeCodec.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/BridgeCodec.java index 334f659..cd7b9e7 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/BridgeCodec.java +++ b/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> packetsById = new HashMap<>(); private final Map, BridgePacketDefinition> 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 getPacketDefinition(String id) { return packetsById.get(id); } + /** + * Gets the bridge packet definition by the id. + * @param classOf Packet class + * @param Packet type + * @return BridgePacketDefinition or null + */ @SuppressWarnings("unchecked") public @Nullable BridgePacketDefinition getPacketDefinition(Class classOf) { return (BridgePacketDefinition) packetsByClass.get(classOf); } + /** + * Register the packet definition. + * + * @param definition BridgePacketDefinition + * @param Packet type + * @throws BridgeCodecException If the packet is already registered + */ public void registerPacket(BridgePacketDefinition 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 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 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 void tryEncode(ByteBuf buffer, T packet) { BridgePacketSerializerHelper helper = new BridgePacketSerializerHelper(buffer); @@ -89,6 +137,11 @@ public 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); diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacket.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacket.java index 5157db2..fe15ddd 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacket.java +++ b/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(); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDefinition.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDefinition.java index a11aba4..016f2e3 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDefinition.java +++ b/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 Packet type + */ @Value public class BridgePacketDefinition { String id; diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDirection.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDirection.java index 2914479..502af2a 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketDirection.java +++ b/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 } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketFactory.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketFactory.java index 48c8626..036aa1e 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgePacketFactory.java +++ b/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 Packet type + */ @FunctionalInterface public interface BridgePacketFactory { + + /** + * Creates a new bridge packet instance. + * + * @return A new bridge packet instance + */ T create(); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgeUnknownPacket.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgeUnknownPacket.java index fba96f0..61dbe65 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgeUnknownPacket.java +++ b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/BridgeUnknownPacket.java @@ -7,6 +7,10 @@ import lombok.EqualsAndHashCode; import org.jetbrains.annotations.NotNull; +/** + * Unknown packet class. + * If an unregistered packet arrives to the codec, it will be handled as "BridgeUnknownPacket". + */ @Data @EqualsAndHashCode(doNotUseGetters = true) public final class BridgeUnknownPacket implements BridgePacket { diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/handler/BridgePacketHandler.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/handler/BridgePacketHandler.java index b62b474..8b1a573 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/handler/BridgePacketHandler.java +++ b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/handler/BridgePacketHandler.java @@ -3,6 +3,18 @@ import com.luminiadev.bridge.network.codec.packet.BridgePacket; import com.luminiadev.bridge.network.codec.packet.BridgePacketDirection; +/** + * Bridge packet handler. + */ +@FunctionalInterface public interface BridgePacketHandler { + + /** + * Called when a packet is sent or received by the service. + * + * @param packet Packet object + * @param direction Packet direction (from or to service) + * @param serviceId Sender's service Id + */ void handle(BridgePacket packet, BridgePacketDirection direction, String serviceId); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializer.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializer.java index 8c30854..0aa7521 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializer.java +++ b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializer.java @@ -3,9 +3,28 @@ import com.luminiadev.bridge.network.codec.packet.BridgePacket; import io.netty.buffer.ByteBuf; +/** + * Bridge packet serializer. + * + * @param + */ public interface BridgePacketSerializer { + /** + * Serializes the packet into a byte buffer. + * + * @param buffer Netty ByteBuf + * @param helper Packet serializer helper + * @param packet Packet object + */ void serialize(ByteBuf buffer, BridgePacketSerializerHelper helper, T packet); + /** + * Deserializes the byte buffer into a packet. + * + * @param buffer Netty ByteBuf + * @param helper Packet serializer helper + * @param packet Packet object + */ void deserialize(ByteBuf buffer, BridgePacketSerializerHelper helper, T packet); } diff --git a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializerHelper.java b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializerHelper.java index 13ed0bc..4ef6544 100644 --- a/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializerHelper.java +++ b/bridge-common/src/main/java/com/luminiadev/bridge/network/codec/packet/serializer/BridgePacketSerializerHelper.java @@ -16,6 +16,9 @@ import java.util.function.ObjIntConsumer; import java.util.function.ToLongFunction; +/** + * Packet serializer helper. Contains methods for reading and writing strings, var ints arrays, etc. + */ @AllArgsConstructor public final class BridgePacketSerializerHelper { diff --git a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/exception/BridgeRabbitMQException.java b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/exception/BridgeRabbitMQException.java index de7ff9a..76cbe31 100644 --- a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/exception/BridgeRabbitMQException.java +++ b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/exception/BridgeRabbitMQException.java @@ -1,15 +1,34 @@ package com.luminiadev.bridge.exception; +/** + * Custom exception for errors in the bridge implementation for RabbitMQ. + */ public class BridgeRabbitMQException extends BridgeException { + /** + * Creates a new BridgeRabbitMQException with the specified message. + * + * @param message The detail message + */ public BridgeRabbitMQException(String message) { super(message); } + /** + * Creates a new BridgeRabbitMQException with the specified message and cause. + * + * @param message The detail message + * @param cause The cause of the exception + */ public BridgeRabbitMQException(String message, Throwable cause) { super(message, cause); } + /** + * Creates a new BridgeRabbitMQException with the specified cause. + * + * @param cause The cause of the exception + */ public BridgeRabbitMQException(Throwable cause) { super(cause); } diff --git a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQConfig.java b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQConfig.java index a919e2e..1b211a4 100644 --- a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQConfig.java +++ b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQConfig.java @@ -6,6 +6,7 @@ @Builder @Getter public class BridgeRabbitMQConfig { + private final String host; @Builder.Default private final int port = -1; // -1 for use default value diff --git a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQNetwork.java b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQNetwork.java index b468b9f..56514d6 100644 --- a/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQNetwork.java +++ b/bridge-rabbitmq/src/main/java/com/luminiadev/bridge/network/BridgeRabbitMQNetwork.java @@ -9,11 +9,15 @@ import com.rabbitmq.client.impl.DefaultCredentialsProvider; import io.netty.buffer.ByteBuf; import io.netty.buffer.Unpooled; +import org.jetbrains.annotations.NotNull; import java.io.IOException; import java.util.UUID; import java.util.concurrent.TimeoutException; +/** + * The bridge network interface implementation for RabbitMQ + */ public class BridgeRabbitMQNetwork extends AbstractBridgeNetwork { public static final String PACKET_SEND_EXCHANGE = "lumibridge.packet_send_exchange"; @@ -46,7 +50,7 @@ public BridgeRabbitMQNetwork(BridgeRabbitMQConfig config) { } @Override - public String getServiceId() { + public @NotNull String getServiceId() { return serviceId; }