biz.neustar.wpm.api
Interface WebSocket

public interface WebSocket

This is an implementation of the W3C WebSocket API.

WebSockets allows Clients to implement two-way communication (full-duplex) with a remote host that supports WebSockets.

Being this still a work-in-progress specification, our API implement what is currently the latest stable specs, as documented in the link above.

The following example script shows how to use this API to test an echo server - the idea is to send a message and receive the same message back. We do this at least 5 times.

 test.beginTransaction();
 test.beginStep("send 5 messages over websocket");

 var ws = test.openWebSocket("ws://echo.websocket.org");
 var count = 0;

 ws.onhandshake = function() {
   test.log("WebSocket handshake: " + ws.url)
   return { "Origin" : "http://www.example.com/" };
 };

 ws.onopen = function() {
   ws.send("echo0");
   test.log("WebSocket open: " + ws.url)
 };

 ws.onmessage = function(msg) {
   test.log("Got message: " + msg);

   ++count;
   ws.send("echo" + count);
 };

 ws.onerror = function(e) {
   test.log("WebSocket error: " + e.toString())
 };

 ws.onclose = function(code, reason, remote) {
   test.log("WebSocket closed code: " + code + " reason: " + reason + " remote: " + remote);
 };

 test.waitFor(function() {
   return count >= 5;
 }, 60000); // 1 minute

 ws.close();

 test.assertTrue(count >= 5, "less than 5 messages");

 test.endStep();
 test.endTransaction();
 

As it's possible to notice, the way an instance of WebSocket is created does not comply to the official specification: this is motivated by our internal implementation. But it's extremely easy to compensate this with a little JavaScript-shim:

     function WebSocket(url, protocols) {
         return test.openWebSocket(url);
     }

     var ws = new WebSocket("ws://my.websocket.server");
     ...
 

Method Summary

void	close() Initiate connection closing.
void	close(short code) Initiate connection closing.
void	close(short code, java.lang.String reason) Initiate connection closing.
void	close(java.lang.String reason) Initiate connection closing.
long	getBufferedAmount() Returns the 'bufferedAmount'.
java.lang.String	getExtensions() Returns the 'extensions' selected by the server.
NativeFunction	getOnclose() Accessor for 'wsInstance.onclose'.
NativeFunction	getOnerror() Accessor for 'wsInstance.onerror'.
NativeFunction	getOnhandshake() Accessor for 'wsInstance.onhandshake'.
NativeFunction	getOnmessage() Accessor for 'wsInstance.onmessage'.
NativeFunction	getOnopen() Accessor for 'wsInstance.onopen'.
java.lang.String	getProtocol() Returns the 'protocol' selected by the server.
int	getReadyState() Returns the 'readyState'.
java.lang.String	getUrl() Returns the 'url' passed to the constructor.
void	send(byte[] data) Transmits data using the connection.
void	send(java.lang.String str) Transmits data using the connection.
void	setOnclose(NativeFunction oncloseHandler) Set an Event Handler for 'wsInstance.onclose'.
void	setOnerror(NativeFunction onerrorHandler) Set an Event Handler for 'wsInstance.onerror'.
void	setOnhandshake(NativeFunction onhandshakeHandler) Set an Event Handler for 'wsInstance.onhandshake'.
void	setOnmessage(NativeFunction onmessageHandler) Set an Event Handler for 'wsInstance.onmessage'.
void	setOnopen(NativeFunction onopenHandler) Set an Event Handler for 'wsInstance.onopen'.

Method Detail

getUrl

java.lang.String getUrl()

Returns the 'url' passed to the constructor.

Can be accessed via this getter or via the JavaScript-like read-only property:

     var ws = test.openWebSocket("ws://..."),
         wsurl = ws.url;
 

Returns:

URL the WebSocket Server

getReadyState

int getReadyState()

Returns the 'readyState'. This is the state of the connection.

Can be accessed via this getter or via the more JavaScript-like read-only property:

     var ws = test.openWebSocket("ws://..."),
         wsreadyState = ws.readyState;
 

Returns:

Returns '0 = CONNECTING', '1 = OPEN', '2 = CLOSING' or '3 = CLOSED'

getBufferedAmount

long getBufferedAmount()

Returns the 'bufferedAmount'. This is the amount of data buffered/queued but not sent yet.

In details, it returns the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network.

Can be accessed via this getter or via the more JavaScript-like read-only property:

     var ws = test.openWebSocket("ws://..."),
         wsbufferedAmount = ws.bufferedAmount;
 

Returns:

Amount still buffered/queued but not sent yet.

setOnmessage

void setOnmessage(NativeFunction onmessageHandler)

Set an Event Handler for 'wsInstance.onmessage'. Instead of this, you can also use the standard-compliant:

   'wsInstance.onmessage = function(msg) {...}'.
 

The event handler should expect the arguments:

• message: data/message received from the server

Parameters:

onmessageHandler - A JavaScript function

getOnmessage

NativeFunction getOnmessage()

Accessor for 'wsInstance.onmessage'. Instead of this, you can also use the standard-compliant:

   'typeof(wsInstance.onmessage) === "function"'.
 

Returns:

The function previously given

setOnopen

void setOnopen(NativeFunction onopenHandler)

Set an Event Handler for 'wsInstance.onopen'. Instead of this, you can also use the standard-compliant:

   'wsInstance.onopen = function() {...}'.
 

Parameters:

onopenHandler - A JavaScript function

getOnopen

NativeFunction getOnopen()

