1corba(3) Erlang Module Definition corba(3)
2
6 corba - The functions on CORBA module level
7
9 This module contains functions that are specified on the CORBA module
10 level. It also contains some functions for creating and disposing
11 objects.
12
14 create(Module, TypeID) -> Object
15 create(Module, TypeID, Env) -> Object
16 create(Module, TypeID, Env, Optons1) -> Object
17 create_link(Module, TypeID) -> Object
18 create_link(Module, TypeID, Env) -> Object
19 create_link(Module, TypeID, Env, Options2) -> Reply
20 Types:
22 Module = atom()
24 TypeID = string()
25 Env = term()
26 Options1 = [{persistent, Bool} | {regname, RegName} |
27 {local_typecheck, Bool}]
28 Options2 = [{sup_child, Bool} | {persistent, Bool} | {reg‐
29 name, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]
30 RegName = {local, atom()} | {global, term()}
31 Reply = #objref | {ok, Pid, #objref}
32 Bool = true | false
33 Object = #objref
34 These functions start a new server object. If you start it with‐
36 out RegName it can only be accessed through the returned object
37 key. Started with a RegName the name is registered locally or
38 globally.
39 TypeID is the repository ID of the server object type and could
41 for example look like "IDL:StackModule/Stack:1.0".
42 Module is the name of the interface API module.
44 Env is the arguments passed which will be passed to the imple‐
46 mentations init call-back function.
47 A server started with create/2, create/3 or create/4 does not
49 care about the parent, which means that the parent is not han‐
50 dled explicitly in the generic process part.
51 A server started with create_link2, create_link/3 or cre‐
53 ate_link/4 is initially linked to the caller, the parent, and it
54 will terminate whenever the parent process terminates, and with
55 the same reason as the parent. If the server traps exits, the
56 terminate/2 call-back function is called in order to clean up
57 before the termination. These functions should be used if the
58 server is a worker in a supervision tree.
59 If you use the option {sup_child, true} create_link/4 will
61 return {ok, Pid, #objref}, otherwise #objref, and make it possi‐
62 ble to start a server as a supervisor child (stdlib-1.7 or
63 later).
64 If you use the option {persistent, true} you also must use the
66 option {regname, {global, Name}}. This combination makes it pos‐
67 sible to tell the difference between a server permanently termi‐
68 nated or in the process of restarting.
69 The option {pseudo, true}, allow us to create an object which is
71 not a server. Using {pseudo, true} overrides all other start
72 options. For more information see section Module_Interface.
73 If a server is started using the option {persistent, true} the
75 object key will not be removed unless it terminates with reason
76 normal or shutdown. Hence, if persistent servers is used as
77 supervisor children they should be transient and the objec‐
78 tkeys_gc_time should be modified (default equals infinity).
79 The option {local_typecheck, boolean()}, which overrides the
81 Local Typechecking environment flag, turns on or off typecheck‐
82 ing. If activated, parameters, replies and raised exceptions
83 will be checked to ensure that the data is correct, when invok‐
84 ing operations on CORBA Objects within the same Orber domain.
85 Due to the extra overhead, this option MAY ONLY be used during
86 testing and development.
87 Example:
89 corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})
91 dispose(Object) -> ok
94 Types:
96 Object = #objref
98 This function is used for terminating the execution of a server
100 object. Invoking this operation on a NIL object reference, e.g.,
101 the return value of corba:create_nil_objref/0, always return ok.
102 For valid object references, invoking this operation more than
103 once, will result in a system exception.
104 create_nil_objref() -> Object
106 Types:
108 Object = #objref representing NIL.
110 Creates an object reference that represents the NIL value.
112 Attempts to invoke operations using the returned object refer‐
113 ence will return a system exception.
114 create_subobject_key(Object, Key) -> Result
116 Types:
118 Object = #objref
120 Key = term()
121 Result = #objref
122 This function is used to create a subobject in a server object.
124 It can for example be useful when one wants unique access to
125 separate rows in a mnesia or an ETS table. The Result is an
126 object reference that will be seen as a unique reference to the
127 outside world but will access the same server object where one
128 can use the get_subobject_key/1 function to get the private key
129 value.
130 Key is stored in the object reference Object. If it is a binary
132 it will be stored as is and otherwise it is converted to a
133 binary before storage.
134 get_subobject_key(Object) -> Result
136 Types:
138 Object = #objref
140 Result = #binary
141 This function is used to fetch a subobject key from the object
143 reference Object. The result is a always a binary, if it was an
144 Erlang term that was stored with create_subobject_key/2 one can
145 to do binary_to_term/1 to get the real value.
146 get_pid(Object) -> Result
148 Types:
150 Object = #objref
152 Result = #pid | {error, Reason} | {'EXCEPTION',E}
153 This function is to get the process id from an object, which is
155 a must when CORBA objects is started/handled in a supervisor
156 tree. The function will throw exceptions if the key is not found
157 or some other error occurs.
158 raise(Exception)
160 Types:
162 Exception = record()
164 This function is used for raising corba exceptions as an Erlang
166 user generated exit signal. It will throw the tuple {'EXCEP‐
167 TION', Exception}.
168 reply(To, Reply) -> true
170 Types:
172 To = client reference
174 Reply = IDL type
175 This function can be used by a CORBA object to explicitly send a
177 reply to a client that invoked a two-way operation. If this
178 operation is used, it is not possible to return a reply in the
179 call-back module.
180 To must be the From argument provided to the callback function,
181 which requires that the IC option from was used when compiling
182 the IDL-file.
183 resolve_initial_references(ObjectId) -> Object
185 resolve_initial_references(ObjectId, Contexts) -> Object
186 Types:
188 ObjectId = string()
190 Contexts = [Context]
191 Context = #'IOP_ServiceContext'{context_id = CtxId, con‐
192 text_data = CtxData}
193 CtxId = ?ORBER_GENERIC_CTX_ID
194 CtxData = {interface, Interface} | {userspecific, term()} |
195 {configuration, Options}
196 Interface = string()
197 Options = [{Key, Value}]
198 Key = ssl_client_options
199 Value = allowed value associated with the given key
200 Object = #objref
201 This function returns the object reference associated with the
203 given object id. Initially, only "NameService" is available. To
204 add or remove services use add_initial_service/2 or remove_ini‐
205 tial_service/1.
206 The configuration context is used to override the global SSL
208 client side configuration.
209 add_initial_service(ObjectId, Object) -> boolean()
211 Types:
213 ObjectId = string()
215 Object = #objref
216 This operation allows us to add initial services, which can be
218 accessed by using resolve_initial_references/1 or the corbaloc
219 schema. If using an Id defined by the OMG, the given object must
220 be of the correct type; for more information see the Interopera‐
221 ble Naming Service. Returns false if the given id already
222 exists.
223 remove_initial_service(ObjectId) -> boolean()
225 Types:
227 ObjectId = string()
229 If we don not want a certain service to be accessible, invoking
231 this function will remove the association. Returns true if able
232 to terminate the binding. If no such binding existed false is
233 returned.
234 list_initial_services() -> [ObjectId]
236 Types:
238 ObjectId = string()
240 This function returns a list of allowed object id's.
242 resolve_initial_references_remote(ObjectId, Address) -> Object
244 resolve_initial_references_remote(ObjectId, Address, Contexts) ->
245 Object
246 Types:
248 ObjectId = string()
250 Address = [RemoteModifier]
251 RemoteModifier = string()
252 Contexts = [Context]
253 Context = #'IOP_ServiceContext'{context_id = CtxId, con‐
254 text_data = CtxData}
255 CtxId = ?ORBER_GENERIC_CTX_ID
256 CtxData = {interface, Interface} | {userspecific, term()} |
257 {configuration, Options}
258 Interface = string()
259 Options = [{Key, Value}]
260 Key = ssl_client_options
261 Value = allowed value associated with the given key
262 Object = #objref
263 This function returns the object reference for the object id
265 asked for. The remote modifier string has the following format:
266 "iiop://"<host>":"<port> where <host> = <DNS hostname> | <IPv4
267 address> | "["<IPv6 address>"]".
268 The configuration context is used to override the global SSL
270 client side configuration.
271 Warning:
273 This operation is not supported by most ORB's. Hence, use
274 corba:string_to_object/1 instead.
275 list_initial_services_remote(Address) -> [ObjectId]
278 list_initial_services_remote(Address, Contexts) -> [ObjectId]
279 Types:
281 Address = [RemoteModifier]
283 RemoteModifier = string()
284 Contexts = [Context]
285 Context = #'IOP_ServiceContext'{context_id = CtxId, con‐
286 text_data = CtxData}
287 CtxId = ?ORBER_GENERIC_CTX_ID
288 CtxData = {interface, Interface} | {userspecific, term()} |
289 {configuration, Options}
290 Interface = string()
291 Options = [{Key, Value}]
292 Key = ssl_client_options
293 Value = allowed value associated with the given key
294 ObjectId = string()
295 This function returns a list of allowed object id's. The remote
297 modifier string has the following format:
298 "iiop://"<host>":"<port> where <host> = <DNS hostname> | <IPv4
299 address> | "["<IPv6 address>"]".
300 The configuration context is used to override the global SSL
302 client side configuration.
303 Warning:
305 This operation is not supported by most ORB's. Hence, avoid
306 using it.
307 object_to_string(Object) -> IOR_string
310 Types:
312 Object = #objref
314 IOR_string = string()
315 This function returns the object reference as the external
317 string representation of an IOR.
318 string_to_object(IOR_string) -> Object
320 string_to_object(IOR_string, Contexts) -> Object
321 Types:
323 IOR_string = string()
325 Contexts = [Context]
326 Context = #'IOP_ServiceContext'{context_id = CtxId, con‐
327 text_data = CtxData}
328 CtxId = ?ORBER_GENERIC_CTX_ID
329 CtxData = {interface, Interface} | {userspecific, term()} |
330 {configuration, Options}
331 Interface = string()
332 Options = [{Key, Value}]
333 Key = ssl_client_options
334 Value = allowed value associated with the given key
335 Object = #objref
336 This function takes a corbaname, corbaloc or an IOR on the
338 external string representation and returns the object reference.
339 To lookup the NameService reference, simply use:
341 corbaloc:iiop:1.2@123.0.0.12:4001/NameService
343 We can also resolve an object from the NameService by using:
345 corbaname:iiop:1.2@123.0.0.12:4001/NameService#org/Erlang/MyObj
347 To lookup the NameService reference with an IPv6 address, simply
349 use:
350 corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService
352 For more information about corbaname and corbaloc, see the
354 User's Guide (Interoperable Naming Service).
355 The configuration context is used to override the global SSL
357 client side configuration.
358 How to handle the interface context is further described in the
360 User's Guide.
361 print_object(Data [, Type]) -> ok | {'EXCEPTION', E} | {'EXIT', R} |
363 string()
364 Types:
366 Data = IOR_string | #objref (local or external) | cor‐
368 baloc/corbaname string
369 Type = IoDevice | error_report | {error_report, Reason} |
370 info_msg | {info_msg, Comment} | string
371 IoDevice = see the io-module
372 Reason = Comment = string()
373 The object represented by the supplied data is dissected and
375 presented in a more readable form. The Type parameter is
376 optional; if not supplied standard output is used. For
377 error_report and info_msg the error_logger module is used, with
378 or without Reason or Comment. If the atom string is supplied
379 this function will return a flat list. The IoDevice is passed to
380 the operation io:format/2.
381 If the supplied object is a local reference, the output is
383 equivalent to an object exported from the node this function is
384 invoked on.
385 add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEP‐
387 TION', E}
388 Types:
390 Object = NewObject = local #objref
392 Host = string()
393 Port = integer()
394 This operation creates a new instance of the supplied object
396 containing an ALTERNATE_IIOP_ADDRESS component. Only the new
397 instance contains the new component. When this object is passed
398 to another ORB, which supports the ALTERNATE_IIOP_ADDRESS,
399 requests will be routed to the alternate address if it is not
400 possible to communicate with the main address.
401 The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1.2 is
403 used. Hence, make sure both Orber and the other ORB is correctly
404 configured.
405 Note:
407 Make sure that the given Object is accessible via the alternate
408 Host/port. For example, if the object is correctly started as
409 local or pseudo, the object should be available on all nodes
410 within a multi-node Orber installation. Since only one instance
411 exists for other object types, it will not be possible to access
412 it if the node it was started on terminates.
413 orb_init(KeyValueList) -> ok | {'EXIT', Reason}
416 Types:
418 KeyValueList = [{Key, Value}]
420 Key = any key listed in the configuration chapter
421 Value = allowed value associated with the given key
422 This function allows the user to configure Orber in, for exam‐
424 ple, an Erlang shell. Orber may NOT be started prior to invoking
425 this operation. For more information, see configuration settings
426 in the User's Guide.
427Ericsson AB orber 4.5.2 corba(3)