0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A* Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A* This code is free software; you can redistribute it and/or modify it 0N/A* under the terms of the GNU General Public License version 2 only, as 0N/A* published by the Free Software Foundation. Oracle designates this 0N/A* particular file as subject to the "Classpath" exception as provided 0N/A* by Oracle in the LICENSE file that accompanied this code. 0N/A* This code is distributed in the hope that it will be useful, but WITHOUT 0N/A* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A* version 2 for more details (a copy is included in the LICENSE file that 0N/A* accompanied this code). 0N/A* You should have received a copy of the GNU General Public License version 0N/A* 2 along with this work; if not, write to the Free Software Foundation, 0N/A* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<
body bgcolor="white">
0N/A Provides a naming service for Java IDL. The Object Request Broker Daemon
0N/A (ORBD) also includes both a transient and persistent naming service.
0N/A The package and all its classes and interfaces
0N/A were generated by running the tool <
code>idlj</
code> on the file
0N/A <
H3>Package Specification</
H3>
0N/A<
P>For a precise list of supported sections of official specifications with which
0N/Athe Java[tm] Platform, Standard Edition 6, ORB complies, see <
A 0N/Asupport in Java[tm] SE 6</
A>.
0N/A and several auxiliary classes.
0N/A <
LI><
TT>NamingContext</
TT>
0N/A <
LI><
TT>BindingIterator</
TT>
0N/A These two interfaces provide the means to
bind/
unbind names and object
0N/A references, to retrieve bound object references, and
0N/A to iterate through a list of bindings. The <
code>NamingContext</
code>
0N/A interface supplies the main functionality for the naming service, and
0N/A <
code>BindingIterator</
code> provides a means of iterating through a list
0N/A <
H2>Auxiliary Classes</
H2>
0N/A In order to map an OMG IDL interface to the Java programming language,
0N/A the idlj compiler creates Java classes that can be thought of
0N/A as auxiliary classes.
0N/A Comments for the generated auxiliary classes
0N/A used by the interfaces <
code>NamingContext</
code> and
0N/A <
code>BindingIterator</
code> are included here.
0N/A <
H3>Classes Used by <
code>NamingContext</
code> and
0N/A <
code>BindingIterator</
code></
H3>
0N/A The following are classes used by
0N/A the naming service. (Helper and holder classes, which are
0N/A generated for each of the classes listed here, are discussed below.)
0N/A <
LI><
code>public final class <
B>NameComponent</
B></
code> --
0N/A a building block for names. (Names are bound to object references
0N/A in a naming context.)
0N/A <
P>A name is an array of one or more <
code>NameComponent</
code> objects.
0N/A A name with a single <
code>NameComponent</
code> is called
0N/A a <
I>simple name</
I>; a name with multiple <
code>NameComponent</
code>
0N/A objects is called a <
I>compound name</
I>.
0N/A A <
code><
B>NameComponent</
B></
code> object consists of two fields:
0N/A <
LI><
code><
B>id</
B></
code> -- a <
code>String</
code> used as an identifier
0N/A <
LI><
code><
B>kind</
B></
code> -- a <
code>String</
code> that can be used for
0N/A descriptive purpose. Its importance is that it
0N/A can be used to describe an object without affecting syntax.
0N/A The C programming language, for example, uses the the syntactic convention
0N/A of appending the extension ".c" to a file name to indicate that it is
0N/A a source code file. In a <
code>NameComponent</
code> object,
0N/A the <
code>kind</
code> field can be used to describe the type of object
0N/A rather than a file extension or some other syntactic convention.
0N/A Examples of the value of the <
code>kind</
code> field include the strings
0N/A <
code>"c_source"</
code>, <
code>"object_code"</
code>,
0N/A <
code>"executable"</
code>,
0N/A <
code>"postscript"</
code>, and <
code>""</
code>. It is not unusual
0N/A for the <
code>kind</
code> field to be the empty string.
0N/A In a name, each <
code>NameComponent</
code> object except the last denotes
0N/A a <
code>NamingContext</
code> object; the last <
code>NameComponent</
code>
0N/A object denotes the bound object reference.
0N/A This is similar to a path name, in which the last name is the
0N/A file name, and all names before it are directory names.<
p>
0N/A <
LI><
code>public final class <
B>Binding</
B></
code> --
0N/A an object that associates a name with an object reference or a
0N/A A <
code>Binding</
code> object has two fields:
0N/A <
LI><
code><
B>binding_name</
B></
code> - an array of one or more
0N/A <
code>NameComponent</
code> objects that represents the bound name
0N/A <
LI><
code><
B>binding_type</
B></
code> - a <
code>BindingType</
code> object
0N/A indicating whether the binding is between a name and an object
0N/A reference or between a name and a naming context
0N/A The interface <
code>NamingContext</
code> has methods for
0N/A for listing bindings,
0N/A and for resolving bindings (given a name, the method
0N/A <
code>resolve</
code> returns the object reference bound to it).
0N/A <
LI><
code>public final class <
B>BindingType</
B></
code> --
0N/A an object that specifies whether the given <
code>Binding</
code>
0N/A object is a binding between a name and an object reference (that is,
0N/A not a naming context) or between a name and a naming context.
0N/A The class<
code>BindingType</
code> consists of two methods and
0N/A four constants. Two of these constants are
0N/A <
code>BindingType</
code> objects, and two are <
code>int</
code>s.
0N/A The <
code>BindingType</
code> objects
0N/A can be passed to the constructor for the class
0N/A <
code>Binding</
code> or used as parameters or return values. These
0N/A <
code>BindingType</
code> objects are:
0N/A <
LI><
code>public static final BindingType <
B>nobject</
B></
code> --
0N/A 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
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>.
<
LI><
code>public static final int <
B>_nobject</
B></
code>
<
LI><
code>public static final int <
B>_ncontext</
B></
code>
If the method <
code>from_int</
code> is supplied with anything other
than <
code>_nobject</
code>
or <
code>_ncontext</
code>, it will throw
BindingType btObject = from_int(_nobject);
BindingType btContext = from_int(_ncontext);
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.
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>:
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
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
<
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>
there is a holder class for each of the basic Java types:
<
code>IntHolder</
code>, <
code>ShortHolder</
code>,
<
code>StringHolder</
code>, and so on.
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:
<
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>
<
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
A holder class for a user-defined type (a Java class) has three more
methods, but application developers do not use them directly.
Helper classes, which are generated for all user-defined types
in an OMG IDL interface, supply static methods needed to manipulate
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.
<
LI><
code>public static NamingContext
CORBA object to a <
code>NamingContext</
code> object
<
LI><
code>public static BindingIterator
CORBA object to a <
code>BindingIterator</
code> object
This package supplies Helper and Holder classes for the exceptions used
<
code>NotFoundReason</
code>, which supplies a reason for the exception
There are Helper and Holder classes for the following exceptions:
<
LI><
code>AlreadyBound</
code>
<
LI><
code>CannotProceed</
code>
<
LI><
code>InvalidName</
code>
<
LI><
code>NotEmpty</
code>
<
LI><
code>NotFound</
code>
<
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:
<
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
This associates <
code>NameService</
code> with the Root Naming
Context of the <
code>CosNaming</
code> implementation that you
<
LI>Start the standalone Bootstrap server using the following command:
java -classpath $(CLASSPATH)
Note that the square brackets at the end of the command indicate that
specifying a port number is optional.
Now when an application calls the method
processes will contact the Bootstrap Server to get the Root Naming
<
h2>Package Specification</
h2>
<
li>Interoperable Naming Service (<
a <
h2>Related Documentation</
h2>
For an overview and examples of how to use the
<
code>CosNaming</
code> API, please see:
For an overview of Java IDL, please see:
Java IDL home page</
a>