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