path: root/CIAO/docs/schema/CIAOEvents.txt

	How to integrate TAO Real-Time Event Service into CIAO deployments
		
To integrate the TAO Real-Time Event Service into a CIAO application, you
need to use a CIAO-specific extension type of XML descriptor to "describe"
how your Real-Time Event Service should be configured.

An XML file with the ending extension called .ced (CIAO Events Descriptor)
which contains information about the configurations of EventService is
used for such a purpose. Once the .ced file defines the details of 
the event service configurations, this file can be referenced within a 
deployment plan descriptor (.cdp), which defines how CCM components
can use such services.

1. A Simple Example

Below "ciao-events-example.ced" file shows a simple example, which can
be found at $CIAO_ROOT/examples/Hello/descriptor_events/ciao-events-example.ced

    <CIAO:CIAOEvents
     xmlns:CIAO="http://www.dre.vanderbilt.edu/CIAOEvents"
     xmlns:xmi="http://www.omg.org/XMI"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.dre.vanderbilt.edu/CIAOEvents CIAOEvents.xsd">

      <eventServiceConfiguration id="es_configuration-01">
        <name>ES_01</name>
        <node>SenderNode</node>
        <type>RTEC</type>
        <svc_cfg_file>svc.conf</svc_cfg_file>
      </eventServiceConfiguration>
    </CIAO:CIAOEvents>  

The fields of the <eventServiceConfiguration> element are described below:

- <name> identifier for this real-time event service, which can be later 
         referenced in a deployment plan.
- <node> node name of the node in the deloyment plan, where the 
         EventService is running on. The node name should correspond
         to one of the node names given in the deployment plan descriptor.

- <type> type of the event channel, possible values are:
         EC       - CORBA Event Service
         RTEC     - TAO Real-Time Event Service
         NOTIFY   - CORBA Notification Service
         RTNOTIFY - TAO Real-Time Notification Service

         Currently only the RTEC type is implemented.

- <svc_cfg_file> path to the service configuration file, which configures the Event Service.

To integrate this information into the deployemnt plan, you have to
add the following XML description to the end of the deployment plan. 
An example of this can be found at 
$CIAO_ROOT/examples/Hello/descriptor_events/flattened_deploymentplan_events.cdp

  <infoProperty>
    <name>CIAOEvents</name>
    <value>
      <type>
        <kind>tk_string</kind>
      </type>
      <value>
        <string>ciao-events-example.ced</string>
      </value>
    </value>

  </infoProperty>

The string value has to contain the concrete filename of the.ced file.
A conventional connection between two event ports looks like the following
in the deployment plan:

  <connection>
    <name>click_out_click_in</name>
    <internalEndpoint>
      <portName>click_out</portName>
      <kind>EventPublisher</kind>
      <instance>Hello-Sender-idd</instance>
    </internalEndpoint>
    <internalEndpoint>
      <portName>click_in</portName>
      <kind>EventConsumer</kind>
      <instance>Hello-Receiver-idd</instance>
    </internalEndpoint>
  </connection>

This has to be changed to achieve a connection through an EventService.
Assuming there should be an event connection between the port
"click_out" of the component "Hello-Sender" and the port
"click_in" of the component "Hello-Receiver". Two connections
have to be declared in the deployment plan:
One from the "click_out" port to the external EventService and
one from the "click_in" port to the same event EventService.

The following example shows how this looks like in practice:

  <connection>
    <name>hello_event_ec_publisher_connection</name>
    <internalEndpoint>
      <portName>click_out</portName>
      <kind>EventPublisher</kind>
      <instance>Hello-Sender-idd</instance>
    </internalEndpoint>
    <externalReference>
      <location>ES_01</location>
    </externalReference>
  </connection>

  <connection>
    <name>hello_event_ec_consumer_connection</name>
    <internalEndpoint>
      <portName>click_in</portName>
      <kind>EventConsumer</kind>
      <instance>Hello-Receiver-idd</instance>
    </internalEndpoint>
    <externalReference>
      <location>ES_01</location>
    </externalReference>
  </connection>

