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.

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.

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.

Response

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.

Response

getSubscribers

Returns all subscribers of the given channel.

Response

authorize

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

publish

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

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.

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.