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:

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: Possible closing codes are: 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:

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:

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:

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.


Copyright © 2014 Neustar, Inc. All Rights Reserved.