Note that the value of the <location> elemnt of the <externalReference>
corresponds to the <name> element in the .ced file.

At deployment time, you can use the plan_launcher utility to specify
the .cdp file, and DAnCE will automatically find the .ced file, parse it 
and then do all the event service installation and configuration for you.

2. More Complex Examples

This example will show some additional QoS configurations, including
event filtering and event channel federation.

2.1 Event Filtering Configuration

CIAO event service allows event filtering based on event source id, i.e.,
one can configure that one event sink is only receiving events
published from particular event sources. 

An example of such a configuration can be found at:

$CIAO_ROOT/examples/Hello/descriptors_events/ciao-events-example-with-filters.ced

For example, below configuration illustrates that an event filter named
<my_filter_01> is a DISJUNCTION type of filter, and it refereces to two
event ports: <Hello-Sender-idd_click_out> and <Hello-Sender-idd-02_click_out>.
The <Hello-Sender-idd_click_out> port means an event source port is on the 
<Hello-Sender-idd> component instance with port name <click_out>. Likewise,
the <Hello-Sender-idd-02_click_out> port means an event source port on the
<Hello-Sender-idd-02> component with port name <click_out>.

The general way, <source> names are put together is, to use the elements
<instance id="INSTANCE-ID"> and the 
<connection><internalEndpoint><portName>PORT-NAME</...>
of the .cdp file and combine them by a "_" character, like this:
<source>INSTANCE-ID_PORT-NAME</source>. This assures, that every source is 
identified by a unique name.

    <filter>
      <name>my_filter_01</name>
      <type>DISJUNCTION</type>
      <source>Hello-Sender-idd_click_out</source>
      <source>Hello-Sender-idd-02_click_out</source>
    </filter>

DISJUNCTION filter type can also reference to one event source, which means
the filter will accept events published from this particular event source only. 
An example of such a configuration is shown below:
	
    <filter>
      <name>my_filter_02</name>
      <type>DISJUNCTION</type>
      <source>Hello-Sender-idd_click_out</source>
    </filter>	

Similarly, in constrast fo the DISJUNCTION type of filter, 
one can also configure CONJUNCTION type of filers, as shown below:

    <filter>
      <name>my_filter_03</name>
      <type>CONJUNCTION</type>
      <source>Hello-Sender-idd_click_out</source>
      <source>Hello-Sender-idd-02_click_out</source>
     </filter>	 

Currently CONJUNCTION and DISJUNCTION filters are implemented.
NEGATION filters can be added in the future.
The "Logical AND" filter does not apply to the CIAO event service, 
because the bit-mask mechanism does not conform to the level of abstraction
of the CCM.

Of course, once you define event filters, these filters can be referenced
in a deployment plan descriptor (.cdp). For example, in below deployment
plan descriptor:

$CIAO_ROOT/examples/Hello/descriptor_events/flattened_deploymentplan_with_filters.cdp     

One can define an event filtering mechanism like this:

  <connection>
    <name>hello_event_ec_consumer_connection</name>

    <!-- The position of the below "deployRequirement" element matters -->
    <deployRequirement>
      <resourceType>EventFilter</resourceType>
      <name>my_filter_01</name>
      <property>
        <name>EventFilter</name>
        <value>
	        <type>
	          <kind>tk_string</kind>
	        </type>
	        <value>
	          <string>my_filter_01</string>
	        </value>
        </value>	        
      </property>              
    </deployRequirement>    

    <internalEndpoint>
      <portName>click_in</portName>
      <kind>EventConsumer</kind>
      <instance>Hello-Receiver-idd</instance>
    </internalEndpoint>
    <externalReference>
      <location>ES_01</location>
    </externalReference>
  </connection>     

As we can see, the <deployRequirement> XML tag can refer a named event
filter defined in the .ced file.  

2.2 Event Channel Federation Configuration     

