CosNaming.idl

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 // CosNaming.idl,v 1.9 2003/10/28 18:34:05 bala Exp
00003 
00004 // ============================================================================
00005 //
00006 // = LIBRARY
00007 //    cos
00008 //
00009 // = FILENAME
00010 //    CosNaming.idl
00011 //
00012 // = AUTHOR
00013 //    Marina Spivak <marina@cs.wustl.edu>
00014 //
00015 // ============================================================================
00016 
00017 #ifndef TAO_NAMING_IDL
00018 #define TAO_NAMING_IDL
00019 
00020 #pragma prefix "omg.org"
00021 
00022 module CosNaming
00023 {
00024   // = TITLE
00025   // This module provides interface for using COS Naming Service.
00026 
00027   typedef string Istring;
00028   // Define a typedef for String.  Maybe at some point, <Istring> will
00029   // be different to support Internationalization.
00030 
00031   struct NameComponent
00032   {
00033     // = TITLE
00034     //   This is a 'simple' name.
00035     //
00036     // = DESCRIPTION
00037     //   Both id and kind fields are used in resolving names.
00038 
00039     Istring id;
00040     // This is the name that is used to identify object references.
00041 
00042     Istring kind;
00043     // Stores any addtional info about the object reference.
00044   };
00045 
00046   typedef sequence <NameComponent> Name;
00047   // This is a compound name: <c1; c2; c3; cn> where c1 to cn-1 are
00048   // the names of the nested contexts, and cn is the name of the
00049   // object bound in cn-1.
00050 
00051   enum BindingType
00052   {
00053     nobject,
00054     // object binding.
00055 
00056     ncontext
00057     // Naming context binding.
00058   };
00059 
00060   struct Binding
00061   {
00062     Name binding_name;
00063     // Simple name, under which an object is bound in a given context.
00064 
00065     BindingType binding_type;
00066     // Indicates whether the binding_name identifies a context, and, therefore, can
00067     // participate in name resolution.
00068   };
00069 
00070   typedef sequence <Binding> BindingList;
00071 
00072   interface BindingIterator;
00073   // Forward declaration.
00074 
00075   interface NamingContext
00076     {
00077       // = TITLE
00078       // Interface for managing name bindings and naming contexts.
00079 
00080       // = Exceptions.
00081 
00082       enum NotFoundReason
00083       {
00084               missing_node,
00085               not_context,
00086               not_object
00087       };
00088 
00089       exception NotFound
00090             {
00091         // = TITLE
00092         //   Indicates that the name does not identify a binding.
00093 
00094               NotFoundReason why;
00095               Name rest_of_name;
00096             };
00097 
00098       exception CannotProceed
00099             {
00100         // = TITLE
00101         // Implementation may throw this exception if some reason it cannot
00102               // complete the operation.  This is currently not used in TAO.
00103 
00104               NamingContext cxt;
00105               Name rest_of_name;
00106             };
00107 
00108       exception InvalidName 
00109       {
00110         // = TITLE
00111         // A name of length 0 is invalid.  Implementations may place
00112         // further restrictions. 
00113       };
00114 
00115       exception AlreadyBound 
00116       {
00117         // = TITLE
00118         // Indicates that the specified name is already bound to
00119         // some object.  Only one object can be bound to a
00120         // particular name in an context.  To change the binding,
00121         // <rebind> and <rebind_context> can be used.
00122       };
00123 
00124       exception NotEmpty 
00125       {
00126         // = TITLE
00127         // Indicates that the context is not empty.
00128       };
00129 
00130       // = Binding operations.
00131 
00132       void bind (in Name n, in Object obj)
00133               raises (NotFound, CannotProceed, InvalidName, AlreadyBound);
00134       // Create a binding for name <n> and object <obj> in the naming
00135       // context.  Compound names are treated as follows: ctx->bind
00136       // (<c1; c2; c3; cn>, obj) = (ctx->resolve (<c1; c2;
00137       // cn-1>))->bind (<cn>, obj) if the there already exists a
00138       // binding for the specified name, <AlreadyBound> exception is
00139       // thrown.  Naming contexts should be bound using <bind_context>
00140       // and <rebind_context> in order to participate in name
00141       // resolution later.
00142 
00143       void rebind (in Name n, in Object obj)
00144               raises (NotFound, CannotProceed, InvalidName);
00145       // This is similar to <bind> operation above, except for when
00146       // the binding for the specified name already exists in the
00147       // specified context.  In that case, the existing binding is
00148       // replaced with the new one.
00149 
00150       void bind_context (in Name n, in NamingContext nc)
00151               raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
00152       // This is the version of <bind> specifically for binding naming
00153       // contexts, so that they will participate in name resolution
00154       // when compound names are passed to be resolved.
00155 
00156       void rebind_context (in Name n, in NamingContext nc)
00157               raises (NotFound, CannotProceed, InvalidName);
00158       // This is a version of <rebind> specifically for naming
00159       // contexts, so that they can participate in name resolution
00160       // when compound names are passed.
00161 
00162       // = Resolving names.
00163 
00164       Object resolve (in Name n)
00165               raises (NotFound, CannotProceed, InvalidName);
00166       // Return object reference that is bound to the name.  Compound
00167       // name resolve is defined as follows: ctx->resolve (<c1; c2;
00168       // cn>) = ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The
00169       // naming service does not return the type of the object.
00170       // Clients are responsible for "narrowing" the object to the
00171       // appropriate type.
00172 
00173       // = Unbinding names.
00174 
00175       void unbind (in Name n)
00176               raises (NotFound, CannotProceed, InvalidName);
00177       // Remove the name binding from the context.  When compound
00178       // names are used, unbind is defined as follows: ctx->unbind
00179       // (<c1; c2; cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind
00180       // (<cn>)
00181 
00182       // = Creating Naming Contexts.
00183 
00184       NamingContext new_context ();
00185       // This operation returns a new naming context implemented by
00186       // the same naming server in which the operation was invoked.
00187       // The context is not bound.
00188 
00189       NamingContext bind_new_context (in Name n)
00190               raises (NotFound, AlreadyBound, CannotProceed, InvalidName);
00191       // This operation creates a new context and binds it to the name
00192       // supplied as an argument.  The newly-created context is
00193       // implemented by the same server as the context in which it was
00194       // bound (the name argument excluding the last component).
00195 
00196       // = Deleting contexts.
00197 
00198       void destroy ()
00199               raises (NotEmpty);
00200       // Delete the naming context.  NOTE: the user should <unbind>
00201       // any bindings in which the given context is bound to some
00202       // names before invoking <destroy> operation on it. 
00203       
00204 
00205       // = Listing the naming context.
00206 
00207       void list (in unsigned long how_many,
00208                              out BindingList bl,
00209                  out BindingIterator bi);
00210       // Returns at most the requested number of bindings <how_many>
00211       // in <bl>.  If the naming context contains additional bindings,
00212       // they are returned with a BindingIterator.  In the naming
00213       // context does not contain any additional bindings <bi>
00214       // returned as null.
00215     };
00216 
00217   interface BindingIterator
00218     {
00219       // = TITLE
00220       // Interface for iterating over Bindings returned with the
00221       // <list> operation.
00222 
00223       boolean next_one (out Binding b);
00224       // This operation returns the next binding.  If there are no
00225       // more bindings false is returned.
00226 
00227       boolean next_n (in unsigned long how_many,
00228                                   out BindingList bl);
00229       // This operation returns at most the requested number of
00230       // bindings.
00231 
00232       void destroy ();
00233       // This operation destroys the iterator.
00234     };
00235 
00236   interface NamingContextExt : NamingContext 
00237     {
00238       // = TITLE
00239       // Interface for providing operations required to use URLs and
00240       // stringified names.
00241       //
00242       // Reference to: Document orbos/98-10-11 (Interoperable Naming Joint Revised Submission)
00243       // Joint Submission by BEA Systems, DSTC, IONA, and Inprise
00244 
00245       typedef string StringName;
00246       // Stringified form of a Name.
00247       
00248       typedef string Address;
00249       // URL<address> such as myhost.xyz.com.
00250       
00251       typedef string URLString;
00252       // Stringified form of a URL<address> componoent.
00253       
00254       StringName to_string (in Name n)
00255         raises (InvalidName);
00256       // This operation accepts a Name and returns a stringified
00257       // name. If the name is invalid, an InvalidName exception is
00258       // raised.
00259       
00260       Name to_name (in StringName sn)
00261         raises (InvalidName);
00262       // This operation returns a Name. If the input stringified
00263       // name is syntactically malformed or violates an
00264       // implementation limit, an InvalidName exception is
00265       // raised.
00266 
00267       exception InvalidAddress {
00268         // = TITLE
00269         // Indicates that the URL<address> is invalid.
00270       };
00271       
00272       URLString to_url (in Address addr, 
00273                         in StringName sn)
00274         raises (InvalidAddress, InvalidName);
00275       //
00276       // It performs any escapes necessary on the stringified name
00277       // and returns a fully formed URL string. An exception is
00278       // raised if either the protocol or name parameters are invalid.
00279       
00280       
00281       Object resolve_str (in StringName n)
00282         raises (NotFound, CannotProceed, InvalidName);
00283       //
00284       // This is similar to <resolve> as in the
00285       // CosNaming::NamingContext interface, except that it accepts
00286       // a stringified name as an argument instead of a Name.
00287       
00288     };
00289 };
00290 
00291 #endif /* TAO_NAMING_IDL */

Generated on Thu Nov 9 13:57:01 2006 for TAO_CosNaming by doxygen 1.3.6