1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2 <html> 3 <head> 4 <!-- 5 /* 6 * Copyright (c) 1998, 2015, 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 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 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 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 any 93 descriptive purpose. Its importance is that it 94 can be used to describe an object without affecting syntax. 95 The C programming language, for example, uses the the syntactic convention 96 of appending the extension ".c" to a file name to indicate that it is 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 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 101 <code>"c_source"</code>, <code>"object_code"</code>, 102 <code>"executable"</code>, 103 <code>"postscript"</code>, and <code>""</code>. It is not unusual 104 for the <code>kind</code> field to be the empty string. 105 </OL> 106 <P> 107 In a name, each <code>NameComponent</code> object except the last denotes 108 a <code>NamingContext</code> object; the last <code>NameComponent</code> 109 object denotes the bound object reference. 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. 112 113 <LI><code>public final class <B>Binding</B></code> -- 114 an object that associates a name with an object reference or a 115 naming context. 116 A <code>Binding</code> object has two fields: 117 <OL> 118 <LI><code><B>binding_name</B></code> - an array of one or more 119 <code>NameComponent</code> objects that represents the bound name 120 <LI><code><B>binding_type</B></code> - a <code>BindingType</code> object 121 indicating whether the binding is between a name and an object 122 reference or between a name and a naming context 123 </OL> 124 <P> 125 The interface <code>NamingContext</code> has methods for 126 binding/unbinding names with object references or naming contexts, 127 for listing bindings, 128 and for resolving bindings (given a name, the method 129 <code>resolve</code> returns the object reference bound to it). 130 131 <LI><code>public final class <B>BindingType</B></code> -- 132 an object that specifies whether the given <code>Binding</code> 133 object is a binding between a name and an object reference (that is, 134 not a naming context) or between a name and a naming context. 135 <P> 136 The class<code>BindingType</code> consists of two methods and 137 four constants. Two of these constants are 138 <code>BindingType</code> objects, and two are <code>int</code>s. 139 <P> 140 The <code>BindingType</code> objects 141 can be passed to the constructor for the class 142 <code>Binding</code> or used as parameters or return values. These 143 <code>BindingType</code> objects are: 144 <UL> 145 <LI><code>public static final BindingType <B>nobject</B></code> -- 146 to indicate that the binding is with an object reference 147 <LI><code>public static final BindingType <B>ncontext</B></code> -- 148 to indicate that the binding is with a naming context 149 </UL> 150 <P> 151 The <code>int</code> constants can be supplied to the method 152 <code>from_int</code> to create <code>BindingType</code> objects, 153 or they can be return values for the method <code>value</code>. 154 These constants are: 155 <UL> 156 <LI><code>public static final int <B>_nobject</B></code> 157 <LI><code>public static final int <B>_ncontext</B></code> 158 </UL> 159 If the method <code>from_int</code> is supplied with anything other 160 than <code>_nobject</code> 161 or <code>_ncontext</code>, it will throw 162 the exception <code>org.omg.CORBA.BAD_PARAM</code>. 163 <P>Usage is as follows: 164 <PRE> 165 BindingType btObject = from_int(_nobject); 166 BindingType btContext = from_int(_ncontext); 167 </PRE> 168 The variable <code>btObject</code> refers to a <code>BindingType</code> 169 object initialized to represent a binding with an object reference. 170 The variable <code>btContext</code> refers to a <code>BindingType</code> 171 object initialized to represent a binding with a 172 <code>NamingContex</code> object. 173 <P> 174 The method <code>value</code> returns either 175 <code>_nobject</code> or <code>_ncontext</code>, so 176 in the following line of code, the variable <code>bt</code> 177 will contain <code>_nobject</code> or <code>_ncontext</code>: 178 <PRE> 179 int bt = BindingType.value(); 180 </PRE> 181 </UL> 182 183 <H3>Holder Classes</H3> 184 185 OMG IDL uses OUT and INOUT parameters for returning values from operations. 186 The mapping to the Java programming language, which does not have OUT 187 and INOUT parameters, creates a special class for each type, called 188 a holder class. 189 An instance of a holder class can be passed to a 190 Java method as a parameter, and 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. 193 <P>The following holder classes are generated for the package 194 <code>org.omg.CosNaming</code>: 195 <UL> 196 <LI><code>NamingContextHolder</code> 197 <LI><code>BindingIteratorHolder</code> 198 <LI><code>BindingHolder</code> 199 <LI><code>BindingListHolder</code> 200 <LI><code>BindingTypeHolder</code> 201 <LI><code>NameComponentHolder</code> 202 <LI><code>NameHolder</code> 203 </UL> 204 <P> 205 Note that in the <code>org.omg.CORBA</code> package, 206 there is a holder class for each of the basic Java types: 207 <code>IntHolder</code>, <code>ShortHolder</code>, 208 <code>StringHolder</code>, and so on. 209 <P> 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 212 <code>BindingListHolder</code> class even though there is no 213 <code>BindingList</code> class. This is true because in the OMG IDL 214 interface, <code>Name</code> and <code>BindingList</code> are 215 <code>typedef</code>s. There is no mapping from an IDL 216 <code>typedef</code> to a Java construct, but holder classes 217 are generated if the <code>typedef</code> is for a sequence or 218 an array. As mapped to the 219 Java programming language, <code>Name</code> is an array of 220 <code>NameComponent</code> objects, and a <code>BindingList</code> 221 is an array of <code>Binding</code> objects. 222 223 All holder classes have at least two constructors and one field: 224 <UL> 225 <LI><code><B>value</B></code> field -- an instance of the type being used as 226 an OUT or INOUT parameter. For example, the <code>value</code> field of a 227 <code>NamingContextHolder</code> will be a <code>NamingContext</code> 228 object. 229 <LI>default constructor -- a constructor that creates a new holder object 230 initialized with the default value for the type. For example, a new 231 <code>BindingHolder</code> object created with the default constructor 232 will have its <code>value</code> field set to <code>null</code> because 233 that is the default value for an object. Other defaults are 234 <code>false</code> for <code>boolean</code>, 235 <code>0</code> for numeric and char types, and 236 <code>null</code> for object references. 237 <LI>constructor from an instance -- a constructor that creates a new 238 holder object whose <code>value</code> field is 239 initialized with the instance supplied 240 </UL> 241 <P> 242 A holder class for a user-defined type (a Java class) has three more 243 methods, but application developers do not use them directly. 244 245 <H3>Helper Classes</H3> 246 Helper classes, which are generated for all user-defined types 247 in an OMG IDL interface, supply static methods needed to manipulate 248 those types. 249 <P> 250 There is only one method in a helper class that an 251 application programmer uses: the 252 method <code>narrow</code>. Only Java interfaces mapped from IDL 253 interfaces will have a helper class that includes a <code>narrow</code> 254 method, so in the <code>CosNaming</code> package, only the classes 255 <code>NamingContextHelper</code> and <code>BindingIteratorHelper</code> 256 have a <code>narrow</code> method. 257 <UL> 258 <LI><code>public static NamingContext 259 <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given 260 CORBA object to a <code>NamingContext</code> object 261 <LI><code>public static BindingIterator 262 <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given 263 CORBA object to a <code>BindingIterator</code> object 264 </UL> 265 <H2>Package <code>org.omg.CosNaming.NamingContextPackage</code></H2> 266 This package supplies Helper and Holder classes for the exceptions used 267 in the package <code>org.omg.CosNaming</code> and also for the class 268 <code>NotFoundReason</code>, which supplies a reason for the exception 269 <code>NotFound</code>. 270 <P> 271 There are Helper and Holder classes for the following exceptions: 272 <UL> 273 <LI><code>AlreadyBound</code> 274 <LI><code>CannotProceed</code> 275 <LI><code>InvalidName</code> 276 <LI><code>NotEmpty</code> 277 <LI><code>NotFound</code> 278 </UL> 279 280 <h2>Naming Service Compatibility</h2> 281 282 Sun's implementation of the <code>CosNaming</code> package complies 283 with the OMG <code>COSNaming</code> specification. In other words, 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 286 third-party vendor has implemented a naming service that is OMG 287 compliant, it is possible to switch between Sun's implementation of 288 <code>CosNaming</code> and the third-party vendor's implementation. 289 However, it is important to understand that there can be minor 290 variations in the way different vendors implement the naming service, 291 such as differences in the exception strings. 292 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 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. 297 Here are the steps to follow: 298 <OL> 299 <LI>Create a properties file for the Bootstrap server and give it 300 two entries. For example, you could call this properties file 301 <code>/tmp/services</code> and put the following in it: 302 <code>NameService, <Stringified IOR of the Root Naming 303 Context></code>. 304 <P> 305 This associates <code>NameService</code> with the Root Naming 306 Context of the <code>CosNaming</code> implementation that you 307 want to use. 308 <LI>Start the standalone Bootstrap server using the following command: 309 <pre> 310 <code> 311 java -classpath $(CLASSPATH) 312 com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile 313 "/tmp/services" [-ORBInitialPort port] 314 </code> 315 </pre> 316 <P> 317 Note that the square brackets at the end of the command indicate that 318 specifying a port number is optional. 319 </OL> 320 <P> 321 Now when an application calls the method 322 <code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA 323 processes will contact the Bootstrap Server to get the Root Naming 324 Context. 325 326 <h2>Package Specification</h2> 327 328 <ul> 329 <li>Interoperable Naming Service (<a 330 href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) 331 </ul> 332 333 <h2>Related Documentation</h2> 334 335 For an overview and examples of how to use the 336 <code>CosNaming</code> API, please see: 337 <ul> 338 <li><a href="../../../../technotes/guides/idl/tnameserv.html"> 339 Naming Service</a> 340 </ul> 341 <p> 342 For an overview of Java IDL, please see: 343 <ul> 344 <li><a href="../../../../technotes/guides/idl/index.html"> 345 Java IDL home page</a> 346 </ul> 347 348 @since JDK1.3 349 350 351 352 </body> 353 </html> 354