package.html revision 891:bd32b2b28de5
135069Speter<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2158502Speter<html> 335069Speter<head> 435069Speter<!-- 535069Speter/* 635069Speter* Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 735069Speter* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 835069Speter* 935069Speter* This code is free software; you can redistribute it and/or modify it 1035069Speter* under the terms of the GNU General Public License version 2 only, as 1135069Speter* published by the Free Software Foundation. Oracle designates this 1235069Speter* particular file as subject to the "Classpath" exception as provided 1335069Speter* by Oracle in the LICENSE file that accompanied this code. 1435069Speter* 1535069Speter* This code is distributed in the hope that it will be useful, but WITHOUT 1635069Speter* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1735069Speter* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1835069Speter* version 2 for more details (a copy is included in the LICENSE file that 1935069Speter* accompanied this code). 2035069Speter* 2135069Speter* You should have received a copy of the GNU General Public License version 2235069Speter* 2 along with this work; if not, write to the Free Software Foundation, 2335069Speter* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2435069Speter* 2535069Speter* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2650477Speter* or visit www.oracle.com if you need additional information or have any 2735069Speter* questions. 2835069Speter*/ 2987702Sjhb--> 30166540Sbde</head> 3165557Sjasone<body bgcolor="white"> 32143063Sjoerg 33166540Sbde Provides a naming service for Java IDL. The Object Request Broker Daemon 34143063Sjoerg (ORBD) also includes both a transient and persistent naming service. 35143063Sjoerg 3665557Sjasone 3765557Sjasone <P> 3865557Sjasone The package and all its classes and interfaces 39311653Sjah were generated by running the tool <code>idlj</code> on the file 40311653Sjah <code>nameservice.idl</code>, which is a module written in OMG IDL. 41311653Sjah 4235069Speter <H3>Package Specification</H3> 4335069Speter 4435069Speter<P>For a precise list of supported sections of official specifications with which 4535069Speterthe Java[tm] Platform, Standard Edition 6, ORB complies, see <A 4635069SpeterHREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA 4735069Spetersupport in Java[tm] SE 6</A>. 4835069Speter 49181775Skmacy <H2>Interfaces</H2> 50181775Skmacy The package <code>org.omg.CosNaming</code> contains two public interfaces 51181775Skmacy and several auxiliary classes. 52181775Skmacy <P> 53181775Skmacy The interfaces are: 54181775Skmacy <UL> 55181775Skmacy <LI><code>NamingContext</code> 56181775Skmacy <LI><code>BindingIterator</code> 57181775Skmacy </UL> 58181775Skmacy <P> 59181775Skmacy These two interfaces provide the means to bind/unbind names and object 60181775Skmacy references, to retrieve bound object references, and 61208507Sjhb to iterate through a list of bindings. The <code>NamingContext</code> 62256073Sgibbs interface supplies the main functionality for the naming service, and 63282274Sjhb <code>BindingIterator</code> provides a means of iterating through a list 64311653Sjah of name/object reference bindings. 65311653Sjah 66311653Sjah <H2>Auxiliary Classes</H2> 67311653Sjah In order to map an OMG IDL interface to the Java programming language, 68311653Sjah the idlj compiler creates Java classes that can be thought of 69286296Sjah as auxiliary classes. 70307856Skib Comments for the generated auxiliary classes 71334152Skib used by the interfaces <code>NamingContext</code> and 72347568Skib <code>BindingIterator</code> are included here. 73347568Skib 74347568Skib <H3>Classes Used by <code>NamingContext</code> and 75347568Skib <code>BindingIterator</code></H3> 76347568Skib The following are classes used by 7735069Speter the naming service. (Helper and holder classes, which are 78181875Sjhb generated for each of the classes listed here, are discussed below.) 79181875Sjhb 80166540Sbde <UL> 81166540Sbde <LI><code>public final class <B>NameComponent</B></code> -- 82104291Sphk a building block for names. (Names are bound to object references 83104291Sphk in a naming context.) 84313862Sjah <P>A name is an array of one or more <code>NameComponent</code> objects. 85166540Sbde A name with a single <code>NameComponent</code> is called 86184198Skmacy a <I>simple name</I>; a name with multiple <code>NameComponent</code> 87170291Sattilio objects is called a <I>compound name</I>. 88166540Sbde <P> 89166540Sbde A <code><B>NameComponent</B></code> object consists of two fields: 90166540Sbde <OL> 91166540Sbde <LI><code><B>id</B></code> -- a <code>String</code> used as an identifier 92166540Sbde <LI><code><B>kind</B></code> -- a <code>String</code> that can be used for any 9387702Sjhb descriptive purpose. Its importance is that it 9487702Sjhb can be used to describe an object without affecting syntax. 9587702Sjhb The C programming language, for example, uses the the syntactic convention 9687702Sjhb of appending the extension ".c" to a file name to indicate that it is 9787702Sjhb a source code file. In a <code>NameComponent</code> object, 9887702Sjhb the <code>kind</code> field can be used to describe the type of object 9987702Sjhb rather than a file extension or some other syntactic convention. 10087702Sjhb Examples of the value of the <code>kind</code> field include the strings 10187702Sjhb <code>"c_source"</code>, <code>"object_code"</code>, 10287702Sjhb <code>"executable"</code>, 10387702Sjhb <code>"postscript"</code>, and <code>""</code>. It is not unusual 10487702Sjhb for the <code>kind</code> field to be the empty string. 10587702Sjhb </OL> 10687702Sjhb <P> 10787702Sjhb In a name, each <code>NameComponent</code> object except the last denotes 108122833Sbde a <code>NamingContext</code> object; the last <code>NameComponent</code> 10987702Sjhb object denotes the bound object reference. 11087702Sjhb This is similar to a path name, in which the last name is the 11187702Sjhb file name, and all names before it are directory names. 11287702Sjhb 11387702Sjhb <LI><code>public final class <B>Binding</B></code> -- 11487702Sjhb an object that associates a name with an object reference or a 11587702Sjhb naming context. 11687702Sjhb A <code>Binding</code> object has two fields: 11787702Sjhb <OL> 11887702Sjhb <LI><code><B>binding_name</B></code> - an array of one or more 11987702Sjhb <code>NameComponent</code> objects that represents the bound name 12087702Sjhb <LI><code><B>binding_type</B></code> - a <code>BindingType</code> object 12187702Sjhb indicating whether the binding is between a name and an object 122122833Sbde reference or between a name and a naming context 123166540Sbde </OL> 124166540Sbde <P> 125196816Sjulian The interface <code>NamingContext</code> has methods for 126166540Sbde binding/unbinding names with object references or naming contexts, 12787702Sjhb for listing bindings, 128166540Sbde and for resolving bindings (given a name, the method 129166540Sbde <code>resolve</code> returns the object reference bound to it). 130166536Sbde 131166536Sbde <LI><code>public final class <B>BindingType</B></code> -- 132166536Sbde an object that specifies whether the given <code>Binding</code> 133166540Sbde object is a binding between a name and an object reference (that is, 13487702Sjhb not a naming context) or between a name and a naming context. 135166540Sbde <P> 13687702Sjhb The class<code>BindingType</code> consists of two methods and 137166540Sbde four constants. Two of these constants are 13887702Sjhb <code>BindingType</code> objects, and two are <code>int</code>s. 13987702Sjhb <P> 14087702Sjhb The <code>BindingType</code> objects 141170291Sattilio can be passed to the constructor for the class 142170291Sattilio <code>Binding</code> or used as parameters or return values. These 143170291Sattilio <code>BindingType</code> objects are: 144170291Sattilio <UL> 145170291Sattilio <LI><code>public static final BindingType <B>nobject</B></code> -- 146170291Sattilio to indicate that the binding is with an object reference 147196816Sjulian <LI><code>public static final BindingType <B>ncontext</B></code> -- 148170291Sattilio to indicate that the binding is with a naming context 149170291Sattilio </UL> 150170291Sattilio <P> 151170291Sattilio The <code>int</code> constants can be supplied to the method 152170291Sattilio <code>from_int</code> to create <code>BindingType</code> objects, 153170291Sattilio or they can be return values for the method <code>value</code>. 154170291Sattilio These constants are: 155170291Sattilio <UL> 156170291Sattilio <LI><code>public static final int <B>_nobject</B></code> 157170291Sattilio <LI><code>public static final int <B>_ncontext</B></code> 158170291Sattilio </UL> 159170291Sattilio If the method <code>from_int</code> is supplied with anything other 160170291Sattilio than <code>_nobject</code> 161170291Sattilio or <code>_ncontext</code>, it will throw 162167429Salc the exception <code>org.omg.CORBA.BAD_PARAM</code>. 163167429Salc <P>Usage is as follows: 164167429Salc <PRE> 165170291Sattilio BindingType btObject = from_int(_nobject); 166167429Salc BindingType btContext = from_int(_ncontext); 167167429Salc </PRE> 168167429Salc The variable <code>btObject</code> refers to a <code>BindingType</code> 169167429Salc object initialized to represent a binding with an object reference. 170167429Salc The variable <code>btContext</code> refers to a <code>BindingType</code> 171167429Salc object initialized to represent a binding with a 172167429Salc <code>NamingContex</code> object. 173167429Salc <P> 174167429Salc The method <code>value</code> returns either 175167429Salc <code>_nobject</code> or <code>_ncontext</code>, so 176167429Salc in the following line of code, the variable <code>bt</code> 177167429Salc will contain <code>_nobject</code> or <code>_ncontext</code>: 178167429Salc <PRE> 179167429Salc int bt = BindingType.value(); 180167429Salc </PRE> 181167429Salc </UL> 182167429Salc 183167429Salc <H3>Holder Classes</H3> 184167429Salc 18587702Sjhb OMG IDL uses OUT and INOUT parameters for returning values from operations. 18687702Sjhb The mapping to the Java programming language, which does not have OUT 187196811Sjulian and INOUT parameters, creates a special class for each type, called 188166540Sbde a holder class. 189166540Sbde An instance of a holder class can be passed to a 190196811Sjulian Java method as a parameter, and 191166540Sbde a value can be assigned to its <code>value</code> field. This allows 19287702Sjhb it to perform the function of an OUT or INOUT parameter. 193166540Sbde <P>The following holder classes are generated for the package 194166536Sbde <code>org.omg.CosNaming</code>: 195166536Sbde <UL> 196166536Sbde <LI><code>NamingContextHolder</code> 197166536Sbde <LI><code>BindingIteratorHolder</code> 198166536Sbde <LI><code>BindingHolder</code> 199166536Sbde <LI><code>BindingListHolder</code> 20087702Sjhb <LI><code>BindingTypeHolder</code> 20187702Sjhb <LI><code>NameComponentHolder</code> 20287702Sjhb <LI><code>NameHolder</code> 203196811Sjulian </UL> 20487702Sjhb <P> 205313862Sjah Note that in the <code>org.omg.CORBA</code> package, 206313862Sjah there is a holder class for each of the basic Java types: 207313862Sjah <code>IntHolder</code>, <code>ShortHolder</code>, 208313862Sjah <code>StringHolder</code>, and so on. 209313862Sjah <P> 210313862Sjah Note also that there is a <code>NameHolder</code> class even though 211313862Sjah there is no <code>Name</code> class; similarly, there is a 212313862Sjah <code>BindingListHolder</code> class even though there is no 213313862Sjah <code>BindingList</code> class. This is true because in the OMG IDL 21487702Sjhb interface, <code>Name</code> and <code>BindingList</code> are 215170291Sattilio <code>typedef</code>s. There is no mapping from an IDL 216170291Sattilio <code>typedef</code> to a Java construct, but holder classes 21787702Sjhb are generated if the <code>typedef</code> is for a sequence or 21887702Sjhb an array. As mapped to the 21987702Sjhb Java programming language, <code>Name</code> is an array of 220238792Skib <code>NameComponent</code> objects, and a <code>BindingList</code> 221238792Skib is an array of <code>Binding</code> objects. 222238792Skib 223238792Skib All holder classes have at least two constructors and one field: 224238792Skib <UL> 225210623Sjhb <LI><code><B>value</B></code> field -- an instance of the type being used as 226122931Speter an OUT or INOUT parameter. For example, the <code>value</code> field of a 227122931Speter <code>NamingContextHolder</code> will be a <code>NamingContext</code> 228122931Speter object. 229122931Speter <LI>default constructor -- a constructor that creates a new holder object 230238792Skib initialized with the default value for the type. For example, a new 231238792Skib <code>BindingHolder</code> object created with the default constructor 232122931Speter will have its <code>value</code> field set to <code>null</code> because 233122931Speter that is the default value for an object. Other defaults are 234238792Skib <code>false</code> for <code>boolean</code>, 235238792Skib <code>0</code> for numeric and char types, and 236238792Skib <code>null</code> for object references. 237166540Sbde <LI>constructor from an instance -- a constructor that creates a new 238122931Speter holder object whose <code>value</code> field is 239238792Skib initialized with the instance supplied 240238792Skib </UL> 241238792Skib <P> 242238792Skib A holder class for a user-defined type (a Java class) has three more 243238792Skib methods, but application developers do not use them directly. 244238792Skib 245238792Skib <H3>Helper Classes</H3> 246238792Skib Helper classes, which are generated for all user-defined types 247238792Skib in an OMG IDL interface, supply static methods needed to manipulate 248238792Skib those types. 249238792Skib <P> 250333053Skib There is only one method in a helper class that an 251333053Skib application programmer uses: the 252166540Sbde method <code>narrow</code>. Only Java interfaces mapped from IDL 253100079Smarkm interfaces will have a helper class that includes a <code>narrow</code> 254166540Sbde method, so in the <code>CosNaming</code> package, only the classes 25581763Sobrien <code>NamingContextHelper</code> and <code>BindingIteratorHelper</code> 256166540Sbde have a <code>narrow</code> method. 257166540Sbde <UL> 258166540Sbde <LI><code>public static NamingContext 259166540Sbde <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given 260166540Sbde 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> 266This package supplies Helper and Holder classes for the exceptions used 267in 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> 271There 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 282Sun's implementation of the <code>CosNaming</code> package complies 283with the OMG <code>COSNaming</code> specification. In other words, 284the APIs in Sun's naming service are implemented according to the 285guidelines for a naming service provided by OMG. Therefore, if a 286third-party vendor has implemented a naming service that is OMG 287compliant, it is possible to switch between Sun's implementation of 288<code>CosNaming</code> and the third-party vendor's implementation. 289However, it is important to understand that there can be minor 290variations in the way different vendors implement the naming service, 291such as differences in the exception strings. 292 293<h3>Instructions for Using a Third Party's Naming Service</h3> 294Although we encourage using an ORB and ORB services that are both 295from one vendor, it is possible to plug in a third party's 296<code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. 297Here 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 Context></code>. 303 <P> 304 This associates <code>NameService</code> with the Root Naming 305 Context of the <code>CosNaming</code> implementation that you 306 want to use. 307 <LI>Start the standalone Bootstrap server using the following command: 308 <pre> 309 <code> 310 java -classpath $(CLASSPATH) 311 com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile 312 "/tmp/services" [-ORBInitialPort port] 313 </code> 314 </pre> 315 <P> 316 Note that the square brackets at the end of the command indicate that 317 specifying a port number is optional. 318</OL> 319<P> 320Now when an application calls the method 321<code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA 322processes will contact the Bootstrap Server to get the Root Naming 323Context. 324 325<h2>Package Specification</h2> 326 327<ul> 328 <li>Interoperable Naming Service (<a 329href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) 330</ul> 331 332<h2>Related Documentation</h2> 333 334For an overview and examples of how to use the 335<code>CosNaming</code> API, please see: 336<ul> 337 <li>{@extLink tnameserv NamingService} 338</ul> 339<p> 340For an overview of Java IDL, please see: 341<ul> 342 <li>{@extLink idl_guides Java IDL developer's home page} 343</ul> 344 345@since JDK1.3 346 347 348 349</body> 350</html> 351 352