author | avstepan |
Sun, 13 Sep 2015 23:31:47 +0300 | |
changeset 32688 | 936c391804a5 |
parent 29827 | aac4782e69ac |
child 45443 | 57dbb6453a4d |
permissions | -rw-r--r-- |
4 | 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
2 |
<html> |
|
3 |
<head> |
|
4 |
<!-- |
|
5 |
/* |
|
29827 | 6 |
* Copyright (c) 1998, 2015, 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. |
|
29827 | 35 |
|
4 | 36 |
|
37 |
<P> |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
38 |
The package and all its classes and interfaces |
4 | 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. |
|
29827 | 41 |
|
4 | 42 |
<H3>Package Specification</H3> |
29827 | 43 |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
44 |
<P>For a precise list of supported sections of official specifications with which |
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
45 |
the Java[tm] Platform, Standard Edition 6, ORB complies, see <A |
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
46 |
HREF="../CORBA/doc-files/compliance.html">Official Specifications for CORBA |
4 | 47 |
support in Java[tm] SE 6</A>. |
29827 | 48 |
|
4 | 49 |
<H2>Interfaces</H2> |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
50 |
The package <code>org.omg.CosNaming</code> contains two public interfaces |
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
51 |
and several auxiliary classes. |
4 | 52 |
<P> |
53 |
The interfaces are: |
|
54 |
<UL> |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
55 |
<LI><code>NamingContext</code> |
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
56 |
<LI><code>BindingIterator</code> |
4 | 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. |
|
29827 | 65 |
|
4 | 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 |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
71 |
used by the interfaces <code>NamingContext</code> and |
4 | 72 |
<code>BindingIterator</code> are included here. |
29827 | 73 |
|
4 | 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.) |
|
29827 | 79 |
|
4 | 80 |
<UL> |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
81 |
<LI><code>public final class <B>NameComponent</B></code> -- |
4 | 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 |
|
29827 | 92 |
<LI><code><B>kind</B></code> -- a <code>String</code> that can be used for any |
4 | 93 |
descriptive purpose. Its importance is that it |
94 |
can be used to describe an object without affecting syntax. |
|
95 |
The C programming language, for example, uses the the syntactic convention |
|
96 |
of appending the extension ".c" to a file name to indicate that it is |
|
97 |
a source code file. In a <code>NameComponent</code> object, |
|
98 |
the <code>kind</code> field can be used to describe the type of object |
|
99 |
rather than a file extension or some other syntactic convention. |
|
100 |
Examples of the value of the <code>kind</code> field include the strings |
|
101 |
<code>"c_source"</code>, <code>"object_code"</code>, |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
102 |
<code>"executable"</code>, |
4 | 103 |
<code>"postscript"</code>, and <code>""</code>. It is not unusual |
29827 | 104 |
for the <code>kind</code> field to be the empty string. |
4 | 105 |
</OL> |
106 |
<P> |
|
107 |
In a name, each <code>NameComponent</code> object except the last denotes |
|
108 |
a <code>NamingContext</code> object; the last <code>NameComponent</code> |
|
109 |
object denotes the bound object reference. |
|
110 |
This is similar to a path name, in which the last name is the |
|
29827 | 111 |
file name, and all names before it are directory names. |
112 |
||
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
113 |
<LI><code>public final class <B>Binding</B></code> -- |
4 | 114 |
an object that associates a name with an object reference or a |
115 |
naming context. |
|
116 |
A <code>Binding</code> object has two fields: |
|
117 |
<OL> |
|
118 |
<LI><code><B>binding_name</B></code> - an array of one or more |
|
119 |
<code>NameComponent</code> objects that represents the bound name |
|
120 |
<LI><code><B>binding_type</B></code> - a <code>BindingType</code> object |
|
121 |
indicating whether the binding is between a name and an object |
|
122 |
reference or between a name and a naming context |
|
123 |
</OL> |
|
124 |
<P> |
|
125 |
The interface <code>NamingContext</code> has methods for |
|
29827 | 126 |
binding/unbinding names with object references or naming contexts, |
127 |
for listing bindings, |
|
4 | 128 |
and for resolving bindings (given a name, the method |
129 |
<code>resolve</code> returns the object reference bound to it). |
|
29827 | 130 |
|
131 |
<LI><code>public final class <B>BindingType</B></code> -- |
|
4 | 132 |
an object that specifies whether the given <code>Binding</code> |
133 |
object is a binding between a name and an object reference (that is, |
|
134 |
not a naming context) or between a name and a naming context. |
|
135 |
<P> |
|
136 |
The class<code>BindingType</code> consists of two methods and |
|
29827 | 137 |
four constants. Two of these constants are |
138 |
<code>BindingType</code> objects, and two are <code>int</code>s. |
|
139 |
<P> |
|
140 |
The <code>BindingType</code> objects |
|
4 | 141 |
can be passed to the constructor for the class |
142 |
<code>Binding</code> or used as parameters or return values. These |
|
29827 | 143 |
<code>BindingType</code> objects are: |
4 | 144 |
<UL> |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
145 |
<LI><code>public static final BindingType <B>nobject</B></code> -- |
29827 | 146 |
to indicate that the binding is with an object reference |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
147 |
<LI><code>public static final BindingType <B>ncontext</B></code> -- |
29827 | 148 |
to indicate that the binding is with a naming context |
4 | 149 |
</UL> |
150 |
<P> |
|
29827 | 151 |
The <code>int</code> constants can be supplied to the method |
152 |
<code>from_int</code> to create <code>BindingType</code> objects, |
|
153 |
or they can be return values for the method <code>value</code>. |
|
154 |
These constants are: |
|
155 |
<UL> |
|
4 | 156 |
<LI><code>public static final int <B>_nobject</B></code> |
157 |
<LI><code>public static final int <B>_ncontext</B></code> |
|
29827 | 158 |
</UL> |
4 | 159 |
If the method <code>from_int</code> is supplied with anything other |
29827 | 160 |
than <code>_nobject</code> |
4 | 161 |
or <code>_ncontext</code>, it will throw |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
162 |
the exception <code>org.omg.CORBA.BAD_PARAM</code>. |
29827 | 163 |
<P>Usage is as follows: |
4 | 164 |
<PRE> |
165 |
BindingType btObject = from_int(_nobject); |
|
166 |
BindingType btContext = from_int(_ncontext); |
|
167 |
</PRE> |
|
168 |
The variable <code>btObject</code> refers to a <code>BindingType</code> |
|
169 |
object initialized to represent a binding with an object reference. |
|
170 |
The variable <code>btContext</code> refers to a <code>BindingType</code> |
|
171 |
object initialized to represent a binding with a |
|
172 |
<code>NamingContex</code> object. |
|
173 |
<P> |
|
174 |
The method <code>value</code> returns either |
|
175 |
<code>_nobject</code> or <code>_ncontext</code>, so |
|
176 |
in the following line of code, the variable <code>bt</code> |
|
177 |
will contain <code>_nobject</code> or <code>_ncontext</code>: |
|
178 |
<PRE> |
|
179 |
int bt = BindingType.value(); |
|
180 |
</PRE> |
|
181 |
</UL> |
|
29827 | 182 |
|
4 | 183 |
<H3>Holder Classes</H3> |
29827 | 184 |
|
4 | 185 |
OMG IDL uses OUT and INOUT parameters for returning values from operations. |
186 |
The mapping to the Java programming language, which does not have OUT |
|
187 |
and INOUT parameters, creates a special class for each type, called |
|
188 |
a holder class. |
|
189 |
An instance of a holder class can be passed to a |
|
190 |
Java method as a parameter, and |
|
191 |
a value can be assigned to its <code>value</code> field. This allows |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
192 |
it to perform the function of an OUT or INOUT parameter. |
4 | 193 |
<P>The following holder classes are generated for the package |
194 |
<code>org.omg.CosNaming</code>: |
|
195 |
<UL> |
|
196 |
<LI><code>NamingContextHolder</code> |
|
197 |
<LI><code>BindingIteratorHolder</code> |
|
198 |
<LI><code>BindingHolder</code> |
|
199 |
<LI><code>BindingListHolder</code> |
|
200 |
<LI><code>BindingTypeHolder</code> |
|
201 |
<LI><code>NameComponentHolder</code> |
|
202 |
<LI><code>NameHolder</code> |
|
203 |
</UL> |
|
204 |
<P> |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
205 |
Note that in the <code>org.omg.CORBA</code> package, |
4 | 206 |
there is a holder class for each of the basic Java types: |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
207 |
<code>IntHolder</code>, <code>ShortHolder</code>, |
4 | 208 |
<code>StringHolder</code>, and so on. |
209 |
<P> |
|
210 |
Note also that there is a <code>NameHolder</code> class even though |
|
211 |
there is no <code>Name</code> class; similarly, there is a |
|
212 |
<code>BindingListHolder</code> class even though there is no |
|
213 |
<code>BindingList</code> class. This is true because in the OMG IDL |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
214 |
interface, <code>Name</code> and <code>BindingList</code> are |
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
215 |
<code>typedef</code>s. There is no mapping from an IDL |
4 | 216 |
<code>typedef</code> to a Java construct, but holder classes |
217 |
are generated if the <code>typedef</code> is for a sequence or |
|
218 |
an array. As mapped to the |
|
219 |
Java programming language, <code>Name</code> is an array of |
|
220 |
<code>NameComponent</code> objects, and a <code>BindingList</code> |
|
221 |
is an array of <code>Binding</code> objects. |
|
222 |
||
223 |
All holder classes have at least two constructors and one field: |
|
224 |
<UL> |
|
225 |
<LI><code><B>value</B></code> field -- an instance of the type being used as |
|
226 |
an OUT or INOUT parameter. For example, the <code>value</code> field of a |
|
227 |
<code>NamingContextHolder</code> will be a <code>NamingContext</code> |
|
228 |
object. |
|
229 |
<LI>default constructor -- a constructor that creates a new holder object |
|
230 |
initialized with the default value for the type. For example, a new |
|
231 |
<code>BindingHolder</code> object created with the default constructor |
|
232 |
will have its <code>value</code> field set to <code>null</code> because |
|
233 |
that is the default value for an object. Other defaults are |
|
234 |
<code>false</code> for <code>boolean</code>, |
|
235 |
<code>0</code> for numeric and char types, and |
|
236 |
<code>null</code> for object references. |
|
237 |
<LI>constructor from an instance -- a constructor that creates a new |
|
238 |
holder object whose <code>value</code> field is |
|
239 |
initialized with the instance supplied |
|
240 |
</UL> |
|
241 |
<P> |
|
242 |
A holder class for a user-defined type (a Java class) has three more |
|
243 |
methods, but application developers do not use them directly. |
|
244 |
||
245 |
<H3>Helper Classes</H3> |
|
246 |
Helper classes, which are generated for all user-defined types |
|
247 |
in an OMG IDL interface, supply static methods needed to manipulate |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
248 |
those types. |
4 | 249 |
<P> |
250 |
There is only one method in a helper class that an |
|
251 |
application programmer uses: the |
|
252 |
method <code>narrow</code>. Only Java interfaces mapped from IDL |
|
253 |
interfaces will have a helper class that includes a <code>narrow</code> |
|
254 |
method, so in the <code>CosNaming</code> package, only the classes |
|
255 |
<code>NamingContextHelper</code> and <code>BindingIteratorHelper</code> |
|
256 |
have a <code>narrow</code> method. |
|
257 |
<UL> |
|
258 |
<LI><code>public static NamingContext |
|
259 |
<B>narrow</B>(org.omg.CORBA.Object obj)</code> -- converts the given |
|
260 |
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> |
|
266 |
This package supplies Helper and Holder classes for the exceptions used |
|
267 |
in 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> |
|
271 |
There 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 |
||
282 |
Sun's implementation of the <code>CosNaming</code> package complies |
|
283 |
with the OMG <code>COSNaming</code> specification. In other words, |
|
284 |
the APIs in Sun's naming service are implemented according to the |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
285 |
guidelines for a naming service provided by OMG. Therefore, if a |
4 | 286 |
third-party vendor has implemented a naming service that is OMG |
287 |
compliant, it is possible to switch between Sun's implementation of |
|
288 |
<code>CosNaming</code> and the third-party vendor's implementation. |
|
289 |
However, it is important to understand that there can be minor |
|
290 |
variations in the way different vendors implement the naming service, |
|
291 |
such as differences in the exception strings. |
|
292 |
||
293 |
<h3>Instructions for Using a Third Party's Naming Service</h3> |
|
294 |
Although we encourage using an ORB and ORB services that are both |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
295 |
from one vendor, it is possible to plug in a third party's |
4 | 296 |
<code>COSNaming</code> implementation with Sun's RMI-IIOP ORB. |
297 |
Here are the steps to follow: |
|
298 |
<OL> |
|
299 |
<LI>Create a properties file for the Bootstrap server and give it |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
300 |
two entries. For example, you could call this properties file |
4 | 301 |
<code>/tmp/services</code> and put the following in it: |
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
302 |
<code>NameService, <Stringified IOR of the Root Naming Context></code>. |
4 | 303 |
<P> |
304 |
This associates <code>NameService</code> with the Root Naming |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
305 |
Context of the <code>CosNaming</code> implementation that you |
4 | 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> |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
320 |
Now when an application calls the method |
4 | 321 |
<code>org.omg.CORBA.ORB.resolve_initial_references</code>, CORBA |
322 |
processes will contact the Bootstrap Server to get the Root Naming |
|
323 |
Context. |
|
324 |
||
325 |
<h2>Package Specification</h2> |
|
326 |
||
327 |
<ul> |
|
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
328 |
<li>Interoperable Naming Service (<a |
23749 | 329 |
href="http://www.omg.org/cgi-bin/doc?ptc/00-08-07">ptc/00-08-07</a>) |
4 | 330 |
</ul> |
331 |
||
332 |
<h2>Related Documentation</h2> |
|
333 |
||
32688
936c391804a5
8133650: replace some <tt> tags (obsolete in html5) in CORBA docs
avstepan
parents:
29827
diff
changeset
|
334 |
For an overview and examples of how to use the |
4 | 335 |
<code>CosNaming</code> API, please see: |
336 |
<ul> |
|
337 |
<li><a href="../../../../technotes/guides/idl/tnameserv.html"> |
|
29827 | 338 |
Naming Service</a> |
4 | 339 |
</ul> |
340 |
<p> |
|
341 |
For an overview of Java IDL, please see: |
|
342 |
<ul> |
|
343 |
<li><a href="../../../../technotes/guides/idl/index.html"> |
|
29827 | 344 |
Java IDL home page</a> |
4 | 345 |
</ul> |
346 |
||
347 |
@since JDK1.3 |
|
348 |
||
349 |
||
350 |
||
351 |
</body> |
|
352 |
</html> |
|
353 |