enhancing documentation

Author: jkyberneees

src/main/java/de/backendstack21/realtime/pubsub/ConnectionInfo.java

@@ -2,30 +2,85 @@
 
 import java.util.Map;
 
-
+/**
+ * Represents the connection information for a client.
+ *
+ * <h2>Typical Usage Example:</h2>
+ * <pre>{@code
+ * // Register event listener for session started
+ * client.on("session.started", (Object... eventArgs) -> {
+ *     logger.info("Session started: " + (ConnectionInfo) eventArgs[0]);
+ *
+ *     // ...
+ * });
+ * }</pre>
+ */
 public class ConnectionInfo {
+    /**
+     * A unique identifier for this connection. This ID typically remains constant
+     * throughout the lifecycle of a single session or connection instance.
+     */
     private final String id;
+
+    /**
+     * The application identifier associated with this connection. This value is often used
+     * to distinguish one application's client connections from another's.
+     */
     private final String appId;
+
+    /**
+     * The remote network address of the connected client (e.g., IP address).
+     * This information can be vital for auditing, debugging, or policy enforcement.
+     */
     private final String remoteAddress;
 
+    /**
+     * Constructs a new {@code ConnectionInfo} instance with the provided attributes.
+     *
+     * @param id            the unique identifier of the connection
+     * @param appId         the application identifier associated with the connection
+     * @param remoteAddress the remote address (e.g., IP address) of the connection
+     */
     private ConnectionInfo(String id, String appId, String remoteAddress) {
         this.id = id;
         this.appId = appId;
         this.remoteAddress = remoteAddress;
     }
 
+    /**
+     * Retrieves the unique identifier of this connection.
+     *
+     * @return the connection ID as a {@link String}
+     */
     public String getId() {
         return id;
     }
 
+    /**
+     * Retrieves the application ID associated with this connection.
+     *
+     * @return the application ID as a {@link String}
+     */
     public String getAppId() {
         return appId;
     }
 
+    /**
+     * Retrieves the remote address of the client. This may be an IP address or
+     * a domain name depending on the server's configuration.
+     *
+     * @return the remote address as a {@link String}
+     */
     public String getRemoteAddress() {
         return remoteAddress;
     }
 
+    /**
+     * Constructs a new {@code ConnectionInfo} instance from a map of attributes.
+     *
+     * @param message a {@link Map} containing connection attributes
+     * @return a new {@code ConnectionInfo} instance constructed from the provided attributes
+     */
     public static ConnectionInfo from(Map<String, Object> message) {
         String id = (String) message.get("id");
         String appId = (String) message.get("appId");
@@ -34,6 +89,18 @@ public static ConnectionInfo from(Map<String, Object> message) {
         return new ConnectionInfo(id, appId, remoteAddress);
     }
 
+    /**
+     * Constructs a new {@code ConnectionInfo} instance from a generic object,
+     * which must be a {@link Map} containing connection attributes.
+     * <p>
+     * If the provided object is not a {@link Map}, this method will throw
+     * an {@link IllegalArgumentException}.
+     * </p>
+     *
+     * @param message the object expected to be a {@link Map} of connection attributes
+     * @return a new {@code ConnectionInfo} instance
+     * @throws IllegalArgumentException if the provided object is not a {@link Map}
+     */
     @SuppressWarnings("unchecked")
     public static ConnectionInfo from(Object message) {
         if (message instanceof Map) {
@@ -43,8 +110,14 @@ public static ConnectionInfo from(Object message) {
         }
     }
 
+    /**
+     * Returns a string representation of this {@code ConnectionInfo},
+     * including the connection ID, application ID, and remote address.
+     *
+     * @return a string in the format {@code ConnectionInfo{id='...', appId='...', remoteAddress='...'}}
+     */
     @Override
     public String toString() {
         return "ConnectionInfo{" + "id='" + id + '\'' + ", appId='" + appId + '\'' + ", remoteAddress='" + remoteAddress + '\'' + '}';
     }
-}
+}

src/main/java/de/backendstack21/realtime/pubsub/EventEmitter.java

@@ -16,7 +16,6 @@ public class EventEmitter {
      */
     private static final Logger logger = Logger.getLogger(EventEmitter.class.getName());
 
-
     private final Map<String, List<EventListener>> events;
 
     /**
@@ -113,6 +112,15 @@ public static boolean eventMatches(String pattern, String eventName) {
         return matchSegments(patternSegments, eventSegments, 0, 0);
     }
 
+    /**
+     * Helper method to match event segments with pattern segments.
+     *
+     * @param patternSegments The segments of the event pattern.
+     * @param eventSegments   The segments of the event name.
+     * @param i               The current index in the pattern segments.
+     * @param j               The current index in the event segments.
+     * @return True if the segments match, False otherwise.
+     */
     private static boolean matchSegments(String[] patternSegments, String[] eventSegments, int i, int j) {
         while (i < patternSegments.length && j < eventSegments.length) {
             if (patternSegments[i].equals("**")) {

src/main/java/de/backendstack21/realtime/pubsub/EventListener.java

@@ -2,8 +2,15 @@
 
 /**
  * A functional interface for event listeners.
+ * Implementations of this interface can be used to handle events emitted by the EventEmitter.
  */
 @FunctionalInterface
 public interface EventListener {
+    /**
+     * Handles an event with the given arguments.
+     *
+     * @param args the arguments passed to the event
+     * @throws Exception if an error occurs while handling the event
+     */
     void handle(Object... args) throws Exception;
 }

src/main/java/de/backendstack21/realtime/pubsub/IncomingMessage.java

@@ -2,44 +2,124 @@
 
 import java.util.Map;
 
+/**
+ * Represents an incoming topic message.
+ * <p>
+ * This class encapsulates the details of a message received on a specific topic,
+ * including its type, payload, and optional compression flag.
+ * </p>
+ *
+ * <h2>Key Features:</h2>
+ * <ul>
+ *     <li>Stores information about the topic, message type, compression status, and payload.</li>
+ *     <li>Supports creation from a {@link Map} representation or a generic object.</li>
+ *     <li>Provides getters for accessing message details.</li>
+ * </ul>
+ */
 public class IncomingMessage {
+
+    /**
+     * The topic on which the message was published.
+     */
     private final String topic;
+
+    /**
+     * The type of the message. Used to identify the message format or purpose.
+     */
     private final String messageType;
+
+    /**
+     * Whether the message data is compressed. Defaults to {@code false} if not specified.
+     */
     private final Boolean compression;
+
+    /**
+     * The actual message payload. Can be String or Map.
+     */
     private final Object data;
 
+    /**
+     * Private constructor for creating an IncomingMessage object with the specified properties.
+     *
+     * @param topic       the topic associated with the message.
+     * @param messageType the type or purpose of the message.
+     * @param compression a flag indicating if the message is compressed (optional).
+     * @param data        the payload or data of the message.
+     */
     private IncomingMessage(String topic, String messageType, Boolean compression, Object data) {
         this.topic = topic;
         this.messageType = messageType;
         this.compression = compression;
         this.data = data;
     }
 
+    /**
+     * Returns the topic on which the message was published.
+     *
+     * @return the topic as a {@link String}.
+     */
     public String getTopic() {
         return topic;
     }
 
+    /**
+     * Returns the type of the message.
+     *
+     * @return the message type as a {@link String}.
+     */
     public String getMessageType() {
         return messageType;
     }
 
+    /**
+     * Returns whether the message data is compressed.
+     * Defaults to {@code false} if not explicitly specified.
+     *
+     * @return a {@link Boolean} indicating if the data is compressed.
+     */
     public Boolean getCompression() {
         return compression;
     }
 
+    /**
+     * Returns the message data.
+     *
+     * @return the payload as an {@link Object}.
+     */
     public Object getData() {
         return data;
     }
 
+    /**
+     * Creates an {@link IncomingMessage} object from a {@link Map} representation.
+     * The map is expected to contain the following keys:
+     * <ul>
+     *     <li>{@code "topic"}: The topic of the message (required).</li>
+     *     <li>{@code "messageType"}: The type of the message (required).</li>
+     *     <li>{@code "compression"}: A flag indicating compression (optional, defaults to {@code false}).</li>
+     *     <li>{@code "data"}: The message payload (required).</li>
+     * </ul>
+     *
+     * @param message a {@link Map} containing the message properties.
+     * @return an {@link IncomingMessage} object constructed from the map.
+     */
     public static IncomingMessage from(Map<String, Object> message) {
         String topic = (String) message.get("topic");
         String messageType = (String) message.get("messageType");
-        Boolean compression = (Boolean) message.get("compression");
+        Boolean compression = (Boolean) message.getOrDefault("compression", false);
         Object data = message.get("data");
 
         return new IncomingMessage(topic, messageType, compression, data);
     }
 
+    /**
+     * Creates an {@link IncomingMessage} object from a generic object.
+     * The object must be a {@link Map}, or an {@link IllegalArgumentException} will be thrown.
+     *
+     * @param message an {@link Object}, expected to be a {@link Map} representation of a message.
+     * @return an {@link IncomingMessage} object constructed from the object.
+     * @throws IllegalArgumentException if the input object is not a {@link Map}.
+     */
     @SuppressWarnings("unchecked")
     public static IncomingMessage from(Object message) {
         if (message instanceof Map) {
@@ -49,6 +129,12 @@ public static IncomingMessage from(Object message) {
         }
     }
 
+    /**
+     * Returns a string representation of the {@link IncomingMessage}.
+     * The string includes the topic, message type, compression status, and payload.
+     *
+     * @return a {@link String} representing the message details.
+     */
     @Override
     public String toString() {
         return "IncomingMessage{" + "topic='" + topic + '\'' + ", messageType='" + messageType + '\'' + ", compression=" + compression + ", data=" + data + '}';