Package io.muserver

Interface SsePublisher

  • public interface SsePublisher

    An interface for sending Server-Sent Events (SSE) to a client.

    The following example creates a publisher and publishes 10 messages to it from another thread:

    
 server = httpsServer()
     .addHandler(Method.GET, "/streamer", (request, response, pathParams) -> {
         SsePublisher ssePublisher = SsePublisher.start(request, response);
         new Thread(() -> {
             try {
                 for (int i = 0; i < 100; i++) {
                     ssePublisher.send("This is message " + i);
                     Thread.sleep(1000);
                 }
             } catch (Exception e) {
                 // the user has probably disconnected; stop publishing
             } finally {
                 ssePublisher.close();
             }
         }).start();

     })
     .start();

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Stops the event stream.
      void send​(java.lang.String message)
      Sends a message (without an ID or event type)
      void send​(java.lang.String message, java.lang.String event)
      Sends a message with an event type (without an ID).
      void send​(java.lang.String message, java.lang.String event, java.lang.String eventID)
      Sends a message with an event type and ID.
      void sendComment​(java.lang.String comment)
      Sends a comment to the client.
      void setClientReconnectTime​(long timeToWait, java.util.concurrent.TimeUnit unit)
      Sends a message to the client instructing it to reconnect after the given time period in case of any disconnection (including calling close() from the server).
      static SsePublisher start​(MuRequest request, MuResponse response)
      Creates a new Server-Sent Events publisher.

    • Method Detail

      • send

        void send​(java.lang.String message)
   throws java.io.IOException
        Sends a message (without an ID or event type)
        Parameters:
        message - The message to send
        Throws:
        java.io.IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

      • send

        void send​(java.lang.String message,
          java.lang.String event)
   throws java.io.IOException

        Sends a message with an event type (without an ID).

        Clients can use the event type to listen to different types of events, for example if the event type is pricechange the the following JavaScript can be used:

        
     var source = new EventSource('/streamer');
     source.addEventListener('pricechange', e => console.log(e.data));
        Parameters:
        message - The message to send
        event - An event name. If null is specified, clients default to a message type of message
        Throws:
        java.io.IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

      • send

        void send​(java.lang.String message,
          java.lang.String event,
          java.lang.String eventID)
   throws java.io.IOException

        Sends a message with an event type and ID.

        Clients can use the event type to listen to different types of events, for example if the event type is pricechange the the following JavaScript can be used:

        
     var source = new EventSource('/streamer');
     source.addEventListener('pricechange', e => console.log(e.data));
        Parameters:
        message - The message to send
        event - An event name. If null is specified, clients default to a message type of message
        eventID - An identifier for the message. If set, and the browser reconnects, then the last event ID will be sent by the browser in the Last-Event-ID request header.
        Throws:
        java.io.IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

      • close

        void close()

        Stops the event stream.

        Warning: most clients will reconnect several seconds after this message is called. To prevent that happening, close the stream from the client or on the next request return a 204 No Content to the client.

      • sendComment

        void sendComment​(java.lang.String comment)
          throws java.io.IOException
        Sends a comment to the client. Clients will ignore this, however it can be used as a way to keep the connection alive.
        Parameters:
        comment - A single-line string to send as a comment.
        Throws:
        java.io.IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

      • setClientReconnectTime

        void setClientReconnectTime​(long timeToWait,
                            java.util.concurrent.TimeUnit unit)
                     throws java.io.IOException

        Sends a message to the client instructing it to reconnect after the given time period in case of any disconnection (including calling close() from the server). A common default (controlled by the client) is several seconds.

        Note: clients could ignore this value.

        Parameters:
        timeToWait - The time the client should wait before attempting to reconnect in case of any disconnection.
        unit - The unit of time.
        Throws:
        java.io.IOException - Thrown if there is an error writing to the client, for example if the user has closed their browser.

      • start

        static SsePublisher start​(MuRequest request,
                          MuResponse response)

        Creates a new Server-Sent Events publisher. This is designed by be called from within a MuHandler.

        This will set the content type of the response to text/event-stream and disable caching.

        The request will also switch to async mode, which means you can use the returned publisher in another thread.

        IMPORTANT: The close() method must be called when publishing is complete.

        Parameters:
        request - The current MuRequest
        response - The current MuResponse
        Returns:
        Returns a publisher that can be used to send messages to the client.