org.jwebsocket.api

Interface WebSocketClient

All Known Subinterfaces:

WebSocketTokenClient

All Known Implementing Classes:

BaseTokenClient, BaseWebSocketClient

public interface WebSocketClient

Base interface that represents the jWebSocket java client and it defines all the methods and operations to allow the implementation of jWebSocket specific client protocols and allows to register/deregister different types of listeners for different types of communication and data format.The implementation of this interface handles all the data formats and client protocols and delegates the events and the data to different listeners for further processing.

Version:

$Id: WebSocketClient.java 701 2010-07-18 17:53:06Z mailtopuran@gmail.com $

Author:

aschulze, puran

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(WebSocketClientListener aListener) Adds the client listener to the lists of listener which are interested in receiving the jWebSocket connection and data events.
void	addSubProtocol(WebSocketSubProtocol aSubProt) Adds subprotocol to the list of supported protocols which are negotiated during handshake with web socket server.
void	close() Close the jWebSocket connection.
List<WebSocketClientListener>	getListeners() Returns the list of listeners registered.
WebSocketEncoding	getNegotiatedEncoding() If subprotocol was negotiated, then this method returns sub protocol format (json, csv, binary, custom)
String	getNegotiatedSubProtocol() If subprotocol was negotiated, then this method returns sub protocol name.
WebSocketStatus	getStatus() Method to return if the status of the jWebSocketClient
boolean	isConnected() Method to check if the jWebSocketClient is still connected to the jWebSocketServer
void	notifyClosed(WebSocketClientEvent aEvent) Notifies the jWebSocket client implementation about the connection being closed
void	notifyOpened(WebSocketClientEvent aEvent) Notifies the jWebSocket client implementation about the connection being opened to the jWebSocket server via WebSocket
void	notifyPacket(WebSocketClientEvent aEvent, WebSocketPacket aPacket) Notifies the jWebSocket client implementation about the packet being received from the WebSocket client.
void	notifyReconnecting(WebSocketClientEvent aEvent) Notifies the jWebSocket client implementation about the connection being re-established
void	open(String aURL) Opens the jWebSocket connection
void	removeListener(WebSocketClientListener aListener) Remove the listener from the list of listeners, once the listener is removed it won't be notified of any jWebSocket events.
void	send(byte[] aData) Send the given byte data to the server
void	send(String aData, String aEncoding) Sends the data to the jWebSocket server, data has to be UTF-8 encoded.
void	send(WebSocketPacket aPacket) Sends the websocket data packet to the WebSocket client
void	setVersion(int aVersion) Web socket protocol draft.

Method Detail

open

void open(String aURL)
          throws WebSocketException

Opens the jWebSocket connection

Parameters:

aURL - the websocket connection url

Throws:

WebSocketException - if therre's an

send

void send(byte[] aData)
          throws WebSocketException

Send the given byte data to the server

Parameters:

aData - the byte data

Throws:

WebSocketException - if exception occurs while sending the data

send

void send(String aData,
        String aEncoding)
          throws WebSocketException

Sends the data to the jWebSocket server, data has to be UTF-8 encoded.

Parameters:

aData - the data to send

aEncoding - the encoding type

Throws:

WebSocketException - if there's any exception while sending the data

send

void send(WebSocketPacket aPacket)
          throws WebSocketException

Sends the websocket data packet to the WebSocket client

Parameters:

aPacket - the data packet to send

Throws:

WebSocketException - if there's any exception while sending

close

void close()
           throws WebSocketException

Close the jWebSocket connection. This method should perform all the cleanup operation to release the jWebSocket resources. Closing and connection which is already closed should not lead to any error.

Throws:

WebSocketException - if exception while close operation

isConnected

boolean isConnected()

Method to check if the jWebSocketClient is still connected to the jWebSocketServer

Returns:

true if there's a persistent connection false otherwise

getStatus

WebSocketStatus getStatus()

Method to return if the status of the jWebSocketClient

Returns:

Value of the WebSocketStatus enumeration.

notifyOpened

void notifyOpened(WebSocketClientEvent aEvent)

Notifies the jWebSocket client implementation about the connection being opened to the jWebSocket server via WebSocket

Parameters:

aEvent - the websocket client event object

notifyPacket

void notifyPacket(WebSocketClientEvent aEvent,
                WebSocketPacket aPacket)

Notifies the jWebSocket client implementation about the packet being received from the WebSocket client.

Parameters:

aEvent - the websocket client event object

aPacket - the data packet received

notifyClosed

void notifyClosed(WebSocketClientEvent aEvent)

Notifies the jWebSocket client implementation about the connection being closed

Parameters:

aEvent - the websocket client event object

notifyReconnecting

void notifyReconnecting(WebSocketClientEvent aEvent)

Notifies the jWebSocket client implementation about the connection being re-established

Parameters:

aEvent - the websocket client event object

addListener

void addListener(WebSocketClientListener aListener)

Adds the client listener to the lists of listener which are interested in receiving the jWebSocket connection and data events. Listeners are good way to handle all the jWebSocket specific protocol and data format

Parameters:

aListener - the event listener object

removeListener

void removeListener(WebSocketClientListener aListener)

Remove the listener from the list of listeners, once the listener is removed it won't be notified of any jWebSocket events.

Parameters:

aListener - the listener object to remove

getListeners

List<WebSocketClientListener> getListeners()

Returns the list of listeners registered.

Returns:

the list of all listeners.

addSubProtocol

void addSubProtocol(WebSocketSubProtocol aSubProt)

Adds subprotocol to the list of supported protocols which are negotiated during handshake with web socket server.

Parameters:

aSubProt - sub protocol

aEncoding, - currently either text or binary

getNegotiatedSubProtocol

String getNegotiatedSubProtocol()

If subprotocol was negotiated, then this method returns sub protocol name.

Returns:

name of the subprotocol or null if no subprotocol was negotiated

getNegotiatedEncoding

WebSocketEncoding getNegotiatedEncoding()

If subprotocol was negotiated, then this method returns sub protocol format (json, csv, binary, custom)

Returns:

format of the subprotocol or null if no subprotocol was negotiated

setVersion

void setVersion(int aVersion)

Web socket protocol draft. Specification recommends using only draft number in relevant header, but anything may be used as long as server understands it. JWebSocket adheres to the specification and therefore understands only draft number as valid value, e.g. "Sec-WebSocket-Draft: 3". Anything else will probably fail on server side.

Parameters:

aVersion - which draft to use for web socket protocol communication