1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/org/omg/CosNaming/nameservice.idl Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,511 @@
1.4 +/*
1.5 + * Copyright 1996-2002 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +// name.idl - Naming service interface
1.30 +#pragma prefix "omg.org"
1.31 +
1.32 +
1.33 +/**
1.34 + * The CORBA COS Naming Service provides the ability to bind a name
1.35 + * to an object relative to a naming context. A naming context is an
1.36 + * object that contains a set of name bindings in which each name is unique.
1.37 + * To resolve a name is to determine the object associated with the name in
1.38 + * a given context. <p>
1.39 + *
1.40 + * See http://www.omg.org/technology/documents/formal/naming_service.htm
1.41 + * for the complete CORBA
1.42 + * COS Naming Specification. <p>
1.43 + */
1.44 +module CosNaming
1.45 +{
1.46 + typedef string Istring;
1.47 +
1.48 + /**
1.49 + * Many of the operations defined on a naming context take names as
1.50 + * parameters. Names have structure. A name is an ordered sequence of
1.51 + * components. <p>
1.52 + *
1.53 + * A name with a single component is called a simple name; a name with
1.54 + * multiple components is called a compound name. Each component except
1.55 + * the last is used to name a context; the last component denotes the
1.56 + * bound object. <p>
1.57 + *
1.58 + * A name component consists of two attributes: the identifier
1.59 + * attribute and the kind attribute. Both the identifier attribute and the
1.60 + * kind attribute are represented as IDL strings. The kind attribute adds
1.61 + * descriptive power to names in a syntax-independent way. Examples of the
1.62 + * value of the kind attribute include c_source, object_code, executable,
1.63 + * postscript, or " ".
1.64 + */
1.65 + struct NameComponent
1.66 + {
1.67 + Istring id;
1.68 + Istring kind;
1.69 + };
1.70 +
1.71 + /**
1.72 + * A name is a sequence of name components.
1.73 + */
1.74 + typedef sequence <NameComponent> Name;
1.75 +
1.76 + /**
1.77 + * Specifies whether the given binding is for a object (that is not a
1.78 + * naming context) or for a naming context.
1.79 + */
1.80 + enum BindingType
1.81 + {
1.82 + nobject, // name is bound to an object
1.83 + ncontext // name is bound to a naming context
1.84 + };
1.85 +
1.86 + /**
1.87 + * A name-to-object association is called a Binding.
1.88 + */
1.89 + struct Binding
1.90 + {
1.91 + Name binding_name; // name
1.92 + BindingType binding_type; // whether name is bound to an object
1.93 + // or a naming context
1.94 + };
1.95 +
1.96 + /**
1.97 + * List of Bindings.
1.98 + */
1.99 + typedef sequence <Binding> BindingList;
1.100 +
1.101 + /**
1.102 + * The BindingIterator interface allows a client to iterate through
1.103 + * the bindings using the next_one or next_n operations.
1.104 + *
1.105 + * The bindings iterator is obtained by using the <tt>list</tt>
1.106 + * method on the <tt>NamingContext</tt>.
1.107 + * @see org.omg.CosNaming.NamingContext#list
1.108 + */
1.109 + interface BindingIterator
1.110 + {
1.111 + /**
1.112 + * This operation returns the next binding. If there are no more
1.113 + * bindings, false is returned.
1.114 + *
1.115 + * @param b the returned binding
1.116 + */
1.117 + boolean next_one(out Binding b);
1.118 +
1.119 + /**
1.120 + * This operation returns at most the requested number of bindings.
1.121 + *
1.122 + * @param how_many the maximum number of bindings tro return <p>
1.123 + *
1.124 + * @param bl the returned bindings
1.125 + */
1.126 + boolean next_n(in unsigned long how_many,
1.127 + out BindingList bl);
1.128 +
1.129 + // Destroy binding iterator
1.130 + /**
1.131 + * This operation destroys the iterator.
1.132 + */
1.133 + void destroy();
1.134 + };
1.135 +
1.136 +/**
1.137 + * A naming context is an object that contains a set of name bindings in
1.138 + * which each name is unique. Different names can be bound to an object
1.139 + * in the same or different contexts at the same time. <p>
1.140 + *
1.141 + * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
1.142 + * CORBA COS
1.143 + * Naming Specification.</a>
1.144 + */
1.145 + interface NamingContext
1.146 + {
1.147 + // Declare exceptions
1.148 + /**
1.149 + * Indicates the reason for not able to resolve.
1.150 + */
1.151 + enum NotFoundReason
1.152 + {
1.153 + missing_node,
1.154 + not_context,
1.155 + not_object
1.156 + };
1.157 +
1.158 +/**
1.159 + * Indicates the name does not identify a binding.
1.160 + */
1.161 + exception NotFound
1.162 + {
1.163 + NotFoundReason why;
1.164 + Name rest_of_name;
1.165 + };
1.166 +
1.167 +/**
1.168 + * Indicates that the implementation has given up for some reason.
1.169 + * The client, however, may be able to continue the operation at the
1.170 + * returned naming context.
1.171 + */
1.172 + exception CannotProceed
1.173 + {
1.174 + NamingContext cxt;
1.175 + Name rest_of_name;
1.176 + };
1.177 +
1.178 +/**
1.179 + * Indicates the name is invalid.
1.180 + */
1.181 + exception InvalidName
1.182 + {};
1.183 +
1.184 +/**
1.185 + * Indicates an object is already bound to the specified name. Only
1.186 + * one object can be bound to a particular name in a context.
1.187 + */
1.188 + exception AlreadyBound
1.189 + {};
1.190 +
1.191 +/**
1.192 + * Indicates that the Naming Context contains bindings.
1.193 + */
1.194 + exception NotEmpty
1.195 + {};
1.196 +
1.197 +/**
1.198 + * Creates a binding of a name and an object in the naming context.
1.199 + * Naming contexts that are bound using bind do not participate in name
1.200 + * resolution when compound names are passed to be resolved.
1.201 + *
1.202 + * @param n Name of the object <p>
1.203 + *
1.204 + * @param obj The Object to bind with the given name<p>
1.205 + *
1.206 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates
1.207 + * the name does not identify a binding.<p>
1.208 + *
1.209 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
1.210 + * Indicates that the implementation has given up for some reason.
1.211 + * The client, however, may be able to continue the operation
1.212 + * at the returned naming context.<p>
1.213 + *
1.214 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName
1.215 + * Indicates that the name is invalid. <p>
1.216 + *
1.217 + * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound
1.218 + * Indicates an object is already bound to the specified name.<p>
1.219 + */
1.220 + void bind(in Name n,
1.221 + in Object obj)
1.222 + raises(NotFound,
1.223 + CannotProceed,
1.224 + InvalidName,
1.225 + AlreadyBound);
1.226 +
1.227 +/**
1.228 + * Names an object that is a naming context. Naming contexts that
1.229 + * are bound using bind_context() participate in name resolution
1.230 + * when compound names are passed to be resolved.
1.231 + *
1.232 + * @param n Name of the object <p>
1.233 + *
1.234 + * @param nc NamingContect object to bind with the given name <p>
1.235 + *
1.236 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.237 + *
1.238 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.239 + * given up for some reason. The client, however, may be able to
1.240 + * continue the operation at the returned naming context.<p>
1.241 + *
1.242 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.243 + *
1.244 + * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
1.245 + * bound to the specified name.<p>
1.246 + */
1.247 + void bind_context(in Name n,
1.248 + in NamingContext nc)
1.249 + raises(NotFound,
1.250 + CannotProceed,
1.251 + InvalidName,
1.252 + AlreadyBound);
1.253 +
1.254 +/**
1.255 + * Creates a binding of a name and an object in the naming context
1.256 + * even if the name is already bound in the context. Naming contexts
1.257 + * that are bound using rebind do not participate in name resolution
1.258 + * when compound names are passed to be resolved.
1.259 + *
1.260 + * @param n Name of the object <p>
1.261 + *
1.262 + * @parm obj The Object to rebind with the given name <p>
1.263 + *
1.264 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.265 + *
1.266 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.267 + * given up for some reason. The client, however, may be able to
1.268 + * continue the operation at the returned naming context.<p>
1.269 + *
1.270 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.271 + */
1.272 + void rebind(in Name n,
1.273 + in Object obj)
1.274 + raises(NotFound,
1.275 + CannotProceed,
1.276 + InvalidName);
1.277 +
1.278 +/**
1.279 + * Creates a binding of a name and a naming context in the naming
1.280 + * context even if the name is already bound in the context. Naming
1.281 + * contexts that are bound using rebind_context() participate in name
1.282 + * resolution when compound names are passed to be resolved.
1.283 + *
1.284 + * @param n Name of the object <p>
1.285 + *
1.286 + * @param nc NamingContect object to rebind with the given name <p>
1.287 + *
1.288 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.289 + *
1.290 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.291 + * given up for some reason. The client, however, may be able to
1.292 + * continue the operation at the returned naming context.<p>
1.293 + *
1.294 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.295 + */
1.296 + void rebind_context(in Name n,
1.297 + in NamingContext nc)
1.298 + raises(NotFound,
1.299 + CannotProceed,
1.300 + InvalidName);
1.301 +
1.302 +/**
1.303 + * The resolve operation is the process of retrieving an object
1.304 + * bound to a name in a given context. The given name must exactly
1.305 + * match the bound name. The naming service does not return the type
1.306 + * of the object. Clients are responsible for "narrowing" the object
1.307 + * to the appropriate type. That is, clients typically cast the returned
1.308 + * object from Object to a more specialized interface.
1.309 + *
1.310 + * @param n Name of the object <p>
1.311 + *
1.312 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.313 + *
1.314 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.315 + * given up for some reason. The client, however, may be able to
1.316 + * continue the operation at the returned naming context.<p>
1.317 + *
1.318 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.319 + */
1.320 + Object resolve(in Name n)
1.321 + raises(NotFound,
1.322 + CannotProceed,
1.323 + InvalidName);
1.324 +
1.325 +/**
1.326 + * The unbind operation removes a name binding from a context.
1.327 + *
1.328 + * @param n Name of the object <p>
1.329 + *
1.330 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.331 + *
1.332 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.333 + * given up for some reason. The client, however, may be able to
1.334 + * continue the operation at the returned naming context.<p>
1.335 + *
1.336 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.337 + */
1.338 + void unbind(in Name n)
1.339 + raises(NotFound,
1.340 + CannotProceed,
1.341 + InvalidName);
1.342 +
1.343 +/**
1.344 + * The list operation allows a client to iterate through a set of
1.345 + * bindings in a naming context. <p>
1.346 + *
1.347 + * The list operation returns at most the requested number of
1.348 + * bindings in BindingList bl.
1.349 + * <ul>
1.350 + * <li>If the naming context contains additional
1.351 + * bindings, the list operation returns a BindingIterator with the
1.352 + * additional bindings.
1.353 + * <li>If the naming context does not contain additional
1.354 + * bindings, the binding iterator is a nil object reference.
1.355 + * </ul>
1.356 + *
1.357 + * @param how_many the maximum number of bindings to return <p>
1.358 + *
1.359 + * @param bl the returned list of bindings <p>
1.360 + *
1.361 + * @param bi the returned binding iterator <p>
1.362 + */
1.363 + void list(in unsigned long how_many,
1.364 + out BindingList bl,
1.365 + out BindingIterator bi);
1.366 +
1.367 +/**
1.368 + * This operation returns a naming context implemented by the same
1.369 + * naming server as the context on which the operation was invoked.
1.370 + * The new context is not bound to any name.
1.371 + */
1.372 + NamingContext new_context();
1.373 +
1.374 +/**
1.375 + * This operation creates a new context and binds it to the name
1.376 + * supplied as an argument. The newly-created context is implemented
1.377 + * by the same naming server as the context in which it was bound (that
1.378 + * is, the naming server that implements the context denoted by the
1.379 + * name argument excluding the last component).
1.380 + *
1.381 + * @param n Name of the object <p>
1.382 + *
1.383 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.<p>
1.384 + *
1.385 + * @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
1.386 + * bound to the specified name.<p>
1.387 + *
1.388 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
1.389 + * given up for some reason. The client, however, may be able to
1.390 + * continue the operation at the returned naming context.<p>
1.391 + *
1.392 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid. <p>
1.393 + */
1.394 + NamingContext bind_new_context(in Name n)
1.395 + raises(NotFound,
1.396 + AlreadyBound,
1.397 + CannotProceed,
1.398 + InvalidName);
1.399 +
1.400 +/**
1.401 + * The destroy operation deletes a naming context. If the naming
1.402 + * context contains bindings, the NotEmpty exception is raised.
1.403 + *
1.404 + * @exception org.omg.CosNaming.NamingContextPackage.NotEmpty Indicates that the Naming Context contains bindings.
1.405 + */
1.406 + void destroy()
1.407 + raises(NotEmpty);
1.408 +
1.409 + };
1.410 +
1.411 +
1.412 +/**
1.413 + * <code>NamingContextExt</code> is the extension of <code>NamingContext</code>
1.414 + * which
1.415 + * contains a set of name bindings in which each name is unique and is
1.416 + * part of Interoperable Naming Service.
1.417 + * Different names can be bound to an object in the same or different
1.418 + * contexts at the same time. Using <tt>NamingContextExt</tt>, you can use
1.419 + * URL-based names to bind and resolve. <p>
1.420 + *
1.421 + * See <a href="http://www.omg.org/technology/documents/formal/naming_service.htm">
1.422 + * CORBA COS
1.423 + * Naming Specification.</a>
1.424 + */
1.425 + interface NamingContextExt: NamingContext
1.426 + {
1.427 +/**
1.428 + * StringName is the Stringified Name, Array of Name Components
1.429 + * represented as a String.
1.430 + */
1.431 + typedef string StringName;
1.432 +
1.433 +/**
1.434 + * Address is the Host and Port information represented as a String.
1.435 + */
1.436 + typedef string Address;
1.437 +
1.438 +/**
1.439 + * URLString is the URL address (corbaloc: or corbaname:) represented as
1.440 + * a String.
1.441 + */
1.442 + typedef string URLString;
1.443 +
1.444 +/**
1.445 + * This operation creates a stringified name from the array of Name
1.446 + * components.
1.447 + *
1.448 + * @param n Name of the object <p>
1.449 + *
1.450 + * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
1.451 + * Indicates the name does not identify a binding.<p>
1.452 + *
1.453 + */
1.454 + StringName to_string( in Name n ) raises (InvalidName);
1.455 +
1.456 +/**
1.457 + * This operation converts a Stringified Name into an equivalent array
1.458 + * of Name Components.
1.459 + *
1.460 + * @param sn Stringified Name of the object <p>
1.461 + *
1.462 + * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
1.463 + * Indicates the name does not identify a binding.<p>
1.464 + *
1.465 + */
1.466 + Name to_name( in StringName sn ) raises (InvalidName);
1.467 +
1.468 +
1.469 +/**
1.470 + * Indicates the invalid Stringified name for the object, The
1.471 + * reason could be invalid syntax.
1.472 + */
1.473 + exception InvalidAddress
1.474 + { };
1.475 +
1.476 +/**
1.477 + * This operation creates a URL based "iiopname://" format name
1.478 + * from the Stringified Name of the object.
1.479 + *
1.480 + * @param addr internet based address of the host machine where Name Service is running <p>
1.481 + * @param sn Stringified Name of the object <p>
1.482 + *
1.483 + * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
1.484 + * Indicates the name does not identify a binding.<p>
1.485 + * @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress
1.486 + * Indicates the internet based address of the host machine is
1.487 + * incorrect <p>
1.488 + *
1.489 + */
1.490 + URLString to_url( in Address addr, in StringName sn )
1.491 + raises( InvalidAddress, InvalidName );
1.492 +
1.493 +
1.494 +/**
1.495 + * This operation resolves the Stringified name into the object
1.496 + * reference.
1.497 + *
1.498 + * @param sn Stringified Name of the object <p>
1.499 + *
1.500 + * @exception org.omg.CosNaming.NamingContextPackage.NotFound
1.501 + * Indicates there is no object reference for the given name. <p>
1.502 + * @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
1.503 + * Indicates that the given compound name is incorrect <p>
1.504 + * @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
1.505 + * Indicates the name does not identify a binding.<p>
1.506 + *
1.507 + */
1.508 + Object resolve_str( in StringName sn)
1.509 + raises( NotFound, CannotProceed,
1.510 + InvalidName);
1.511 +
1.512 + };
1.513 +
1.514 +};