CIAO event service allows event channels to be federated through
event channel gateways. An example of this can be found at:

$CIAO_ROOT/examples/Hello/descriptors_events/ciao-events-federation-mcast.ced

In this example, two real-time event channels are defined, ES_01 and ES_02.
ES_01 is associated with a UDP Sender gateway object, and ES_02 is associated
with a UDP Receiver gatway object. Once ES_01 receives an event, it will 
try to forward this event to other event channels through its UDP Sender gatway
object. 

When defining a UDP Sender gatway object, the remote event channel's host name
and port name must be defined, which is through an XML tag called <addr_serv>.
In our example, we use the multicast address 224.9.9.2.

  <eventServiceConfiguration id="es_configuration-01">
    <name>ES_01</name>
    <node>SenderNode</node>
    <type>RTEC</type>
    <svc_cfg_file>dummy.conf</svc_cfg_file>

    <!-- The remote EC's host name and port # -->
    <addr_serv>
      <name>addr_serv_0</name>
      <port>1234</port>
      <address>224.9.9.2</address>
    </addr_serv>

    <udp_sender>
      <name>upd_sender_1</name>
      <addr_serv_id>addr_serv_0</addr_serv_id>
    </udp_sender>
  </eventServiceConfiguration>

Likewise, when defining a UDP Receiver gatway object, we need to define
the actual address server, which has an IP address and port number, which
is illustrated in the below <addr_serv> XML element. Once this XML element
is defined, it can be referenced in the <udp_receiver> element as shown
below. The <udp_receiver> element also defines whether this is a muticast 
or not through the <is_multicast> XML tag, and defines a <listen_port>
for its event handler. In practice, this <listen_port> is redundant to the 
the <port> defined in the <addr_serv>.
The port number is only necessary for unicast connections. For multicast
connections, no port number needs to be given (neither in the <addr_serv>
field nor in the <listen_port> field).

  <eventServiceConfiguration id="es_configuration-02">
    <name>ES_02</name>
    <node>SenderNode</node>
    <type>RTEC</type>
    <svc_cfg_file>dummy.conf</svc_cfg_file>

    <addr_serv>
      <name>addr_serv_1</name>
      <port>1234</port>
      <address>224.9.9.2</address>
    </addr_serv>    
    <udp_receiver>
      <name>upd_receiver_1</name>
      <addr_serv_id>addr_serv_1</addr_serv_id>  
      <is_multicast>true</is_multicast>

      <!-- Listen port for this EC's event handler -->
      <listen_port>1234</listen_port>
    </udp_receiver>
  </eventServiceConfiguration>  

Note that for now, only UDP federation (either unicast or multicast) is supported.
CORBA gateway federation is not implemented for CIAO.

Once the event channel federation configuration is defined in the .ced
file, the majority of the configuration effort is done. The rest of the
thing is quite simple, as shown in the below deployment plan descriptor:

$CIAO_ROOT/examples/Hello/descriptor_events/flattened_deploymentplan_federation_mcast.cdp

Basically, you only need to describe which event channels you want to
connect to (e.g., ES_01 or ES_02), as illustrated below, and that's it.

  <connection>
    <name>hello_event_ec_publisher_connection</name>
    <internalEndpoint>
      <portName>click_out</portName>
      <kind>EventPublisher</kind>
      <instance>Hello-Sender-idd</instance>
    </internalEndpoint>
    <externalReference>
      <location>ES_01</location>
    </externalReference>
  </connection>

  <connection>
    <name>hello_event_ec_consumer_connection</name>
    <internalEndpoint>
      <portName>click_in</portName>
      <kind>EventConsumer</kind>
      <instance>Hello-Receiver-idd</instance>
    </internalEndpoint>
    <externalReference>
      <location>ES_02</location>
    </externalReference>
  </connection>

The connection between the two event channels is set up, by only using the 
addresses in the .ced file. It is transparent for the .cdp file, how the
event channels are federated.