Mercurial > jdk8-mips64-public > corba / file revision
src/share/classes/org/omg/CosNaming/package.html@abe5b0157c36
src/share/classes/org/omg/CosNaming/package.html
Wed, 26 Feb 2014 14:43:56 -0800
- author
- katleman
- date
- Wed, 26 Feb 2014 14:43:56 -0800
- changeset 589
- abe5b0157c36
- parent 158
- 91006f157c46
- child 748
- 6845b95cba6b
- permissions
- -rw-r--r--
Added tag jdk8u20-b03 for changeset 9059a1c85704
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2 <html>
3 <head>
4 <!--
5 /*
6 * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
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
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 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, <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.
330 <h2>Package Specification</h2>
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>
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 IDL, please see:
347 <ul>
348 <li><a href="../../../../technotes/guides/idl/index.html">
349 Java IDL home page</a>
350 </ul>
352 @since JDK1.3
356 </body>
357 </html>
