2 <html>
   3 <head>
   4 <!--
   5 /*
   6 * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
   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">
  33   Provides a naming service for Java&nbsp;IDL.  The Object Request Broker Daemon
  34   (ORBD) also includes both a transient and persistent naming service.
  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.
  42   <H3>Package Specification</H3>
  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.)
  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>
 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).
 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>
 186   <H3>Holder Classes</H3>
 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.
 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.
 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>
 283 <h2>Naming Service Compatibility</h2>
 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.
 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, &lt;Stringified IOR of the Root Naming 
 306 Context&gt;</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.
 330 <h2>Package Specification</h2>
 332 <ul>
 333  <li>Interoperable Naming Service (<a 
 334 href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>)
 335 </ul>
 337 <h2>Related Documentation</h2>
 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&nbsp;IDL, please see:
 347 <ul>
 348   <li><a href="../../../../technotes/guides/idl/index.html">
 349         Java&nbsp;IDL home page</a>
 350 </ul>
 352 @since JDK1.3
 356 </body>
 357 </html>