Package org.java_websocket.server

Class WebSocketServer

  • All Implemented Interfaces:
    Runnable, WebSocketListener
    Direct Known Subclasses:
    WsServer
    public abstract class WebSocketServer
extends AbstractWebSocket
implements Runnable
    WebSocketServer is an abstract class that only takes care of the HTTP handshake portion of WebSockets. It's up to a subclass to add functionality/purpose to the server.

    • Constructor Detail

      • WebSocketServer

        public WebSocketServer()
        Creates a WebSocketServer that will attempt to listen on port WebSocket.DEFAULT_PORT.
        See Also:
        more details here

      • WebSocketServer

        public WebSocketServer​(InetSocketAddress address)
        Creates a WebSocketServer that will attempt to bind/listen on the given address.
        Parameters:
        address - The address to listen to
        See Also:
        more details here

      • WebSocketServer

        public WebSocketServer​(InetSocketAddress address,
                       int decodercount)
        Parameters:
        address - The address (host:port) this server should listen on.
        decodercount - The number of WebSocketServer.WebSocketWorkers that will be used to process the incoming network data. By default this will be Runtime.getRuntime().availableProcessors()
        See Also:
        more details here

      • WebSocketServer

        public WebSocketServer​(InetSocketAddress address,
                       List<Draft> drafts)
        Parameters:
        address - The address (host:port) this server should listen on.
        drafts - The versions of the WebSocket protocol that this server instance should comply to. Clients that use an other protocol version will be rejected.
        See Also:
        more details here

      • WebSocketServer

        public WebSocketServer​(InetSocketAddress address,
                       int decodercount,
                       List<Draft> drafts)
        Parameters:
        address - The address (host:port) this server should listen on.
        decodercount - The number of WebSocketServer.WebSocketWorkers that will be used to process the incoming network data. By default this will be Runtime.getRuntime().availableProcessors()
        drafts - The versions of the WebSocket protocol that this server instance should comply to. Clients that use an other protocol version will be rejected.
        See Also:
        more details here

      • WebSocketServer

        public WebSocketServer​(InetSocketAddress address,
                       int decodercount,
                       List<Draft> drafts,
                       Collection<WebSocket> connectionscontainer)
        Creates a WebSocketServer that will attempt to bind/listen on the given address, and comply with Draft version draft.
        Parameters:
        address - The address (host:port) this server should listen on.
        decodercount - The number of WebSocketServer.WebSocketWorkers that will be used to process the incoming network data. By default this will be Runtime.getRuntime().availableProcessors()
        drafts - The versions of the WebSocket protocol that this server instance should comply to. Clients that use an other protocol version will be rejected.
        connectionscontainer - Allows to specify a collection that will be used to store the websockets in.
        If you plan to often iterate through the currently connected websockets you may want to use a collection that does not require synchronization like a CopyOnWriteArraySet. In that case make sure that you overload removeConnection(WebSocket) and addConnection(WebSocket).
        By default a HashSet will be used.
        See Also:
        for more control over syncronized operation, more about drafts

    • Method Detail

      • start

        public void start()
        Starts the server selectorthread that binds to the currently set port number and listeners for WebSocket connection requests. Creates a fixed thread pool with the size DECODERS
        May only be called once. Alternatively you can call run() directly.
        Throws:
        IllegalStateException - Starting an instance again

      • stop

        public void stop​(int timeout)
          throws InterruptedException
        Closes all connected clients sockets, then closes the underlying ServerSocketChannel, effectively killing the server socket selectorthread, freeing the port the server was bound to and stops all internal workerthreads. If this method is called before the server is started it will never start.
        Parameters:
        timeout - Specifies how many milliseconds the overall close handshaking may take altogether before the connections are closed without proper close handshaking.
        Throws:
        InterruptedException - Interrupt

      • connections

        @Deprecated
