This file contains information on installing, building and using omniEvents, an
implementation of the OMG Event Service Specification v1.0 for omniORB3.

General Information
===================

Information on the Event Service specification can be obtained from the
"CORBAservices : Common Object Services Specification" pages at:

http://www.omg.org/corba/sectrans.html

omniEvents implements untyped event channels and can be used in one of
two ways:

- Channels can be instanciated within a user process by linking user code with
  the static libraries supplied.

- Channels can be created in a foreign process implemented by omniEvents.

omniEvents supports all combinations of push/pull communication models :

   Push Supplier - Push Consumer
   Pull Supplier - Push Consumer
   Push Supplier - Pull Consumer
   Pull Supplier - Pull Consumer

See "OMG Event Object Service", SIGS Vol9, Num 2, February 1997 for an
introduction to the various communication models at:

http://www.cs.wustl.edu/~schmidt/C++-report-col9.ps.gz

As of Release 2.0, omniEvents is fully persistent and supports Quality of 
Service (QOS) parameters for specifying:

- How fast a channel polls when in Pull Supplier - Push Consumer mode.
- How many events are buffered by each ProxySupplier. The discard policy is
  FIFO, meaning that the oldest events are discarded first in case of overflow.
- The maximum number of events queued by the channel. The discard policy is
  FIFO, meaning that the oldest events are discarded first in case of overflow.

Platforms Supported
===================

omniEvents 2.1 has been tested with omniORB 3.1.0 on the following platform(s):

   o HPUX 10.20/ aC++ (B3910B A.01.21)
   o HPUX 11.00/ aC++ (B3910B A.03.25)
   o Windows NT 4.0 / Visual C++ 6.0 SP3
   o Solaris 2.5/ gcc-2.8.1
   o Solaris 2.6/ 
   o x86 Redhat linux 4.2 / gcc-2.7.2

Roadmap
=======

The directory structure of this distribution looks as follows:

./idl             : idl files
./include         : include files
./bin             : binary files
./config          : site-specific configuration files
./lib             : static libraries
./src             : source files
./util            : source files for utility functions
./fe              : source files for persistency logfile parser
./examples        : source files for examples

Configuration
=============

You can optionally modify any of the parameters in the config/config.mk file
to cater for requirements that are specific to your site (eg default location
for log files, etc).

Please refer to the config/config.mk file for descriptions of all parameters.

Building omniEvents
=====================

Follow these steps to buidl omniEvents:

1. First configure omniORB3 to build on your particular platform. This is
   required even if you have downloaded an omniORB3 binary distribution.
   omniEvents uses the same make mechanism as omniORB3 so make sure that
   'make' is GNUmake as the makefiles are GNUmake specific.

2. cd into src/contrib/omniEvents

3. Type 'make export'

% cd src/contrib/omniEvents
% make export

If all goes well you should end up with the following executables in a
platform-dependent directory inside the src/contrib/omniEvents/bin directory:

  +-----------------------------+-----------------------------------------+
  |         Filename            |                                         |
  +------------+----------------+              Description                |
  |   Unix     |     Win32      |                                         |
  +------------+----------------+-----------------------------------------+
  | omniEvents | omniEvents.exe | Event Channel factory server            |
  +------------+----------------+-----------------------------------------+
  | eventc     | eventc.exe     | Event Channel factory client            |
  +------------+----------------+-----------------------------------------+
  | pushsupp   | pushsupp.exe   | Push Supplier client                    |
  +------------+----------------+-----------------------------------------+
  | pushcons   | pushcons.exe   | Push Consumer client                    |
  +------------+----------------+-----------------------------------------+
  | pullsupp   | pullsupp.exe   | Pull Supplier client                    |
  +------------+----------------+-----------------------------------------+
  | pullcons   | pullcons.exe   | Pull Consumer client                    |
  +------------+----------------+-----------------------------------------+

Running the examples
====================

1. Start the Naming Service (omniNames)
----------------------------------------

You must start the naming service (omniNames) as the examples make use of
the naming service to locate the event channel factory. Please refer to the
omniORB3 documentation for information on how to setup the naming service.


2. Start the omniEvents process (omniEvents)
---------------------------------------------

omniEvents supports persistent channels as of release 2.0 by writting all state
changes to a logfile :

    o Set the environment variable OMNIORB_CONFIG to contain the full
      path name of the file omniORB.cfg. For example,
      OMNIORB_CONFIG=/wib/wob/omniORB.cfg; export OMNIORB_CONFIG

    o Set the environment variable OMNIEVENTS_LOGDIR to a directory where
      omniEvents can store its data. You can use the same directory as that
      specified for omniNames. For example:
      OMNIEVENTS_LOGDIR=/wib/wob; export OMNIEVENTS_LOGDIR

    o Start omniEvents. The binary is in ./bin/$(platform) where platform is
      the name of the platform (eg sun4_sosV_5.5) . For example:

      % omniEvents -s 7766 &

      Note that you have to give as a parameter to the option -s
      the TCP/IP port number omniEvents will use to receive IIOP requests.

