netty-websocket-spring-boot-starter Documentation

repository·master·Indexed 19 days ago

https://github.com/niezhiliang/netty-websocket-spring-boot

A high-performance, lightweight WebSocket starter for Spring Boot built on Netty. It features an annotation-driven programming model using @WsServerEndpoint and lifecycle annotations such as @HandshakeBefore, @OnOpen, @OnMessage, @OnClose, @OnError, and @OnEvent to handle WebSocket events.

Tokens
1.1K
Snippets
3
Records
4
Agent score
16%

What's inside netty-websocket-spring-boot-starter

  1. Install netty-websocket-spring-boot-starter

    master

    Add the following Maven dependency to your pom.xml to use the Netty-based WebSocket starter in your Spring Boot project.

    <dependency>
        <groupId>com.niezhiliang</groupId>
        <artifactId>netty-websocket-spring-boot-starter</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>
  2. Implement a WebSocket Server with @WsServerEndpoint

    master

    To create a WebSocket server, define a class annotated with @WsServerEndpoint. You can specify the path using the value attribute, which supports path variables (e.g., /websocket/{uid}/{arg}). Use lifecycle annotations to handle different WebSocket events.

    @WsServerEndpoint(value = "/websocket/{uid}/{arg}")
    public class ServerEndpoint {
    
        @HandshakeBefore
        public void before (HttpHeaders headers) {
            System.out.println("before");
        }
    
        @OnOpen
        public void open(Session session, @PathParam (value="uid") String uid, @PathParam String arg){
            System.out.println("open");
            session.sendText("hello client");
        }
    
        @OnMessage
        public void onMessage(Session session, String message){
            System.out.println("message:" + message);
            session.sendText("server: " + message);
        }
    
        @OnClose
        public void onClose(){
            System.out.println("close  " + LocalDateTime.now());
        }
    
        @OnError
        public void onError(Session session, Throwable e) {
            System.out.println("onError");
        }
    
        @OnEvent
        public void onEvent(Session session, Object evt) {
            if (evt instanceof IdleStateEvent) {
                // Handle heartbeat/idle events
            }
        }
    }
  3. Supported WebSocket Event Annotations

    master

    The starter provides several annotations to hook into the WebSocket lifecycle:

    AnnotationEvent TypeTypical Use Case
    @HandshakeBeforeBefore HandshakeAuthentication and authorization
    @OnOpenConnection SuccessInitialization
    @OnMessageMessage ReceivedHandling incoming data
    @OnCloseConnection ClosedCleanup
    @OnErrorErrorException handling
    @OnEventEvent (e.g. Heartbeat)Handling idle state or timeouts
  4. Supported Parameter Types for Annotation Methods

    master

    The following parameter types are supported across the different event annotations. Note that @PathParam is used to extract variables from the @WsServerEndpoint path.

    | Parameter | @HandshakeBefore | @OnOpen | @OnClose | @OnMessage | @OnEvent | @OnError |
    |-----------|-----------------|--------|---------|-----------|---------|----------|
    | HttpHeaders | √ | √ | √ | √ | √ | √ |
    | Session | √ | √ | √ | √ | √ | √ |
    | @PathParam | √ | √ | √ | √ | √ | √ |
    | String (message content) | × | × | × | √ | × | × |
    | Throwable | × | × | × | × | × | √ |
    | Object (event) | × | × | × | × | √ | × |