33 Provides a naming service for Java IDL. The Object Request Broker Daemon |
33 Provides a naming service for Java IDL. The Object Request Broker Daemon |
34 (ORBD) also includes both a transient and persistent naming service. |
34 (ORBD) also includes both a transient and persistent naming service. |
35 |
35 |
36 |
36 |
37 <P> |
37 <P> |
38 The package and all its classes and interfaces |
38 The package and all its classes and interfaces |
39 were generated by running the tool <code>idlj</code> on the file |
39 were generated by running the tool <code>idlj</code> on the file |
40 <code>nameservice.idl</code>, which is a module written in OMG IDL. |
40 <code>nameservice.idl</code>, which is a module written in OMG IDL. |
41 |
41 |
42 <H3>Package Specification</H3> |
42 <H3>Package Specification</H3> |
43 |
43 |
44 <P>For a precise list of supported sections of official specifications with which |
44 <P>For a precise list of supported sections of official specifications with which |
45 the Java[tm] Platform, Standard Edition 6, ORB complies, see <A |
45 the Java[tm] Platform, Standard Edition 6, ORB complies, see <A |
46 HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
46 HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
47 support in Java[tm] SE 6</A>. |
47 support in Java[tm] SE 6</A>. |
48 |
48 |
49 <H2>Interfaces</H2> |
49 <H2>Interfaces</H2> |
50 The package <tt>org.omg.CosNaming</tt> contains two public interfaces |
50 The package <code>org.omg.CosNaming</code> contains two public interfaces |
51 and several auxiliary classes. |
51 and several auxiliary classes. |
52 <P> |
52 <P> |
53 The interfaces are: |
53 The interfaces are: |
54 <UL> |
54 <UL> |
55 <LI><TT>NamingContext</TT> |
55 <LI><code>NamingContext</code> |
56 <LI><TT>BindingIterator</TT> |
56 <LI><code>BindingIterator</code> |
57 </UL> |
57 </UL> |
58 <P> |
58 <P> |
59 These two interfaces provide the means to bind/unbind names and object |
59 These two interfaces provide the means to bind/unbind names and object |
60 references, to retrieve bound object references, and |
60 references, to retrieve bound object references, and |
61 to iterate through a list of bindings. The <code>NamingContext</code> |
61 to iterate through a list of bindings. The <code>NamingContext</code> |
66 <H2>Auxiliary Classes</H2> |
66 <H2>Auxiliary Classes</H2> |
67 In order to map an OMG IDL interface to the Java programming language, |
67 In order to map an OMG IDL interface to the Java programming language, |
68 the idlj compiler creates Java classes that can be thought of |
68 the idlj compiler creates Java classes that can be thought of |
69 as auxiliary classes. |
69 as auxiliary classes. |
70 Comments for the generated auxiliary classes |
70 Comments for the generated auxiliary classes |
71 used by the interfaces <code>NamingContext</code> and |
71 used by the interfaces <code>NamingContext</code> and |
72 <code>BindingIterator</code> are included here. |
72 <code>BindingIterator</code> are included here. |
73 |
73 |
74 <H3>Classes Used by <code>NamingContext</code> and |
74 <H3>Classes Used by <code>NamingContext</code> and |
75 <code>BindingIterator</code></H3> |
75 <code>BindingIterator</code></H3> |
76 The following are classes used by |
76 The following are classes used by |
77 the naming service. (Helper and holder classes, which are |
77 the naming service. (Helper and holder classes, which are |
78 generated for each of the classes listed here, are discussed below.) |
78 generated for each of the classes listed here, are discussed below.) |
79 |
79 |
80 <UL> |
80 <UL> |
81 <LI><code>public final class <B>NameComponent</B></code> -- |
81 <LI><code>public final class <B>NameComponent</B></code> -- |
82 a building block for names. (Names are bound to object references |
82 a building block for names. (Names are bound to object references |
83 in a naming context.) |
83 in a naming context.) |
84 <P>A name is an array of one or more <code>NameComponent</code> objects. |
84 <P>A name is an array of one or more <code>NameComponent</code> objects. |
85 A name with a single <code>NameComponent</code> is called |
85 A name with a single <code>NameComponent</code> is called |
86 a <I>simple name</I>; a name with multiple <code>NameComponent</code> |
86 a <I>simple name</I>; a name with multiple <code>NameComponent</code> |
97 a source code file. In a <code>NameComponent</code> object, |
97 a source code file. In a <code>NameComponent</code> object, |
98 the <code>kind</code> field can be used to describe the type of object |
98 the <code>kind</code> field can be used to describe the type of object |
99 rather than a file extension or some other syntactic convention. |
99 rather than a file extension or some other syntactic convention. |
100 Examples of the value of the <code>kind</code> field include the strings |
100 Examples of the value of the <code>kind</code> field include the strings |
101 <code>"c_source"</code>, <code>"object_code"</code>, |
101 <code>"c_source"</code>, <code>"object_code"</code>, |
102 <code>"executable"</code>, |
102 <code>"executable"</code>, |
103 <code>"postscript"</code>, and <code>""</code>. It is not unusual |
103 <code>"postscript"</code>, and <code>""</code>. It is not unusual |
104 for the <code>kind</code> field to be the empty string. |
104 for the <code>kind</code> field to be the empty string. |
105 </OL> |
105 </OL> |
106 <P> |
106 <P> |
107 In a name, each <code>NameComponent</code> object except the last denotes |
107 In a name, each <code>NameComponent</code> object except the last denotes |
108 a <code>NamingContext</code> object; the last <code>NameComponent</code> |
108 a <code>NamingContext</code> object; the last <code>NameComponent</code> |
109 object denotes the bound object reference. |
109 object denotes the bound object reference. |
110 This is similar to a path name, in which the last name is the |
110 This is similar to a path name, in which the last name is the |
111 file name, and all names before it are directory names. |
111 file name, and all names before it are directory names. |
112 |
112 |
113 <LI><code>public final class <B>Binding</B></code> -- |
113 <LI><code>public final class <B>Binding</B></code> -- |
114 an object that associates a name with an object reference or a |
114 an object that associates a name with an object reference or a |
115 naming context. |
115 naming context. |
116 A <code>Binding</code> object has two fields: |
116 A <code>Binding</code> object has two fields: |
117 <OL> |
117 <OL> |
118 <LI><code><B>binding_name</B></code> - an array of one or more |
118 <LI><code><B>binding_name</B></code> - an array of one or more |
140 The <code>BindingType</code> objects |
140 The <code>BindingType</code> objects |
141 can be passed to the constructor for the class |
141 can be passed to the constructor for the class |
142 <code>Binding</code> or used as parameters or return values. These |
142 <code>Binding</code> or used as parameters or return values. These |
143 <code>BindingType</code> objects are: |
143 <code>BindingType</code> objects are: |
144 <UL> |
144 <UL> |
145 <LI><code>public static final BindingType <B>nobject</B></code> -- |
145 <LI><code>public static final BindingType <B>nobject</B></code> -- |
146 to indicate that the binding is with an object reference |
146 to indicate that the binding is with an object reference |
147 <LI><code>public static final BindingType <B>ncontext</B></code> -- |
147 <LI><code>public static final BindingType <B>ncontext</B></code> -- |
148 to indicate that the binding is with a naming context |
148 to indicate that the binding is with a naming context |
149 </UL> |
149 </UL> |
150 <P> |
150 <P> |
151 The <code>int</code> constants can be supplied to the method |
151 The <code>int</code> constants can be supplied to the method |
152 <code>from_int</code> to create <code>BindingType</code> objects, |
152 <code>from_int</code> to create <code>BindingType</code> objects, |
157 <LI><code>public static final int <B>_ncontext</B></code> |
157 <LI><code>public static final int <B>_ncontext</B></code> |
158 </UL> |
158 </UL> |
159 If the method <code>from_int</code> is supplied with anything other |
159 If the method <code>from_int</code> is supplied with anything other |
160 than <code>_nobject</code> |
160 than <code>_nobject</code> |
161 or <code>_ncontext</code>, it will throw |
161 or <code>_ncontext</code>, it will throw |
162 the exception <code>org.omg.CORBA.BAD_PARAM</code>. |
162 the exception <code>org.omg.CORBA.BAD_PARAM</code>. |
163 <P>Usage is as follows: |
163 <P>Usage is as follows: |
164 <PRE> |
164 <PRE> |
165 BindingType btObject = from_int(_nobject); |
165 BindingType btObject = from_int(_nobject); |
166 BindingType btContext = from_int(_ncontext); |
166 BindingType btContext = from_int(_ncontext); |
167 </PRE> |
167 </PRE> |
187 and INOUT parameters, creates a special class for each type, called |
187 and INOUT parameters, creates a special class for each type, called |
188 a holder class. |
188 a holder class. |
189 An instance of a holder class can be passed to a |
189 An instance of a holder class can be passed to a |
190 Java method as a parameter, and |
190 Java method as a parameter, and |
191 a value can be assigned to its <code>value</code> field. This allows |
191 a value can be assigned to its <code>value</code> field. This allows |
192 it to perform the function of an OUT or INOUT parameter. |
192 it to perform the function of an OUT or INOUT parameter. |
193 <P>The following holder classes are generated for the package |
193 <P>The following holder classes are generated for the package |
194 <code>org.omg.CosNaming</code>: |
194 <code>org.omg.CosNaming</code>: |
195 <UL> |
195 <UL> |
196 <LI><code>NamingContextHolder</code> |
196 <LI><code>NamingContextHolder</code> |
197 <LI><code>BindingIteratorHolder</code> |
197 <LI><code>BindingIteratorHolder</code> |
200 <LI><code>BindingTypeHolder</code> |
200 <LI><code>BindingTypeHolder</code> |
201 <LI><code>NameComponentHolder</code> |
201 <LI><code>NameComponentHolder</code> |
202 <LI><code>NameHolder</code> |
202 <LI><code>NameHolder</code> |
203 </UL> |
203 </UL> |
204 <P> |
204 <P> |
205 Note that in the <code>org.omg.CORBA</code> package, |
205 Note that in the <code>org.omg.CORBA</code> package, |
206 there is a holder class for each of the basic Java types: |
206 there is a holder class for each of the basic Java types: |
207 <code>IntHolder</code>, <code>ShortHolder</code>, |
207 <code>IntHolder</code>, <code>ShortHolder</code>, |
208 <code>StringHolder</code>, and so on. |
208 <code>StringHolder</code>, and so on. |
209 <P> |
209 <P> |
210 Note also that there is a <code>NameHolder</code> class even though |
210 Note also that there is a <code>NameHolder</code> class even though |
211 there is no <code>Name</code> class; similarly, there is a |
211 there is no <code>Name</code> class; similarly, there is a |
212 <code>BindingListHolder</code> class even though there is no |
212 <code>BindingListHolder</code> class even though there is no |
213 <code>BindingList</code> class. This is true because in the OMG IDL |
213 <code>BindingList</code> class. This is true because in the OMG IDL |
214 interface, <code>Name</code> and <code>BindingList</code> are |
214 interface, <code>Name</code> and <code>BindingList</code> are |
215 <code>typedef</code>s. There is no mapping from an IDL |
215 <code>typedef</code>s. There is no mapping from an IDL |
216 <code>typedef</code> to a Java construct, but holder classes |
216 <code>typedef</code> to a Java construct, but holder classes |
217 are generated if the <code>typedef</code> is for a sequence or |
217 are generated if the <code>typedef</code> is for a sequence or |
218 an array. As mapped to the |
218 an array. As mapped to the |
219 Java programming language, <code>Name</code> is an array of |
219 Java programming language, <code>Name</code> is an array of |
220 <code>NameComponent</code> objects, and a <code>BindingList</code> |
220 <code>NameComponent</code> objects, and a <code>BindingList</code> |
243 methods, but application developers do not use them directly. |
243 methods, but application developers do not use them directly. |
244 |
244 |
245 <H3>Helper Classes</H3> |
245 <H3>Helper Classes</H3> |
246 Helper classes, which are generated for all user-defined types |
246 Helper classes, which are generated for all user-defined types |
247 in an OMG IDL interface, supply static methods needed to manipulate |
247 in an OMG IDL interface, supply static methods needed to manipulate |
248 those types. |
248 those types. |
249 <P> |
249 <P> |
250 There is only one method in a helper class that an |
250 There is only one method in a helper class that an |
251 application programmer uses: the |
251 application programmer uses: the |
252 method <code>narrow</code>. Only Java interfaces mapped from IDL |
252 method <code>narrow</code>. Only Java interfaces mapped from IDL |
253 interfaces will have a helper class that includes a <code>narrow</code> |
253 interfaces will have a helper class that includes a <code>narrow</code> |
280 <h2>Naming Service Compatibility</h2> |
280 <h2>Naming Service Compatibility</h2> |
281 |
281 |
282 Sun's implementation of the <code>CosNaming</code> package complies |
282 Sun's implementation of the <code>CosNaming</code> package complies |
283 with the OMG <code>COSNaming</code> specification. In other words, |
283 with the OMG <code>COSNaming</code> specification. In other words, |
284 the APIs in Sun's naming service are implemented according to the |
284 the APIs in Sun's naming service are implemented according to the |
285 guidelines for a naming service provided by OMG. Therefore, if a |
285 guidelines for a naming service provided by OMG. Therefore, if a |
286 third-party vendor has implemented a naming service that is OMG |
286 third-party vendor has implemented a naming service that is OMG |
287 compliant, it is possible to switch between Sun's implementation of |
287 compliant, it is possible to switch between Sun's implementation of |
288 <code>CosNaming</code> and the third-party vendor's implementation. |
288 <code>CosNaming</code> and the third-party vendor's implementation. |
289 However, it is important to understand that there can be minor |
289 However, it is important to understand that there can be minor |
290 variations in the way different vendors implement the naming service, |
290 variations in the way different vendors implement the naming service, |
291 such as differences in the exception strings. |
291 such as differences in the exception strings. |
292 |
292 |
293 <h3>Instructions for Using a Third Party's Naming Service</h3> |
293 <h3>Instructions for Using a Third Party's Naming Service</h3> |
294 Although we encourage using an ORB and ORB services that are both |
294 Although we encourage using an ORB and ORB services that are both |
295 from one vendor, it is possible to plug in a third party's |
295 from one vendor, it is possible to plug in a third party's |
296 <code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. |
296 <code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. |
297 Here are the steps to follow: |
297 Here are the steps to follow: |
298 <OL> |
298 <OL> |
299 <LI>Create a properties file for the Bootstrap server and give it |
299 <LI>Create a properties file for the Bootstrap server and give it |
300 two entries. For example, you could call this properties file |
300 two entries. For example, you could call this properties file |
301 <code>/tmp/services</code> and put the following in it: |
301 <code>/tmp/services</code> and put the following in it: |
302 <code>NameService, <Stringified IOR of the Root Naming |
302 <code>NameService, <Stringified IOR of the Root Naming Context></code>. |
303 Context></code>. |
|
304 <P> |
303 <P> |
305 This associates <code>NameService</code> with the Root Naming |
304 This associates <code>NameService</code> with the Root Naming |
306 Context of the <code>CosNaming</code> implementation that you |
305 Context of the <code>CosNaming</code> implementation that you |
307 want to use. |
306 want to use. |
308 <LI>Start the standalone Bootstrap server using the following command: |
307 <LI>Start the standalone Bootstrap server using the following command: |
309 <pre> |
308 <pre> |
310 <code> |
309 <code> |
311 java -classpath $(CLASSPATH) |
310 java -classpath $(CLASSPATH) |
316 <P> |
315 <P> |
317 Note that the square brackets at the end of the command indicate that |
316 Note that the square brackets at the end of the command indicate that |
318 specifying a port number is optional. |
317 specifying a port number is optional. |
319 </OL> |
318 </OL> |
320 <P> |
319 <P> |
321 Now when an application calls the method |
320 Now when an application calls the method |
322 <code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA |
321 <code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA |
323 processes will contact the Bootstrap Server to get the Root Naming |
322 processes will contact the Bootstrap Server to get the Root Naming |
324 Context. |
323 Context. |
325 |
324 |
326 <h2>Package Specification</h2> |
325 <h2>Package Specification</h2> |
327 |
326 |
328 <ul> |
327 <ul> |
329 <li>Interoperable Naming Service (<a |
328 <li>Interoperable Naming Service (<a |
330 href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) |
329 href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) |
331 </ul> |
330 </ul> |
332 |
331 |
333 <h2>Related Documentation</h2> |
332 <h2>Related Documentation</h2> |
334 |
333 |
335 For an overview and examples of how to use the |
334 For an overview and examples of how to use the |
336 <code>CosNaming</code> API, please see: |
335 <code>CosNaming</code> API, please see: |
337 <ul> |
336 <ul> |
338 <li><a href="../../../../technotes/guides/idl/tnameserv.html"> |
337 <li><a href="../../../../technotes/guides/idl/tnameserv.html"> |
339 Naming Service</a> |
338 Naming Service</a> |
340 </ul> |
339 </ul> |