The omniEvents process implements an Event Channel Factory server which
clients can use to create Event Channels. The factory registers itself
with the Naming Service to enable clients to locate it. omniEvents supports the
following options :

usage: omniEvents [-s port] [-l logdir] [-N name] [-K kind] [-h]

         -s server port
         -l log and data directory
         -N name specify factory name ["EventChannelFactory"]
         -K kind specify factory kind ["EventChannelFactory"]
         -h     display usage

Use -s option to start omniEvents for the first time.
Use -l option to specify the directory where the log/data files are kept.

The options provided allow you to override the default name used to register
the Event Channel Factory with the Naming Service.


3. Run the Event Channel Factory Client (eventc)
------------------------------------------------

eventc resolves the factory name with the Naming service and then contacts
the factory to request an Event Channel. The Event Channel is created within
the factory address space (ie in the omniEvents process).

Note : you can by-pass the factory completely and instanciate the event channel
       directly within your own process by linking your application directly with
       the omniEvents static libraries. The omniEvents.cc file is a good starting
       point to find out how.

eventc then registers the created Event Channel with the Naming Service.

eventc has the folowing options :

usage: eventc [-n name] [-k kind] [-N name] [-K kind] [-r sec] [-m events] [-h]

         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -N name specify factory name ["EventChannelFactory"]
         -K kind specify factory kind ["EventChannelFactory"]
         -r Pull retry Period (in seconds) [1 sec]
         -m Maximum Number of Events queued per Consumer [0 = unlimited]
         -q Maximum Number of Events queued by the channel [0 = unlimited]
         -h     display usage

The options provided allow you to override the default name used to register
the Event Channel Factory and the created Event Channel with the Naming
Service.

eventc starts silently unless it encounters any problems or if you turn tracing
on by supplying the omniORB3 specific option -ORBtraceLevel 20. eventc
terminates once the event channel has been created :

% eventc
%

4. Run one or more suppliers/consumers (pushsupp, pushcons, pullsupp, pullcons)
-------------------------------------------------------------------------------

When run, each supplier and consumer contacts the Naming Service to obtain a
reference to the Event Channel created in step 2 above. They then connect
themselves to the channel and do their bits. The data sent through the channel
is always of type long in the examples.

As per eventc, you can override the default name used to register
the channel in the naming service. The -d option is used to exersize the
disconnect functionaly provided by the channel.

usage: pushsupp [-d n [-s n]] [-n name] [-k kind] [-h]

         -d n   disconnect after n pushes
         -s n   sleep n seconds after disconnecting
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pushcons [-d n -s n]] [-n name] [-k kind] [-h]

         -d n   disconnect after n pushes
         -s n   sleep n seconds after disconnecting
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pullsupp [-d n -s n]] [-n name] [-k kind] [-h]

         -d n   disconnect after n pulls
         -s n   sleep n seconds after disconnecting
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

usage: pullcons [-t] [-d n -s n]] [-n name] [-k kind] [-h]

         -t      enable try_pull mode
         -d n    disconnect after n pulls
         -s n   sleep n seconds after disconnecting
         -n name specify channel name ["EventChannel"]
         -k kind specify channel kind ["EventChannel"]
         -h     display usage

The -t option in pullcons causes the pull consumer to issue non-blocking
try_pull invocations rather than blocking pulls.

Here is what to expect during a typical session :

% ./pushsupp
Looking for EventChannel
Obtained SupplierAdmin.
Obtained ProxyPushConsumer.
Connected Push Supplier.
Push Supplier: push() called. Data : 0
Push Supplier: push() called. Data : 1
Push Supplier: push() called. Data : 2
Push Supplier: push() called. Data : 3
Push Supplier: push() called. Data : 4
Push Supplier: push() called. Data : 5
...

% ./pushcons
Obtained ConsumerAdmin.
Obtained ProxyPushSupplier.
Connected Push Consumer.
Push Consumer: push () called. Data : 0
Push Consumer: push () called. Data : 1
Push Consumer: push () called. Data : 2
Push Consumer: push () called. Data : 3
Push Consumer: push () called. Data : 4
Push Consumer: push () called. Data : 5
Push Consumer: push () called. Data : 6
...


Note, pull consumers cause the event channel to poll every pull supplier
connected when they request an event (using pull, not try_pull) until an
event enters the event channel (which could come from a push supplier).

In order to prevent the Event Channel from consuming excessive CPU when
polling for events the -r option of eventc can be used to specify a pull
retry period QOS parameter. This parameter represents a timeout in Seconds
to wait for before each poll cycle. This parameter defaults to 1 Second.

I hope you find omniEvents useful. If you have any comments or suggestion
for improvements you can email me at Paul.Nader@alcatel.com.au.
