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