1 /*
2 * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 // name.idl - Naming service interface
27 #pragma prefix "omg.org"
28
29
30 /**
31 * The CORBA COS Naming Service provides the ability to bind a name
32 * to an object relative to a naming context. A naming context is an
33 * object that contains a set of name bindings in which each name is unique.
34 * To resolve a name is to determine the object associated with the name in
35 * a given context. <p>
36 *
37 * See http://www.omg.org/technology/documents/formal/naming_service.htm
38 * for the complete CORBA
39 * COS Naming Specification. <p>
40 */
41 module CosNaming
42 {
43 typedef string Istring;
44
45 /**
46 * Many of the operations defined on a naming context take names as
47 * parameters. Names have structure. A name is an ordered sequence of
48 * components. <p>
49 *
50 * A name with a single component is called a simple name; a name with
51 * multiple components is called a compound name. Each component except
52 * the last is used to name a context; the last component denotes the
53 * bound object. <p>
54 *
55 * A name component consists of two attributes: the identifier
56 * attribute and the kind attribute. Both the identifier attribute and the
57 * kind attribute are represented as IDL strings. The kind attribute adds
58 * descriptive power to names in a syntax-independent way. Examples of the
59 * value of the kind attribute include c_source, object_code, executable,
60 * postscript, or " ".
61 */
62 struct NameComponent
63 {
64 Istring id;
65 Istring kind;
66 };
67
68 /**
69 * A name is a sequence of name components.
70 */
71 typedef sequence <NameComponent> Name;
72
73 /**
74 * Specifies whether the given binding is for a object (that is not a
75 * naming context) or for a naming context.
76 */
77 enum BindingType
78 {
79 nobject, // name is bound to an object
80 ncontext // name is bound to a naming context
81 };
82
83 /**
84 * A name-to-object association is called a Binding.
85 */
86 struct Binding
87 {
88 Name binding_name; // name
89 BindingType binding_type; // whether name is bound to an object
90 // or a naming context
91 };
92
93 /**
94 * List of Bindings.
95 */
96 typedef sequence <Binding> BindingList;
97
98 /**
99 * The BindingIterator interface allows a client to iterate through
100 * the bindings using the next_one or next_n operations.
101 *
102 * The bindings iterator is obtained by using the <tt>list</tt>
103 * method on the <tt>NamingContext</tt>.
104 * @see org.omg.CosNaming.NamingContext#list
105 */
106 interface BindingIterator
107 {
108 /**
109 * This operation returns the next binding. If there are no more
110 * bindings, false is returned.
111 *
112 * @param b the returned binding
113 */
114 boolean next_one(out Binding b);
115
116 /**
117 * This operation returns at most the requested number of bindings.
118 *
119 * @param how_many the maximum number of bindings to return
120 *
121 * @param bl the returned bindings
122 */
123 boolean next_n(in unsigned long how_many,
124 out BindingList bl);
125
126 // Destroy binding iterator
127 /**
128 * This operation destroys the iterator.
129 */
130 void destroy();
131 };
132
133 /**
134 * A naming context is an object that contains a set of name bindings in
135 * which each name is unique. Different names can be bound to an object
136 * in the same or different contexts at the same time. <p>
137 *
138 * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
139 * CORBA COS
140 * Naming Specification.</a>
141 */
142 interface NamingContext
143 {
144 // Declare exceptions
145 /**
146 * Indicates the reason for not able to resolve.
147 */
148 enum NotFoundReason
149 {
150 missing_node,
151 not_context,
152 not_object
153 };
154
155 /**
156 * Indicates the name does not identify a binding.
157 */
158 exception NotFound
159 {
160 NotFoundReason why;
161 Name rest_of_name;
162 };
163
164 /**
165 * Indicates that the implementation has given up for some reason.
166 * The client, however, may be able to continue the operation at the
167 * returned naming context.
168 */
169 exception CannotProceed
170 {
171 NamingContext cxt;
172 Name rest_of_name;
173 };
174
175 /**
176 * Indicates the name is invalid.
177 */
178 exception InvalidName
179 {};
180
181 /**
182 * Indicates an object is already bound to the specified name. Only
183 * one object can be bound to a particular name in a context.
184 */
185 exception AlreadyBound
186 {};
187
188 /**
189 * Indicates that the Naming Context contains bindings.
190 */
191 exception NotEmpty
192 {};
193
194 /**
195 * Creates a binding of a name and an object in the naming context.
196 * Naming contexts that are bound using bind do not participate in name
197 * resolution when compound names are passed to be resolved.
198 *
199 * @param n Name of the object.
200 *
201 * @param obj The Object to bind with the given name.
202 *
203 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates
204 * the name does not identify a binding.
205 *
206 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
207 * Indicates that the implementation has given up for some reason.
208 * The client, however, may be able to continue the operation
209 * at the returned naming context.
210 *
211 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName
212 * Indicates that the name is invalid.
213 *
214 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound
215 * Indicates an object is already bound to the specified name.
216 */
217 void bind(in Name n,
218 in Object obj)
219 raises(NotFound,
220 CannotProceed,
221 InvalidName,
222 AlreadyBound);
223
224 /**
225 * Names an object that is a naming context. Naming contexts that
226 * are bound using bind_context() participate in name resolution
227 * when compound names are passed to be resolved.
228 *
229 * @param n Name of the object.
230 *
231 * @param nc NamingContect object to bind with the given name.
232 *
233 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
234 *
235 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
236 * given up for some reason. The client, however, may be able to
237 * continue the operation at the returned naming context.
238 *
239 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
240 *
241 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
242 * bound to the specified name.
243 */
244 void bind_context(in Name n,
245 in NamingContext nc)
246 raises(NotFound,
247 CannotProceed,
248 InvalidName,
249 AlreadyBound);
250
251 /**
252 * Creates a binding of a name and an object in the naming context
253 * even if the name is already bound in the context. Naming contexts
254 * that are bound using rebind do not participate in name resolution
255 * when compound names are passed to be resolved.
256 *
257 * @param n Name of the object.
258 *
259 * @param obj The Object to rebind with the given name.
260 *
261 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
262 *
263 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
264 * given up for some reason. The client, however, may be able to
265 * continue the operation at the returned naming context.
266 *
267 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
268 */
269 void rebind(in Name n,
270 in Object obj)
271 raises(NotFound,
272 CannotProceed,
273 InvalidName);
274
275 /**
276 * Creates a binding of a name and a naming context in the naming
277 * context even if the name is already bound in the context. Naming
278 * contexts that are bound using rebind_context() participate in name
279 * resolution when compound names are passed to be resolved.
280 *
281 * @param n Name of the object.
282 *
283 * @param nc NamingContect object to rebind with the given name.
284 *
285 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
286 *
287 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
288 * given up for some reason. The client, however, may be able to
289 * continue the operation at the returned naming context.
290 *
291 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
292 */
293 void rebind_context(in Name n,
294 in NamingContext nc)
295 raises(NotFound,
296 CannotProceed,
297 InvalidName);
298
299 /**
300 * The resolve operation is the process of retrieving an object
301 * bound to a name in a given context. The given name must exactly
302 * match the bound name. The naming service does not return the type
303 * of the object. Clients are responsible for "narrowing" the object
304 * to the appropriate type. That is, clients typically cast the returned
305 * object from Object to a more specialized interface.
306 *
307 * @param n Name of the object.
308 *
309 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
310 *
311 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
312 * given up for some reason. The client, however, may be able to
313 * continue the operation at the returned naming context.
314 *
315 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
316 */
317 Object resolve(in Name n)
318 raises(NotFound,
319 CannotProceed,
320 InvalidName);
321
322 /**
323 * The unbind operation removes a name binding from a context.
324 *
325 * @param n Name of the object.
326 *
327 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
328 *
329 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
330 * given up for some reason. The client, however, may be able to
331 * continue the operation at the returned naming context.
332 *
333 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
334 */
335 void unbind(in Name n)
336 raises(NotFound,
337 CannotProceed,
338 InvalidName);
339
340 /**
341 * The list operation allows a client to iterate through a set of
342 * bindings in a naming context. <p>
343 *
344 * The list operation returns at most the requested number of
345 * bindings in BindingList bl.
346 * <ul>
347 * <li>If the naming context contains additional
348 * bindings, the list operation returns a BindingIterator with the
349 * additional bindings.
350 * <li>If the naming context does not contain additional
351 * bindings, the binding iterator is a nil object reference.
352 * </ul>
353 *
354 * @param how_many the maximum number of bindings to return.
355 *
356 * @param bl the returned list of bindings.
357 *
358 * @param bi the returned binding iterator.
359 */
360 void list(in unsigned long how_many,
361 out BindingList bl,
362 out BindingIterator bi);
363
364 /**
365 * This operation returns a naming context implemented by the same
366 * naming server as the context on which the operation was invoked.
367 * The new context is not bound to any name.
368 */
369 NamingContext new_context();
370
371 /**
372 * This operation creates a new context and binds it to the name
373 * supplied as an argument. The newly-created context is implemented
374 * by the same naming server as the context in which it was bound (that
375 * is, the naming server that implements the context denoted by the
376 * name argument excluding the last component).
377 *
378 * @param n Name of the object.
379 *
380 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
381 *
382 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
383 * bound to the specified name.
384 *
385 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
386 * given up for some reason. The client, however, may be able to
387 * continue the operation at the returned naming context.
388 *
389 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
390 */
391 NamingContext bind_new_context(in Name n)
392 raises(NotFound,
393 AlreadyBound,
394 CannotProceed,
395 InvalidName);
396
397 /**
398 * The destroy operation deletes a naming context. If the naming
399 * context contains bindings, the NotEmpty exception is raised.
400 *
401 * @exception org.omg.CosNaming.NamingContextPackage.NotEmpty Indicates that the Naming Context contains bindings.
402 */
403 void destroy()
404 raises(NotEmpty);
405
406 };
407
408
409 /**
410 * <code>NamingContextExt</code> is the extension of <code>NamingContext</code>
411 * which
412 * contains a set of name bindings in which each name is unique and is
413 * part of Interoperable Naming Service.
414 * Different names can be bound to an object in the same or different
415 * contexts at the same time. Using <tt>NamingContextExt</tt>, you can use
416 * URL-based names to bind and resolve.
417 *
418 * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
419 * CORBA COS
420 * Naming Specification.</a>
421 */
422 interface NamingContextExt: NamingContext
423 {
424 /**
425 * StringName is the Stringified Name, Array of Name Components
426 * represented as a String.
427 */
428 typedef string StringName;
429
430 /**
431 * Address is the Host and Port information represented as a String.
432 */
433 typedef string Address;
434
435 /**
436 * URLString is the URL address (corbaloc: or corbaname:) represented as
437 * a String.
438 */
439 typedef string URLString;
440
441 /**
442 * This operation creates a stringified name from the array of Name
443 * components.
444 *
445 * @param n Name of the object.
446 *
447 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
448 * Indicates the name does not identify a binding.
449 *
450 */
451 StringName to_string( in Name n ) raises (InvalidName);
452
453 /**
454 * This operation converts a Stringified Name into an equivalent array
455 * of Name Components.
456 *
457 * @param sn Stringified Name of the object.
458 *
459 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
460 * Indicates the name does not identify a binding.
461 *
462 */
463 Name to_name( in StringName sn ) raises (InvalidName);
464
465
466 /**
467 * Indicates the invalid Stringified name for the object, The
468 * reason could be invalid syntax.
469 */
470 exception InvalidAddress
471 { };
472
473 /**
474 * This operation creates a URL based "iiopname://" format name
475 * from the Stringified Name of the object.
476 *
477 * @param addr internet based address of the host machine where Name Service is running.
478 * @param sn Stringified Name of the object.
479 *
480 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
481 * Indicates the name does not identify a binding.
482 * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress
483 * Indicates the internet based address of the host machine is incorrect
484 */
485 URLString to_url( in Address addr, in StringName sn )
486 raises( InvalidAddress, InvalidName );
487
488
489 /**
490 * This operation resolves the Stringified name into the object
491 * reference.
492 *
493 * @param sn Stringified Name of the object.
494 *
495 * @exception org.omg.CosNaming.NamingContextPackage.NotFound
496 * Indicates there is no object reference for the given name.
497 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
498 * Indicates that the given compound name is incorrect.
499 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
500 * Indicates the name does not identify a binding.
501 *
502 */
503 Object resolve_str( in StringName sn)
504 raises( NotFound, CannotProceed,
505 InvalidName);
506
507 };
508
509 };