The R13B03 release.OTP_R13B03

1 files changed, 221 insertions, 0 deletions

diff --git a/lib/cosEvent/doc/src/ch_event_service.xml b/lib/cosEvent/doc/src/ch_event_service.xml
new file mode 100644
index 0000000000..c65f6767ad
--- /dev/null
+++ b/lib/cosEvent/doc/src/ch_event_service.xml
@@ -0,0 +1,221 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Event Service</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>97-11-19</date>
+    <rev>A</rev>
+    <file>ch_es_intro.xml</file>
+  </header>
+
+  <section>
+    <title>Overview of the CosEvent Service</title>
+    <p>The Event service allows programmers to subscribe to
+      information channels. Suppliers can generate events without knowing the
+      consumer identities and the consumer can receive events without knowing
+      the supplier identity. Both push and pull event delivery are supported.
+      The Event service will queue information and processes.
+      </p>
+    <p>The CORBA Event service provides a flexible model for
+      asynchronous,  decoupled communication between objects. This
+      chapter outlines communication  models and the roles and
+      relationships of key components in the CosEvent service. It
+      shows a simple example on use of this service.</p>
+  </section>
+
+  <section>
+    <title>Event Service Components</title>
+    <p>There are five components in the OMG CosEvent service architecture. These
+      are described below:</p>
+    <marker id="e_s_components"></marker>
+    <image file="e_s_components.gif">
+      <icaption>
+Figure 1: Event service Components</icaption>
+    </image>
+    <list type="bulleted">
+      <item><em>Suppliers and consumers:</em> Consumers are the ultimate targets of
+       events generated by suppliers. Consumers and suppliers can both play active
+       and 
+       passive roles. There could be two types of consumers and suppliers: push
+       or pull. A PushSupplier object can actively push an event to a passive
+       PushConsumer object. Likewise, a PullSupplier object can passively 
+       wait for a PullConsumer object to actively pull an event from it.</item>
+      <item><em>EventChannel:</em> The central abstraction in the CosEvent service is the 
+       EventChannel which plays the role of a mediator between consumers and 
+       suppliers. Consumers and suppliers register their interest with the 
+       EventChannel. It can provide many-to-many communication. The channel 
+       consumes events from one or more suppliers, and supplies events to one 
+       or more consumers. An EventChannel can support consumers and suppliers
+       using different communication models.</item>
+      <item><em>ProxySuppliers and ProxyConsumers:</em> ProxySuppliers act as middlemen
+       between consumers and the EventChannel. A ProxySupplier is similar to
+       a normal supplier, but includes an additional method for connecting a 
+       consumer to the ProxySupplier. Likewise, ProxyConsumers act as 
+       middlemen between suppliers and the EventChannel. A ProxyConsumer is
+       similar to a normal consumer, but includes an additional method for
+       connecting a supplier to the ProxyConsumer.</item>
+      <item><em>Supplier and consumer administrations:</em> Consumer administration acts as
+       a factory for creating ProxySuppliers.  Supplier administration acts as
+       a factory for creating ProxyConsumers.</item>
+    </list>
+  </section>
+
+  <section>
+    <title>Event Service Communication Models</title>
+    <p>There are four general models of component collaboration in the OMG CosEvent service 
+      architecture.  The following describes these models:
+      (Please note that proxies are not shown in the diagrams for simplicity).</p>
+    <marker id="e_s_models"></marker>
+    <image file="e_s_models.gif">
+      <icaption>
+Figure 2: Event service Communication Models</icaption>
+    </image>
+    <list type="bulleted">
+      <item><em>The Canonical Push Model:</em> The Canonical push model shown in figure 2(A) allows
+       the suppliers of events to initiate the transfer of event data to consumers.
+       In this model, suppliers are active initiators and consumers are the passive
+       targets of the requests. EventChannels play the role of <c><![CDATA[Notifier]]></c>.
+       Thus, active suppliers use EventChannels to push data to passive consumers that 
+       have registered with the EventChannels.</item>
+      <item><em>The Canonical Pull Model:</em>The Canonical pull model shown
+       in figure 2(B) 
+       allows consumers to request events from suppliers. In this model,
+       Consumers are 
+       active initiators and suppliers are the passive targets of the pull
+       requests. 
+       EventChannel plays the role of <c><![CDATA[Procurer]]></c> since it procures
+       events
+       on behalf of consumers. Thus, active consumers can explicitly pull
+       data 
+       from passive suppliers via the EventChannels.</item>
+      <item><em>The Hybrid Push/Pull Model:</em> The push/pull model shown in figure 2(C) is a 
+       hybrid that allows consumers to request events queued at an EventChannel
+       by suppliers. In this model, both suppliers and consumers are active 
+       initiators of the requests. EventChannels play the role of <c><![CDATA[Queue]]></c>.
+       Thus, active consumers can explicitly pull data deposited by active
+       suppliers via the EventChannels.</item>
+      <item><em>The Hybrid Pull/Push Model:</em> The pull/push model shown in figure 2(D) is another
+       hybrid that allows the channel to pull events from suppliers and push them 
+       to consumers. In this model, suppliers are passive targets of pull requests 
+       and consumers are passive targets of pushes. EventChannels play the role of 
+      <c><![CDATA[Intelligent Agent]]></c>. Thus, active EventChannels can pull data from 
+       passive suppliers and push that data to passive consumers.</item>
+    </list>
+  </section>
+
+  <section>
+    <title>A Tutorial on How to Create a Simple Service</title>
+    <p>To be able to use the cosEvent application supplier and consumer objects
+      must be implemented, which must inherit from the appropriate interface
+      defined in the <em>CosEventComm.idl</em> specification.</p>
+    <p>We start by creating an interface which inherits from the correct interface, 
+      e.g., CosEventComm::PushConsumer. Hence, we must also implement all
+      operations defined in the PushConsumer interface. The IDL-file could look like: 
+      </p>
+    <code type="c"><![CDATA[
+#ifndef _MYCLIENT_IDL
+#define _MYCLIENT_IDL
+#include <CosEventComm.idl>
+ 
+module myClientImpl {
+ 
+  interface ownInterface:CosEventComm::PushConsumer {
+ 
+    void ownFunctions(in any NeededArguments)
+       raises(OwnExceptions);
+ 
+  };
+};
+ 
+#endif
+    ]]></code>
+    <p>Run the IDL compiler on this file by calling the <c><![CDATA[ic:gen/1]]></c> function. 
+      This will produce the API named <c><![CDATA[myClientImpl_ownInterface.erl]]></c>.
+      After generating the API stubs and the server skeletons it is time to 
+      implement the servers and if no special options are sent 
+      to the IDl compiler the file name is <c><![CDATA[myClientImpl_ownInterface_impl.erl]]></c>.</p>
+  </section>
+
+  <section>
+    <title>How to Run Everything</title>
+    <p>Below is a short transcript on how to run cosEvent. </p>
+    <code type="none"><![CDATA[
+ 
+%% Start Mnesia and Orber
+mnesia:delete_schema([node()]),
+mnesia:create_schema([node()]),
+orber:install([node()]),
+mnesia:start(),
+orber:start(),
+ 
+%% Install cosEvent in the IFR.
+cosEventApp:install(), 
+
+%% Register the application specific Client implementations
+%% in the IFR.
+'oe_myClientImpl':'oe_register'(), 
+ 
+%% Start the cosEvent application.
+cosEventApp:start(), 
+ 
+%% Start a channel using the default configuration
+Ch = cosEventApp:start_channel(),
+%% ... or use configuration parameters.
+Ch = cosEventApp:start_channel([{pull_interval, 10}, {maxEvents, 50}]),
+ 
+%% Retrieve a SupplierAdmin and a ConsumerAdmin.
+AdminSupplier = 'CosEventChannelAdmin_EventChannel':for_suppliers(Ch),
+AdminConsumer = 'CosEventChannelAdmin_EventChannel':for_consumers(Ch),
+
+%% Use the corresponding Admin object to get access to wanted Proxies
+
+%% Create a Push Consumer Proxy, which the Client Push Supplier will push 
+%% events to.
+ProxyPushConsumer = 
+  'CosEventChannelAdmin_SupplierAdmin':obtain_push_consumer(AdminSupplier),
+
+%% Create a Push Supplier Proxy, which will push events to the registered
+%% Push Consumer.
+ProxyPushSupplier =
+  'CosEventChannelAdmin_ConsumerAdmin':obtain_push_supplier(AdminConsumer),
+
+
+%% Create application Clients. We can, for example, start the Clients 
+%% our selves or look them up in the naming service. This is application
+%% specific.
+Consumer = myClientImpl_ownInterface:oe_create(),
+Supplier = ...
+
+%% Connect each Client to the corresponding Proxy.
+'CosEventChannelAdmin_ProxyPushConsumer':
+   connect_push_supplier(ProxyPushConsumer, Supplier),
+'CosEventChannelAdmin_ProxyPushSupplier':
+   connect_push_consumer(ProxyPushSupplier, Consumer),
+    ]]></code>
+    <p>The example above, exemplifies a event system, i.e., the <em>Canonical Push Model</em>, where the Supplier client in some way generates event
+      and pushes them to the proxy. The push supplier proxies will eventually
+      push the events to each Consumer client.</p>
+  </section>
+</chapter>
+