1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2 <html> 3 <head> 4 <!-- 5 /* 6 * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 7 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 8 * 9 * This code is free software; you can redistribute it and/or modify it 10 * under the terms of the GNU General Public License version 2 only, as 11 * published by the Free Software Foundation. Oracle designates this 12 * particular file as subject to the "Classpath" exception as provided 13 * by Oracle in the LICENSE file that accompanied this code. 14 * 15 * This code is distributed in the hope that it will be useful, but WITHOUT 16 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 17 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 18 * version 2 for more details (a copy is included in the LICENSE file that 19 * accompanied this code). 20 * 21 * You should have received a copy of the GNU General Public License version 22 * 2 along with this work; if not, write to the Free Software Foundation, 23 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24 * 25 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 26 * or visit www.oracle.com if you need additional information or have any 27 * questions. 28 */ 29 --> 30 </head> 31 <body bgcolor="white"> 32 33 Provides a naming service for Java IDL. The Object Request Broker Daemon 34 (ORBD) also includes both a transient and persistent naming service. 35 36 37 <P> 38 The package and all its classes and interfaces 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. 41 42 <H3>Package Specification</H3> 43 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 46 HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA 47 support in Java[tm] SE 6</A>. 48 <P> 49 <H2>Interfaces</H2> 50 The package <tt>org.omg.CosNaming</tt> contains two public interfaces 51 and several auxiliary classes. 52 <P> 53 The interfaces are: 54 <UL> 55 <LI><TT>NamingContext</TT> 56 <LI><TT>BindingIterator</TT> 57 </UL> 58 <P> 59 These two interfaces provide the means to bind/unbind names and object 60 references, to retrieve bound object references, and 61 to iterate through a list of bindings. The <code>NamingContext</code> 62 interface supplies the main functionality for the naming service, and 63 <code>BindingIterator</code> provides a means of iterating through a list 64 of name/object reference bindings. 65 <P> 66 <H2>Auxiliary Classes</H2> 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 69 as auxiliary classes. 70 Comments for the generated auxiliary classes 71 used by the interfaces <code>NamingContext</code> and 72 <code>BindingIterator</code> are included here. 73 <P> 74 <H3>Classes Used by <code>NamingContext</code> and 75 <code>BindingIterator</code></H3> 76 The following are classes used by 77 the naming service. (Helper and holder classes, which are 78 generated for each of the classes listed here, are discussed below.) 79 80 <UL> 81 <LI><code>public final class <B>NameComponent</B></code> -- 82 a building block for names. (Names are bound to object references 83 in a naming context.) 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 86 a <I>simple name</I>; a name with multiple <code>NameComponent</code> 87 objects is called a <I>compound name</I>. 88 <P> 89 A <code><B>NameComponent</B></code> object consists of two fields: 90 <OL> 91 <LI><code><B>id</B></code> -- a <code>String</code> used as an identifier 92 <LI><code><B>kind</B></code> -- a <code>String</code> that can be used for 93 any 94 descriptive purpose. Its importance is that it 95 can be used to describe an object without affecting syntax. 96 The C programming language, for example, uses the the syntactic convention 97 of appending the extension ".c" to a file name to indicate that it is 98 a source code file. In a <code>NameComponent</code> object, 99 the <code>kind</code> field can be used to describe the type of object 100 rather than a file extension or some other syntactic convention. 101 Examples of the value of the <code>kind</code> field include the strings 102 <code>"c_source"</code>, <code>"object_code"</code>, 103 <code>"executable"</code>, 104 <code>"postscript"</code>, and <code>""</code>. It is not unusual 105 for the <code>kind</code> field to be the empty string. 106 </OL> 107 <P> 108 In a name, each <code>NameComponent</code> object except the last denotes 109 a <code>NamingContext</code> object; the last <code>NameComponent</code> 110 object denotes the bound object reference. 111 This is similar to a path name, in which the last name is the 112 file name, and all names before it are directory names.<p> 113 <P> 114 115 <LI><code>public final class <B>Binding</B></code> -- 116 an object that associates a name with an object reference or a 117 naming context. 118 A <code>Binding</code> object has two fields: 119 <OL> 120 <LI><code><B>binding_name</B></code> - an array of one or more 121 <code>NameComponent</code> objects that represents the bound name 122 <LI><code><B>binding_type</B></code> - a <code>BindingType</code> object 123 indicating whether the binding is between a name and an object 124 reference or between a name and a naming context 125 </OL> 126 <P> 127 The interface <code>NamingContext</code> has methods for 128 binding/unbinding names with object references or naming contexts, 129 for listing bindings, 130 and for resolving bindings (given a name, the method 131 <code>resolve</code> returns the object reference bound to it). 132 133 <P> 134 <LI><code>public final class <B>BindingType</B></code> -- 135 an object that specifies whether the given <code>Binding</code> 136 object is a binding between a name and an object reference (that is, 137 not a naming context) or between a name and a naming context. 138 <P> 139 The class<code>BindingType</code> consists of two methods and 140 four constants. Two of these constants are 141 <code>BindingType</code> objects, and two are <code>int</code>s. 142 <P> 143 The <code>BindingType</code> objects 144 can be passed to the constructor for the class 145 <code>Binding</code> or used as parameters or return values. These 146 <code>BindingType</code> objects are: 147 <UL> 148 <LI><code>public static final BindingType <B>nobject</B></code> -- 149 to indicate that the binding is with an object reference 150 <LI><code>public static final BindingType <B>ncontext</B></code> -- 151 to indicate that the binding is with a naming context 152 </UL> 153 <P> 154 The <code>int</code> constants can be supplied to the method 155 <code>from_int</code> to create <code>BindingType</code> objects, 156 or they can be return values for the method <code>value</code>. 157 These constants are: 158 <UL> 159 <LI><code>public static final int <B>_nobject</B></code> 160 <LI><code>public static final int <B>_ncontext</B></code> 161 </UL> 162 If the method <code>from_int</code> is supplied with anything other 163 than <code>_nobject</code> 164 or <code>_ncontext</code>, it will throw 165 the exception <code>org.omg.CORBA.BAD_PARAM</code>. 166 <P>Usage is as follows: 167 <PRE> 168 BindingType btObject = from_int(_nobject); 169 BindingType btContext = from_int(_ncontext); 170 </PRE> 171 The variable <code>btObject</code> refers to a <code>BindingType</code> 172 object initialized to represent a binding with an object reference. 173 The variable <code>btContext</code> refers to a <code>BindingType</code> 174 object initialized to represent a binding with a 175 <code>NamingContex</code> object. 176 <P> 177 The method <code>value</code> returns either 178 <code>_nobject</code> or <code>_ncontext</code>, so 179 in the following line of code, the variable <code>bt</code> 180 will contain <code>_nobject</code> or <code>_ncontext</code>: 181 <PRE> 182 int bt = BindingType.value(); 183 </PRE> 184 </UL> 185 186 <H3>Holder Classes</H3> 187 188 OMG IDL uses OUT and INOUT parameters for returning values from operations. 189 The mapping to the Java programming language, which does not have OUT 190 and INOUT parameters, creates a special class for each type, called 191 a holder class. 192 An instance of a holder class can be passed to a 193 Java method as a parameter, and 194 a value can be assigned to its <code>value</code> field. This allows 195 it to perform the function of an OUT or INOUT parameter. 196 <P>The following holder classes are generated for the package 197 <code>org.omg.CosNaming</code>: 198 <UL> 199 <LI><code>NamingContextHolder</code> 200 <LI><code>BindingIteratorHolder</code> 201 <LI><code>BindingHolder</code> 202 <LI><code>BindingListHolder</code> 203 <LI><code>BindingTypeHolder</code> 204 <LI><code>NameComponentHolder</code> 205 <LI><code>NameHolder</code> 206 </UL> 207 <P> 208 Note that in the <code>org.omg.CORBA</code> package, 209 there is a holder class for each of the basic Java types: 210 <code>IntHolder</code>, <code>ShortHolder</code>, 211 <code>StringHolder</code>, and so on. 212 <P> 213 Note also that there is a <code>NameHolder</code> class even though 214 there is no <code>Name</code> class; similarly, there is a 215 <code>BindingListHolder</code> class even though there is no 216 <code>BindingList</code> class. This is true because in the OMG IDL 217 interface, <code>Name</code> and <code>BindingList</code> are 218 <code>typedef</code>s. There is no mapping from an IDL 219 <code>typedef</code> to a Java construct, but holder classes 220 are generated if the <code>typedef</code> is for a sequence or 221 an array. As mapped to the 222 Java programming language, <code>Name</code> is an array of 223 <code>NameComponent</code> objects, and a <code>BindingList</code> 224 is an array of <code>Binding</code> objects. 225 226 All holder classes have at least two constructors and one field: 227 <UL> 228 <LI><code><B>value</B></code> field -- an instance of the type being used as 229 an OUT or INOUT parameter. For example, the <code>value</code> field of a 230 <code>NamingContextHolder</code> will be a <code>NamingContext</code> 231 object. 232 <LI>default constructor -- a constructor that creates a new holder object 233 initialized with the default value for the type. For example, a new 234 <code>BindingHolder</code> object created with the default constructor 235 will have its <code>value</code> field set to <code>null</code> because 236 that is the default value for an object. Other defaults are 237 <code>false</code> for <code>boolean</code>, 238 <code>0</code> for numeric and char types, and 239 <code>null</code> for object references. 240 <LI>constructor from an instance -- a constructor that creates a new 241 holder object whose <code>value</code> field is 242 initialized with the instance supplied 243 </UL> 244 <P> 245 A holder class for a user-defined type (a Java class) has three more 246 methods, but application developers do not use them directly. 247 248 <H3>Helper Classes</H3> 249 Helper classes, which are generated for all user-defined types 250 in an OMG IDL interface, supply static methods needed to manipulate 251 those types. 252 <P> 253 There is only one method in a helper class that an 254 application programmer uses: the 255 method <code>narrow</code>. Only Java interfaces mapped from IDL 256 interfaces will have a helper class that includes a <code>narrow</code> 257 method, so in the <code>CosNaming</code> package, only the classes 258 <code>NamingContextHelper</code> and <code>BindingIteratorHelper</code> 259 have a <code>narrow</code> method. 260 <UL> 261 <LI><code>public static NamingContext 262 <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given 263 CORBA object to a <code>NamingContext</code> object 264 <LI><code>public static BindingIterator 265 <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given 266 CORBA object to a <code>BindingIterator</code> object 267 </UL> 268 <H2>Package <code>org.omg.CosNaming.NamingContextPackage</code></H2> 269 This package supplies Helper and Holder classes for the exceptions used 270 in the package <code>org.omg.CosNaming</code> and also for the class 271 <code>NotFoundReason</code>, which supplies a reason for the exception 272 <code>NotFound</code>. 273 <P> 274 There are Helper and Holder classes for the following exceptions: 275 <UL> 276 <LI><code>AlreadyBound</code> 277 <LI><code>CannotProceed</code> 278 <LI><code>InvalidName</code> 279 <LI><code>NotEmpty</code> 280 <LI><code>NotFound</code> 281 </UL> 282 283 <h2>Naming Service Compatibility</h2> 284 285 Sun's implementation of the <code>CosNaming</code> package complies 286 with the OMG <code>COSNaming</code> specification. In other words, 287 the APIs in Sun's naming service are implemented according to the 288 guidelines for a naming service provided by OMG. Therefore, if a 289 third-party vendor has implemented a naming service that is OMG 290 compliant, it is possible to switch between Sun's implementation of 291 <code>CosNaming</code> and the third-party vendor's implementation. 292 However, it is important to understand that there can be minor 293 variations in the way different vendors implement the naming service, 294 such as differences in the exception strings. 295 296 <h3>Instructions for Using a Third Party's Naming Service</h3> 297 Although we encourage using an ORB and ORB services that are both 298 from one vendor, it is possible to plug in a third party's 299 <code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. 300 Here are the steps to follow: 301 <OL> 302 <LI>Create a properties file for the Bootstrap server and give it 303 two entries. For example, you could call this properties file 304 <code>/tmp/services</code> and put the following in it: 305 <code>NameService, <Stringified IOR of the Root Naming 306 Context></code>. 307 <P> 308 This associates <code>NameService</code> with the Root Naming 309 Context of the <code>CosNaming</code> implementation that you 310 want to use. 311 <P> 312 <LI>Start the standalone Bootstrap server using the following command: 313 <pre> 314 <code> 315 java -classpath $(CLASSPATH) 316 com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile 317 "/tmp/services" [-ORBInitialPort port] 318 </code> 319 </pre> 320 <P> 321 Note that the square brackets at the end of the command indicate that 322 specifying a port number is optional. 323 </OL> 324 <P> 325 Now when an application calls the method 326 <code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA 327 processes will contact the Bootstrap Server to get the Root Naming 328 Context. 329 330 <h2>Package Specification</h2> 331 332 <ul> 333 <li>Interoperable Naming Service (<a 334 href="http://cgi.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) 335 </ul> 336 337 <h2>Related Documentation</h2> 338 339 For an overview and examples of how to use the 340 <code>CosNaming</code> API, please see: 341 <ul> 342 <li><a href="../../../../technotes/guides/idl/tnameserv.html"> 343 Naming Service</a> 344 </ul> 345 <p> 346 For an overview of Java IDL, please see: 347 <ul> 348 <li><a href="../../../../technotes/guides/idl/index.html"> 349 Java IDL home page</a> 350 </ul> 351 352 @since JDK1.3 353 354 355 356 </body> 357 </html> 358