ExternalComm

The built-in External Communication application allows to communicate through UDP or TCP with any external process:

• Any Service for which the application is a provider will be rerouted from the UDP or TCP socket reception to the framework
• Any Service for which the application is a subscriber will be rerouted to an UDP or TCP socket emission

Note that it is advisable to generate the Module interface declaration in the browser for the External Communication module, to help the external application to identify which interfaces are exchanged.

Services

• The Services for which the application is a provider will be rerouted from the UDP or TCP socket reception to the framework
• The Services for which the application is a subscriber will be rerouted to an UDP or TCP socket emission

Starting and stopping services

It is possible to start and stop services (both Services for which the application is a provider or subscriber) through the two following services:

• The http://dassault-aviation.com/externalcomm:stopServices service allow to stop an array of services
• The http://dassault-aviation.com/externalcomm:startServices service allow to start an array of services

The services which are provided in the array of services can be declared as Strings or as NamespaceKeys^[1]

See also namespace for more information on how a service key is defined and used

Runtime sequence

Sequence for Services for which the application is a subscriber

For a Service for which the External Communication application is a subscriber, the External Communication module will reroute the content of the service to an UDP or TCP socket. The sequence of communication is as follows:

• The External Communication module is notified from a Service
• The module encodes the content of the service datas in a binary array
• The module sends the array content though the associated UDP or TCP port

Sequence for Services for which the application is a provider

For a Service for which the External Communication application is a provider, the UDP or TCP socket reception will be rerouted to the framework. The sequence of communication is as follows:

• The External Communication module receives a content through the UDP or UDP socket
• The module decodes the content of the message:
• The module decodes the Service ID described specified in the message and checks if this Service is associated with the socket port
• The module decodes the data content for the Service and update the values for these datas
• The module invoke the Service. The invocation may clone the service depending on the value of the invokeCopy property

Communication binary format

The binary format of the UDP or TCP byte content is very close to the framework Communication Protocol, except that the format does not contain the applicationID or moduleID.

Properties

Mandatory properties

The ExternalComm Application has ony one mandatory property:

• network: the XML file defining the configuration of the Network for the UDP or TCP socket emission or reception

See ExternalComm network property for an explanation of how to specify this XML file.

Optional properties

The ExternalComm Application has several optional properties.

Properties about encoding and decoding configuration

These properties specify how the content is encoded or decoded.


The list of encoding and decoding configuration properties is:

• charAs8Bits: true if chars will be sent and received as 8 bits (the default). Note that in Java chars are encoded as 16 bits, whereas in C chars are encoded as 8 bits
• channelSize: the size to use for the communication. By default a default size will be assumed by the underlying Netty library^[3]
  For example, this size is of 2048 bytes for an UDP channel
• endianness: the endianness to use for the communication. By default it is Big Endian, which is the endianness of the Java platform. See endianness for more information
• swapMAGIC: true if the MAGIC number of the communication protocol will be swapped (regardless of the value of the endianness property), false if it will be not swapped (regardless of the value of the endianness property). By default it will follow the behavior specified by the endianness property
• checkMAGIC: true if the MAGIC number value must be checked
• acceptMultiple: true if multiple services can be received in the same buffer
• swapServiceID: true if the serviceID in the communication protocol will be swapped (regardless of the value of the endianness property), false if it will be not swapped (regardless of the value of the endianness property). By default it will follow the behavior specified by the endianness property

Properties about the queuing of inputs and outputs

These properties specify explains how by default Channels which receives content from the network will manage the emitting of this content in the framework.

• queueServiceOutputs: true if the outputs from the network to the framework must be queued
• queueServiceOutputsSize: the size of the queue to use for the queuing of outputs from the network to the framework
• invokeCopy: true if services coming from decoding the network should be cloned before they are called
• queueServiceInputs: true if the inputs from the framework to the network must be queued
• queueServiceInputsSize: the size of the queue to use for the queuing of inputs from the framework to the network

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 modified by the module decoder (or encoder) before it could be used by the receiver modules in the framework, which could lead to incorrect processed content.

Properties about the output format

By default the output is binary data, but it is possible to configure the module to send JSON data instead:

• serializeAsJSON: true if the output must be serialzied as a JSON string (default is false)
• jsonCharset: the charset to use for the JSON output (default is "UTF-8")

Properties about the launcher

• launcher: allows to specify the path to an external executable to launch and its launch arguments. See externalComm launcher for more information

Properties about logging

• serializeURL: the XML file which should be used to serialized the reception of emission buffers. The format of this file is compatible with the player Application scenario format. Depending on the serializeInputs boolean property, the inputs or outputs of the module from the external application will be serialized
• serializeInputs: true if the inputs of the module from the external application must be serialized (in association with the serializeURL property), false if the output of the module to the external application must be serialized
• serializeBuffer: true if the inputs or outputs of the module must be serialized
• logDatas: allows to specify the datas will be logged. Note that the logFile property must also be specified to effectively log the datas
• logFile: allows to specify a log file which will print the content of the buffer received by the ExternalComm module from the external application. This may be used to debug content which could be incorrectly serialized by your external application. Note that the logDatas property must also be true to effectively log the datas

Tutorials

The External Communication tutorial will reuse the first tutorial, and execute two framework instances:

• The first framework instance will contain the eventAppli and a rerouting External Communication to communicate with the second instance
• The second framework will contain the publishAppli and a rerouting External Communication to communicate with the first instance

The External Communication CSharp tutorial will implement the PublishModule with the ExternalComm module using C# code, and communicate using the External Communication module.

The External Communication Launcher tutorial will implement the PublishModule with the ExternalComm module, and launch a CSharp executable using the launcher property.