TAO/orbsvcs/tests/Notify/Reconnecting/README

   1
   2
   3 README for the Notification Service Reconnection Test
   4 -----------------------------------------------------
   5
   6 Implementation notes
   7 --------------------
   8
   9 Notification Service Supplier/Consumer reconnection test.
  10
  11 This directory contains:
  12
  13    Supplier.cpp     -- source for a configurable event supplier
  14    Supplier.h
  15    Consumer.cpp     -- source for a configurable consumer for events produced
  16    Consumer.h          by a Supplier
  17    run_ns.pl        -- a script to start the Notification Service manually
  18    run_supplier.pl  -- a script to start Supplier manually
  19    run_consumer.pl  -- a script to start Consumer manually
  20    run_test.pl      -- a script to run several tests of the Reliable
  21                        Notification Service
  22    ns_st.conf       -- configures the Notification Service for single
  23                        thread operation with no persistence support.
  24    ns_mt.conf       -- configures the Notification Service for multi-
  25                        threaded operation with no persistence support.
  26    ns_st_topo.conf  -- configures the Notification Service for single
  27                        thread operation with support for topological,
  28                        but not event persistence.
  29    ns_mt_topo.conf  -- configures the Notification Service for multi-
  30                        threaded operation with support for topological,
  31                        but not event persistence.
  32    ns_st_both.conf  -- configures the Notification Service for single
  33                        thread operation with support for both topological,
  34                        and event persistence.
  35    ns_mt_both.conf  -- configures the Notification Service for multi-
  36                        threaded operation with support for both topological,
  37                        and event persistence.
  38    event.conf       -- configures the Notification Service for event
  39                        persistence without topology persistence.  This is
  40                        an invalid configuration and should cause the
  41                        Notification Service to refuse to start.
  42    Reconnecting.mpc -- a configuration/build file for MPC
  43    README           -- this file
  44
  45 Supplier
  46 --------
  47 This program connects to the Notification Service and generates events based
  48 on command line parameters.
  49
  50   -nonamesvc            Don't use the Naming Service to find
  51                         EventChannelFactory
  52   -channel filename     Where to find a channel number
  53   -any or -str or -seq  What type of event to send (pick one, default is -any)
  54   -send n               How many events to send
  55   -pause n              Pause after sending n events
  56                         Signal the pause by writing to file "Supplier.paused"
  57   -serial_number n      What serial number to start with
  58   -v                    Verbose output
  59
  60 Because the Supplier and Consumer share many command line options, the
  61 descriptions of these options will be combined below.
  62
  63 Consumer
  64 --------
  65 This program connects to the Notification Service and consumes events from
  66 the Supplier.
  67
  68   -nonamesvc            Don't use the Naming Service to find
  69                         EventChannelFactory
  70   -channel filename     Where to store a channel number so the Supplier can
  71                         find it
  72   -any or -str or -seq  What type of event supplier will send (pick one,
  73                         default: -any)
  74   -expect n             How many events are expected.
  75   -fail n               Simulate a recoverable failure every n events.
  76   -serial_number n      What serial number to expect first.  If -1 is
  77                         used, then serial number checking is disabled.
  78                         This allows testing the consumer with multiple
  79                         Suppliers.
  80   -disconnect           Disconnect from notfication service cleanly
  81                         (no reconnect will be possible)
  82   -v                    Verbose output.
  83
  84 Command line option: -nonamesvc
  85 -------------------------------
  86 There are several techniques that Notification Service clients (Suppliers
  87 and Consumers) may use to find and connect to the Notification Service.
  88 One common technique is for the Notification Service to register an Event
  89 Channel Factory with the Naming Service using a well-known name (specified in
  90 the CORBA standard.)
  91
  92 Although this technique is a good one for use in a system that already depends
  93 on the Naming Service, the test scripts in this directory do not depend on the
  94 Naming Service.  When this option is specified, the Supplier and Consumer use
  95 "resolve_initial_references ()" to find the Notification Service.
  96
  97 When this option is used, the ORB option -ORBInitRef must also be used to
  98 define an initial reference to the Notification Service.
  99
 100 Command line option: -channel filename
 101 --------------------------------------
 102 The Notification Service has the ability to support several channels
 103 simultaneously.  For these tests to work, the Supplier and Consumer must
 104 use the same channel.  There are several techniques the Consumer(s) and
 105 Supplier(s) can use to select which channel to use.  These programs use a
 106 shared file to communicate the channel number from the Consumer that creates
 107 the channel to the Supplier that uses it.
 108
 109 When the Consumer starts up but is not reconnecting to an existing service,
 110 it creates a new channel and writes the channel ID to the file specified by
 111 this command (if no -channel option is given, the channel ID is not written.)
 112
 113 When the Supplier starts up, but is not reconnecting to an existing service,
 114 it attempts to read the channel ID from the file specified by this option.
 115 If it is successful it uses that channel ID to send events.
 116
 117 Command line options: -any or -str or -seq
 118 ------------------------------------------
 119 The Notification Service supports three types of Events.  Any events are
 120 like those used by the Event Service (an ancestor to the Notification
 121 Service).  Structured events and Sequence events are events supported only
 122 by the Notification Service.  See the TAO Developer's Guide or the CORBA
 123 specification for more details.
 124
 125 Only one of these three options should be specified.  If none of these
 126 is specified, the default is "-any".
 127
 128 Command line option: -send n
 129 ----------------------------
 130 This Supplier-only option tells the Supplier how many events to send.
 131 After it has sent that many events, the Supplier will shut down.
 132
 133 Command line option: -expect n
 134 ------------------------------
 135 This Consumer-only option tells the Consumer how many events to expect.
 136 After it has received that many events, the Consumer will shut down.
 137
 138 Command line option: -fail n
 139 ------------------------------
 140 This Consumer-only option tells the Consumer to throw an exception
 141 (CORBA::UNKNOWN) every n events.  This simulates a recoverable error in
 142 the consumer.  After throwing the exception, the consumer continues
 143 to listen for incoming events. It expects the event it was processing
 144 to be retransmitted.
 145
 146 Because of the retransmission, the use of the -fail option may be
 147 counterintuitive.  If the consumer options are "-expect 10 -fail 4" then
 148 it will receive events 0, 1, 2, and fail on event 3.  It will then
 149 receive 3, 4, 5, and fail on event 6.  Then it will receive 6, 7, 8,
 150 and fail on event 9.  Finally it will receive the retransmission of event
 151 9 and exit.
 152
 153 Command line option: -pause n
 154 -----------------------------
 155 This Supplier-only option is used during testing.  The Supplier will send
 156 the specified number of events then wait for the Notification Service to
 157 stop and restart before sending the remaining events.
 158
 159 To signal test scripts that a pause has happened, the Supplier will create
 160 a file named "Supplier.pause"  This file can be used to  synchronize a
 161 script with a running Supplier.  It has no other purpose.
 162
 163 Obviously the -pause option should specify a smaller number than the -send
 164 option.  If this option is not used, no pause will occur.
 165
 166 Command line option: -serial_number n
 167 -------------------------------------
 168 Each event sent by the the Supplier has a sequential serial number.  As the
 169 Consumer receives events, it checks to see that the events arrived in serial
 170 number order.  Missing or duplicated events will be detected by the Consumer.
 171
 172 This option tells the Supplier what serial number to use for the first event
 173 it sends, and the Consumer what serial number to expect in the first event
 174 it receives.
 175
 176 For the Consumer only, a value of -1 disables checking of incoming serial
 177 numbers.  This should be used when the Consumer is receiving events from
 178 multiple suppliers.
 179
 180 Command line option: -v
 181 -----------------------
 182 This option enables verbose messages.   The Supplier and Consumer are
 183 relatively silent during normal operation -- displaying messages only when
 184 something goes wrong.  If this verbose option is specified, more detailed
 185 progress messages will be displayed.
 186
 187 Reconnection
 188 ------------
 189 Reconnection to the Notification Service is based on ID numbers assigned to
 190 the objects within the Notification Service (objects like Channels, Admins,
 191 and Proxies).  After initially starting up, the supplier writes the IDs it
 192 needs to preserve to a file named Supplier.ids.  The Consumer writes its
 193 IDs to Consumer.ids.
 194
 195 When a client (Supplier or Consumer) starts up, it looks for its corresponding
 196 ".ids" file.  If the file is found, the client attempts to reconnect to an
 197 existing Notification Service using these IDs.  If the file is not found, or
 198 the reconnection fails, the client falls back on its normal startup procedure.
 199
 200 In addition, a running client can receive a request for reconnection from
 201 the Notification Service.  When it does so, it uses the saved ID numbers to
 202 complete the reconnection process.
 203
 204 Programming Style
 205 -----------------
 206 The Supplier and Consumer source files were designed to be complete,
 207 stand-alone applications.  Other than their basic dependency on ACE, TAO,
 208 and CORBA, they avoid using outside facilities.  For example, there is a
 209 Notification Tests library used by many Notification Service tests that
 210 encapsulates connections to the Notification Service and typical CORBA
 211 application issues.  Because these programs were intended to illustrate
 212 everything necessary for a client application to work with a reliable
 213 Notification Service, this library is not used.
 214
 215 Obviously a real-world application should take advantage of such helper
 216 classes to allow the developer to concentrate on the domain problem for
 217 which the application is written.
 218
 219 Also these programs use ACE-style platform independence techniques.
 220 Applications that do not need to support the wide variety of platforms
 221 supported by ACE and TAO can relax some of these coding techniques.
 222
 223 run_test.pl
 224 -----------
 225 The run_test.pl script runs tests of different cases in which
 226 reliable topology is needed.  The following command line options can
 227 be given to the test script:
 228
 229 run_test.pl: command line options -any, -str, or -seq
 230 -----------------------------------------------------
 231 Specify one of these options to determine what type of event will be used
 232 during the test.  The default if none of these options is present is "-any".
 233
 234 run_test.pl: command line option -v
 235 --------------------------------------------
 236 This option controls the verbosity of the test script and the Supplier and
 237 Consumer applications.  When it is present, a detailed step-by-step
 238 report is produced by the test.
 239
 240 run_test.pl: Test #1: Supplier reconnection.
 241 --------------------------------------------
 242 All persistent information is discarded before the test starts.  The test
 243 script starts the Notification Service, a Consumer and a Supplier.
 244
 245 The Consumer is configured to receive 20 events.  The Supplier is configured
 246 to send ten events.
 247
 248 After sending ten events, the Supplier exits -- simulating a Supplier failure.
 249 The test script starts a new copy of the Supplier.  The new Supplier is
 250 configured to send ten events starting with event number 10.
 251 It uses information saved by the previous supplier to reconnect to the same
 252 channel, admin, and proxy in the Notification Services.
 253 The Suppler sends the remaining ten events then exists.  The Consumer having
 254 received the 20 events it expects, exits as well and the test is complete.
 255
 256 This demonstrates that a Supplier can stop then restart and its events will e
 257 delivered to the correct Consumer.
 258
 259 run_test.pl: Test #2: Consumer reconnection.
 260 --------------------------------------------
 261 The Notification Service from the previous test is still running and the
 262 saved reconnection information for both the Supplier and Consumer is still
 263 available.
 264
 265 The test script starts a Consumer configured to receive 20 events and a
 266 Supplier configured to send twenty events.  Both clients use the reconnection
 267 information from the previous test to reconnect to the Notification Service.
 268
 269 Twenty events are sent successfully, then both clients exit and the test
 270 is complete.
 271
 272 This demonstrates that a Consumer can stop then restart and reconnect.  It
 273 will continue to receive the events on the channel to which it was originally
 274 connected.
 275
 276 run_test.pl: Test #3: Saving and Restoring Topology
 277 ---------------------------------------------------
 278 The test script stops the Notification Server from the previous two tests and
 279 starts a new Notification Server. It reloads the topology from the XML topology
 280 persistence files saved during the first two tests.
 281
 282 The test script starts a Consumer and a Supplier.  They are configured to
 283 receive and send respectively twenty events.  The clients use the reconnection
 284 information from the previous tests to connect to the event channel, admins,
 285 and proxies that were reloaded from persistent topology information.
 286 The Supplier sends and the Consumer receives 20 events.  Both clients exit.
 287
 288 This demonstrates that the Notification Server can save its topology, then
 289 reload it, and the resulting topology behaves correctly when clients reconnect.
 290
 291 run_test.pl: Test #4: The Reconnection Registry
 292 -----------------------------------------------
 293 This test starts with the Notification Service from the previous test.
 294
 295 The script starts a new Consumer that expects to receive 20 events. The
 296 Consumer reconnects to the Notification Server.
 297 The script starts a Supplier.  It is configured to send 10 events then
 298 pause waiting for a Notification Service initiated reconnection before
 299 sending the remaining 10 events.
 300
 301 Both clients register with the Reconnection Registry to receive reconnection
 302 callbacks.
 303
 304 The test script waits for the Supplier to pause.  It then kills the
 305 Notification Service and starts a new copy.  The new Notification Service
 306 is not configured to listen at the same endpoint as the previous one did,
 307 so the clients have no way to find the new copy directly.  They must rely
 308 on the callback received from the Reconnection Registry.
 309
 310 The new Notification Service reloads its topology, including the Reconnection
 311 Registry entries from the XML file. It sends reconnection callbacks to the
 312 registered clients.
 313
 314 Using their saved reconnection information, the clients complete the
 315 reconnection to the new Notification Service.
 316
 317 The Supplier sends the remaining 10 events then terminates.  The Consumer,
 318 having received its expected 10 events also terminates.
 319
 320 This demonstrates the reconnection registry and reconnection to live clients.
 321
 322 run_test.pl: Test #5: Consumer Recoverable Exception
 323 ----------------------------------------------------
 324 Using the Notification Service still running from the previous test,
 325 but discarding reconnection information, a new Consumer is started.
 326 It is configured to expect 10 events, but to throw an exception after
 327 receiving the sixth event.  After throwing the exception it expects to see
 328 the sixth event retransmitted, then to receive the remaining four events.
 329 A Supplier is started that sends 10 events, and then exits.
 330 When the Consumer has received the events it expects, including the
 331 retransmission of the sixth event, it shuts down.
 332
 333 This demonstrates the Notification Service can recover from transient
 334 communication or Consumer failures.
 335
 336 Known Problems as of Feb 2004.
 337 ------------------------------
 338 Sequence events are not working.  It is unclear whether this is a problem in
 339 the test or in the Notification Service itself.
 340
 341 Known Problems as of Mar 2004.
 342 ------------------------------
 343 The problem with sequence events reported previously turned out to be problems
 344 in both the test and in the Notification Service itself.  These problems
 345 have been resolved.  It is now possible to mix and match consumers and
 346 suppliers.
 347
 348 There are no new known problems.
 349
 350 [----------------------------------------------------------------------------]
 351