DistributorWsGateway

The DistributorWsGateway a.k.a DWG is a application server allowing WEB clients to subscribe to Distributor real time broadcast using WebSocket.

Overview

The Distributor is a framework allowing applications to publish / subscribe real time message flows. The the Distributor framework use IP multicast to exchange information.

The DWG component is an application gateway allowing WEB applications to subscribe to real time information published by Distributor publisher applications.

The DWG gateway acts as a Distributor subscriber application and proxy server for WEB applications that like obtain real time information published by publisher applications.

WEB applications connects to the DWG using the WebSockets protokoll. In order for WEB applications to receive updates the must submit subscriptions defining what information they have an interest in.

The DWG will maintain the subscriptions the WEB apps have submited. When the DWG app receives updates, it forwared the update to the WEB application having the interest in the information.

DWG Configuration

The DWG server takes the following args "-configuration "

An example of a DWG is found below

   <DistributorWebSocketGateway
       appName = "WsGateway"
       clientSenderThreads = "2"
       localIpAddress = "192.168.42.100"
       cmaAddress = "224.42.42.100"
       cmaPort = "4242"
       ipBufferSize = "128000"
       segmentSize = "8192"
       payloadB64 = "true"
       sslKeyStore = "distributor-keystore.jks"
       keyStoreAlias = "distributor"
       keyStorePassword = "sesame"
       httpPort = "8888">
       
       <MulticastGroups>
           <Group address="224.42.42.1" port="4201" groupId="1"/>
           <Group address="224.66.66.1" port="4201" groupId="2"/>
       </MulticastGroups>
   
       <AllowedClients enabled="true">
           <Host ipAddress="192.168.1.0/24"/>
           <Host ipAddress="192.168.42.0/24"/>
       </AllowedClients>
   
       <AuthorizedUsers enabled="true">
           <User username="joshua" password="tictactoe"/>
           <User username="test" password="test"/>
       </AuthorizedUsers>
    </DistributorWebSocketGateway>   

Attributes

• appName, name of of the application when announce itself as a Distributor application.
• clientSenderThreads, number of threads being used to send update messages to WEB apps. A WEB app will always be served by the same sender thread in order to guarantee message order.
• localIpAddress, indetify the network interface on which the DWG app will use when communicate with other Distributor applications.
• cmaAddress, IP mulicast address the DWG uses when exchanging controll messages with other Distributor applications.
• cmaPort, IP UDP port the DWG uses when exchanging control messages with other Distributor applications.
• ipBufferSize, the IP buffer size used for the Distributor IP sockets used. (no reason to change)
• segmentSize, the segment used when exchange / distributing Distributor messages. (no reason to change)
• payloadB64, if applications messages distributed with the Distributor frawework are binary it will be a good idea to set this flag to true. Then the DWG will B64 encode the updates.
• sslKeyStore, key store to be used if the WebSockets are to be SSL encrypted. This attribute is optional. If not being present WS sessions will be uncrypted.
• keyStoreAlias, key store alias name.
• keyStorePassword, key store password
• httpPort, HTTP port on which the DWG gateway will accept WS connections.
• MulticastGroups, IP multicast groups used when interacting with other Distributor applications.
  • address IP multicast address (i.e. IP class D address).
  • port IP multicast / UDP port.
  • groupId identifies the multicast group, used by WEB apps to address where a subscription should be applied.
• AllowedClients If possible to restrict what host that should be allowed to connect to the DWG. The validation check can be enabled/disabled by setting the enabled attribute. ** ipAddress the ipaddress or a range of host addresses that should be allowed to connect. The user authorization check can be enabled/diabled by setting the enabled attribute.
• AuthorizedUsers it is possible to enable authorization on a user basis.
  • username authorized fictive user identity.
  • password password for the user.

WEB App

WEB applications should use an appropriate WebSocket API. The WEB apps can and should send a few messages inorder to receive updates. The messages are defined in the file DistributorMessages.xml All messages being sent and received are Json encoded. An example of how to interact with a DWG are found in the file distributor.html

Messages

• AddSubscriptionRqst, message used to register an interest in a message flow. Without setting up a subscription no information will be received.

  • rqstId, identifies the request. Used to pair the response
  • subjectId, identifies the information being of interest for the application. Subjects are string with an hierarchical name structure e.g /foo/bar/fie More info about subject identities see Subject Names
  • groupId, identifies the IP multicast group where the information is published.
  • callbackRef, user defined parameter passed back in the unsolicited update sent out when the subject is updated.

• RemoveSubscriptionRqst, removes a previously added subscription

  • rqstId, identifies the request. Used to pair the response
  • handle, idetifies the subscriptio. The handle is returned in the AddSubscriptionRsp

• LoginRqst, must be sent as first message in case user authorization is enabled in the DWG

  • username, user identity to use when authorizing the session
  • password, password for the user.

• Update, send unsolicited from the DWG to the WEB app when information that the app has an interest is updated.

  • subjectId subject idetifying the data being updated.
  • handle the subscription handle associated with the subscription causing the update to be sent. The handle is returned in the AddSubscriptionRsp
  • time the time in the DWG when the update was queued. Format "HH::mm:ss.SSS"
  • payLoadIsB64 is true is payload is B64 encoded
  • payload data being update. (can be B64 encoded depending on the DWG configuration).
  • callbackRef user callback reference defined when the subscription was setup.