Accessor for 'wsInstance.onopen'. Instead of this, you can also use the standard-compliant:

   'typeof(wsInstance.onopen) === "function"'.
 

Returns:

The function previously given

setOnclose

void setOnclose(NativeFunction oncloseHandler)

Set an Event Handler for 'wsInstance.onclose'. Instead of this, you can also use the standard-compliant:

   'wsInstance.onclose = function(code, reason, remote) {...}'.
 

The event handler should expect the arguments:

• code: closing code
• reason: closing reason
• remote: is remote?

Possible closing codes are:

• 1000: CLOSE_NORMAL
• 1001: CLOSE_GOING_AWAY
• 1002: CLOSE_PROTOCOL_ERROR
• 1003: CLOSE_UNSUPPORTED
• 1004: CLOSE_TOO_LARGE
• 1005: CLOSE_NO_STATUS
• 1006: CLOSE_ABNORMAL

More info about Close Event Codes on MDN.

Parameters:

oncloseHandler - A JavaScript function

getOnclose

NativeFunction getOnclose()

Accessor for 'wsInstance.onclose'. Instead of this, you can also use the standard-compliant:

   'typeof(wsInstance.onclose) === "function"'.
 

Returns:

The function previously given

setOnerror

void setOnerror(NativeFunction onerrorHandler)

Set an Event Handler for 'wsInstance.onerror'. Instead of this, you can also use the standard-compliant:

   'wsInstance.onerror = function(error) {...}'.
 

The event handler should expect the arguments:

• error: error

Parameters:

onerrorHandler - A JavaScript function

getOnerror

NativeFunction getOnerror()

Accessor for 'wsInstance.onerror'. Instead of this, you can also use the standard-compliant:

   'typeof(wsInstance.onerror) === "function"'.
 

Returns:

The function previously given

setOnhandshake

void setOnhandshake(NativeFunction onhandshakeHandler)

Set an Event Handler for 'wsInstance.onhandshake'. It's useful to add/change headers before they are sent for the Websocket Handshake phase. NOTE: Bear in mind that the effect of manipulating those headers might affect the ability of the WebSocket to establish a connection. Instead of this, you can also use the standard-compliant:

   'wsInstance.onhandshake = function() {...}'.
 

The event handler expects no arguments and should send back a plain Javascript Object to set headers. For example:

   ws.onhandshake = function() {
     return {
       "Origin" : "http://www.example.com/"
     };
   };
 

Parameters:

onhandshakeHandler - A JavaScript function

getOnhandshake

NativeFunction getOnhandshake()

Accessor for 'wsInstance.onhandshake'. Instead of this, you can also use the standard-compliant:

   'typeof(wsInstance.onhandshake) === "function"'.
 

Returns:

The function previously given

getExtensions

java.lang.String getExtensions()

Returns the 'extensions' selected by the server. Currently it's an empty script: future specifications will change this.

Can be accessed via this getter or via the JavaScript-like read-only property:

     var ws = test.openWebSocket("ws://..."),
         wsextensions = ws.extensions;
 

Returns:

Extensions chosen by the Server (currently just an empty string)

getProtocol

java.lang.String getProtocol()

Returns the 'protocol' selected by the server. Currently it's an empty script: future specifications will change this.

Can be accessed via this getter or via the JavaScript-like read-only property:

     var ws = test.openWebSocket("ws://..."),
         wsprotocol = ws.protocol;
 

Returns:

Protocol chosen by the Server (currently just an empty string)

send

void send(java.lang.String str)

Transmits data using the connection.

If the readyState attribute is CONNECTING, it must throw an InvalidStateError exception.

Calls to this increases the value of the 'bufferedAmount' property, until the data is sent.

Parameters:

str - String to Send

send

void send(byte[] data)

Transmits data using the connection.

If the readyState attribute is CONNECTING, it must throw an InvalidStateError exception.

Calls to this increases the value of the 'bufferedAmount' property, until the data is sent.

Parameters:

data - Array of Binary Data to Send

close

void close(short code,
           java.lang.String reason)

Initiate connection closing.

Will cause a call to the callback ws.onclose(), if registered. Possible closing codes are:

• 1000: CLOSE_NORMAL
• 1001: CLOSE_GOING_AWAY
• 1002: CLOSE_PROTOCOL_ERROR
• 1003: CLOSE_UNSUPPORTED
• 1004: CLOSE_TOO_LARGE
• 1005: CLOSE_NO_STATUS
• 1006: CLOSE_ABNORMAL

More info about Close Event Codes on MDN.

Parameters:

code - Closing code that will be sent to the Server

reason - String carrying a reason for closing

close

void close(short code)

Initiate connection closing.

Will cause a call to the callback ws.onclose(), if registered. Possible closing codes are:

• 1000: CLOSE_NORMAL
• 1001: CLOSE_GOING_AWAY
• 1002: CLOSE_PROTOCOL_ERROR
• 1003: CLOSE_UNSUPPORTED
• 1004: CLOSE_TOO_LARGE
• 1005: CLOSE_NO_STATUS
• 1006: CLOSE_ABNORMAL

More info about Close Event Codes on MDN.

Parameters:

code - Closing code that will be sent to the Server

close

void close(java.lang.String reason)

Initiate connection closing.

Will cause a call to the callback ws.onclose(), if registered.

Parameters:

reason - String carrying a reason for closing

close

void close()

Initiate connection closing.

Will cause a call to the callback ws.onclose(), if registered.