diff options
Diffstat (limited to 'CIAO/docs/schema/CIAOEvents.txt')
| -rw-r--r-- | CIAO/docs/schema/CIAOEvents.txt | 339 |
1 files changed, 0 insertions, 339 deletions
diff --git a/CIAO/docs/schema/CIAOEvents.txt b/CIAO/docs/schema/CIAOEvents.txt deleted file mode 100644 index d5aae8b8bc3..00000000000 --- a/CIAO/docs/schema/CIAOEvents.txt +++ /dev/null @@ -1,339 +0,0 @@ - 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. |