annotate src/bsd/doc/man/tnameserv.1 @ 2640:9282f04c3555

. Make changes to the BSD man pages identical to those made to the Linux man pages.
author Greg Lewis <glewis@eyesbeyond.com>
date Sat, 17 Jul 2010 18:02:36 -0700
parents 8356c7fa1a33
children 2d3bbea20640
rev   line source
glewis@2640 1 ." Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
mr@489 2 ." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
mr@489 3 ."
mr@489 4 ." This code is free software; you can redistribute it and/or modify it
mr@489 5 ." under the terms of the GNU General Public License version 2 only, as
mr@489 6 ." published by the Free Software Foundation.
mr@489 7 ."
mr@489 8 ." This code is distributed in the hope that it will be useful, but WITHOUT
mr@489 9 ." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
mr@489 10 ." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
mr@489 11 ." version 2 for more details (a copy is included in the LICENSE file that
mr@489 12 ." accompanied this code).
mr@489 13 ."
mr@489 14 ." You should have received a copy of the GNU General Public License version
mr@489 15 ." 2 along with this work; if not, write to the Free Software Foundation,
mr@489 16 ." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
mr@489 17 ."
glewis@2552 18 ." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
glewis@2552 19 ." or visit www.oracle.com if you need additional information or have any
glewis@2552 20 ." questions.
mr@489 21 ."
glewis@2640 22 .TH tnameserv 1 "02 Jun 2010"
mr@489 23
mr@489 24 .LP
kurt@1245 25 .SH "Name"
mr@489 26 Java IDL: Transient Naming Service \- \f2tnameserv\fP
mr@489 27 .LP
mr@489 28 .LP
kurt@1245 29 This document discusses using the Java IDL Transient Naming Service, \f2tnameserv\fP. Java IDL also includes the Object Request Broker Daemon (ORBD). ORBD is a daemon process containing a Bootstrap Service, a Transient Naming Service, a \f3Persistent\fP Naming Service, and a Server Manager. The Java IDL tutorials all use ORBD, however, you can substitute \f2tnameserv\fP for \f2orbd\fP in any of the examples that use a Transient Naming Service. For documentation on the \f2orbd\fP tool, link to its orbd(1) or the
mr@489 30 .na
mr@489 31 \f2Java IDL Naming Service Included with ORBD\fP @
mr@489 32 .fi
mr@489 33 http://java.sun.com/javase/6/docs/technotes/guides/idl/jidlNaming.html topic.
mr@489 34 .LP
mr@489 35 .LP
mr@489 36 Topics in this section include:
mr@489 37 .LP
mr@489 38 .RS 3
mr@489 39 .TP 2
mr@489 40 o
mr@489 41 Java\ IDL Transient Naming Service
mr@489 42 .TP 2
mr@489 43 o
mr@489 44 Starting the Java\ IDL Transient Naming Service
mr@489 45 .TP 2
mr@489 46 o
mr@489 47 Stopping the Java\ IDL Transient Naming Service
mr@489 48 .TP 2
mr@489 49 o
mr@489 50 Sample Client: Adding Objects to the Namespace
mr@489 51 .TP 2
mr@489 52 o
mr@489 53 Sample Client: Browsing the Namespace
mr@489 54 .RE
mr@489 55
mr@489 56 .LP
mr@489 57 .SH "Java\ IDL Transient Naming Service"
mr@489 58 .LP
mr@489 59 .LP
mr@489 60 The CORBA COS (Common Object Services) Naming Service provides a tree\-like directory for object references much like a filesystem provides a directory structure for files. The Transient Naming Service provided with Java IDL, \f2tnameserv\fP, is a simple implementation of the COS Naming Service specification.
mr@489 61 .LP
mr@489 62 .LP
mr@489 63 Object references are stored in the namespace by name and each object reference\-name pair is called a name \f2binding\fP. Name bindings may be organized under \f2naming contexts\fP. Naming contexts are themselves name bindings and serve the same organizational function as a file system subdirectory. All bindings are stored under the \f2initial naming context\fP. The initial naming context is the only persistent binding in the namespace; the rest of the namespace is lost if the Java IDL naming service process halts and restarts.
mr@489 64 .LP
mr@489 65 .LP
mr@489 66 For an applet or application to use COS naming, its ORB must know the port of a host running a naming service or have access to a stringified initial naming context for that naming service. The naming service can either be the Java\ IDL naming service or another COS\-compliant naming service.
mr@489 67 .LP
mr@489 68 .SH "Starting the Java\ IDL Transient Naming Service"
mr@489 69 .LP
mr@489 70 .LP
mr@489 71 You must start the Java\ IDL naming service before an application or applet that uses its naming service. Installation of the Java\ IDL product creates a script (Solaris: \f2tnameserv\fP) or executable file (Windows NT: \f2tnameserv.exe\fP) that starts the Java\ IDL naming service. Start the naming service so it runs in the background.
mr@489 72 .LP
mr@489 73 .LP
mr@489 74 If you do not specify otherwise, the Java\ IDL naming service listens on port 900 for the bootstrap protocol used to implement the ORB \f2resolve_initial_references()\fP and \f2list_initial_references()\fP methods, as follows:
mr@489 75 .LP
mr@489 76 .nf
mr@489 77 \f3
mr@489 78 .fl
mr@489 79 tnameserv \-ORBInitialPort \fP\f4nameserverport\fP\f3&
mr@489 80 .fl
mr@489 81 \fP
mr@489 82 .fi
mr@489 83
mr@489 84 .LP
mr@489 85 .LP
mr@489 86 If you do not specify the name server port, port 900 is used by default. When running Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. To specify a different port, for example, 1050, and to run the naming service in the background, from a UNIX command shell, enter:
mr@489 87 .LP
mr@489 88 .nf
mr@489 89 \f3
mr@489 90 .fl
mr@489 91 tnameserv \-ORBInitialPort 1050&
mr@489 92 .fl
mr@489 93 \fP
mr@489 94 .fi
mr@489 95
mr@489 96 .LP
mr@489 97 .LP
mr@489 98 From an MS\-DOS system prompt (Windows), enter:
mr@489 99 .LP
mr@489 100 .nf
mr@489 101 \f3
mr@489 102 .fl
mr@489 103 start tnameserv \-ORBInitialPort 1050
mr@489 104 .fl
mr@489 105 \fP
mr@489 106 .fi
mr@489 107
mr@489 108 .LP
mr@489 109 .LP
mr@489 110 Clients of the name server must be made aware of the new port number. Do this by setting the \f2org.omg.CORBA.ORBInitialPort\fP property to the new port number when creating the ORB object.
mr@489 111 .LP
mr@489 112 .SS
mr@489 113 Running the server and client on different hosts
mr@489 114 .LP
mr@489 115 .LP
mr@489 116 In most of the Java IDL and RMI\-IIOP tutorials, the Naming Service, Server, and Client are all running on the development machine. In real world deployment, it is likely that the client and server will run on different host machines than the Naming Service.
mr@489 117 .LP
mr@489 118 .LP
mr@489 119 For the client and server to find the Naming Service, they must be made aware of the port number and host on which the naming service is running. Do this by setting the \f2org.omg.CORBA.ORBInitialPort\fP and \f2org.omg.CORBA.ORBInitialHost\fP properties in the client and server files to the machine name and port number on which the Naming Service is running. An example of this is shown in
mr@489 120 .na
mr@489 121 \f2The Hello World Example Using RMI\-IIOP\fP @
mr@489 122 .fi
mr@489 123 http://java.sun.com/javase/6/docs/technotes/guides/rmi\-iiop/rmiiiopexample.html. You could also use the command line options \f2\-ORBInitialPort\fP \f2nameserverport#\fP and \f2\-ORBInitialHost\fP \f2nameserverhostname\fP to tell the client and server where to find the Naming Service.
mr@489 124 .na
mr@489 125 \f2Java IDL: Running the Hello World Example on TWO Machines\fP @
mr@489 126 .fi
mr@489 127 http://java.sun.com/javase/6/docs/technotes/guides/idl/tutorial/jidl2machines.html shows one way of doing this using the command line option.
mr@489 128 .LP
mr@489 129 .LP
mr@489 130 For example, suppose the Transient Naming Service, \f2tnameserv\fP is running on port 1050 on host \f2nameserverhost\fP. The client is running on host \f2clienthost\fP and the server is running on host \f2serverhost\fP.
mr@489 131 .LP
mr@489 132 .RS 3
mr@489 133 .TP 2
mr@489 134 o
mr@489 135 Start \f2tnameserv\fP on the host \f2nameserverhost\fP, as follows:
mr@489 136 .nf
mr@489 137 \f3
mr@489 138 .fl
mr@489 139 tnameserv \-ORBInitialPort 1050
mr@489 140 .fl
mr@489 141
mr@489 142 .fl
mr@489 143 \fP
mr@489 144 .fi
mr@489 145 .TP 2
mr@489 146 o
mr@489 147 Start the server on the \f2serverhost\fP, as follows:
mr@489 148 .nf
mr@489 149 \f3
mr@489 150 .fl
mr@489 151 java Server \-ORBInitialPort 1050 \-ORBInitialHost nameserverhost
mr@489 152 .fl
mr@489 153 \fP
mr@489 154 .fi
mr@489 155 .TP 2
mr@489 156 o
mr@489 157 Start the client on the \f2clienthost\fP, as follows:
mr@489 158 .nf
mr@489 159 \f3
mr@489 160 .fl
mr@489 161 java Client \-ORBInitialPort 1050 \-ORBInitialHost nameserverhost
mr@489 162 .fl
mr@489 163 \fP
mr@489 164 .fi
mr@489 165 .RE
mr@489 166
mr@489 167 .LP
mr@489 168 .SS
mr@489 169 The \-J option
mr@489 170 .LP
mr@489 171 This command\-line option is available for use with \f2tnameserve\fP:
mr@489 172 .RS 3
mr@489 173
mr@489 174 .LP
kurt@1245 175 .RS 3
mr@489 176 .TP 3
mr@489 177 \-Joption
kurt@1245 178 Pass \f2option\fP to the Java virtual machine, where \f2option\fP is one of the options described on the reference page for java(1). For example, \f3\-J\-Xms48m\fP sets the startup memory to 48 megabytes. It is a common convention for \f3\-J\fP to pass options to the underlying virtual machine.
kurt@1245 179 .RE
kurt@1245 180
mr@489 181 .LP
mr@489 182 .RE
mr@489 183 .SH "Stopping the Java\ IDL Transient Naming Service"
mr@489 184 .LP
mr@489 185 .LP
mr@489 186 To stop the Java\ IDL naming service, use the relevant operating system command, such as \f2kill\fP for a Unix process, or \f2Ctrl\-C\fP for a Windows process. The naming service will continue to wait for invocations until it is explicitly shutdown. Note that names registered with the Java\ IDL naming service disappear when the service is terminated.
mr@489 187 .LP
mr@489 188 .SH "Sample Client: Adding Objects to the Namespace"
mr@489 189 .LP
mr@489 190 .LP
mr@489 191 The following sample program illustrates how to add names to the namespace. It is a self\-contained Transient Naming Service client that creates the following simple tree.
mr@489 192 .LP
mr@489 193 .nf
mr@489 194 \f3
mr@489 195 .fl
mr@489 196 \fP\f3
mr@489 197 .fl
mr@489 198 \fP\f4Initial\fP\f3
mr@489 199 .fl
mr@489 200 \fP\f4Naming Context\fP\f3
mr@489 201 .fl
kurt@1245 202 / \\
mr@489 203 .fl
kurt@1245 204 / \\
mr@489 205 .fl
mr@489 206 plans \fP\f4Personal\fP\f3
mr@489 207 .fl
kurt@1245 208 / \\
mr@489 209 .fl
kurt@1245 210 / \\
mr@489 211 .fl
mr@489 212 calendar schedule\fP
mr@489 213 .fl
mr@489 214 .fi
mr@489 215
mr@489 216 .LP
mr@489 217 .LP
mr@489 218 In this example, \f3plans\fP is an object reference and \f3Personal\fP is a naming context that contains two object references: \f3calendar\fP and \f3schedule\fP.
mr@489 219 .LP
mr@489 220 .nf
mr@489 221 \f3
mr@489 222 .fl
mr@489 223 import java.util.Properties;
mr@489 224 .fl
mr@489 225 import org.omg.CORBA.*;
mr@489 226 .fl
mr@489 227 import org.omg.CosNaming.*;
mr@489 228 .fl
mr@489 229
mr@489 230 .fl
mr@489 231 public class NameClient
mr@489 232 .fl
mr@489 233 {
mr@489 234 .fl
mr@489 235 public static void main(String args[])
mr@489 236 .fl
mr@489 237 {
mr@489 238 .fl
mr@489 239 try {
mr@489 240 .fl
mr@489 241 \fP
mr@489 242 .fi
mr@489 243
mr@489 244 .LP
mr@489 245 In the above section, Starting the Java IDL Transient Naming Service, the nameserver was started on port 1050. The following code ensures that the client program is aware of this port number.
mr@489 246 .nf
mr@489 247 \f3
mr@489 248 .fl
mr@489 249 Properties props = new Properties();
mr@489 250 .fl
mr@489 251 props.put("org.omg.CORBA.ORBInitialPort", "1050");
mr@489 252 .fl
mr@489 253 ORB orb = ORB.init(args, props);
mr@489 254 .fl
mr@489 255
mr@489 256 .fl
mr@489 257 \fP
mr@489 258 .fi
mr@489 259
mr@489 260 .LP
mr@489 261 This code obtains the initial naming context and assigns it to \f3ctx\fP. The second line copies \f3ctx\fP into a dummy object reference \f3objref\fP that we'll attach to various names and add into the namespace.
mr@489 262 .nf
mr@489 263 \f3
mr@489 264 .fl
mr@489 265 NamingContext ctx =
mr@489 266 .fl
mr@489 267 NamingContextHelper.narrow(orb.resolve_initial_references("NameService"));
mr@489 268 .fl
mr@489 269 NamingContext objref = ctx;
mr@489 270 .fl
mr@489 271
mr@489 272 .fl
mr@489 273 \fP
mr@489 274 .fi
mr@489 275
mr@489 276 .LP
mr@489 277 This code creates a name "plans" of type "text" and binds it to our dummy object reference. "plans" is then added under the initial naming context using \f2rebind\fP. The \f2rebind\fP method allows us to run this program over and over again without getting the exceptions we'd get from using \f2bind\fP.
mr@489 278 .nf
mr@489 279 \f3
mr@489 280 .fl
mr@489 281 NameComponent nc1 = new NameComponent("plans", "text");
mr@489 282 .fl
mr@489 283 NameComponent[] name1 = {nc1};
mr@489 284 .fl
mr@489 285 ctx.rebind(name1, objref);
mr@489 286 .fl
mr@489 287 System.out.println("plans rebind sucessful!");
mr@489 288 .fl
mr@489 289
mr@489 290 .fl
mr@489 291 \fP
mr@489 292 .fi
mr@489 293
mr@489 294 .LP
mr@489 295 This code creates a naming context called "Personal" of type "directory". The resulting object reference, \f3ctx2\fP, is bound to the name and added under the initial naming context.
mr@489 296 .nf
mr@489 297 \f3
mr@489 298 .fl
mr@489 299 NameComponent nc2 = new NameComponent("Personal", "directory");
mr@489 300 .fl
mr@489 301 NameComponent[] name2 = {nc2};
mr@489 302 .fl
mr@489 303 NamingContext ctx2 = ctx.bind_new_context(name2);
mr@489 304 .fl
mr@489 305 System.out.println("new naming context added..");
mr@489 306 .fl
mr@489 307
mr@489 308 .fl
mr@489 309 \fP
mr@489 310 .fi
mr@489 311
mr@489 312 .LP
mr@489 313 The remainder of the code binds the dummy object reference using the names "schedule" and "calendar" under the "Personal" naming context (\f3ctx2\fP).
mr@489 314 .nf
mr@489 315 \f3
mr@489 316 .fl
mr@489 317 NameComponent nc3 = new NameComponent("schedule", "text");
mr@489 318 .fl
mr@489 319 NameComponent[] name3 = {nc3};
mr@489 320 .fl
mr@489 321 ctx2.rebind(name3, objref);
mr@489 322 .fl
mr@489 323 System.out.println("schedule rebind sucessful!");
mr@489 324 .fl
mr@489 325
mr@489 326 .fl
mr@489 327 NameComponent nc4 = new NameComponent("calender", "text");
mr@489 328 .fl
mr@489 329 NameComponent[] name4 = {nc4};
mr@489 330 .fl
mr@489 331 ctx2.rebind(name4, objref);
mr@489 332 .fl
mr@489 333 System.out.println("calender rebind sucessful!");
mr@489 334 .fl
mr@489 335
mr@489 336 .fl
mr@489 337
mr@489 338 .fl
mr@489 339 } catch (Exception e) {
mr@489 340 .fl
mr@489 341 e.printStackTrace(System.err);
mr@489 342 .fl
mr@489 343 }
mr@489 344 .fl
mr@489 345 }
mr@489 346 .fl
mr@489 347 }
mr@489 348 .fl
mr@489 349 \fP
mr@489 350 .fi
mr@489 351
mr@489 352 .LP
mr@489 353 .SH "Sample Client: Browsing the Namespace"
mr@489 354 .LP
mr@489 355 .LP
mr@489 356 The following sample program illustrates how to browse the namespace.
mr@489 357 .LP
mr@489 358 .nf
mr@489 359 \f3
mr@489 360 .fl
mr@489 361 import java.util.Properties;
mr@489 362 .fl
mr@489 363 import org.omg.CORBA.*;
mr@489 364 .fl
mr@489 365 import org.omg.CosNaming.*;
mr@489 366 .fl
mr@489 367
mr@489 368 .fl
mr@489 369 public class NameClientList
mr@489 370 .fl
mr@489 371 {
mr@489 372 .fl
mr@489 373 public static void main(String args[])
mr@489 374 .fl
mr@489 375 {
mr@489 376 .fl
mr@489 377 try {
mr@489 378 .fl
mr@489 379 \fP
mr@489 380 .fi
mr@489 381
mr@489 382 .LP
mr@489 383 In the above section, Starting the Java IDL Transient Naming Service, the nameserver was started on port 1050. The following code ensures that the client program is aware of this port number.
mr@489 384 .nf
mr@489 385 \f3
mr@489 386 .fl
mr@489 387
mr@489 388 .fl
mr@489 389 Properties props = new Properties();
mr@489 390 .fl
mr@489 391 props.put("org.omg.CORBA.ORBInitialPort", "1050");
mr@489 392 .fl
mr@489 393 ORB orb = ORB.init(args, props);
mr@489 394 .fl
mr@489 395
mr@489 396 .fl
mr@489 397
mr@489 398 .fl
mr@489 399 \fP
mr@489 400 .fi
mr@489 401
mr@489 402 .LP
mr@489 403 The following code obtains the intial naming context.
mr@489 404 .nf
mr@489 405 \f3
mr@489 406 .fl
mr@489 407 NamingContext nc =
mr@489 408 .fl
mr@489 409 NamingContextHelper.narrow(orb.resolve_initial_references("NameService"));
mr@489 410 .fl
mr@489 411
mr@489 412 .fl
mr@489 413 \fP
mr@489 414 .fi
mr@489 415
mr@489 416 .LP
mr@489 417 The \f2list\fP method lists the bindings in the naming context. In this case, up to 1000 bindings from the initial naming context will be returned in the BindingListHolder; any remaining bindings are returned in the BindingIteratorHolder.
mr@489 418 .nf
mr@489 419 \f3
mr@489 420 .fl
mr@489 421 BindingListHolder bl = new BindingListHolder();
mr@489 422 .fl
mr@489 423 BindingIteratorHolder blIt= new BindingIteratorHolder();
mr@489 424 .fl
mr@489 425 nc.list(1000, bl, blIt);
mr@489 426 .fl
mr@489 427
mr@489 428 .fl
mr@489 429 \fP
mr@489 430 .fi
mr@489 431
mr@489 432 .LP
mr@489 433 This code gets the array of bindings out of the returned BindingListHolder. If there are no bindings, the program ends.
mr@489 434 .nf
mr@489 435 \f3
mr@489 436 .fl
mr@489 437 Binding bindings[] = bl.value;
mr@489 438 .fl
mr@489 439 if (bindings.length == 0) return;
mr@489 440 .fl
mr@489 441
mr@489 442 .fl
mr@489 443 \fP
mr@489 444 .fi
mr@489 445
mr@489 446 .LP
mr@489 447 The remainder of the code loops through the bindings and prints the names out.
mr@489 448 .nf
mr@489 449 \f3
mr@489 450 .fl
mr@489 451 for (int i=0; i < bindings.length; i++) {
mr@489 452 .fl
mr@489 453
mr@489 454 .fl
mr@489 455 // get the object reference for each binding
mr@489 456 .fl
mr@489 457 org.omg.CORBA.Object obj = nc.resolve(bindings[i].binding_name);
mr@489 458 .fl
mr@489 459 String objStr = orb.object_to_string(obj);
mr@489 460 .fl
mr@489 461 int lastIx = bindings[i].binding_name.length\-1;
mr@489 462 .fl
mr@489 463
mr@489 464 .fl
mr@489 465 // check to see if this is a naming context
mr@489 466 .fl
mr@489 467 if (bindings[i].binding_type == BindingType.ncontext) {
mr@489 468 .fl
mr@489 469 System.out.println( "Context: " +
mr@489 470 .fl
mr@489 471 bindings[i].binding_name[lastIx].id);
mr@489 472 .fl
mr@489 473 } else {
mr@489 474 .fl
mr@489 475 System.out.println("Object: " +
mr@489 476 .fl
mr@489 477 bindings[i].binding_name[lastIx].id);
mr@489 478 .fl
mr@489 479 }
mr@489 480 .fl
mr@489 481 }
mr@489 482 .fl
mr@489 483
mr@489 484 .fl
mr@489 485 } catch (Exception e) {
mr@489 486 .fl
mr@489 487 e.printStackTrace(System.err);
mr@489 488 .fl
mr@489 489 }
mr@489 490 .fl
mr@489 491 }
mr@489 492 .fl
mr@489 493 }
mr@489 494 .fl
mr@489 495 \fP
mr@489 496 .fi
mr@489 497
mr@489 498 .LP
mr@489 499