org.java_websocket.server

Class WebSocketServer

java.lang.Object

org.java_websocket.WebSocketAdapter

org.java_websocket.AbstractWebSocket

org.java_websocket.server.WebSocketServer

All Implemented Interfaces:

Runnable, WebSocketListener

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	WebSocketServer.WebSocketWorker This class is used to process incoming data

Field Summary

Fields

Modifier and Type	Field and Description
protected List<WebSocketServer.WebSocketWorker>	decoders
static int	DECODERS

Constructor Summary

Constructors

Constructor and Description
WebSocketServer() Creates a WebSocketServer that will attempt to listen on port WebSocket.DEFAULT_PORT.
WebSocketServer(InetSocketAddress address) Creates a WebSocketServer that will attempt to bind/listen on the given address.
WebSocketServer(InetSocketAddress address, int decodercount)
WebSocketServer(InetSocketAddress address, int decodercount, List<Draft> drafts)
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.
WebSocketServer(InetSocketAddress address, List<Draft> drafts)

Method Summary

Modifier and Type	Method and Description
protected boolean	addConnection(WebSocket ws)
protected void	allocateBuffers(WebSocket c)
void	broadcast(byte[] data) Send a byte array to all connected endpoints
void	broadcast(byte[] data, Collection<WebSocket> clients) Send a byte array to a specific collection of websocket connections
void	broadcast(String text) Send a text to all connected endpoints
void	broadcast(String text, Collection<WebSocket> clients) Send a text to a specific collection of websocket connections
Collection<WebSocket>	connections() Deprecated.
ByteBuffer	createBuffer()
InetSocketAddress	getAddress()
Collection<WebSocket>	getConnections() Returns all currently connected clients.
List<Draft>	getDraft()
InetSocketAddress	getLocalSocketAddress(WebSocket conn)
int	getPort() Gets the port number that this server listens on.
InetSocketAddress	getRemoteSocketAddress(WebSocket conn)
WebSocketFactory	getWebSocketFactory()
abstract void	onClose(WebSocket conn, int code, String reason, boolean remote) Called after the websocket connection has been closed.
void	onCloseInitiated(WebSocket conn, int code, String reason)
void	onClosing(WebSocket conn, int code, String reason, boolean remote)
protected boolean	onConnect(SelectionKey key) Returns whether a new connection shall be accepted or not. Therefore method is well suited to implement some kind of connection limitation.
abstract void	onError(WebSocket conn, Exception ex) Called when errors occurs.
void	onFragment(WebSocket conn, Framedata fragment) Deprecated.
void	onMessage(WebSocket conn, ByteBuffer message) Callback for binary messages received from the remote host
abstract void	onMessage(WebSocket conn, String message) Callback for string messages received from the remote host
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.
abstract void	onStart() Called when the server started up successfully.
void	onWebsocketClose(WebSocket conn, int code, String reason, boolean remote) Called after WebSocket#close is explicity called, or when the other end of the WebSocket connection is closed.
void	onWebsocketCloseInitiated(WebSocket conn, int code, String reason) send when this peer sends a close handshake
void	onWebsocketClosing(WebSocket conn, int code, String reason, boolean remote) Called as soon as no further frames are accepted
void	onWebsocketError(WebSocket conn, Exception ex) Called if an exception worth noting occurred.
ServerHandshakeBuilder	onWebsocketHandshakeReceivedAsServer(WebSocket conn, Draft draft, ClientHandshake request) This default implementation does not do anything.
void	onWebsocketMessage(WebSocket conn, ByteBuffer blob) Called when an entire binary frame has been received.
void	onWebsocketMessage(WebSocket conn, String message) Called when an entire text frame has been received.
void	onWebsocketMessageFragment(WebSocket conn, Framedata frame) Deprecated.
void	onWebsocketOpen(WebSocket conn, Handshakedata handshake) Called after onHandshakeReceived returns true.
void	onWriteDemand(WebSocket w) This method is used to inform the selector thread that there is data queued to be written to the socket.
protected void	queue(WebSocketImpl ws)
protected void	releaseBuffers(WebSocket c)
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
void	run()
void	setWebSocketFactory(WebSocketServerFactory wsf)
void	start() Starts the server selectorthread that binds to the currently set port number and listeners for WebSocket connection requests.
void	stop()
void	stop(int timeout) 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.

Methods inherited from class org.java_websocket.AbstractWebSocket

getConnectionLostTimeout, isReuseAddr, isTcpNoDelay, setConnectionLostTimeout, setReuseAddr, setTcpNoDelay, startConnectionLostTimer, stopConnectionLostTimer