public Collection<WebSocket> connections()
        Deprecated.
        PLEASE use the method getConnections() in the future! Returns a WebSocket[] of currently connected clients. Its iterators will be failfast and its not judicious to modify it.
        Returns:
        The currently connected clients.

      • getConnections

        public Collection<WebSocket> getConnections()
        Returns all currently connected clients. This collection does not allow any modification e.g. removing a client.
        Specified by:
        getConnections in class AbstractWebSocket
        Returns:
        A unmodifiable collection of all currently connected clients
        Since:
        1.3.8

      • getPort

        public int getPort()
        Gets the port number that this server listens on.
        Returns:
        The port number.

      • run

        public void run()
        Specified by:
        run in interface Runnable

      • onWebsocketMessage

        public final void onWebsocketMessage​(WebSocket conn,
                                     String message)
        Description copied from interface: WebSocketListener
        Called when an entire text frame has been received. Do whatever you want here...
        Specified by:
        onWebsocketMessage in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occurring on.
        message - The UTF-8 decoded message that was received.

      • onWebsocketMessage

        public final void onWebsocketMessage​(WebSocket conn,
                                     ByteBuffer blob)
        Description copied from interface: WebSocketListener
        Called when an entire binary frame has been received. Do whatever you want here...
        Specified by:
        onWebsocketMessage in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occurring on.
        blob - The binary message that was received.

      • onWebsocketOpen

        public final void onWebsocketOpen​(WebSocket conn,
                                  Handshakedata handshake)
        Description copied from interface: WebSocketListener
        Called after onHandshakeReceived returns true. Indicates that a complete WebSocket connection has been established, and we are ready to send/receive data.
        Specified by:
        onWebsocketOpen in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        handshake - The handshake of the websocket instance

      • onWebsocketClose

        public final void onWebsocketClose​(WebSocket conn,
                                   int code,
                                   String reason,
                                   boolean remote)
        Description copied from interface: WebSocketListener
        Called after WebSocket#close is explicity called, or when the other end of the WebSocket connection is closed.
        Specified by:
        onWebsocketClose in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        code - The codes can be looked up here: CloseFrame
        reason - Additional information string
        remote - Returns whether or not the closing of the connection was initiated by the remote host.

      • removeConnection

        protected boolean removeConnection​(WebSocket ws)
        This method performs remove operations on the connection and therefore also gives control over whether the operation shall be synchronized

        WebSocketServer(InetSocketAddress, int, List, Collection) allows to specify a collection which will be used to store current connections in.
        Depending on the type on the connection, modifications of that collection may have to be synchronized.

        Parameters:
        ws - The Webscoket connection which should be removed
        Returns:
        Removing connection successful

      • addConnection

        protected boolean addConnection​(WebSocket ws)
        Parameters:
        ws - the Webscoket connection which should be added
        Returns:
        Adding connection successful
        See Also:
        removeConnection(WebSocket)

      • onWebsocketError

        public final void onWebsocketError​(WebSocket conn,
                                   Exception ex)
        Description copied from interface: WebSocketListener
        Called if an exception worth noting occurred. If an error causes the connection to fail onClose will be called additionally afterwards.
        Specified by:
        onWebsocketError in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        ex - The exception that occurred.
        Might be null if the exception is not related to any specific connection. For example if the server port could not be bound.

      • onWriteDemand

        public final void onWriteDemand​(WebSocket w)
        Description copied from interface: WebSocketListener
        This method is used to inform the selector thread that there is data queued to be written to the socket.
        Specified by:
        onWriteDemand in interface WebSocketListener
        Parameters:
        w - The WebSocket instance this event is occuring on.

      • onWebsocketCloseInitiated

        public void onWebsocketCloseInitiated​(WebSocket conn,
                                      int code,
                                      String reason)
        Description copied from interface: WebSocketListener
        send when this peer sends a close handshake
        Specified by:
        onWebsocketCloseInitiated in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        code - The codes can be looked up here: CloseFrame
        reason - Additional information string

      • onWebsocketClosing

        public void onWebsocketClosing​(WebSocket conn,
                               int code,
                               String reason,
                               boolean remote)
        Description copied from interface: WebSocketListener
        Called as soon as no further frames are accepted
        Specified by:
        onWebsocketClosing in interface WebSocketListener
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        code - The codes can be looked up here: CloseFrame
        reason - Additional information string
        remote - Returns whether or not the closing of the connection was initiated by the remote host.

      • onCloseInitiated

        public void onCloseInitiated​(WebSocket conn,
                             int code,
                             String reason)

      • onClosing

        public void onClosing​(WebSocket conn,
                      int code,
                      String reason,
                      boolean remote)

      • onOpen

        public abstract void onOpen​(WebSocket conn,
                            ClientHandshake handshake)
        Called after an opening handshake has been performed and the given websocket is ready to be written on.
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        handshake - The handshake of the websocket instance

      • onClose

        public abstract void onClose​(WebSocket conn,
                             int code,
                             String reason,
                             boolean remote)
        Called after the websocket connection has been closed.
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        code - The codes can be looked up here: CloseFrame
        reason - Additional information string
        remote - Returns whether or not the closing of the connection was initiated by the remote host.

      • onMessage

        public abstract void onMessage​(WebSocket conn,
                               String message)
        Callback for string messages received from the remote host
        Parameters:
        conn - The WebSocket instance this event is occuring on.
        message - The UTF-8 decoded message that was received.
        See Also:
        onMessage(WebSocket, ByteBuffer)

      • onError

        public abstract void onError​(WebSocket conn,
                             Exception ex)
        Called when errors occurs. If an error causes the websocket connection to fail onClose(WebSocket, int, String, boolean) will be called additionally.
        This method will be called primarily because of IO or protocol errors.
        If the given exception is an RuntimeException that probably means that you encountered a bug.
        Parameters:
        conn - Can be null if there error does not belong to one specific websocket. For example if the servers port could not be bound.
        ex - The exception causing this error

      • onStart

        public abstract void onStart()
        Called when the server started up successfully. If any error occured, onError is called instead.

      • onMessage

        public void onMessage​(WebSocket conn,
                      ByteBuffer message)
        Callback for binary messages received from the remote host
        Parameters:
        conn - The WebSocket instance this event is occurring on.
        message - The binary message that was received.
        See Also:
        onMessage(WebSocket, ByteBuffer)

      • broadcast

        public void broadcast​(String text)
        Send a text to all connected endpoints
        Parameters:
        text - the text to send to the endpoints

      • broadcast

        public void broadcast​(byte[] data)
        Send a byte array to all connected endpoints
        Parameters:
        data - the data to send to the endpoints

      • broadcast

        public void broadcast​(ByteBuffer data)
        Send a ByteBuffer to all connected endpoints
        Parameters:
        data - the data to send to the endpoints

      • broadcast

        public void broadcast​(byte[] data,
                      Collection<WebSocket> clients)
        Send a byte array to a specific collection of websocket connections
        Parameters:
        data - the data to send to the endpoints
        clients - a collection of endpoints to whom the text has to be send

      • broadcast

        public void broadcast​(ByteBuffer data,
                      Collection<WebSocket> clients)
        Send a ByteBuffer to a specific collection of websocket connections
        Parameters:
        data - the data to send to the endpoints
        clients - a collection of endpoints to whom the text has to be send

      • broadcast

        public void broadcast​(String text,
                      Collection<WebSocket> clients)
        Send a text to a specific collection of websocket connections
        Parameters:
        text - the text to send to the endpoints
        clients - a collection of endpoints to whom the text has to be send