path: root/trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README

$Id$

README for the Notification Service Reconnection Test
-----------------------------------------------------

Implementation notes
--------------------

Notification Service Supplier/Consumer reconnection test.

This directory contains:

   Supplier.cpp     -- source for a configurable event supplier
   Supplier.h
   Consumer.cpp     -- source for a configurable consumer for events produced
   Consumer.h          by a Supplier
   run_ns.pl        -- a script to start the Notification Service manually
   run_supplier.pl  -- a script to start Supplier manually
   run_consumer.pl  -- a script to start Consumer manually
   run_test.pl      -- a script to run several tests of the Reliable
                       Notification Service
   ns_st.conf       -- configures the Notification Service for single
                       thread operation with no persistence support.
   ns_mt.conf       -- configures the Notification Service for multi-
                       threaded operation with no persistence support.
   ns_st_topo.conf  -- configures the Notification Service for single
                       thread operation with support for topological,
                       but not event persistence.
   ns_mt_topo.conf  -- configures the Notification Service for multi-
                       threaded operation with support for topological,
                       but not event persistence.
   ns_st_both.conf  -- configures the Notification Service for single
                       thread operation with support for both topological,
                       and event persistence. 
   ns_mt_both.conf  -- configures the Notification Service for multi-
                       threaded operation with support for both topological,
                       and event persistence. 
   event.conf       -- configures the Notification Service for event
                       persistence without topology persistence.  This is
                       an invalid configuration and should cause the
                       Notification Service to refuse to start.
   Reconnecting.mpc -- a configuration/build file for MPC
   README           -- this file

Supplier
--------
This program connects to the Notification Service and generates events based
on command line parameters.

  -nonamesvc            Don't use the Naming Service to find
                        EventChannelFactory
  -channel filename     Where to find a channel number
  -any or -str or -seq  What type of event to send (pick one, default is -any)
  -send n               How many events to send
  -pause n              Pause after sending n events
                        Signal the pause by writing to file "Supplier.paused"
  -serial_number n      What serial number to start with
  -v                    Verbose output

Because the Supplier and Consumer share many command line options, the
descriptions of these options will be combined below.

Consumer
--------
This program connects to the Notification Service and consumes events from
the Supplier.

  -nonamesvc            Don't use the Naming Service to find
                        EventChannelFactory
  -channel filename     Where to store a channel number so the Supplier can 
                        find it
  -any or -str or -seq  What type of event supplier will send (pick one, 
                        default: -any)
  -expect n             How many events are expected.
  -fail n               Simulate a recoverable failure every n events.
  -serial_number n      What serial number to expect first.  If -1 is
                        used, then serial number checking is disabled.
                        This allows testing the consumer with multiple
                        Suppliers.
  -disconnect           Disconnect from notfication service cleanly 
                        (no reconnect will be possible)
  -v                    Verbose output.

Command line option: -nonamesvc
-------------------------------
There are several techniques that Notification Service clients (Suppliers
and Consumers) may use to find and connect to the Notification Service.
One common technique is for the Notification Service to register an Event
Channel Factory with the Naming Service using a well-known name (specified in
the CORBA standard.)

Although this technique is a good one for use in a system that already depends
on the Naming Service, the test scripts in this directory do not depend on the
Naming Service.  When this option is specified, the Supplier and Consumer use
"resolve_initial_references ()" to find the Notification Service.

When this option is used, the ORB option -ORBInitRef must also be used to
define an initial reference to the Notification Service.

Command line option: -channel filename
--------------------------------------
The Notification Service has the ability to support several channels
simultaneously.  For these tests to work, the Supplier and Consumer must
use the same channel.  There are several techniques the Consumer(s) and
Supplier(s) can use to select which channel to use.  These programs use a
shared file to communicate the channel number from the Consumer that creates
the channel to the Supplier that uses it.

When the Consumer starts up but is not reconnecting to an existing service,
it creates a new channel and writes the channel ID to the file specified by
this command (if no -channel option is given, the channel ID is not written.)

When the Supplier starts up, but is not reconnecting to an existing service,
it attempts to read the channel ID from the file specified by this option.
If it is successful it uses that channel ID to send events.

