|
1 /* |
|
2 * Copyright 1996-2002 Sun Microsystems, Inc. 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. Sun designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any 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 tro return <p> |
|
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 <p> |
|
200 * |
|
201 * @param obj The Object to bind with the given name<p> |
|
202 * |
|
203 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates |
|
204 * the name does not identify a binding.<p> |
|
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.<p> |
|
210 * |
|
211 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName |
|
212 * Indicates that the name is invalid. <p> |
|
213 * |
|
214 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound |
|
215 * Indicates an object is already bound to the specified name.<p> |
|
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 <p> |
|
230 * |
|
231 * @param nc NamingContect object to bind with the given name <p> |
|
232 * |
|
233 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
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.<p> |
|
238 * |
|
239 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
240 * |
|
241 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already |
|
242 * bound to the specified name.<p> |
|
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 <p> |
|
258 * |
|
259 * @parm obj The Object to rebind with the given name <p> |
|
260 * |
|
261 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
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.<p> |
|
266 * |
|
267 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
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 <p> |
|
282 * |
|
283 * @param nc NamingContect object to rebind with the given name <p> |
|
284 * |
|
285 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
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.<p> |
|
290 * |
|
291 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
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 <p> |
|
308 * |
|
309 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
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.<p> |
|
314 * |
|
315 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
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 <p> |
|
326 * |
|
327 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
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.<p> |
|
332 * |
|
333 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
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 <p> |
|
355 * |
|
356 * @param bl the returned list of bindings <p> |
|
357 * |
|
358 * @param bi the returned binding iterator <p> |
|
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 <p> |
|
379 * |
|
380 * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p> |
|
381 * |
|
382 * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already |
|
383 * bound to the specified name.<p> |
|
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.<p> |
|
388 * |
|
389 * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p> |
|
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. <p> |
|
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 <p> |
|
446 * |
|
447 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName |
|
448 * Indicates the name does not identify a binding.<p> |
|
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 <p> |
|
458 * |
|
459 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName |
|
460 * Indicates the name does not identify a binding.<p> |
|
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 <p> |
|
478 * @param sn Stringified Name of the object <p> |
|
479 * |
|
480 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName |
|
481 * Indicates the name does not identify a binding.<p> |
|
482 * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress |
|
483 * Indicates the internet based address of the host machine is |
|
484 * incorrect <p> |
|
485 * |
|
486 */ |
|
487 URLString to_url( in Address addr, in StringName sn ) |
|
488 raises( InvalidAddress, InvalidName ); |
|
489 |
|
490 |
|
491 /** |
|
492 * This operation resolves the Stringified name into the object |
|
493 * reference. |
|
494 * |
|
495 * @param sn Stringified Name of the object <p> |
|
496 * |
|
497 * @exception org.omg.CosNaming.NamingContextPackage.NotFound |
|
498 * Indicates there is no object reference for the given name. <p> |
|
499 * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed |
|
500 * Indicates that the given compound name is incorrect <p> |
|
501 * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName |
|
502 * Indicates the name does not identify a binding.<p> |
|
503 * |
|
504 */ |
|
505 Object resolve_str( in StringName sn) |
|
506 raises( NotFound, CannotProceed, |
|
507 InvalidName); |
|
508 |
|
509 }; |
|
510 |
|
511 }; |