sync: cherry-pick changes from feature/3.0.x

Author: loong10k

src/main/java/com/corundumstudio/socketio/spring/boot/AbstractSocketEventHandler.java

@@ -1,17 +1,17 @@
 /*
- * Copyright (c) 2018, Loong Wan (https://github.com/loong10k).
+ * Copyright (c) 2018-present, easy-4-java (https://github.com/easy-4-java).
  *
- * Licensed 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
+ * Licensed 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
+ *      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.
+ * 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.
  */
 package com.corundumstudio.socketio.spring.boot.handler;
 
@@ -25,20 +25,69 @@
 import java.util.Collection;
 import java.util.UUID;
 
+/**
+ * Reusable base class for netty-socketio event handlers.
+ *
+ * <p>Subclasses only have to declare their own event methods (annotated with
+ * {@code @OnEvent}, {@link OnConnect}, {@link OnDisconnect}, etc.); the base
+ * class provides:</p>
+ * <ul>
+ *   <li>Lifecycle callbacks that log the session id and send a {@code welcome}
+ *       event when a client connects.</li>
+ *   <li>Convenience accessors for retrieving connected clients, broadcast
+ *       operations and per-room broadcast operations from the underlying
+ *       {@link SocketIOServer}.</li>
+ *   <li>A standard {@link SocketIOServer} reference injectable via constructor
+ *       or setter so the same handler instance can be wired up by Spring or
+ *       instantiated manually.</li>
+ * </ul>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see SocketIOServer
+ * @see SocketIOClient
+ */
 @Slf4j
 public abstract class AbstractSocketEventHandler {
 
+    /**
+     * The Socket.IO server that produced this handler. May be {@code null}
+     * until {@link #setSocketIOServer(SocketIOServer)} or the convenience
+     * constructor has been invoked.
+     */
 	private SocketIOServer socketIOServer;
 
+    /**
+     * Default constructor; useful when the Socket.IO server is supplied later
+     * via {@link #setSocketIOServer(SocketIOServer)} or by the Spring
+     * container during bean initialisation.
+     */
 	public AbstractSocketEventHandler() {
 	}
 
+    /**
+     * Convenience constructor that wires the handler directly to a Socket.IO
+     * server instance.
+     *
+     * @param socketIOServer the server to dispatch events to; must not be
+     *                       {@code null} if any {@code getXxx} method is
+     *                       going to be called from this handler.
+     */
 	public AbstractSocketEventHandler(SocketIOServer socketIOServer) {
 		this.socketIOServer = socketIOServer;
 	}
 
-	// 添加connect事件，当客户端发起连接时调用，本文中将clientid与sessionid存入数据库
-	// 方便后面发送消息时查找到对应的目标client,
+    /**
+     * Default {@code connect} callback invoked by netty-socketio.
+     *
+     * <p>Logs the handshake data and emits a {@code welcome} event back to the
+     * newly connected client. Subclasses may override this method to add
+     * custom logic but should call {@code super.onConnect(client)} first if
+     * they want to preserve the welcome message.</p>
+     *
+     * @param client the client that just established a connection; never
+     *               {@code null}.
+     */
 	@OnConnect
 	public void onConnect(SocketIOClient client) {
 		log.debug("Connect OK.");
@@ -49,35 +98,82 @@ public void onConnect(SocketIOClient client) {
 		client.sendEvent("welcome", "ok");
 	}
 
-	// 添加@OnDisconnect事件，客户端断开连接时调用，刷新客户端信息
+    /**
+     * Default {@code disconnect} callback invoked by netty-socketio.
+     *
+     * <p>Logs the leaving client. Subclasses may override this method to add
+     * custom cleanup logic.</p>
+     *
+     * @param client the client that just disconnected; never {@code null}.
+     */
 	@OnDisconnect
 	public void onDisconnect(SocketIOClient client) {
 		log.debug("Disconnect OK.");
 		log.debug("Session ID  : %s", client.getSessionId());
 	}
 
+    /**
+     * Returns every client currently connected to the given namespace.
+     *
+     * @param namespace the namespace name (use the empty string for the
+     *                  default namespace); must not be {@code null}.
+     * @return the live collection of clients; never {@code null}.
+     */
 	public Collection<SocketIOClient> getClients(String namespace) {
 		return getSocketIOServer().getNamespace(namespace).getAllClients();
 	}
 
+    /**
+     * Looks up a single client in the given namespace by its session id.
+     *
+     * @param namespace the namespace name; must not be {@code null}.
+     * @param sessionId the session id; must not be {@code null}.
+     * @return the matching client, or {@code null} if no client with that
+     *         session id is currently connected.
+     */
 	public SocketIOClient getClient(String namespace, UUID sessionId) {
 		return getSocketIOServer().getNamespace(namespace).getClient(sessionId);
 	}
 
+    /**
+     * Returns the {@link BroadcastOperations} for an entire namespace.
+     *
+     * @param namespace the namespace name; must not be {@code null}.
+     * @return the broadcast handle; never {@code null}.
+     */
 	public BroadcastOperations getBroadcastOperations(String namespace) {
 		return getSocketIOServer().getNamespace(namespace).getBroadcastOperations();
 	}
 
+    /**
+     * Returns the {@link BroadcastOperations} scoped to a single room inside a
+     * namespace.
+     *
+     * @param namespace the namespace name; must not be {@code null}.
+     * @param room      the room name; must not be {@code null}.
+     * @return the room-scoped broadcast handle; never {@code null}.
+     */
 	public BroadcastOperations getBroadcastOperations(String namespace, String room) {
 		return getSocketIOServer().getNamespace(namespace).getRoomOperations(room);
 	}
 
+    /**
+     * Returns the Socket.IO server bound to this handler.
+     *
+     * @return the bound server, possibly {@code null} if none has been set.
+     */
 	public SocketIOServer getSocketIOServer() {
 		return socketIOServer;
 	}
 
+    /**
+     * Replaces the Socket.IO server bound to this handler.
+     *
+     * @param socketIOServer the new server; may be {@code null} to clear the
+     *                       reference (not recommended for production code).
+     */
 	public void setSocketIOServer(SocketIOServer socketIOServer) {
 		this.socketIOServer = socketIOServer;
 	}
 
-}
+}