Command line options: -any or -str or -seq
------------------------------------------
The Notification Service supports three types of Events.  Any events are
like those used by the Event Service (an ancestor to the Notification
Service).  Structured events and Sequence events are events supported only
by the Notification Service.  See the TAO Developer's Guide or the CORBA
specification for more details.

Only one of these three options should be specified.  If none of these 
is specified, the default is "-any".

Command line option: -send n
----------------------------
This Supplier-only option tells the Supplier how many events to send.
After it has sent that many events, the Supplier will shut down.

Command line option: -expect n
------------------------------
This Consumer-only option tells the Consumer how many events to expect.
After it has received that many events, the Consumer will shut down.

Command line option: -fail n
------------------------------
This Consumer-only option tells the Consumer to throw an exception 
(CORBA::UNKNOWN) every n events.  This simulates a recoverable error in
the consumer.  After throwing the exception, the consumer continues
to listen for incoming events. It expects the event it was processing
to be retransmitted.

Because of the retransmission, the use of the -fail option may be
counterintuitive.  If the consumer options are "-expect 10 -fail 4" then 
it will receive events 0, 1, 2, and fail on event 3.  It will then 
receive 3, 4, 5, and fail on event 6.  Then it will receive 6, 7, 8, 
and fail on event 9.  Finally it will receive the retransmission of event 
9 and exit.

Command line option: -pause n
-----------------------------
This Supplier-only option is used during testing.  The Supplier will send
the specified number of events then wait for the Notification Service to
stop and restart before sending the remaining events.

To signal test scripts that a pause has happened, the Supplier will create
a file named "Supplier.pause"  This file can be used to  synchronize a
script with a running Supplier.  It has no other purpose.

Obviously the -pause option should specify a smaller number than the -send
option.  If this option is not used, no pause will occur.

Command line option: -serial_number n
-------------------------------------
Each event sent by the the Supplier has a sequential serial number.  As the
Consumer receives events, it checks to see that the events arrived in serial
number order.  Missing or duplicated events will be detected by the Consumer.

This option tells the Supplier what serial number to use for the first event
it sends, and the Consumer what serial number to expect in the first event
it receives.

For the Consumer only, a value of -1 disables checking of incoming serial
numbers.  This should be used when the Consumer is receiving events from
multiple suppliers.

Command line option: -v
-----------------------
This option enables verbose messages.   The Supplier and Consumer are
relatively silent during normal operation -- displaying messages only when
something goes wrong.  If this verbose option is specified, more detailed
progress messages will be displayed.

Reconnection
------------
Reconnection to the Notification Service is based on ID numbers assigned to
the objects within the Notification Service (objects like Channels, Admins,
and Proxies).  After initially starting up, the supplier writes the IDs it
needs to preserve to a file named Supplier.ids.  The Consumer writes its
IDs to Consumer.ids.

When a client (Supplier or Consumer) starts up, it looks for its corresponding
".ids" file.  If the file is found, the client attempts to reconnect to an
existing Notification Service using these IDs.  If the file is not found, or
the reconnection fails, the client falls back on its normal startup procedure.

In addition, a running client can receive a request for reconnection from
the Notification Service.  When it does so, it uses the saved ID numbers to
complete the reconnection process.

Programming Style
-----------------
The Supplier and Consumer source files were designed to be complete,
stand-alone applications.  Other than their basic dependency on ACE, TAO,
and CORBA, they avoid using outside facilities.  For example, there is a
Notification Tests library used by many Notification Service tests that
encapsulates connections to the Notification Service and typical CORBA
application issues.  Because these programs were intended to illustrate
everything necessary for a client application to work with a reliable
Notification Service, this library is not used.

Obviously a real-world application should take advantage of such helper
classes to allow the developer to concentrate on the domain problem for
which the application is written.

Also these programs use ACE-style platform independence techniques.
Applications that do not need to support the wide variety of platforms
supported by ACE and TAO can relax some of these coding techniques.

run_test.pl
-----------
The run_test.pl script runs tests of different cases in which
reliable topology is needed.  The following command line options can
be given to the test script:

run_test.pl: command line options -any, -str, or -seq
-----------------------------------------------------
Specify one of these options to determine what type of event will be used
during the test.  The default if none of these options is present is "-any".

