Package io.muserver

Interface AsyncSsePublisher

  • public interface AsyncSsePublisher

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

    This is preferrable to the (blocking) SsePublisher when you have a large number of subscribers as messages will be sent in a non-blocking fashion.

    The usage is that same as for the synchronous version except that each send method returns a CompletionStage which contains completion or exception info.

    See Also:
    SsePublisher

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void close()
      Stops the event stream.
      boolean isClosed()
      Checks if this publisher has been closed.
      java.util.concurrent.CompletionStage<?> send​(java.lang.String message)
      Sends a message (without an ID or event type)
      java.util.concurrent.CompletionStage<?> send​(java.lang.String message, java.lang.String event)
      Sends a message with an event type (without an ID).
      java.util.concurrent.CompletionStage<?> send​(java.lang.String message, java.lang.String event, java.lang.String eventID)
      Sends a message with an event type and ID.
      java.util.concurrent.CompletionStage<?> sendComment​(java.lang.String comment)
      Sends a comment to the client.
      java.util.concurrent.CompletionStage<?> 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).
      void setResponseCompleteHandler​(ResponseCompleteListener responseCompleteListener)
      Add a listener for when request processing is complete.
      static AsyncSsePublisher start​(MuRequest request, MuResponse response)
      Creates a new Server-Sent Events publisher.

    • Method Detail

      • send

        java.util.concurrent.CompletionStage<?> send​(java.lang.String message)
        Sends a message (without an ID or event type)
        Parameters:
        message - The message to send
        Returns:
        completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

      • send

        java.util.concurrent.CompletionStage<?> send​(java.lang.String message,
                                             java.lang.String event)

        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
        Returns:
        completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

      • send

        java.util.concurrent.CompletionStage<?> send​(java.lang.String message,
                                             java.lang.String event,
                                             java.lang.String eventID)

        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.
        Returns:
        completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

      • 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

        java.util.concurrent.CompletionStage<?> sendComment​(java.lang.String comment)
        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.
        Returns:
        completion stage that completes when the comment has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

      • setClientReconnectTime

        java.util.concurrent.CompletionStage<?> 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). 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.
        Returns:
        completion stage that completes when the event has been sent. If there is a problem during sending of an event, completion stage will be completed exceptionally.

      • setResponseCompleteHandler

        void setResponseCompleteHandler​(ResponseCompleteListener responseCompleteListener)
        Add a listener for when request processing is complete. One use of this is to detect early client disconnects so that expensive operations can be cancelled.

        Check ResponseInfo.completedSuccessfully() for false for SSE streams that did not complete.

        Parameters:
        responseCompleteListener - The handler to invoke when the request is complete.

      • isClosed

        boolean isClosed()
        Checks if this publisher has been closed.

        This will be true if the server or the client closes the SSE stream.

        Returns:
        true if it is closed; otherwise false

      • start

        static AsyncSsePublisher 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.