Module jdk.incubator.httpclient
Package jdk.incubator.http

Interface WebSocket.Listener

  • Enclosing interface:
    WebSocket
    public static interface WebSocket.Listener
    The receiving interface of WebSocket.
    Incubating Feature. Will be removed in a future release.

    A WebSocket invokes methods on its listener when it receives messages or encounters events. The invoking WebSocket is passed as an argument to Listener's methods. A WebSocket invokes methods on its listener in a thread-safe manner.

    Unless otherwise stated if a listener's method throws an exception or a CompletionStage returned from a method completes exceptionally, the WebSocket will invoke onError with this exception.

    If a listener's method returns null rather than a CompletionStage, WebSocket will behave as if the listener returned a CompletionStage that is already completed normally.

    Since:
    9

    • Method Detail

      • onOpen

        default void onOpen​(WebSocket webSocket)
        A WebSocket has been connected.

        This is the first invocation and it is made at most once. This method is typically used to make an initial request for messages.

        Implementation Requirements:
        The default implementation of this method behaves as if: 
        
     webSocket.request(1);
        Parameters:
        webSocket - the WebSocket that has been connected

      • onText

        default CompletionStage<?> onText​(WebSocket webSocket,
                                  CharSequence message,
                                  WebSocket.MessagePart part)
        A Text message has been received.

        If a whole message has been received, this method will be invoked with MessagePart.WHOLE marker. Otherwise, it will be invoked with FIRST, possibly a number of times with PART and, finally, with LAST markers. If this message is partial, it may be an incomplete UTF-16 sequence. However, the concatenation of all messages through the last will be a complete UTF-16 sequence.

        Return a CompletionStage which will be used by the WebSocket as a signal it may reclaim the CharSequence. Do not access the CharSequence after this has completed.

        Implementation Requirements:
        The default implementation of this method behaves as if: 
        
     webSocket.request(1);
     return null;
        Implementation Note:
        This method is always invoked with character sequences which are complete UTF-16 sequences.
        Parameters:
        webSocket - the WebSocket on which the message has been received
        message - the message
        part - the part
        Returns:
        a CompletionStage which completes when the CharSequence may be reclaimed; or null if it may be reclaimed immediately

      • onBinary

        default CompletionStage<?> onBinary​(WebSocket webSocket,
                                    ByteBuffer message,
                                    WebSocket.MessagePart part)
        A Binary message has been received.

        If a whole message has been received, this method will be invoked with MessagePart.WHOLE marker. Otherwise, it will be invoked with FIRST, possibly a number of times with PART and, finally, with LAST markers.

        This message consists of bytes from the buffer's position to its limit.

        Return a CompletionStage which will be used by the WebSocket as a signal it may reclaim the ByteBuffer. Do not access the ByteBuffer after this has completed.

        Implementation Requirements:
        The default implementation of this method behaves as if: 
        
     webSocket.request(1);
     return null;
        Parameters:
        webSocket - the WebSocket on which the message has been received
        message - the message
        part - the part
        Returns:
        a CompletionStage which completes when the ByteBuffer may be reclaimed; or null if it may be reclaimed immediately

      • onPing

        default CompletionStage<?> onPing​(WebSocket webSocket,
                                  ByteBuffer message)
        A Ping message has been received.

        The message consists of not more than 125 bytes from the buffer's position to its limit.

        Return a CompletionStage which will be used by the WebSocket as a signal it may reclaim the ByteBuffer. Do not access the ByteBuffer after this has completed.

        Implementation Requirements:
        The default implementation of this method behaves as if: 
        
     webSocket.request(1);
     return null;
        Parameters:
        webSocket - the WebSocket on which the message has been received
        message - the message
        Returns:
        a CompletionStage which completes when the ByteBuffer may be reclaimed; or null if it may be reclaimed immediately

      • onPong

        default CompletionStage<?> onPong​(WebSocket webSocket,
                                  ByteBuffer message)
        A Pong message has been received.

        The message consists of not more than 125 bytes from the buffer's position to its limit.

        Return a CompletionStage which will be used by the WebSocket as a signal it may reclaim the ByteBuffer. Do not access the ByteBuffer after this has completed.

        Implementation Requirements:
        The default implementation of this method behaves as if: 
        
     webSocket.request(1);
     return null;
        Parameters:
        webSocket - the WebSocket on which the message has been received
        message - the message
        Returns:
        a CompletionStage which completes when the ByteBuffer may be reclaimed; or null if it may be reclaimed immediately

      • onClose

        default CompletionStage<?> onClose​(WebSocket webSocket,
                                   int statusCode,
                                   String reason)
        A Close message has been received.

        This is the last invocation from the WebSocket. By the time this invocation begins the WebSocket's input will have been closed. Be prepared to receive this invocation at any time after onOpen regardless of whether or not any messages have been requested from the WebSocket.

        A Close message consists of a status code and a reason for closing. The status code is an integer from the range 1000 <= code <= 65535. The reason is a string which has an UTF-8 representation not longer than 123 bytes.

        Return a CompletionStage that will be used by the WebSocket as a signal that it may close the output. The WebSocket will close the output at the earliest of completion of the returned CompletionStage or invoking a sendClose method.

        If an exception is thrown from this method or a CompletionStage returned from it completes exceptionally, the resulting behaviour is undefined.

        Parameters:
        webSocket - the WebSocket on which the message has been received
        statusCode - the status code
        reason - the reason
        Returns:
        a CompletionStage which completes when the WebSocket may be closed; or null if it may be closed immediately

      • onError

        default void onError​(WebSocket webSocket,
                     Throwable error)
        An unrecoverable error has occurred.

        This is the last invocation from the WebSocket. By the time this invocation begins both WebSocket's input and output will have been closed. Be prepared to receive this invocation at any time after onOpen regardless of whether or not any messages have been requested from the WebSocket.

        If an exception is thrown from this method, resulting behavior is undefined.

        Parameters:
        webSocket - the WebSocket on which the error has occurred
        error - the error