|
4
|
1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
|
2 |
<html>
|
|
|
3 |
<head>
|
|
|
4 |
<!--
|
|
|
5 |
/*
|
|
5555
|
6 |
* Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
|
|
4
|
7 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
|
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
|
|
5555
|
11 |
* published by the Free Software Foundation. Oracle designates this
|
|
4
|
12 |
* particular file as subject to the "Classpath" exception as provided
|
|
5555
|
13 |
* by Oracle in the LICENSE file that accompanied this code.
|
|
4
|
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 |
*
|
|
5555
|
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.
|
|
4
|
28 |
*/
|
|
|
29 |
-->
|
|
|
30 |
</head>
|
|
|
31 |
<body bgcolor="white">
|
|
|
32 |
|
|
|
33 |
Provides a naming service for Java IDL. The Object Request Broker Daemon
|
|
|
34 |
(ORBD) also includes both a transient and persistent naming service.
|
|
|
35 |
|
|
|
36 |
|
|
|
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.
|
|
|
41 |
|
|
|
42 |
<H3>Package Specification</H3>
|
|
|
43 |
|
|
|
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.)
|
|
|
79 |
|
|
|
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>
|
|
|
114 |
|
|
|
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).
|
|
|
132 |
|
|
|
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>
|
|
|
185 |
|
|
|
186 |
<H3>Holder Classes</H3>
|
|
|
187 |
|
|
|
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.
|
|
|
225 |
|
|
|
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.
|
|
|
247 |
|
|
|
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>
|
|
|
282 |
|
|
|
283 |
<h2>Naming Service Compatibility</h2>
|
|
|
284 |
|
|
|
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.
|
|
|
295 |
|
|
|
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, <Stringified IOR of the Root Naming
|
|
|
306 |
Context></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.
|
|
|
329 |
|
|
|
330 |
<h2>Package Specification</h2>
|
|
|
331 |
|
|
|
332 |
<ul>
|
|
|
333 |
<li>Interoperable Naming Service (<a
|
|
|
334 |
href="http://cgi.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>)
|
|
|
335 |
</ul>
|
|
|
336 |
|
|
|
337 |
<h2>Related Documentation</h2>
|
|
|
338 |
|
|
|
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 IDL, please see:
|
|
|
347 |
<ul>
|
|
|
348 |
<li><a href="../../../../technotes/guides/idl/index.html">
|
|
|
349 |
Java IDL home page</a>
|
|
|
350 |
</ul>
|
|
|
351 |
|
|
|
352 |
@since JDK1.3
|
|
|
353 |
|
|
|
354 |
|
|
|
355 |
|
|
|
356 |
</body>
|
|
|
357 |
</html>
|
|
|
358 |
|