Methods inherited from class org.java_websocket.WebSocketAdapter

onWebsocketHandshakeReceivedAsClient, onWebsocketHandshakeSentAsClient, onWebsocketPing, onWebsocketPong

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DECODERS

public static int DECODERS

decoders

protected List<WebSocketServer.WebSocketWorker> decoders

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

stop

public void stop()
          throws IOException,
                 InterruptedException

Throws:

IOException

InterruptedException

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

getAddress

public InetSocketAddress getAddress()

getPort

public int getPort()

Gets the port number that this server listens on.

Returns:

The port number.

getDraft

public List<Draft> getDraft()

run

public void run()

Specified by:

run in interface Runnable

allocateBuffers

protected void allocateBuffers(WebSocket c)
                        throws InterruptedException

Throws:

InterruptedException

releaseBuffers

protected void releaseBuffers(WebSocket c)
                       throws InterruptedException

Throws:

InterruptedException

createBuffer

public ByteBuffer createBuffer()

queue

protected void queue(WebSocketImpl ws)
              throws InterruptedException

Throws:

InterruptedException

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.

onWebsocketMessageFragment

@Deprecated
public void onWebsocketMessageFragment(WebSocket conn,
                                                   Framedata frame)

Deprecated.

Description copied from class: WebSocketAdapter

This default implementation does not do anything. Go ahead and overwrite it

Specified by:

onWebsocketMessageFragment in interface WebSocketListener

Overrides:

onWebsocketMessageFragment in class WebSocketAdapter

Parameters:

conn - The WebSocket instance this event is occurring on.

frame - The fragmented frame

See Also:

WebSocketListener.onWebsocketMessageFragment(WebSocket, Framedata)

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

onWebsocketHandshakeReceivedAsServer

public ServerHandshakeBuilder onWebsocketHandshakeReceivedAsServer(WebSocket conn,
                                                                   Draft draft,
                                                                   ClientHandshake request)
                                                            throws InvalidDataException

Description copied from class: WebSocketAdapter

This default implementation does not do anything. Go ahead and overwrite it.

Specified by:

onWebsocketHandshakeReceivedAsServer in interface WebSocketListener

Overrides:

onWebsocketHandshakeReceivedAsServer in class WebSocketAdapter

Parameters:

conn - The WebSocket related to this event

draft - The protocol draft the client uses to connect

request - The opening http message send by the client. Can be used to access additional fields like cookies.

Returns:

Returns an incomplete handshake containing all optional fields

Throws:

InvalidDataException - Throwing this exception will cause this handshake to be rejected

See Also:

WebSocketListener.onWebsocketHandshakeReceivedAsServer(WebSocket, Draft, ClientHandshake)

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)

setWebSocketFactory

public final void setWebSocketFactory(WebSocketServerFactory wsf)

getWebSocketFactory

public final WebSocketFactory getWebSocketFactory()

onConnect

protected boolean onConnect(SelectionKey key)

Returns whether a new connection shall be accepted or not.
Therefore method is well suited to implement some kind of connection limitation.

Parameters:

key - the SelectionKey for the new connection

Returns:

Can this new connection be accepted

See Also:

onOpen(WebSocket, ClientHandshake), onWebsocketHandshakeReceivedAsServer(WebSocket, Draft, ClientHandshake)

getLocalSocketAddress

public InetSocketAddress getLocalSocketAddress(WebSocket conn)

Specified by:

getLocalSocketAddress in interface WebSocketListener

Parameters:

conn - The WebSocket instance this event is occuring on.

Returns:

Returns the address of the endpoint this socket is bound to.

See Also:

WebSocket.getLocalSocketAddress()

getRemoteSocketAddress

public InetSocketAddress getRemoteSocketAddress(WebSocket conn)

Specified by:

getRemoteSocketAddress in interface WebSocketListener

Parameters:

conn - The WebSocket instance this event is occuring on.

Returns:

Returns the address of the endpoint this socket is connected to, ornull if it is unconnected.

See Also:

WebSocket.getRemoteSocketAddress()

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)

onFragment

@Deprecated
public void onFragment(WebSocket conn,
                                   Framedata fragment)

Deprecated.

Callback for fragmented frames

Parameters:

conn - The WebSocket instance this event is occurring on.

fragment - The fragmented frame

See Also:

WebSocket.sendFragmentedFrame(org.java_websocket.framing.Framedata.Opcode, ByteBuffer, boolean)

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(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(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