Package ej.websocket

Class WebSocket

java.lang.Object

ej.websocket.WebSocket

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

WebSocketSecure

public class WebSocket
extends Object
implements AutoCloseable

Representation for the physical websocket connection following RFC 6455 definition. It needs a WebSocketURI that describes the server to connect and an Endpoint to handle events (errors, incoming data). A WebSocket is the physical medium, managing underlying TCP connection and low level websocket events, whereas the Endpoint is here to handle high level events. The latter is more application oriented whereas the former is the physical medium.

WARNING: this implementation is designed so that WebSocket is only for client-side connection.

Constructor Summary

Constructors

Constructor	Description
WebSocket(WebSocketURI uri, Endpoint endpoint)	Create a new WebSocket instance.

Method Summary

Modifier and Type	Method	Description
void	addHeader(String name, String value)	Adds a header to send when connecting.
void	close()	Equivalent to close(new ReasonForClosure(CloseCodes.NORMAL_CLOSURE, "")).
void	close(ReasonForClosure reasonForClosure)	Close the websocket connection as described in Section 7.
void	connect()	Establish a connection to the server described by the URI.
ConnectionStates	getCurrentState()	Returns the current state of this WebSocket, see ConnectionStates for the returned states.
Endpoint	getEndpoint()	Returns the Endpoint associated to this WebSocket.
WebSocketURI	getURI()
void	ping()	Send ping with no payload to remote endpoint.
void	ping(byte[] payload)	Send ping to remote endpoint.
void	pong()	Send an unsolicited pong with no payload to remote endpoint.
void	pong(byte[] payload)	Send an unsolicited pong to remote endpoint.
void	sendBinary(byte[] binary)	Sends a binary message.
void	sendText(String text)	Sends a text message.
protected void	setSocket(Socket socket)	Sets the socket.
protected void	setupSocket()	Open the socket and sets it.

Methods inherited from class java.lang.Object

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

Constructor Detail

WebSocket

public WebSocket(WebSocketURI uri,
                 Endpoint endpoint)
          throws NullPointerException

Create a new WebSocket instance. It doesn't connect to the remote server; user has to call connect() to do so.

Parameters:

uri - URI to connect to

endpoint - the endpoint that will handle events

Throws:

NullPointerException - if 'endpoint' or 'uri' is null

Method Detail

addHeader

public void addHeader(String name,
                      String value)

Adds a header to send when connecting.

Parameters:

name - the header name

value - the header value

connect

public void connect()
             throws IllegalArgumentException,
                    WebSocketException,
                    ServerException

Establish a connection to the server described by the URI. Once the connection is up, the endpoint will be notify of high level events whereas the websocket will manage low level events (such as ping, close, etc) thank a thread running a Receiver. If at some point a problem is found, this method will throw a WebSocketException.

See section 4.1. Client Requirements.

Throws:

IllegalArgumentException - if the current state of this websocket is not NEW

ServerException - if the connection is established but the server doesn't answer properly

WebSocketException - if an error occurs during connection (most probably a socket error)

setupSocket

protected void setupSocket()
                    throws IOException

Open the socket and sets it.

Throws:

IOException - if an IOException occurs.

See Also:

setSocket(Socket)

setSocket

protected void setSocket(Socket socket)
                  throws IOException

Sets the socket.

Parameters:

socket - the socket to set.

Throws:

IOException

getCurrentState

public ConnectionStates getCurrentState()

Returns the current state of this WebSocket, see ConnectionStates for the returned states.

Returns:

the current state of this WebSocket

getEndpoint

public Endpoint getEndpoint()

Returns the Endpoint associated to this WebSocket.

Returns:

the Endpoint associated to this WebSocket

getURI

public WebSocketURI getURI()

Returns:

the WebSocketURI of the remote endpoint

close

public void close(ReasonForClosure reasonForClosure)
           throws IOException

Close the websocket connection as described in Section 7. Closing the Connection..

• Send a closing handshake to the server (see Section 7.1.2. Start the WebSocket Closing Handshake).
• Start a thread that will close the TCP connection after a timeout if the server doesn't answer thanks to a OnTimeOutCloser.
• Wait for a close frame in the Receiver to close the TCP connection and stop the OnTimeOutCloser thread.

As described in section 7.1.1 of the RFC, the client should ask the server to close the underlying TCP connection. If the client closes the TCP connection first, it would prevent it from re-opening the connection.

Parameters:

reasonForClosure - the reason for closing the connection that will be sent to remote endpoint

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

See Also:

OnTimeOutCloser

close

public void close()
           throws IOException

Equivalent to close(new ReasonForClosure(CloseCodes.NORMAL_CLOSURE, "")).

Specified by:

close in interface AutoCloseable

Throws:

IOException - thrown by the underlying Socket and associated streams when an error occurs

ping

public void ping(byte[] payload)
          throws IllegalStateException,
                 IOException

Send ping to remote endpoint.

Parameters:

payload - the payload of the ping

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

ping

public void ping()
          throws IllegalStateException,
                 IOException

Send ping with no payload to remote endpoint.

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

pong

public void pong(byte[] payload)
          throws IllegalStateException,
                 IOException

Send an unsolicited pong to remote endpoint.

Parameters:

payload - the payload of the pong

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

pong

public void pong()
          throws IllegalStateException,
                 IOException

Send an unsolicited pong with no payload to remote endpoint.

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

sendBinary

public void sendBinary(byte[] binary)
                throws IllegalStateException,
                       IOException

Sends a binary message.

Parameters:

binary - binary message to send

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs

sendText

public void sendText(String text)
              throws IllegalStateException,
                     IOException

Sends a text message.

Warning: by default, MicroEJ strings are not encoded in UTF-8, to send an UTF-8 string you need to declare it as follow String s = new String("yourString".getBytes("UTF-8);

Parameters:

text - text message to send

Throws:

IllegalStateException - if the connection state is not OPEN

IOException - thrown by the underlying Socket and associated streams when an error occurs