TAO/orbsvcs/tests/Simple_Naming/README

   1
   2
   3 This application tests different features of TAO's Naming Service.
   4
   5 To run all tests automatically -
   6         execute Perl script run_test.pl
   7
   8 To run tests manually -
   9         start the Naming Service (see
  10         TAO/orbsvcs/Naming_Service/README for valid options),
  11         then run ./client with one of the options below.
  12
  13 NOTE: if running tests manually, Naming Service has to be restarted
  14 before each test (this is due to some tests not 'cleaning up' bindings
  15 after themselves).
  16
  17 The following options exist:
  18 ---------------------------
  19 -s      Run the Simple test of the Naming Service.
  20
  21 -t      Run the Tree test of the Naming Service.
  22
  23 -e      Run the Exceptions test of the Naming Service
  24
  25 -i      Run the Iterator test of the Naming Service.
  26
  27 -y      Run the Destroy test of the Naming Service.
  28
  29 -m <n>  Run the Multi-Threaded test of the Naming Service (multiple
  30         client threads).  Requires integer argument specifying number
  31         of thread to spawn.  (If running this test manually, its
  32         output should be redirected to some file, say, "foo".  Then,
  33         "process-m-output.pl" script can be used to analyze the test
  34         output and print out a diagnostic message.  Invoke the output
  35         processing script like so:
  36         "process-m-output.pl foo number_of_threads",
  37         where <foo> is the name of the file containing test output,
  38         and <number_of_threads> is the argument that was supplied with
  39         "-m" option  to the client.)
  40
  41         Example (on a Unix system):
  42         $ ../../Naming_Service &
  43         $ ./client -m 10 >& foo
  44         $ ./process-m-output.pl foo 10
  45
  46         where the steps correspond to 1)starting the Naming Service,
  47         2) running the client and redirecting the output to a file,
  48         and 3) running the diagnostic script.
  49         Don't forget to kill the Naming Service after you are done.
  50
  51 Persistent test consists of two parts (below).
  52
  53 -p <file_name>
  54         Run the Persistent Naming Service test, part 1.  Requires an
  55         argument specifying the name of the file in which to store an ior for
  56         use by Persistent Naming Service test, part 2.  Note, in order
  57         to test out persistent capabilities of the Naming Service, the
  58         Naming Service must be started with -f and -ORBendpoint options.
  59         The values for these options must be the same for both runs of
  60         the Naming Service (i.e., for part 1 and part 2 of persistent test).
  61
  62 -c <ior>
  63         Run the Persistent Naming Service test, part 2.  Requires an
  64         argument specifying the ior, which was produced in part 1 of
  65         the test.  Note, in order to test out persistent capabilities
  66         of the Naming Service, the Naming Service must be started with
  67         -f and -ORBendpoint options.  The values for these options
  68         must remain the same for both runs of the Naming Service (i.e.,
  69         for part 1 and part 2 of persistent test).
  70
  71         Example of testing persistence on a Unix system:
  72         $ ../../Naming_Service -f log -ORBendpoint iiop://localhost:20000
  73         $ ./client -p ior_file
  74         kill the Naming_Service process
  75         $ ../../Naming_Service -f log -ORBendpoint iiop://localhost:20000
  76         $ ./client -c file://ior_file
  77
  78         where the steps correspond to 1)starting the Naming Service on
  79         port 20000 in persistent mode, with persistent state being
  80         stored in file called "log", 2) running the first part of the
  81         client persistent naming test, and sending its data to file
  82         called "ior_file", 3) killing the Naming Service process, 4)
  83         restarting the Naming Service on the same port with the same
  84         persistent state storage file, and 5) running the second part
  85         of the client persistence test by specifying the ior from part
  86         1 in the file format.
  87
  88         We kill the Naming Service process between 2 client runs to
  89         make sure it can recreate its state from persistent storage.
  90         It is necessary to restart the Naming Service on the same
  91         host/port in order for the persistent IORs from the first
  92         run to be valid for the second run.
  93
  94 If no option is specified, Simple test is run.  If more than one
  95 option is specified, only one test runs.
  96
  97
  98 DESCRIPTION AND EXPECTED OUTPUT FOR EACH TEST
  99 *******************************************
 100
 101 Simple Test.
 102
 103 Performs bind (), resolve (), and unbind () of an object reference in
 104 the root context.
 105
 106 Expected Output:
 107
 108 Bound name OK
 109 Resolved name OK
 110 Unbound name OK
 111
 112 ********************************************
 113
 114 MT Test.
 115
 116 Spawns a specified number of threads.  Threads concurrently attempt to
 117 bind (), resolve (), and unbind () the object reference.
 118
 119 Expected Output (produced by the output processing script):
 120
 121 Multithreaded output is ok
 122
 123 The output of the actual test varies from run to run, due to the
 124 variation in the thread scheduling.  Correct output must have the
 125 following properties (these are the properties that the processing
 126 script checks for):
 127 1) number of bind () calls = number of resolve () calls = number of
 128 unbind () calls = number of threads specified for the test
 129 2) number of successful bind () calls = number of successful unbind () calls.
 130
 131 *******************************************
 132
 133 Tree Test.
 134
 135 Checks all Naming Service functions with a tree of Naming Contexts.
 136
 137 root->bind_new_context (level1)
 138
 139 new = root->new_context (), new->bind (foo, obj), and
 140   root->bind_context (level1/level2, new)
 141
 142 We now have root->level1->level2->foo
 143
 144 root->resolve (level1/level2/foo).
 145 root->unbind (level1/level2/foo).
 146 root->bind (level1/level2/foo, obj).
 147
 148 new = root->new_context()
 149 root->rebind_context(level1/level2, new)
 150
 151 root->bind (level1/level2/foo obj)
 152 root->resolve (level1/level2/foo)
 153 root->rebind (level1/level2/foo, obj2) to have a different object under the name bar.
 154 root->resolve (level1/level2/foo) to make sure correct reference is returned.
 155
 156
 157 Expected Output:
 158
 159 All functions work properly
 160 ********************************************
 161
 162 Exceptions Test.
 163
 164 Makes sure that Naming Service throws exceptions as expected, and data
 165 inside exceptions is set correctly.
 166
 167 Create a tree of Naming Contexts: root context -> level1 -> level2.
 168
 169 Bind an object with the name foo into each of the Naming Contexts.
 170
 171 root->resolve () (with a Name of length 0) - should get InvalidName exception.
 172 root->bind (foo, obj) - should get AlreadyBound exception.
 173 root->bind (level1/foo, obj) - should get AlreadyBound exception.
 174 root->unbind (level1/level2/bar) - should get NotFound exception
 175   with why = missing_node, rest_of_name = bar.
 176 root->unbind (level1/level3/foo) - should get NotFound exception
 177   with why = missing_node, rest_of_name = level3/foo.
 178 root->unbind (level1/foo/foo) -should get NotFound exception
 179   with why = not_context, rest_of_name = foo/foo.
 180
 181
 182 Expected Output:
 183
 184 AlreadyBound exception (case 1) works properly
 185 AlreadyBound  exception (case 2) works properly
 186 NotFound  exception (case 1) works properly
 187 NotFound  exception (case 2) works properly
 188 NotFound  exception (case 3) works properly
 189
 190 *********************************************
 191
 192 Iterator Test.
 193
 194 Checks iterator functions.
 195
 196 Bind () objects with the following names foo1, foo2, foo3, and foo4
 197 into the root Naming Context.
 198
 199 root->lists (1, bl, iter)
 200 iter->next_one ()
 201 iter->next_n (2, bl)
 202 iter->next_one () - should return false
 203 iter->destroy ()
 204
 205
 206 Expected Output:
 207
 208 First binding: foo1
 209 Second binding: foo2
 210 Third binding: foo3
 211 Fourth binding: foo4
 212
 213 *********************************************
 214
 215 Destroy Test.
 216
 217 Makes sure destroy method is working properly.
 218
 219 Create a context and bind an object under it.
 220 Attempt to destroy the context - NotEmpty exception should be raised.
 221
 222 Unbind the object and call destroy on the context.
 223 Attempt to call destroy on the object again - OBJECT_NOT_EXIST
 224 exception should be raised.
 225
 226
 227 Expected Output:
 228
 229 NotEmpty exception works properly
 230 Destroy works properly
 231
 232 ********************************************
 233
 234 Persistent Test (part 1).
 235
 236 Makes sure persistence mode of the Naming Service functions properly:
 237 this test sets things up for part 2
 238
 239 Creates the Naming Context hierarchy:
 240 root -> level1_context -> level2_context,
 241 and prints out the ior of the <level1_context> to the specified file.
 242
 243
 244 Expected Output:
 245
 246 Persistent Naming test (part 1) OK.
 247
 248 ********************************************
 249 Persistent Test (part 2).
 250
 251 Makes sure persistence mode of the Naming Service functions properly.
 252
 253 Attempts to resolve <level2_context> both through the ior obtained
 254 from part 1 of the test, and through the Naming Context obtained from
 255 <resolve_initial_references>.  Compares the results of both resolve ()
 256 calls.
 257
 258 Expected Output:
 259
 260 Persistent Naming test (part 2) OK.
 261
 262 ********************************************