javascript_client.textile

Javascript Client  

The PushStream javascript class is an abstraction for which kind of connection is in use.
It supports 4 kinds of connection: Stream, EventSource, WebSocket and LongPolling.
The main idea is to provide a single interface to be used on your code, be easy to change from one kind to another, or to use some of the kinds together, one as a fallback to the others.
It does not depend of any framework, like jQuery or MooTools, and can be used with any of them.

Basic Usage  

<script>
  var pushstream = new PushStream();
  pushstream.onmessage = function(data) {
    alert(data);
  };
  pushstream.addChannel('example');
  pushstream.connect();
</script>

Configuration  

The PushStream class accept some configurations on its constructor to replace the default values.
Example:

<script>
  var pushstream = new PushStream({
    timeout: 20000,
    modes: 'eventsource|stream'
  });
  // ... extra code ...
</script>

configuration	default	type	description
useSSL	false	boolean	if should use or not SSL on the connection
host	current host name	string	the host name to connect and get messages
port	80/443 (if using SSL)	number	the port number to connect and get messages
timeout	30000	number	the amount of time to consider that a connection has some problem (in milliseconds)
pingtimeout	30000	number	the amount of time to consider that a connection does not receive a ping message (in milliseconds)
reconnectOnTimeoutInterval	3000	number	the amount of time to do a new connection after a timeout happens (in milliseconds)
reconnectOnChannelUnavailableInterval	60000	number	the amount of time to do a new connection after receives a 403, indicating that a channel is unavailable (in milliseconds)
autoReconnect	true	boolean	enable / disable the internal routine to reconnect the client after a failure
messagesPublishedAfter	–	number/date	get messages published at less than this time, on the first connection
lastEventId	–	string	get messages published after the message with this event id
messagesControlByArgument	true	boolean	when to use time and tag values by headers instead of arguments on long polling connections
tagArgument	‘tag’	string	argument name to send tag value, specially used on JSONP mode
timeArgument	‘time’	string	argument name to send time value, specially used on JSONP mode
eventIdArgument	‘eventid’	string	argument name to send eventid value, specially used on JSONP mode
useJSONP	false	boolean	when to use JSONP mode on long polling connections, mandatorily true when current domain or port is different from the target server (cross domain restrictions)
urlPrefixPublisher	‘/pub’	string	the location prefix used to post messages
urlPrefixStream	‘/sub’	string	the location prefix used to do Stream mode connections
urlPrefixEventsource	‘/ev’	string	the location prefix used to do EventSource mode connections
urlPrefixLongpolling	‘/lp’	string	the location prefix used to do LongPolling mode connections
urlPrefixWebsocket	‘/ws’	string	the location prefix used to do WebSocket mode connections
jsonIdKey	‘id’	string	the key name to extract message id from received message
jsonChannelKey	‘channel’	string	the key name to extract channel id from received message
jsonTextKey	‘text’	string	the key name to extract message text from received message
jsonTagKey	‘tag’	string	the key name to extract message tag from received message
jsonTimeKey	‘time’	string	the key name to extract message time from received message
jsonEventIdKey	‘eventid’	string	the key name to extract message event id from received message
modes	‘eventsource|websocket|stream|longpolling’	string	methods supported by the server which can be used by the browser, separated by ‘|’, on the order of preference
channelsByArgument	false	boolean	when to send target channels names by argument on subscriber connections
channelsArgument	‘channels’	string	the argument name to send target channels names on subscriber connections

Callbacks and Functions  

The PushStream class has some callbacks and functions that can be overwritten.
Example:

<script>
  var pushstream = new PushStream();
  pushstream.onstatuschange = function(status) {
    alert("The new status is: " + status);
  };
  // ... extra code ...
</script>

callback/function	description
extraParams	implement this function returning an object with extra parameters to send on subscriber connections, where the key is the parameter name and the value will be the parameter value, like {"foo":“bar”, “xyz”:"1"} → “foo=bar&xyz=1”
onerror	implement this function to be notified when an error happens, the argument received is an object with a key named ‘type’ indicating if was a ‘load’ or a ‘timeout’ error
onstatuschange	implement this function to receive the new connection status as argument, which can be PushStream.CLOSED, PushStream.CONNECTING or PushStream.OPEN
onchanneldeleted	implement this function to be notified when a channel was deleted on the server. The channel id will be the given argument
onmessage	implement this function to receive the messages from server, the arguments are, in order: text, id, channel, eventid, isLastMessageFromBatch, time. The isLastMessageFromBatch argument indicate when is, or not, the last message received on a batch when using long polling connections