run_test.pl: command line option -v
--------------------------------------------
This option controls the verbosity of the test script and the Supplier and
Consumer applications.  When it is present, a detailed step-by-step 
report is produced by the test.

run_test.pl: Test #1: Supplier reconnection.
--------------------------------------------
All persistent information is discarded before the test starts.  The test
script starts the Notification Service, a Consumer and a Supplier.

The Consumer is configured to receive 20 events.  The Supplier is configured
to send ten events.

After sending ten events, the Supplier exits -- simulating a Supplier failure.
The test script starts a new copy of the Supplier.  The new Supplier is 
configured to send ten events starting with event number 10.  
It uses information saved by the previous supplier to reconnect to the same
channel, admin, and proxy in the Notification Services.
The Suppler sends the remaining ten events then exists.  The Consumer having
received the 20 events it expects, exits as well and the test is complete.

This demonstrates that a Supplier can stop then restart and its events will e
delivered to the correct Consumer.

run_test.pl: Test #2: Consumer reconnection.
--------------------------------------------
The Notification Service from the previous test is still running and the
saved reconnection information for both the Supplier and Consumer is still
available.

The test script starts a Consumer configured to receive 20 events and a 
Supplier configured to send twenty events.  Both clients use the reconnection
information from the previous test to reconnect to the Notification Service.  

Twenty events are sent successfully, then both clients exit and the test
is complete.

This demonstrates that a Consumer can stop then restart and reconnect.  It
will continue to receive the events on the channel to which it was originally
connected.

run_test.pl: Test #3: Saving and Restoring Topology
---------------------------------------------------
The test script stops the Notification Server from the previous two tests and
starts a new Notification Server. It reloads the topology from the XML topology
persistence files saved during the first two tests.

The test script starts a Consumer and a Supplier.  They are configured to
receive and send respectively twenty events.  The clients use the reconnection
information from the previous tests to connect to the event channel, admins,
and proxies that were reloaded from persistent topology information.
The Supplier sends and the Consumer receives 20 events.  Both clients exit.

This demonstrates that the Notification Server can save its topology, then
reload it, and the resulting topology behaves correctly when clients reconnect.

run_test.pl: Test #4: The Reconnection Registry
-----------------------------------------------
This test starts with the Notification Service from the previous test.

The script starts a new Consumer that expects to receive 20 events. The 
Consumer reconnects to the Notification Server.
The script starts a Supplier.  It is configured to send 10 events then 
pause waiting for a Notification Service initiated reconnection before 
sending the remaining 10 events.

Both clients register with the Reconnection Registry to receive reconnection 
callbacks.

The test script waits for the Supplier to pause.  It then kills the
Notification Service and starts a new copy.  The new Notification Service
is not configured to listen at the same endpoint as the previous one did,
so the clients have no way to find the new copy directly.  They must rely
on the callback received from the Reconnection Registry.

The new Notification Service reloads its topology, including the Reconnection
Registry entries from the XML file. It sends reconnection callbacks to the
registered clients.

Using their saved reconnection information, the clients complete the
reconnection to the new Notification Service.

The Supplier sends the remaining 10 events then terminates.  The Consumer,
having received its expected 10 events also terminates.

This demonstrates the reconnection registry and reconnection to live clients.

run_test.pl: Test #5: Consumer Recoverable Exception
----------------------------------------------------
Using the Notification Service still running from the previous test,
but discarding reconnection information, a new Consumer is started.
It is configured to expect 10 events, but to throw an exception after
receiving the sixth event.  After throwing the exception it expects to see
the sixth event retransmitted, then to receive the remaining four events.
A Supplier is started that sends 10 events, and then exits.
When the Consumer has received the events it expects, including the
retransmission of the sixth event, it shuts down.

This demonstrates the Notification Service can recover from transient
communication or Consumer failures.

Known Problems as of Feb 2004.
------------------------------
Sequence events are not working.  It is unclear whether this is a problem in 
the test or in the Notification Service itself.

Known Problems as of Mar 2004.
------------------------------
The problem with sequence events reported previously turned out to be problems
in both the test and in the Notification Service itself.  These problems
have been resolved.  It is now possible to mix and match consumers and
suppliers.

There are no new known problems.

[----------------------------------------------------------------------------]