Home
Categories
Dictionary
Glossary
Download
Project Details
Changes Log
What Links Here
FAQ
License

This article explains how to specify the External Communication network property XML file.

Schema

The schema is: network.xsd.

Structure

network: The root of the XML file. It has channel children elements
channel: defines socket communication channels. It has service children elements^[1]
Note that a channel can have more than one service child. There is a mechanism in the External Communication binary format to identify which service is exchanged

Note that:

Only services which are interfaces for the External Communication module can be referred to in Channels
All Services which are interfaces for the External Communication module must be referred to
A Service can not be referred to twice
A channel must only refer to services which are of the same type as the channel:

An input channel can only have services for which the External Communication module is a provider
An output channel can only have services for which the External Communication module is a subscriber

channel

A channel has the following attributes:

name (mandatory): name of the Channel
type (mandatory): "input" or "output". Represents the direction of the communication from / to the External Communication module relative to the network
protocol (optional): "udp" or "tcp". The protocol used for the channel
port (mandatory): the port number
host (optional): the host, only useful for an "output" type
size (optional): the size of the communication buffer. by default the size is equal to the channelSize property defined for the ExternalComm application^[2]
By default a default size will be assumed by the underlying Netty library. For example, this size is of 2048 bytes for an UDP channe

It is possible to have an empty channel. In that case, it will not be used by the External Communication. For example, the following specification is valid:

        <network>
           <channel name="event" type="input" port="8080" >
              <service name="event1" />
           </channel>
           <channel name="event2" type="input" port="8082" />       
        </network>

Output queue management

Main Article: ExternalComm Channel queue management

The channel which receives content from the network can have an outputServiceQueue child which specifies that the Channel content posted to the framework will use a queue to ensure that no content is forgotten.

There are two attributes for this outputServiceQueue element:

queueType explains if there will be a queue or not. The following values are supported:

"queue" or "true": there will be a queue to post decoded content to services
"false": there will be no queue to post decoded content to services, content will be posted immediately
"default": the default behavior for the module (with the queueServiceOutputs property) will be used (the default behavior for Channels)

For example:

      <channel name="event" type="input" port="8080">  
         <outputServiceQueue queueType="queue" queueSize="10" />
         <service name="published" />
      </channel>

By default the buffer content of the Channel is decoded and immediately posted to the relevant service which is invoked. However this default behavior can lead to problems if the buffer content for the same service is received many times with a short delay from the network. In that case the data content for the service may have been modififed by the module decoder before it could be used by the receiver modules in the framework, which could lead to incorrect processed content.

Input queue management

Main Article: ExternalComm Channel queue management

The channel which send content to the network can have an inputServiceQueue or outputServiceQueue child which specifies that the Channel content posted to the network will use a queue to ensure that no content is forgotten.

There are two attributes for this inputServiceQueue or outputServiceQueue element:

queueType explains if there will be a queue or not. The following values are supported:

"queue" or "true": there will be a queue to post decoded content to services
"false": there will be no queue to post decoded content to services, content will be posted immediately
"default": the default behavior for the module (with the queueServiceOutputs property) will be used (the default behavior for Channels)

For example:

      <channel name="event" type="output" port="8080">  
         <inputServiceQueue queueType="queue" queueSize="10" />
         <service name="published" />
      </channel>

By default the buffer content of the Channel is encoded and immediately send to the network.

Host and port definition

The host and the port properties can use global variables declarations. For example for the following Framework configuration:

      <files>
         <file url="applications.xml" />
         <file url="services.xml" />
         <file url="types.xml" />
         <confProperty key="port" value="65500" />
      </files>

and the XML Network configuration file:

      <network>
         <channel name="event" type="input" port="${port}" >
            <service name="published" />
         </channel>
      </network>

service

A service has only a name attribute.

Example

The following applications configuration adds an External Communication application to the eventAppli application of the first tutorial:

externalcommexample

      <applications>
         <application name="eventAppli">
            <deployment>
               <lib url="samplesEvents.jar" />
            </deployment>
            <modules>
               <module name="EventModule">
                  <implementation path="org.da.samples.protoframework.event.EventModule" >
                     <initEntryPoint method="init" />
                     <defaultReceiveEntryPoint method="subscribe" />
                  </implementation>
                  <interfaces>
                     <eventSend service="event"/>
                     <subscribe service="published" />
                  </interfaces>
               </module>
            </modules>
         </application>
         <application name="externalCommEvent">
            <deployment>
               <lib url="externalComm.jar" />
            </deployment>
            <modules>
               <module name="externalComm">
                  <interfaces>
                     <eventReceived service="event"/>
                     <push service="published"/>
                  </interfaces>
               </module>
            </modules>
         </application>
      </applications>

The following XML network file specifies the communication ports to reroute the services through the Network:

      <network>
         <channel name="event" type="input" port="8080" >
            <service name="published" />
         </channel>
         <channel name="publish" type="output" port="8081">
            <service name="event" />
         </channel>
      </network>

Notes

^ Note that a channel can have more than one service child. There is a mechanism in the External Communication binary format to identify which service is exchanged
^ By default a default size will be assumed by the underlying Netty library. For example, this size is of 2048 bytes for an UDP channe

ExternalComm network property