src/main/java/com/corundumstudio/socketio/spring/boot/CacheKey.java

@@ -1,3 +1,18 @@
+/*
+ * Copyright (c) 2018-present, easy-4-java (https://github.com/easy-4-java).
+ *
+ * Licensed 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.
+ */
 package com.corundumstudio.socketio.store;
 
 import org.springframework.util.StringUtils;
@@ -6,67 +21,130 @@
 import java.util.StringJoiner;
 import java.util.function.Function;
 
+/**
+ * Enumerates the canonical Socket.IO cache keys and offers utility helpers to
+ * assemble them into namespaced strings.
+ *
+ * <p>Each enum constant bundles a human-readable description together with a
+ * function that produces the final cache-key string given any required
+ * arguments (e.g. a session identifier or an IP address). The static helpers
+ * {@link #getKeyStr(Object...)} and {@link #getThreadKeyStr(String, Object...)}
+ * perform the actual string assembly, using {@link #REDIS_PREFIX} as the global
+ * prefix and {@link #DELIMITER} ({@code ":"}) as the separator.</p>
+ *
+ * <p>Null or blank segments are skipped silently during assembly so call sites
+ * can pass optional identifiers without conditionals.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see CacheKeyConstant
+ */
 public enum CacheKey {
 
     /**
-     * Socket会话列表
+     * Cache key for the list of all known Socket.IO sessions.
      */
-    SOCKET_IO_SESSIONS("Socket会话列表", (p1) -> {
+    SOCKET_IO_SESSIONS("Socket session list", (p1) -> {
         return CacheKey.getKeyStr(CacheKeyConstant.SOCKET_IO_SESSIONS_KEY);
     }),
     /**
-     * Socket会话信息
+     * Cache key for an individual Socket.IO session; combined with the session
+     * identifier passed to {@link #getKey(Object)}.
      */
-    SOCKET_IO_SESSION("Socket会话信息", (sessionId) -> {
+    SOCKET_IO_SESSION("Socket session info", (sessionId) -> {
         return CacheKey.getKeyStr(CacheKeyConstant.SOCKET_IO_SESSION_KEY, sessionId);
     }),
 
     /**
-     * IP地区编码缓存
+     * Cache key for the region/country code resolved from an IP address.
      */
-    SOCKET_IO_IP_REGION("用户坐标对应的地区编码缓存", (ip)->{
+    SOCKET_IO_IP_REGION("IP-to-region code cache", (ip)->{
         return getKeyStr(CacheKeyConstant.SOCKET_IO_IP_REGION_KEY, ip);
     }),
     /**
-     * IP坐标缓存
+     * Cache key for the geographic coordinate resolved from an IP address.
      */
-    SOCKET_IO_IP_LOCATION("用户坐标对应的地理位置缓存", (ip)->{
+    SOCKET_IO_IP_LOCATION("IP-to-location coordinate cache", (ip)->{
         return getKeyStr(CacheKeyConstant.SOCKET_IO_IP_LOCATION_KEY, ip);
     })
 	;
 
+    /**
+     * Human-readable description of this cache key, intended for logging and
+     * debugging rather than runtime dispatch.
+     */
 	private String desc;
+    /**
+     * Function that builds the final cache-key string when given the
+     * context-specific identifier (or {@code null} for keys without one).
+     */
     private Function<Object, String> function;
 
+    /**
+     * Creates a new enum constant.
+     *
+     * @param desc     a short human-readable description of the key.
+     * @param function the function that produces the final cache-key string;
+     *                 must accept {@code null} for keys that take no argument.
+     */
     CacheKey(String desc, Function<Object, String> function) {
         this.desc = desc;
         this.function = function;
     }
 
-    public String getDesc() {
+    /**
+     * Returns the description associated with this key.
+     *
+     * @return the short human-readable description; never {@code null}.
+     */
+	public String getDesc() {
 		return desc;
 	}
 
     /**
-     * 1、获取全名称key
-     * @return 无参数组合后的redis缓存key
+     * Returns the fully-qualified cache key (no extra arguments required).
+     *
+     * @return the assembled cache key with only {@link #REDIS_PREFIX} and the
+     *         constant segment(s) included.
      */
     public String getKey() {
         return this.function.apply(null);
     }
 
     /**
-     * 1、获取全名称key
-     * @param key 缓存key的部分值
-     * @return key参数组合后的redis缓存key
+     * Returns the fully-qualified cache key, combining the constant prefix with
+     * the supplied identifier.
+     *
+     * @param key the context-specific identifier (e.g. session id, IP address).
+     *            May be {@code null}, in which case it is skipped during
+     *            assembly rather than rendered as the literal string
+     *            {@code "null"}.
+     * @return the assembled cache key.
      */
     public String getKey(Object key) {
         return this.function.apply(key);
     }
 
+    /**
+     * Global prefix applied to every Redis cache key produced by this class.
+     */
     public static String REDIS_PREFIX = "rds";
+    /**
+     * Segment separator used by the cache-key assembly helpers.
+     */
     public final static String DELIMITER = ":";
 
+    /**
+     * Assembles a cache key by concatenating {@link #REDIS_PREFIX} with each
+     * supplied argument using {@link #DELIMITER}.
+     *
+     * <p>Null values and values whose {@code toString()} is blank are silently
+     * skipped, so callers may pass optional identifiers without branching.</p>
+     *
+     * @param args the segments to concatenate after the prefix; may be empty
+     *             but should not be {@code null}.
+     * @return the joined cache key string, never {@code null}.
+     */
     public static String getKeyStr(Object... args) {
         StringJoiner tempKey = new StringJoiner(DELIMITER);
         tempKey.add(REDIS_PREFIX);
@@ -79,6 +157,14 @@ public static String getKeyStr(Object... args) {
         return tempKey.toString();
     }
 
+    /**
+     * Assembles a thread-scoped cache key that includes the current thread id
+     * between the supplied {@code prefix} and the extra arguments.
+     *
+     * @param prefix the leading segment (added before the thread id).
+     * @param args   the additional segments; null or blank entries are skipped.
+     * @return the joined, thread-scoped cache key string, never {@code null}.
+     */
     public static String getThreadKeyStr(String prefix, Object... args) {
 
         StringJoiner tempKey = new StringJoiner(DELIMITER);
@@ -93,9 +179,15 @@ public static String getThreadKeyStr(String prefix, Object... args) {
         return tempKey.toString();
     }
 
+    /**
+     * Local sanity check used during development to print a sample key.
+     *
+     * @param args ignored; present so this class can be executed directly via
+     *             {@code java CacheKey}.
+     */
     public static void main(String[] args) {
         System.out.println(getKeyStr(233,""));
     }
 
 
-}
+}