diff options
Diffstat (limited to 'trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README')
| -rw-r--r-- | trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README b/trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README new file mode 100644 index 00000000000..723c0a4f730 --- /dev/null +++ b/trunk/TAO/orbsvcs/tests/Notify/Reconnecting/README @@ -0,0 +1,351 @@ +$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. + +[----------------------------------------------------------------------------] + |