|
1 .'" t |
|
2 ." |
|
3 ." Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. |
|
4 ." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
5 ." |
|
6 ." This code is free software; you can redistribute it and/or modify it |
|
7 ." under the terms of the GNU General Public License version 2 only, as |
|
8 ." published by the Free Software Foundation. |
|
9 ." |
|
10 ." This code is distributed in the hope that it will be useful, but WITHOUT |
|
11 ." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
12 ." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
13 ." version 2 for more details (a copy is included in the LICENSE file that |
|
14 ." accompanied this code). |
|
15 ." |
|
16 ." You should have received a copy of the GNU General Public License version |
|
17 ." 2 along with this work; if not, write to the Free Software Foundation, |
|
18 ." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
19 ." |
|
20 ." Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
21 ." CA 95054 USA or visit www.sun.com if you need additional information or |
|
22 ." have any questions. |
|
23 ." |
|
24 ." ` |
|
25 .TH tnameserv 1 "06 Aug 2006" |
|
26 ." Generated by html2man |
|
27 |
|
28 .LP |
|
29 .SH NAME |
|
30 Java IDL: Transient Naming Service \- \f2tnameserv\fP |
|
31 .LP |
|
32 |
|
33 .LP |
|
34 .LP |
|
35 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 man page or the |
|
36 .na |
|
37 \f2Java IDL Naming Service Included with ORBD\fP @ |
|
38 .fi |
|
39 http://java.sun.com/javase/6/docs/technotes/guides/idl/jidlNaming.html topic. |
|
40 .LP |
|
41 .LP |
|
42 Topics in this section include: |
|
43 .LP |
|
44 .RS 3 |
|
45 .TP 2 |
|
46 o |
|
47 Java\ IDL Transient Naming Service |
|
48 .TP 2 |
|
49 o |
|
50 Starting the Java\ IDL Transient Naming Service |
|
51 .TP 2 |
|
52 o |
|
53 Stopping the Java\ IDL Transient Naming Service |
|
54 .TP 2 |
|
55 o |
|
56 Sample Client: Adding Objects to the Namespace |
|
57 .TP 2 |
|
58 o |
|
59 Sample Client: Browsing the Namespace |
|
60 .RE |
|
61 |
|
62 .LP |
|
63 .SH "Java\ IDL Transient Naming Service" |
|
64 .LP |
|
65 .LP |
|
66 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. |
|
67 .LP |
|
68 .LP |
|
69 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. |
|
70 .LP |
|
71 .LP |
|
72 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. |
|
73 .LP |
|
74 .SH "Starting the Java\ IDL Transient Naming Service" |
|
75 .LP |
|
76 .LP |
|
77 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. |
|
78 .LP |
|
79 .LP |
|
80 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: |
|
81 .LP |
|
82 .nf |
|
83 \f3 |
|
84 .fl |
|
85 tnameserv \-ORBInitialPort \fP\f4nameserverport\fP\f3& |
|
86 .fl |
|
87 \fP |
|
88 .fi |
|
89 |
|
90 .LP |
|
91 .LP |
|
92 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: |
|
93 .LP |
|
94 .nf |
|
95 \f3 |
|
96 .fl |
|
97 tnameserv \-ORBInitialPort 1050& |
|
98 .fl |
|
99 \fP |
|
100 .fi |
|
101 |
|
102 .LP |
|
103 .LP |
|
104 From an MS\-DOS system prompt (Windows), enter: |
|
105 .LP |
|
106 .nf |
|
107 \f3 |
|
108 .fl |
|
109 start tnameserv \-ORBInitialPort 1050 |
|
110 .fl |
|
111 \fP |
|
112 .fi |
|
113 |
|
114 .LP |
|
115 .LP |
|
116 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. |
|
117 .LP |
|
118 .SS |
|
119 Running the server and client on different hosts |
|
120 .LP |
|
121 .LP |
|
122 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. |
|
123 .LP |
|
124 .LP |
|
125 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 |
|
126 .na |
|
127 \f2The Hello World Example Using RMI\-IIOP\fP @ |
|
128 .fi |
|
129 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. |
|
130 .na |
|
131 \f2Java IDL: Running the Hello World Example on TWO Machines\fP @ |
|
132 .fi |
|
133 http://java.sun.com/javase/6/docs/technotes/guides/idl/tutorial/jidl2machines.html shows one way of doing this using the command line option. |
|
134 .LP |
|
135 .LP |
|
136 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. |
|
137 .LP |
|
138 .RS 3 |
|
139 .TP 2 |
|
140 o |
|
141 Start \f2tnameserv\fP on the host \f2nameserverhost\fP, as follows: |
|
142 .nf |
|
143 \f3 |
|
144 .fl |
|
145 tnameserv \-ORBInitialPort 1050 |
|
146 .fl |
|
147 |
|
148 .fl |
|
149 \fP |
|
150 .fi |
|
151 .TP 2 |
|
152 o |
|
153 Start the server on the \f2serverhost\fP, as follows: |
|
154 .nf |
|
155 \f3 |
|
156 .fl |
|
157 java Server \-ORBInitialPort 1050 \-ORBInitialHost nameserverhost |
|
158 .fl |
|
159 \fP |
|
160 .fi |
|
161 .TP 2 |
|
162 o |
|
163 Start the client on the \f2clienthost\fP, as follows: |
|
164 .nf |
|
165 \f3 |
|
166 .fl |
|
167 java Client \-ORBInitialPort 1050 \-ORBInitialHost nameserverhost |
|
168 .fl |
|
169 \fP |
|
170 .fi |
|
171 .RE |
|
172 |
|
173 .LP |
|
174 .SS |
|
175 The \-J option |
|
176 .LP |
|
177 This command\-line option is available for use with \f2tnameserve\fP: |
|
178 .RS 3 |
|
179 |
|
180 .LP |
|
181 .TP 3 |
|
182 \-Joption |
|
183 Pass \f2option\fP to the Java virtual machine, where \f2option\fP is one of the options described on the reference page for the |
|
184 .na |
|
185 \f2java application launcher\fP @ |
|
186 .fi |
|
187 http://java.sun.com/javase/6/docs/technotes/tools/solaris/java.html. 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. |
|
188 .LP |
|
189 .RE |
|
190 .SH "Stopping the Java\ IDL Transient Naming Service" |
|
191 .LP |
|
192 .LP |
|
193 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. |
|
194 .LP |
|
195 .SH "Sample Client: Adding Objects to the Namespace" |
|
196 .LP |
|
197 .LP |
|
198 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. |
|
199 .LP |
|
200 .nf |
|
201 \f3 |
|
202 .fl |
|
203 \fP\f3 |
|
204 .fl |
|
205 \fP\f4Initial\fP\f3 |
|
206 .fl |
|
207 \fP\f4Naming Context\fP\f3 |
|
208 .fl |
|
209 / \\ |
|
210 .fl |
|
211 / \\ |
|
212 .fl |
|
213 plans \fP\f4Personal\fP\f3 |
|
214 .fl |
|
215 / \\ |
|
216 .fl |
|
217 / \\ |
|
218 .fl |
|
219 calendar schedule\fP |
|
220 .fl |
|
221 .fi |
|
222 |
|
223 .LP |
|
224 .LP |
|
225 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. |
|
226 .LP |
|
227 .nf |
|
228 \f3 |
|
229 .fl |
|
230 import java.util.Properties; |
|
231 .fl |
|
232 import org.omg.CORBA.*; |
|
233 .fl |
|
234 import org.omg.CosNaming.*; |
|
235 .fl |
|
236 |
|
237 .fl |
|
238 public class NameClient |
|
239 .fl |
|
240 { |
|
241 .fl |
|
242 public static void main(String args[]) |
|
243 .fl |
|
244 { |
|
245 .fl |
|
246 try { |
|
247 .fl |
|
248 \fP |
|
249 .fi |
|
250 |
|
251 .LP |
|
252 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. |
|
253 .nf |
|
254 \f3 |
|
255 .fl |
|
256 Properties props = new Properties(); |
|
257 .fl |
|
258 props.put("org.omg.CORBA.ORBInitialPort", "1050"); |
|
259 .fl |
|
260 ORB orb = ORB.init(args, props); |
|
261 .fl |
|
262 |
|
263 .fl |
|
264 \fP |
|
265 .fi |
|
266 |
|
267 .LP |
|
268 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. |
|
269 .nf |
|
270 \f3 |
|
271 .fl |
|
272 NamingContext ctx = |
|
273 .fl |
|
274 NamingContextHelper.narrow(orb.resolve_initial_references("NameService")); |
|
275 .fl |
|
276 NamingContext objref = ctx; |
|
277 .fl |
|
278 |
|
279 .fl |
|
280 \fP |
|
281 .fi |
|
282 |
|
283 .LP |
|
284 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. |
|
285 .nf |
|
286 \f3 |
|
287 .fl |
|
288 NameComponent nc1 = new NameComponent("plans", "text"); |
|
289 .fl |
|
290 NameComponent[] name1 = {nc1}; |
|
291 .fl |
|
292 ctx.rebind(name1, objref); |
|
293 .fl |
|
294 System.out.println("plans rebind sucessful!"); |
|
295 .fl |
|
296 |
|
297 .fl |
|
298 \fP |
|
299 .fi |
|
300 |
|
301 .LP |
|
302 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. |
|
303 .nf |
|
304 \f3 |
|
305 .fl |
|
306 NameComponent nc2 = new NameComponent("Personal", "directory"); |
|
307 .fl |
|
308 NameComponent[] name2 = {nc2}; |
|
309 .fl |
|
310 NamingContext ctx2 = ctx.bind_new_context(name2); |
|
311 .fl |
|
312 System.out.println("new naming context added.."); |
|
313 .fl |
|
314 |
|
315 .fl |
|
316 \fP |
|
317 .fi |
|
318 |
|
319 .LP |
|
320 The remainder of the code binds the dummy object reference using the names "schedule" and "calendar" under the "Personal" naming context (\f3ctx2\fP). |
|
321 .nf |
|
322 \f3 |
|
323 .fl |
|
324 NameComponent nc3 = new NameComponent("schedule", "text"); |
|
325 .fl |
|
326 NameComponent[] name3 = {nc3}; |
|
327 .fl |
|
328 ctx2.rebind(name3, objref); |
|
329 .fl |
|
330 System.out.println("schedule rebind sucessful!"); |
|
331 .fl |
|
332 |
|
333 .fl |
|
334 NameComponent nc4 = new NameComponent("calender", "text"); |
|
335 .fl |
|
336 NameComponent[] name4 = {nc4}; |
|
337 .fl |
|
338 ctx2.rebind(name4, objref); |
|
339 .fl |
|
340 System.out.println("calender rebind sucessful!"); |
|
341 .fl |
|
342 |
|
343 .fl |
|
344 |
|
345 .fl |
|
346 } catch (Exception e) { |
|
347 .fl |
|
348 e.printStackTrace(System.err); |
|
349 .fl |
|
350 } |
|
351 .fl |
|
352 } |
|
353 .fl |
|
354 } |
|
355 .fl |
|
356 \fP |
|
357 .fi |
|
358 |
|
359 .LP |
|
360 .SH "Sample Client: Browsing the Namespace" |
|
361 .LP |
|
362 .LP |
|
363 The following sample program illustrates how to browse the namespace. |
|
364 .LP |
|
365 .nf |
|
366 \f3 |
|
367 .fl |
|
368 import java.util.Properties; |
|
369 .fl |
|
370 import org.omg.CORBA.*; |
|
371 .fl |
|
372 import org.omg.CosNaming.*; |
|
373 .fl |
|
374 |
|
375 .fl |
|
376 public class NameClientList |
|
377 .fl |
|
378 { |
|
379 .fl |
|
380 public static void main(String args[]) |
|
381 .fl |
|
382 { |
|
383 .fl |
|
384 try { |
|
385 .fl |
|
386 \fP |
|
387 .fi |
|
388 |
|
389 .LP |
|
390 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. |
|
391 .nf |
|
392 \f3 |
|
393 .fl |
|
394 |
|
395 .fl |
|
396 Properties props = new Properties(); |
|
397 .fl |
|
398 props.put("org.omg.CORBA.ORBInitialPort", "1050"); |
|
399 .fl |
|
400 ORB orb = ORB.init(args, props); |
|
401 .fl |
|
402 |
|
403 .fl |
|
404 |
|
405 .fl |
|
406 \fP |
|
407 .fi |
|
408 |
|
409 .LP |
|
410 The following code obtains the intial naming context. |
|
411 .nf |
|
412 \f3 |
|
413 .fl |
|
414 NamingContext nc = |
|
415 .fl |
|
416 NamingContextHelper.narrow(orb.resolve_initial_references("NameService")); |
|
417 .fl |
|
418 |
|
419 .fl |
|
420 \fP |
|
421 .fi |
|
422 |
|
423 .LP |
|
424 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. |
|
425 .nf |
|
426 \f3 |
|
427 .fl |
|
428 BindingListHolder bl = new BindingListHolder(); |
|
429 .fl |
|
430 BindingIteratorHolder blIt= new BindingIteratorHolder(); |
|
431 .fl |
|
432 nc.list(1000, bl, blIt); |
|
433 .fl |
|
434 |
|
435 .fl |
|
436 \fP |
|
437 .fi |
|
438 |
|
439 .LP |
|
440 This code gets the array of bindings out of the returned BindingListHolder. If there are no bindings, the program ends. |
|
441 .nf |
|
442 \f3 |
|
443 .fl |
|
444 Binding bindings[] = bl.value; |
|
445 .fl |
|
446 if (bindings.length == 0) return; |
|
447 .fl |
|
448 |
|
449 .fl |
|
450 \fP |
|
451 .fi |
|
452 |
|
453 .LP |
|
454 The remainder of the code loops through the bindings and prints the names out. |
|
455 .nf |
|
456 \f3 |
|
457 .fl |
|
458 for (int i=0; i < bindings.length; i++) { |
|
459 .fl |
|
460 |
|
461 .fl |
|
462 // get the object reference for each binding |
|
463 .fl |
|
464 org.omg.CORBA.Object obj = nc.resolve(bindings[i].binding_name); |
|
465 .fl |
|
466 String objStr = orb.object_to_string(obj); |
|
467 .fl |
|
468 int lastIx = bindings[i].binding_name.length\-1; |
|
469 .fl |
|
470 |
|
471 .fl |
|
472 // check to see if this is a naming context |
|
473 .fl |
|
474 if (bindings[i].binding_type == BindingType.ncontext) { |
|
475 .fl |
|
476 System.out.println( "Context: " + |
|
477 .fl |
|
478 bindings[i].binding_name[lastIx].id); |
|
479 .fl |
|
480 } else { |
|
481 .fl |
|
482 System.out.println("Object: " + |
|
483 .fl |
|
484 bindings[i].binding_name[lastIx].id); |
|
485 .fl |
|
486 } |
|
487 .fl |
|
488 } |
|
489 .fl |
|
490 |
|
491 .fl |
|
492 } catch (Exception e) { |
|
493 .fl |
|
494 e.printStackTrace(System.err); |
|
495 .fl |
|
496 } |
|
497 .fl |
|
498 } |
|
499 .fl |
|
500 } |
|
501 .fl |
|
502 \fP |
|
503 .fi |
|
504 |
|
505 .LP |
|
506 |
|
507 .LP |
|
508 |