<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2000</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>cosNotification Examples</title>
<prepared>Niclas Eklund</prepared>
<docno></docno>
<date>2000-01-31</date>
<rev>A</rev>
<file>ch_example.xml</file>
</header>
<section>
<title>A Tutorial on How to Create a Simple Service</title>
<section>
<title>Interface Design</title>
<p>To use the cosNotification application <em>clients</em> must be implemented.
There are twelve types of clients: </p>
<list type="bulleted">
<item>Structured Push Consumer</item>
<item>Sequence Push Consumer </item>
<item>Any Push Consumer</item>
<item>Structured Pull Consumer</item>
<item>Sequence Pull Consumer</item>
<item>Any Pull Consumer</item>
<item>Structured Push Supplier</item>
<item>Sequence Push Supplier</item>
<item>Any Push Supplier</item>
<item>Structured Pull Supplier</item>
<item>Sequence Pull Supplier</item>
<item>Any Pull Supplier</item>
</list>
<p>The interfaces for these participants are defined in <em>CosNotification.idl</em>
and <em>CosNotifyComm.idl</em>.</p>
</section>
<section>
<title>Generating a Client Interface</title>
<p>We start by creating an interface which inherits from the correct interface, e.g., <em>CosNotifyComm::SequencePushConsumer</em>. Hence,
we must also implement all operations defined in the SequencePushConsumer interface. The IDL-file could look like: </p>
<code type="c"><![CDATA[
#ifndef _MYCLIENT_IDL
#define _MYCLIENT_IDL
#include <CosNotification.idl>
#include <CosNotifyComm.idl>
module myClientImpl {
interface ownInterface:CosNotifyComm::SequencePushConsumer {
void ownFunctions(in any NeededArguments)
raises(Systemexceptions,OwnExceptions);
};
};
#endif
]]></code>
<p>Run the IDL compiler on this file by calling the <c>ic:gen/1</c> function.
This will produce the API named <c>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>myClientImpl_ownInterface_impl.erl</c>.</p>
<p>The callback module must contain the necessary functions inherited from
<em>CosNotification.idl</em> and <em>CosNotifyComm.idl</em>.</p>
</section>
<section>
<title>How to Run Everything</title>
<p>Below is a short transcript on how to run cosNotification. </p>
<code type="none">
%% Start Mnesia and Orber
mnesia:delete_schema([node()]),
mnesia:create_schema([node()]),
orber:install([node()]),
mnesia:start(),
orber:start(),
%% If cosEvent not installed before it is necessary to do it now.
cosEventApp:install(),
%% Install cosNotification in the IFR.
cosNotificationApp:install(30),
%% Register the application specific Client implementations
%% in the IFR.
'oe_myClientImpl':'oe_register'(),
%% Start the cosNotification application.
cosNotificationApp:start(),
%% Start a factory using the default configuration
ChFac = cosNotificationApp:start_factory(),
%% ... or use configuration parameters.
ChFac = cosNotificationApp:start_factory([]),
%% Create a new event channel. Note, if no QoS- anr/or Admin-properties
%% are supplied (i.e. empty list) the default settings are used.
{Ch, ChID} = 'CosNotifyChannelAdmin_EventChannelFactory':
create_channel(ChFac, DefaultQoS, DefaultAdmin),
%% Retrieve a SupplierAdmin and a Consumer Admin.
{AdminSupplier, ASID}=
'CosNotifyChannelAdmin_EventChannel':new_for_suppliers(Ch, 'OR_OP'),
{AdminConsumer, ACID}=
'CosNotifyChannelAdmin_EventChannel':new_for_consumers(Ch,'OR_OP'),
%% Use the corresponding Admin object to get access to wanted Proxies
%% Create a Push Consumer Proxie, i.e., the Client Push Supplier will
%% push events to this Proxy.
{StructuredProxyPushConsumer,ID11}= 'CosNotifyChannelAdmin_SupplierAdmin':
obtain_notification_push_consumer(AdminSupplier, 'STRUCTURED_EVENT')),
%% Create Push Suppliers Proxies, i.e., the Proxy will push events to the
%% registered Push Consumers.
{ProxyPushSupplier,I4D}='CosNotifyChannelAdmin_ConsumerAdmin':
obtain_notification_push_supplier(AdminConsumer, 'ANY_EVENT'),
{StructuredProxyPushSupplier,ID5}='CosNotifyChannelAdmin_ConsumerAdmin':
obtain_notification_push_supplier(AdminConsumer, 'STRUCTURED_EVENT'),
{SequenceProxyPushSupplier,ID6}='CosNotifyChannelAdmin_ConsumerAdmin':
obtain_notification_push_supplier(AdminConsumer, 'SEQUENCE_EVENT'),
%% Create application Clients. We can, for example, start the Clients
%% our selves or look them up in the naming service. This is application
%% specific.
SupplierClient = ...
ConsumerClient1 = ...
ConsumerClient2 = ...
ConsumerClient3 = ...
%% Connect each Client to corresponding Proxy.
'CosNotifyChannelAdmin_StructuredProxyPushConsumer':
connect_structured_push_supplier(StructuredProxyPushConsumer, SupplierClient),
'CosNotifyChannelAdmin_ProxyPushSupplier':
connect_any_push_consumer(ProxyPushSupplier, ConsumerClient1),
'CosNotifyChannelAdmin_StructuredProxyPushSupplier':
connect_structured_push_consumer(StructuredProxyPushSupplier, ConsumerClient2),
'CosNotifyChannelAdmin_SequenceProxyPushSupplier':
connect_sequence_push_consumer(SequenceProxyPushSupplier, ConsumerClient3),
</code>
<p>The example above, exemplifies a notification system where the SupplierClient
in some way generates event and pushes them to the proxy. The push supplier
proxies will eventually push the events to each ConsumerClient.</p>
</section>
</section>
</chapter>
