| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <html> |
| <head> |
| <!-- |
| /* |
| * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| --> |
| </head> |
| <body bgcolor="white"> |
| |
| Provides a naming service for Java IDL. The Object Request Broker Daemon |
| (ORBD) also includes both a transient and persistent naming service. |
| |
| |
| <P> |
| The package and all its classes and interfaces |
| were generated by running the tool <code>idlj</code> on the file |
| <code>nameservice.idl</code>, which is a module written in OMG IDL. |
| |
| <H3>Package Specification</H3> |
| |
| <P>For a precise list of supported sections of official specifications with which |
| the Java[tm] Platform, Standard Edition 6, ORB complies, see <A |
| HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
| support in Java[tm] SE 6</A>. |
| |
| <H2>Interfaces</H2> |
| The package <code>org.omg.CosNaming</code> contains two public interfaces |
| and several auxiliary classes. |
| <P> |
| The interfaces are: |
| <UL> |
| <LI><code>NamingContext</code> |
| <LI><code>BindingIterator</code> |
| </UL> |
| <P> |
| These two interfaces provide the means to bind/unbind names and object |
| references, to retrieve bound object references, and |
| to iterate through a list of bindings. The <code>NamingContext</code> |
| interface supplies the main functionality for the naming service, and |
| <code>BindingIterator</code> provides a means of iterating through a list |
| of name/object reference bindings. |
| |
| <H2>Auxiliary Classes</H2> |
| In order to map an OMG IDL interface to the Java programming language, |
| the idlj compiler creates Java classes that can be thought of |
| as auxiliary classes. |
| Comments for the generated auxiliary classes |
| used by the interfaces <code>NamingContext</code> and |
| <code>BindingIterator</code> are included here. |
| |
| <H3>Classes Used by <code>NamingContext</code> and |
| <code>BindingIterator</code></H3> |
| The following are classes used by |
| the naming service. (Helper and holder classes, which are |
| generated for each of the classes listed here, are discussed below.) |
| |
| <UL> |
| <LI><code>public final class <B>NameComponent</B></code> -- |
| a building block for names. (Names are bound to object references |
| in a naming context.) |
| <P>A name is an array of one or more <code>NameComponent</code> objects. |
| A name with a single <code>NameComponent</code> is called |
| a <I>simple name</I>; a name with multiple <code>NameComponent</code> |
| objects is called a <I>compound name</I>. |
| <P> |
| A <code><B>NameComponent</B></code> object consists of two fields: |
| <OL> |
| <LI><code><B>id</B></code> -- a <code>String</code> used as an identifier |
| <LI><code><B>kind</B></code> -- a <code>String</code> that can be used for any |
| descriptive purpose. Its importance is that it |
| can be used to describe an object without affecting syntax. |
| The C programming language, for example, uses the the syntactic convention |
| of appending the extension ".c" to a file name to indicate that it is |
| a source code file. In a <code>NameComponent</code> object, |
| the <code>kind</code> field can be used to describe the type of object |
| rather than a file extension or some other syntactic convention. |
| Examples of the value of the <code>kind</code> field include the strings |
| <code>"c_source"</code>, <code>"object_code"</code>, |
| <code>"executable"</code>, |
| <code>"postscript"</code>, and <code>""</code>. It is not unusual |
| for the <code>kind</code> field to be the empty string. |
| </OL> |
| <P> |
| In a name, each <code>NameComponent</code> object except the last denotes |
| a <code>NamingContext</code> object; the last <code>NameComponent</code> |
| object denotes the bound object reference. |
| This is similar to a path name, in which the last name is the |
| file name, and all names before it are directory names. |
| |
| <LI><code>public final class <B>Binding</B></code> -- |
| an object that associates a name with an object reference or a |
| naming context. |
| A <code>Binding</code> object has two fields: |
| <OL> |
| <LI><code><B>binding_name</B></code> - an array of one or more |
| <code>NameComponent</code> objects that represents the bound name |
| <LI><code><B>binding_type</B></code> - a <code>BindingType</code> object |
| indicating whether the binding is between a name and an object |
| reference or between a name and a naming context |
| </OL> |
| <P> |
| The interface <code>NamingContext</code> has methods for |
| binding/unbinding names with object references or naming contexts, |
| for listing bindings, |
| and for resolving bindings (given a name, the method |
| <code>resolve</code> returns the object reference bound to it). |
| |
| <LI><code>public final class <B>BindingType</B></code> -- |
| an object that specifies whether the given <code>Binding</code> |
| object is a binding between a name and an object reference (that is, |
| not a naming context) or between a name and a naming context. |
| <P> |
| The class<code>BindingType</code> consists of two methods and |
| four constants. Two of these constants are |
| <code>BindingType</code> objects, and two are <code>int</code>s. |
| <P> |
| The <code>BindingType</code> objects |
| can be passed to the constructor for the class |
| <code>Binding</code> or used as parameters or return values. These |
| <code>BindingType</code> objects are: |
| <UL> |
| <LI><code>public static final BindingType <B>nobject</B></code> -- |
| to indicate that the binding is with an object reference |
| <LI><code>public static final BindingType <B>ncontext</B></code> -- |
| to indicate that the binding is with a naming context |
| </UL> |
| <P> |
| The <code>int</code> constants can be supplied to the method |
| <code>from_int</code> to create <code>BindingType</code> objects, |
| or they can be return values for the method <code>value</code>. |
| These constants are: |
| <UL> |
| <LI><code>public static final int <B>_nobject</B></code> |
| <LI><code>public static final int <B>_ncontext</B></code> |
| </UL> |
| If the method <code>from_int</code> is supplied with anything other |
| than <code>_nobject</code> |
| or <code>_ncontext</code>, it will throw |
| the exception <code>org.omg.CORBA.BAD_PARAM</code>. |
| <P>Usage is as follows: |
| <PRE> |
| BindingType btObject = from_int(_nobject); |
| BindingType btContext = from_int(_ncontext); |
| </PRE> |
| The variable <code>btObject</code> refers to a <code>BindingType</code> |
| object initialized to represent a binding with an object reference. |
| The variable <code>btContext</code> refers to a <code>BindingType</code> |
| object initialized to represent a binding with a |
| <code>NamingContex</code> object. |
| <P> |
| The method <code>value</code> returns either |
| <code>_nobject</code> or <code>_ncontext</code>, so |
| in the following line of code, the variable <code>bt</code> |
| will contain <code>_nobject</code> or <code>_ncontext</code>: |
| <PRE> |
| int bt = BindingType.value(); |
| </PRE> |
| </UL> |
| |
| <H3>Holder Classes</H3> |
| |
| OMG IDL uses OUT and INOUT parameters for returning values from operations. |
| The mapping to the Java programming language, which does not have OUT |
| and INOUT parameters, creates a special class for each type, called |
| a holder class. |
| An instance of a holder class can be passed to a |
| Java method as a parameter, and |
| a value can be assigned to its <code>value</code> field. This allows |
| it to perform the function of an OUT or INOUT parameter. |
| <P>The following holder classes are generated for the package |
| <code>org.omg.CosNaming</code>: |
| <UL> |
| <LI><code>NamingContextHolder</code> |
| <LI><code>BindingIteratorHolder</code> |
| <LI><code>BindingHolder</code> |
| <LI><code>BindingListHolder</code> |
| <LI><code>BindingTypeHolder</code> |
| <LI><code>NameComponentHolder</code> |
| <LI><code>NameHolder</code> |
| </UL> |
| <P> |
| Note that in the <code>org.omg.CORBA</code> package, |
| there is a holder class for each of the basic Java types: |
| <code>IntHolder</code>, <code>ShortHolder</code>, |
| <code>StringHolder</code>, and so on. |
| <P> |
| Note also that there is a <code>NameHolder</code> class even though |
| there is no <code>Name</code> class; similarly, there is a |
| <code>BindingListHolder</code> class even though there is no |
| <code>BindingList</code> class. This is true because in the OMG IDL |
| interface, <code>Name</code> and <code>BindingList</code> are |
| <code>typedef</code>s. There is no mapping from an IDL |
| <code>typedef</code> to a Java construct, but holder classes |
| are generated if the <code>typedef</code> is for a sequence or |
| an array. As mapped to the |
| Java programming language, <code>Name</code> is an array of |
| <code>NameComponent</code> objects, and a <code>BindingList</code> |
| is an array of <code>Binding</code> objects. |
| |
| All holder classes have at least two constructors and one field: |
| <UL> |
| <LI><code><B>value</B></code> field -- an instance of the type being used as |
| an OUT or INOUT parameter. For example, the <code>value</code> field of a |
| <code>NamingContextHolder</code> will be a <code>NamingContext</code> |
| object. |
| <LI>default constructor -- a constructor that creates a new holder object |
| initialized with the default value for the type. For example, a new |
| <code>BindingHolder</code> object created with the default constructor |
| will have its <code>value</code> field set to <code>null</code> because |
| that is the default value for an object. Other defaults are |
| <code>false</code> for <code>boolean</code>, |
| <code>0</code> for numeric and char types, and |
| <code>null</code> for object references. |
| <LI>constructor from an instance -- a constructor that creates a new |
| holder object whose <code>value</code> field is |
| initialized with the instance supplied |
| </UL> |
| <P> |
| A holder class for a user-defined type (a Java class) has three more |
| methods, but application developers do not use them directly. |
| |
| <H3>Helper Classes</H3> |
| Helper classes, which are generated for all user-defined types |
| in an OMG IDL interface, supply static methods needed to manipulate |
| those types. |
| <P> |
| There is only one method in a helper class that an |
| application programmer uses: the |
| method <code>narrow</code>. Only Java interfaces mapped from IDL |
| interfaces will have a helper class that includes a <code>narrow</code> |
| method, so in the <code>CosNaming</code> package, only the classes |
| <code>NamingContextHelper</code> and <code>BindingIteratorHelper</code> |
| have a <code>narrow</code> method. |
| <UL> |
| <LI><code>public static NamingContext |
| <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given |
| CORBA object to a <code>NamingContext</code> object |
| <LI><code>public static BindingIterator |
| <B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given |
| CORBA object to a <code>BindingIterator</code> object |
| </UL> |
| <H2>Package <code>org.omg.CosNaming.NamingContextPackage</code></H2> |
| This package supplies Helper and Holder classes for the exceptions used |
| in the package <code>org.omg.CosNaming</code> and also for the class |
| <code>NotFoundReason</code>, which supplies a reason for the exception |
| <code>NotFound</code>. |
| <P> |
| There are Helper and Holder classes for the following exceptions: |
| <UL> |
| <LI><code>AlreadyBound</code> |
| <LI><code>CannotProceed</code> |
| <LI><code>InvalidName</code> |
| <LI><code>NotEmpty</code> |
| <LI><code>NotFound</code> |
| </UL> |
| |
| <h2>Naming Service Compatibility</h2> |
| |
| Sun's implementation of the <code>CosNaming</code> package complies |
| with the OMG <code>COSNaming</code> specification. In other words, |
| the APIs in Sun's naming service are implemented according to the |
| guidelines for a naming service provided by OMG. Therefore, if a |
| third-party vendor has implemented a naming service that is OMG |
| compliant, it is possible to switch between Sun's implementation of |
| <code>CosNaming</code> and the third-party vendor's implementation. |
| However, it is important to understand that there can be minor |
| variations in the way different vendors implement the naming service, |
| such as differences in the exception strings. |
| |
| <h3>Instructions for Using a Third Party's Naming Service</h3> |
| Although we encourage using an ORB and ORB services that are both |
| from one vendor, it is possible to plug in a third party's |
| <code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. |
| Here are the steps to follow: |
| <OL> |
| <LI>Create a properties file for the Bootstrap server and give it |
| two entries. For example, you could call this properties file |
| <code>/tmp/services</code> and put the following in it: |
| <code>NameService, <Stringified IOR of the Root Naming Context></code>. |
| <P> |
| This associates <code>NameService</code> with the Root Naming |
| Context of the <code>CosNaming</code> implementation that you |
| want to use. |
| <LI>Start the standalone Bootstrap server using the following command: |
| <pre> |
| <code> |
| java -classpath $(CLASSPATH) |
| com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile |
| "/tmp/services" [-ORBInitialPort port] |
| </code> |
| </pre> |
| <P> |
| Note that the square brackets at the end of the command indicate that |
| specifying a port number is optional. |
| </OL> |
| <P> |
| Now when an application calls the method |
| <code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA |
| processes will contact the Bootstrap Server to get the Root Naming |
| Context. |
| |
| <h2>Package Specification</h2> |
| |
| <ul> |
| <li>Interoperable Naming Service (<a |
| href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) |
| </ul> |
| |
| <h2>Related Documentation</h2> |
| |
| For an overview and examples of how to use the |
| <code>CosNaming</code> API, please see: |
| <ul> |
| <li>{@extLink tnameserv NamingService} |
| </ul> |
| <p> |
| For an overview of Java IDL, please see: |
| <ul> |
| <li>{@extLink idl_guides Java IDL developer's home page} |
| </ul> |
| |
| @since JDK1.3 |
| |
| |
| |
| </body> |
| </html> |
| |