1orber(3) Erlang Module Definition orber(3)
2
6 orber - The main module of the Orber application
7
9 This module contains the functions for starting and stopping the appli‐
10 cation. It also has some utility functions to get some of the configu‐
11 ration information from running application.
12
14 start() -> ok
15 start(Type) -> ok
16 Types:
18 Type = temporary | permanent
20 Starts the Orber application (it also starts mnesia if it is not
22 running). Which Type parameter is supplied determines the behav‐
23 ior. If not supplied Orber is started as temporary. See the Ref‐
24 erence Manual application(3) for further information.
25 jump_start(Attributes) -> ok | {'EXIT', Reason}
27 Types:
29 Attributes = Port | Options
31 Port = integer()
32 Options = [{Key, Value}]
33 Key = any key listed in the configuration chapter
34 Value = allowed value associated with the given key
35 Installs and starts the Orber and the Mnesia applications with
37 the configuration parameters domain and iiop_port set to "IP-
38 number:Port" and the supplied Port respectively. Theses settings
39 are in most cases sufficient to ensure that no clash with any
40 other Orber instance occur. If this operation fails, check if
41 the listen port (iiop_port) is already in use. This function MAY
42 ONLY be used during development and tests; how Orber is config‐
43 ured when using this operation may change at any time without
44 warning.
45 stop() -> ok
47 Stops the Orber application.
49 info() -> ok
51 info(IoType) -> ok | {'EXIT', Reason} | string()
52 Types:
54 IoType = info_msg | string | io | {io, IoDevice}
56 Generates an Info Report, which contain Orber's configuration
58 settings. If no IoType is supplied, info_msg is used (see the
59 error_logger documentation). When the atom string is supplied
60 this function will return a flat list. For io and {io, IoDe‐
61 vice}, io:format/1 and io:format/3 is used respectively.
62 exception_info(Exception) -> {ok, string()} | {error, Reason}
64 Returns a printable string, which describes the supplied excep‐
66 tion in greater detail. Note, this function is mainly intended
67 for system exceptions.
68 is_system_exception(Exception) -> true | false
70 Returns true if the supplied exception is a system defined ex‐
72 ception, otherwise false.
73 get_tables() -> [Tables]
75 Returns a list of the Orber specific Mnesia tables. This list is
77 required to restore Mnesia if it has been partitioned.
78 get_ORBInitRef() -> string() | undefined
80 This function returns undefined if we will resolve references
82 locally, otherwise a string describing which host we will con‐
83 tact if the Key given to corba:resolve_initial_references/1
84 matches the Key set in this configuration variable. For more in‐
85 formation see the user's guide.
86 get_ORBDefaultInitRef() -> string() | undefined
88 This function returns undefined if we will resolve references
90 locally, otherwise a string describing which host, or hosts,
91 from which we will try to resolve the Key given to corba:re‐
92 solve_initial_references/1. For more information see the user's
93 guide.
94 domain() -> string()
96 This function returns the domain name of the current Orber do‐
98 main as a string.
99 iiop_port() -> int()
101 This function returns the port-number, which is used by the IIOP
103 protocol. It can be configured by setting the application vari‐
104 able iiop_port, if it is not set it will have the default number
105 4001.
106 iiop_out_ports() -> 0 | {Min, Max}
108 The return value of this operation is what the configuration pa‐
110 rameter iiop_out_ports has been set to.
111 iiop_out_ports_random() -> true | false
113 Return the value of the configuration parameter
115 iiop_out_ports_random.
116 iiop_out_ports_attempts() -> int()
118 Return the value of the configuration parameter
120 iiop_out_ports_attempts.
121 iiop_ssl_port() -> int()
123 This function returns the port-number, which is used by the se‐
125 cure IIOP protocol. It can be configured by setting the applica‐
126 tion variable iiop_ssl_port, if it is not set it will have the
127 default number 4002 if Orber is to configured to run in secure
128 mode. Otherwise it returns -1.
129 iiop_timeout() -> int() (milliseconds)
131 This function returns the timeout value after which outgoing
133 IIOP requests terminate. It can be configured by setting the ap‐
134 plication variable iiop_timeout TimeVal (seconds), if it is not
135 set it will have the default value infinity. If a request times
136 out a system exception, e.g. TIMEOUT, is raised.
137 Note: the iiop_timeout configuration parameter (TimeVal) may
139 only range between 0 and 1000000 seconds. Otherwise, the default
140 value is used.
141 Note: Earlier IC versions required that the compile option
143 {timeout,"module::interface"}, was used, which allow the user to
144 add an extra timeout parameter, e.g., module_interface:func‐
145 tion(ObjRef, Timeout, ... Arguments ...) or module_inter‐
146 face:function(ObjRef, [{timeout, Timeout}], ... Arguments ...),
147 instead of module_interface:function(ObjRef, ... Arguments ...).
148 This is no longer the case and if the extra Timeout is used, ar‐
149 gument will override the configuration parameter iiop_timeout.
150 It is, however, not possible to use infinity to override the
151 Timeout parameter. The Timeout option is also valid for objects
152 which resides within the same Orber domain.
153 iiop_connection_timeout() -> int() (milliseconds)
155 This function returns the timeout value after which outgoing
157 IIOP connections terminate. It can be configured by setting the
158 application variable iiop_connection_timeout TimeVal (seconds),
159 if it is not set it will have the default value infinity. The
160 connection will not be terminated if there are pending requests.
161 Note: the iiop_connection_timeout configuration parameter
163 (TimeVal) may only range between 0 and 1000000 seconds. Other‐
164 wise, the default value is used.
165 iiop_connections() -> Result
167 iiop_connections(Direction) -> Result
168 Types:
170 Direction = in | out | inout
172 Result = [{Host, Port}] | [{Host, Port, Interface}] |
173 {'EXIT',Reason}
174 Host = string()
175 Port = integer()
176 Interface = string()
177 Reason = term()
178 The list returned by this operation contain tuples of remote
180 hosts/ports Orber is currently connected to. If no Direction is
181 not supplied, both incoming and outgoing connections are in‐
182 cluded.
183 If a specific local interface has been defined for the connec‐
185 tion, this will be added to the returned tuple.
186 iiop_connections_pending() -> Result
188 Types:
190 Result = [{Host, Port}] | [{Host, Port, Interface}] |
192 {'EXIT',Reason}
193 Host = string()
194 Port = integer()
195 Interface = string()
196 Reason = term()
197 In some cases a connection attempt (i.e. trying to communicate
199 with another ORB) may block due to a number of reasons. This op‐
200 eration allows the user to check if this is the case. The re‐
201 turned list contain tuples of remote hosts/ports. Normally, the
202 list is empty.
203 If a specific local interface has been defined for the connec‐
205 tion, this will be added to the returned tuple.
206 iiop_in_connection_timeout() -> int() (milliseconds)
208 This function returns the timeout value after which incoming
210 IIOP connections terminate. It can be configured by setting the
211 application variable iiop_in_connection_timeout TimeVal (sec‐
212 onds), if it is not set it will have the default value infinity.
213 The connection will not be terminated if there are pending re‐
214 quests.
215 Note: the iiop_in_connection_timeout configuration parameter
217 (TimeVal) may only range between 0 and 1000000 seconds. Other‐
218 wise, the default value is used.
219 iiop_acl() -> Result
221 Types:
223 Result = [{Direction, Filter}] | [{Direction, Filter, [Inter‐
225 face]}]
226 Direction = tcp_in | ssl_in | tcp_out | ssl_out
227 Filter = string()
228 Interface = string()
229 Returns the ACL configuration. The Filter uses a extended format
231 of Classless Inter Domain Routing (CIDR). For example,
232 "123.123.123.10" limits the connection to that particular host,
233 while "123.123.123.10/17" allows connections to or from any host
234 equal to the 17 most significant bits. Orber also allow the user
235 to specify a certain port or port range, for example,
236 "123.123.123.10/17#4001" and "123.123.123.10/17#4001/5001" re‐
237 spectively. IPv4 or none compressed IPv6 strings are accepted.
238 The list of Interfaces, IPv4 or IPv6 strings, are currently only
239 used for outgoing connections and may only contain one address.
240 If set and access is granted, Orber will use that local inter‐
241 face when connecting to the other ORB. The module orber_acl pro‐
242 vides operations for evaluating the access control for filters
243 and addresses.
244 activate_audit_trail() -> Result
246 activate_audit_trail(Verbosity) -> Result
247 Types:
249 Verbosity = stealth | normal | verbose
251 Result = ok | {error, Reason}
252 Reason = string()
253 Activates audit/trail for all existing incoming and outgoing
255 IIOP connections. The Verbosity parameter, stealth, normal or
256 verbose, determines which of the built in interceptors is used
257 (orber_iiop_tracer_stealth, orber_iiop_tracer_silent or or‐
258 ber_iiop_tracer respectively). If no verbosity level is sup‐
259 plied, then the normal will be used.
260 In case Orber is configured to use other interceptors, the au‐
262 dit/trail interceptors will simply be added to that list.
263 deactivate_audit_trail() -> Result
265 Types:
267 Result = ok | {error, Reason}
269 Reason = string()
270 Deactivates audit/trail for all existing incoming and outgoing
272 IIOP connections. In case Orber is configured to use other in‐
273 terceptors, those will still be used.
274 add_listen_interface(IP, Type) -> Result
276 add_listen_interface(IP, Type, Port) -> Result
277 add_listen_interface(IP, Type, ConfigurationParameters) -> Result
278 Types:
280 IP = string
282 Type = normal | ssl
283 Port = integer() > 0
284 ConfigurationParameters = [{Key, Value}]
285 Key = flags | ip_family | iiop_in_connection_timeout |
286 iiop_max_fragments | iiop_max_in_requests | interceptors |
287 iiop_port | iiop_ssl_port | ssl_server_options
288 Value = as described in the User's Guide or below
289 Result = {ok, Ref} | {error, Reason} | {'EXCEPTION',
290 #'BAD_PARAM'{}}
291 Ref = #Ref
292 Reason = string()
293 Create a new process that handle requests for creating a new in‐
295 coming IIOP connection via the given interface and port. If the
296 latter is excluded, Orber will use the value of the iiop_port or
297 iiop_ssl_port configuration parameters. The Type parameter de‐
298 termines if it is supposed to be IIOP or IIOP via SSL. If suc‐
299 cessful, the returned #Ref shall be passed to orber:remove_lis‐
300 ten_interface/1 when the connection shall be terminated.
301 It is also possible to supply configuration parameters that
303 override the global configuration. The iiop_in_connection_time‐
304 out, iiop_max_fragments, iiop_max_in_requests and interceptors
305 parameters simply overrides the global counterparts (See the
306 Configuration chapter in the User's Guide). But for the follow‐
307 ing parameters there are a few restrictions:
308 * flags - currently it is only possible to override the global
310 setting for the Use Current Interface in IOR and Exclude
311 CodeSet Component flags.
312 * ip_family - can be set to inet or inet6 and is used to get a
314 listen interface that uses another IP version than the de‐
315 fault set with flags at startup.
316 * iiop_port - requires that Use Current Interface in IOR is
318 activated and the supplied Type is normal. If so, exported
319 IOR:s will contain the IIOP port defined by this configura‐
320 tion parameter. Otherwise, the global setting will be used.
321 * iiop_ssl_port - almost equivalent to iiop_port. The differ‐
323 ence is that Type shall be ssl and that exported IOR:s will
324 contain the IIOP via SSL port defined by this configuration
325 parameter.
326 If it is not possible to add a listener based on the supplied
328 interface and port, the error message is one of the ones de‐
329 scribed in inet and/or ssl documentation.
330 remove_listen_interface(Ref) -> ok
332 Types:
334 Ref = #Ref
336 Terminates the listen process, associated with the supplied
338 #Ref, for incoming a connection. The Ref parameter is the return
339 value from the orber:add_listen_interface/2/3 operation. When
340 terminating the connection, all associated requests will not de‐
341 liver a reply to the clients.
342 close_connection(Connection) -> Result
344 close_connection(Connection, Interface) -> Result
345 Types:
347 Connection = Object | [{Host, Port}]
349 Object = #objref (external)
350 Host = string()
351 Port = string()
352 Interface = string()
353 Result = ok | {'EXCEPTION', #'BAD_PARAM'{}}
354 Will try to close all outgoing connections to the host/port com‐
356 binations found in the supplied object reference or the given
357 list of hosts/ports. If a #'IOP_ServiceContext'{} containing a
358 local interface has been used when communicating with the remote
359 object (see also Module_Interface), that interface shall be
360 passed as the second argument. Otherwise, connections via the
361 default local interface, will be terminated.
362 Note:
364 Since several clients maybe communicates via the same connec‐
365 tion, they will be affected when invoking this operation. Other
366 clients may re-create the connection by invoking an operation on
367 the target object.
368 secure() -> no | ssl
371 This function returns the security mode Orber is running in,
373 which is either no if it is an insecure domain or the type of
374 security mechanism used. For the moment the only security mecha‐
375 nism is ssl. This is configured by setting the application vari‐
376 able secure.
377 ssl_server_options() -> list()
379 This function returns the list of SSL options set for the Orber
381 domain as server. This is configured by setting the application
382 variable ssl_server_options.
383 ssl_client_options() -> list()
385 This function returns the list of SSL options used in outgoing
387 calls in the current process. The default value is configured by
388 setting the application variable ssl_client_options.
389 set_ssl_client_options(Options) -> ok
391 Types:
393 Options = list()
395 This function takes a list of SSL options as parameter and sets
397 it for the current process.
398 objectkeys_gc_time() -> int() (seconds)
400 This function returns the timeout value after which after which
402 terminated object keys, related to servers started with the con‐
403 figuration parameter {persistent, true}, will be removed. It can
404 be configured by setting the application variable objec‐
405 tkeys_gc_time TimeVal (seconds), if it is not set it will have
406 the default value infinity.
407 Objects terminating with reason normal or shutdown are removed
409 automatically.
410 Note: the objectkeys_gc_time configuration parameter (TimeVal)
412 may only range between 0 and 1000000 seconds. Otherwise, the de‐
413 fault value is used.
414 orber_nodes() -> RetVal
416 Types:
418 RetVal = [node()]
420 This function returns the list of node names that this orber do‐
422 main consists of.
423 install(NodeList) -> ok
425 install(NodeList, Options) -> ok
426 Types:
428 NodeList = [node()]
430 Options = [Option]
431 Option = {install_timeout, Timeout} | {ifr_storage_type,
432 TableType} | {nameservice_storage_type, TableType} | {ini‐
433 tialreferences_storage_type, TableType} | {load_order, Prior‐
434 ity}
435 Timeout = infinity | integer()
436 TableType = disc_copies | ram_copies
437 Priority = integer()
438 This function installs all the necessary mnesia tables and load
440 default data in some of them. If one or more Orber tables al‐
441 ready exists the installation fails. The function uninstall may
442 be used, if it is safe, i.e., no other application is running
443 Orber.
444 Preconditions:
446 * a mnesia schema must exist before the installation
448 * mnesia is running on the other nodes if the new installation
450 shall be a multi node domain
451 Mnesia will be started by the function if it is not already run‐
453 ning on the installation node and if it was started it will be
454 stopped afterwards.
455 The options that can be sent to the installation program is:
457 * {install_timeout, Timeout} - this timeout is how long we
459 will wait for the tables to be created. The Timeout value
460 can be infinity or an integer number in milliseconds. De‐
461 fault is infinity.
462 * {ifr_storage_type, TableType} - this option sets the type of
464 tables used for the interface repository. The TableType can
465 be disc_copies or ram_copies. Default is disc_copies.
466 * {initialreferences_storage_type, TableType} - this option
468 sets the type of table used for storing initial references.
469 The TableType can be disc_copies or ram_copies. Default is
470 ram_copies.
471 * {nameservice_storage_type, TableType} - the default behavior
473 of Orber is to install the NameService as ram_copies. This
474 option makes it possible to change this to disc_copies. But
475 the user should be aware of that if a node is restarted, all
476 local object references stored in the NameService is not
477 valid. Hence, you cannot switch to disc_copies and expect
478 exactly the same behavior as before.
479 * {load_order, Priority} - per default the priority is set to
481 0. Using this option it will change the priority of in which
482 order Mnesia will load Orber internal tables. For more in‐
483 formation, consult the Mnesia documentation.
484 uninstall() -> ok
486 This function stops the Orber application, terminates all server
488 objects and removes all Orber related mnesia tables.
489 Note: Since other applications may be running on the same node
491 using mnesia uninstall will not stop the mnesia application.
492 add_node(Node, Options) -> RetVal
494 Types:
496 Node = node()
498 Options = IFRStorageType | [KeyValue]
499 IFRStorageType = StorageType
500 StorageType = disc_copies | ram_copies
501 KeyValue = {ifr_storage_type, StorageType} | {initialrefer‐
502 ences_storage_type, StorageType} | {nameservice_storage_type,
503 StorageType} | {type, Type}
504 Type = temporary | permanent
505 RetVal = ok | exit()
506 This function add given node to a existing Orber node group and
508 starts Orber on the new node. orber:add_node is called from a
509 member in the Orber node group.
510 Preconditions for new node:
512 * Erlang started on the new node using the option -mnesia ex‐
514 tra_db_nodes, e.g., erl -sname new_node_name -mnesia ex‐
515 tra_db_nodes ConnectToNodes_List
516 * The new node's domain name is the same for the nodes we want
518 to connect to.
519 * Mnesia is running on the new node (no new schema created).
521 * If the new node will use disc_copies the schema type must be
523 changed using: mnesia:change_table_copy_type(schema, node(),
524 disc_copies).
525 Orber will be started by the function on the new node.
527 Fails if:
529 * Orber already installed on given node.
531 * Mnesia not started as described above on the new node.
533 * Impossible to copy data in Mnesia tables to the new node.
535 * Not able to start Orber on the new node, due to, for exam‐
537 ple, the iiop_port is already in use.
538 The function do not remove already copied tables after a fail‐
540 ure. Use orber:remove_node to remove these tables.
541 remove_node(Node) -> RetVal
543 Types:
545 Node = node()
547 RetVal = ok | exit()
548 This function removes given node from a Orber node group. The
550 Mnesia application is not stopped.
551 configure(Key, Value) -> ok | {'EXIT', Reason}
553 Types:
555 Key = orbDefaultInitRef | orbInitRef | giop_version |
557 iiop_timeout | iiop_connection_timeout | iiop_setup_connec‐
558 tion_timeout | iiop_in_connection_timeout | objec‐
559 tkeys_gc_time | orber_debug_level
560 Value = allowed value associated with the given key
561 This function allows the user to configure Orber in, for exam‐
563 ple, an Erlang shell. It is possible to invoke configure at any
564 time the keys specified above.
565 Any other key must be set before installing and starting Orber.
567 Trying to change the configuration in any other way is NOT al‐
569 lowed since it may affect the behavior of Orber.
570 For more information regarding allowed values, see configuration
572 settings in the User's Guide.
573 Note:
575 Configuring the IIOP timeout values will not affect already ex‐
576 isting connections. If you want a guaranteed uniform behavior,
577 you must set these parameters from the start.
578Ericsson AB orber 5.0.2 orber(3)