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 <code>list</code> 103 * method on the <code>NamingContext</code>. 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 <code>NamingContextExt</code>, 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 };