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 */