Channels

Channels are an highly effective communication model in jWebSocket to allow multiple applications or multiple modules within a single application to interact on separate logical channels without affecting others. You will find a description of the various communication models in jWebSocket in our Press section in the article "Real-time Cross-Platform Communication with WebSockets". Please also refer to the Infrastructure section and select Channels.

The jWebSocket Channel Plug-in provides the following options for Channels:

  • Public Channels
    All clients can subscribe to a public channel to listen on it and optionally publish data on the channel. Unlike private channels public channels are listed by the getChannels request. Optionally public channels can be protected by an access key as well as by a secret key. If a channel is protected the client has to pass the access key to subscribe to that channel. If the optional secret key is configured for the channel the client needs to pass that secret key to publish messages on the channel.
  • Private Channels
    Private channels are supposed for undisclosed communication between 2 or more clients. Thus they are not listed in the getChannels result. In addition private channel must be secured by a access key/secret key pair. To subscribe to a private channel a client must know the channel-id and pass the correct access key. Submitting messages on a private channel is only allowed by knowing the mandatory secret key.
  • System Channels
    System channels are reserved to be used by the Server and usually are created by the server only (i.e. via the jWebSocket.xml config file). System channels cannot be updated or removed by the client.

Configuring Channels

Channels are created either on server start up using the channels.xml configuration or at run-time by using the createChannel method from the ChannelPlugIn. The following xml snippet shows how to configure a public channel in the Channel plug-in configuration from {$JWEBSOCKET_HOME}/conf/ChannelPlugIn/channel.xml.

<!-- THE "<bean>" TAG IS A DEFAULT CONFIGURATION FOR THE CHANNEL MANAGER
  AND SHOULD NOT BE CHANGED FROM THE USER  -->
<bean id="channelManager" class="org.jwebsocket.plugins.channels.ChannelManager" 
   init-method="initialize">
	<constructor-arg>
	   <map>
		<!-- set this to true if you want to allow
                 to create new system channels from the
                 client side, default is false, not
                 recommended!
		<entry key="allowCreateSystemChannels">
		<value>false</value>
		</entry>-->
                <!-- HERE SHOULD BE ADDED ALL THE CHANNELS
                THE USER WANTS USING THE TAG: 
                "<entry><value></entry></value>" -->
		<entry key="channel:privateA">
		  <value>{
                  state:"CREATED",
                  owner:"root",
                  name:"Private A",
                  isPrivate:true,
                  isSystem:false,
                  access_key:"access",
                  secret_key:"secret",
                  token_server:"ts0"
                  }</value>
		</entry>
	   </map>
	</constructor-arg>	
		<constructor-arg ref="storageProvider"/>
	</bean>

Using the Channels

To use the channels the jWebSocket framework provides a Plug-in for the jWebSocket.js in the jwsChannelPlugIn.js. It provides the following methods:

  • channelSubscribe: function( aChannel, aAccessKey, aOptions )
  • channelUnsubscribe: function( aChannel, aOptions )
  • channelAuth: function( aChannel, aAccessKey, aSecretKey, aOptions )
  • channelPublish: function( aChannel, aData, aOptions )
  • channelCreate: function( aId, aName, aOptions )
  • channelRemove: function( aId, aOptions )
  • channelGetSubscribers: function( aChannel, aAccessKey, aOptions )
  • channelGetSubscriptions: function( aOptions )
  • channelGetIds: function( aOptions )

Please refer to the following Token reference for details to the methods.

Token Reference

subscribe

Subscribes to the given channel. If the channels requires an accessKey pair (e.g. for private channels) this must be passed, otherwise these fields can be omitted or left empty or null. If the channel does not exist or the accessKey does not match the request is rejected. If the subscription is successful the next pending messages on this channel will be passed to the client until the client unsubscribes again.

Token Datatype Description
type String Always "subscribe".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel identifier (unique)
accessKey String The access key to subscribe to the given channel (if such has been configured)
secretKey String not required for subscribe operation!

unsubscribe

Unsubscribes from the given channel. If the channel does not exist the request is rejected. If the unsubscribe operation is successful not further messages on that channel will be passed to the client. To unsubscribe from a channel you neither need an access key nor a secret key.

Token Datatype Description
type String Always "unsubscribe".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique)

getChannels

Returns all public channels on the server. Private channels are not returned and only can be accessed by knowing the channel-id and the accessKey of the private channel. The owners of the channels are not returned due to security reasons.

Token Datatype Description
type String Always "getChannels".
ns String Namespace "org.jWebSocket.plugins.channels".

Response

Token Datatype Description
channels Array Array of Channel objects consisting of: id (String, channel-id), name (String, channel-name), isSystem (Boolean), isPrivate (Boolean)

getSubscriptions

Returns all channels to which the current client currently has subscribed to. This also includes private channels. The owners of the channels are not returned due to security reasons.

Token Datatype Description
type String Always "getSubscriptions".
ns String Namespace "org.jWebSocket.plugins.channels".

Response

Token Datatype Description
channels Array Array of Channel objects consisting of: id (String, channel-id), name (String, channel-name), isSystem (Boolean), isPrivate (Boolean)

getSubscribers

Returns all subscribers of the given channel.

Token Datatype Description
type String Always "getSubscriptions".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique)
accessKey String The access key to obtain subscribers of the given channel (if such has been configured)

Response

Token Datatype Description
channel String Channel Identifier (for convenience)
subscribers Array Array of subscribers (Strings, client-ids)

authorize

Authorizes against a channel to get publish rights. You cannot publish on a channel until you are authorized for publish operations.

Token Datatype Description
type String Always "authorize".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique)
accessKey String The access key to publish messages to the given channel (if such has been configured)
secretKey String The secret key to publish messages to the given channel (if such has been configured)

publish

Publishes data on the given channel. The user needs to be registered as a publisher for this channel first (refer to authorize request).

Token Datatype Description
type String Always "authorize".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique)
data String Data to be published on the given channel.

createChannel

Creates a new channel on the server. If a channel with the given channel-id already exists the create channel request is rejected. A private channel requires an access key, if this is not provided for a private channel the request is rejected. For public channel the access key is optional.

Token Datatype Description
type String Always "createChannel".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique).
accessKey String The access key for the given channel (required for private channels).
secretKey String The secret key for the given channel (required for private channels).
isPrivate Boolean Specifies if a channel is private (i.e. can be found on request), this requires a accessKey/secretKey pair.
isSystem Boolean Specifies if c channel is a system channel
owner String User-id of the owner of the channel, only the owner of a channel can remove the channel on demand.
If the owner is not given the currently authenticated user automatically is used as owner.

removeChannel

Removes a (non-system) channel on the server. Only the owner of channel can remove a channel. If a accessKey/secretKey pair is defined for a channel this needs to be passed as well, otherwise the remove request is rejected.

Token Datatype Description
type String Always "removeChannel".
ns String Namespace "org.jWebSocket.plugins.channels".
channel String Channel Identifier (unique)
accessKey String The access key to remove the given channel (if such has been configured).
secretKey String The secret key to remove the given channel (if such has been configured).
owner String User-id of the owner of the channel (the user who created the channel).
If the owner is not given the currently authenticated user automatically is used as owner.
 
Publications

Learn more about WebSockets in general, get background information and gain deeper insight!

Join jWebSocket

Wether developer, designer or translator – join the jWebSocket team and grow together with our success!

Copyright © 2013 Innotrade GmbH. All rights reserved.