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
72 exception, 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
85 information 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
92 corba:resolve_initial_references/1. For more information see the
93 user's guide.
94 domain() -> string()
96 This function returns the domain name of the current Orber
98 domain 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
110 parameter 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
125 secure IIOP protocol. It can be configured by setting the appli‐
126 cation 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
134 application variable iiop_timeout TimeVal (seconds), if it is
135 not set it will have the default value infinity. If a request
136 times 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,
149 argument 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
182 included.
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
200 operation allows the user to check if this is the case. The
201 returned list contain tuples of remote hosts/ports. Normally,
202 the 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
214 requests.
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"
237 respectively. 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
258 orber_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
262 audit/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
273 interceptors, 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
295 incoming IIOP connection via the given interface and port. If
296 the latter is excluded, Orber will use the value of the
297 iiop_port or iiop_ssl_port configuration parameters. The Type
298 parameter determines if it is supposed to be IIOP or IIOP via
299 SSL. If successful, the returned #Ref shall be passed to
300 orber:remove_listen_interface/1 when the connection shall be
301 terminated.
302 It is also possible to supply configuration parameters that
304 override the global configuration. The iiop_in_connection_time‐
305 out, iiop_max_fragments, iiop_max_in_requests and interceptors
306 parameters simply overrides the global counterparts (See the
307 Configuration chapter in the User's Guide). But for the follow‐
308 ing parameters there are a few restrictions:
309 * flags - currently it is only possible to override the global
311 setting for the Use Current Interface in IOR and Exclude
312 CodeSet Component flags.
313 * ip_family - can be set to inet or inet6 and is used to get a
315 listen interface that uses another IP version than the
316 default set with flags at startup.
317 * iiop_port - requires that Use Current Interface in IOR is
319 activated and the supplied Type is normal. If so, exported
320 IOR:s will contain the IIOP port defined by this configura‐
321 tion parameter. Otherwise, the global setting will be used.
322 * iiop_ssl_port - almost equivalent to iiop_port. The differ‐
324 ence is that Type shall be ssl and that exported IOR:s will
325 contain the IIOP via SSL port defined by this configuration
326 parameter.
327 If it is not possible to add a listener based on the supplied
329 interface and port, the error message is one of the ones
330 described in inet and/or ssl documentation.
331 remove_listen_interface(Ref) -> ok
333 Types:
335 Ref = #Ref
337 Terminates the listen process, associated with the supplied
339 #Ref, for incoming a connection. The Ref parameter is the return
340 value from the orber:add_listen_interface/2/3 operation. When
341 terminating the connection, all associated requests will not
342 deliver a reply to the clients.
343 close_connection(Connection) -> Result
345 close_connection(Connection, Interface) -> Result
346 Types:
348 Connection = Object | [{Host, Port}]
350 Object = #objref (external)
351 Host = string()
352 Port = string()
353 Interface = string()
354 Result = ok | {'EXCEPTION', #'BAD_PARAM'{}}
355 Will try to close all outgoing connections to the host/port com‐
357 binations found in the supplied object reference or the given
358 list of hosts/ports. If a #'IOP_ServiceContext'{} containing a
359 local interface has been used when communicating with the remote
360 object (see also Module_Interface), that interface shall be
361 passed as the second argument. Otherwise, connections via the
362 default local interface, will be terminated.
363 Note:
365 Since several clients maybe communicates via the same connec‐
366 tion, they will be affected when invoking this operation. Other
367 clients may re-create the connection by invoking an operation on
368 the target object.
369 secure() -> no | ssl
372 This function returns the security mode Orber is running in,
374 which is either no if it is an insecure domain or the type of
375 security mechanism used. For the moment the only security mecha‐
376 nism is ssl. This is configured by setting the application vari‐
377 able secure.
378 ssl_server_options() -> list()
380 This function returns the list of SSL options set for the Orber
382 domain as server. This is configured by setting the application
383 variable ssl_server_options.
384 ssl_client_options() -> list()
386 This function returns the list of SSL options used in outgoing
388 calls in the current process. The default value is configured by
389 setting the application variable ssl_client_options.
390 set_ssl_client_options(Options) -> ok
392 Types:
394 Options = list()
396 This function takes a list of SSL options as parameter and sets
398 it for the current process.
399 objectkeys_gc_time() -> int() (seconds)
401 This function returns the timeout value after which after which
403 terminated object keys, related to servers started with the con‐
404 figuration parameter {persistent, true}, will be removed. It can
405 be configured by setting the application variable objec‐
406 tkeys_gc_time TimeVal (seconds), if it is not set it will have
407 the default value infinity.
408 Objects terminating with reason normal or shutdown are removed
410 automatically.
411 Note: the objectkeys_gc_time configuration parameter (TimeVal)
413 may only range between 0 and 1000000 seconds. Otherwise, the
414 default value is used.
415 orber_nodes() -> RetVal
417 Types:
419 RetVal = [node()]
421 This function returns the list of node names that this orber
423 domain consists of.
424 install(NodeList) -> ok
426 install(NodeList, Options) -> ok
427 Types:
429 NodeList = [node()]
431 Options = [Option]
432 Option = {install_timeout, Timeout} | {ifr_storage_type,
433 TableType} | {nameservice_storage_type, TableType} | {ini‐
434 tialreferences_storage_type, TableType} | {load_order, Prior‐
435 ity}
436 Timeout = infinity | integer()
437 TableType = disc_copies | ram_copies
438 Priority = integer()
439 This function installs all the necessary mnesia tables and load
441 default data in some of them. If one or more Orber tables
442 already exists the installation fails. The function uninstall
443 may be used, if it is safe, i.e., no other application is run‐
444 ning Orber.
445 Preconditions:
447 * a mnesia schema must exist before the installation
449 * mnesia is running on the other nodes if the new installation
451 shall be a multi node domain
452 Mnesia will be started by the function if it is not already run‐
454 ning on the installation node and if it was started it will be
455 stopped afterwards.
456 The options that can be sent to the installation program is:
458 * {install_timeout, Timeout} - this timeout is how long we
460 will wait for the tables to be created. The Timeout value
461 can be infinity or an integer number in milliseconds.
462 Default is infinity.
463 * {ifr_storage_type, TableType} - this option sets the type of
465 tables used for the interface repository. The TableType can
466 be disc_copies or ram_copies. Default is disc_copies.
467 * {initialreferences_storage_type, TableType} - this option
469 sets the type of table used for storing initial references.
470 The TableType can be disc_copies or ram_copies. Default is
471 ram_copies.
472 * {nameservice_storage_type, TableType} - the default behavior
474 of Orber is to install the NameService as ram_copies. This
475 option makes it possible to change this to disc_copies. But
476 the user should be aware of that if a node is restarted, all
477 local object references stored in the NameService is not
478 valid. Hence, you cannot switch to disc_copies and expect
479 exactly the same behavior as before.
480 * {load_order, Priority} - per default the priority is set to
482 0. Using this option it will change the priority of in which
483 order Mnesia will load Orber internal tables. For more
484 information, consult the Mnesia documentation.
485 uninstall() -> ok
487 This function stops the Orber application, terminates all server
489 objects and removes all Orber related mnesia tables.
490 Note: Since other applications may be running on the same node
492 using mnesia uninstall will not stop the mnesia application.
493 add_node(Node, Options) -> RetVal
495 Types:
497 Node = node()
499 Options = IFRStorageType | [KeyValue]
500 IFRStorageType = StorageType
501 StorageType = disc_copies | ram_copies
502 KeyValue = {ifr_storage_type, StorageType} | {initialrefer‐
503 ences_storage_type, StorageType} | {nameservice_storage_type,
504 StorageType} | {type, Type}
505 Type = temporary | permanent
506 RetVal = ok | exit()
507 This function add given node to a existing Orber node group and
509 starts Orber on the new node. orber:add_node is called from a
510 member in the Orber node group.
511 Preconditions for new node:
513 * Erlang started on the new node using the option -mnesia
515 extra_db_nodes, e.g., erl -sname new_node_name -mnesia
516 extra_db_nodes ConnectToNodes_List
517 * The new node's domain name is the same for the nodes we want
519 to connect to.
520 * Mnesia is running on the new node (no new schema created).
522 * If the new node will use disc_copies the schema type must be
524 changed using: mnesia:change_table_copy_type(schema, node(),
525 disc_copies).
526 Orber will be started by the function on the new node.
528 Fails if:
530 * Orber already installed on given node.
532 * Mnesia not started as described above on the new node.
534 * Impossible to copy data in Mnesia tables to the new node.
536 * Not able to start Orber on the new node, due to, for exam‐
538 ple, the iiop_port is already in use.
539 The function do not remove already copied tables after a fail‐
541 ure. Use orber:remove_node to remove these tables.
542 remove_node(Node) -> RetVal
544 Types:
546 Node = node()
548 RetVal = ok | exit()
549 This function removes given node from a Orber node group. The
551 Mnesia application is not stopped.
552 configure(Key, Value) -> ok | {'EXIT', Reason}
554 Types:
556 Key = orbDefaultInitRef | orbInitRef | giop_version |
558 iiop_timeout | iiop_connection_timeout | iiop_setup_connec‐
559 tion_timeout | iiop_in_connection_timeout | objec‐
560 tkeys_gc_time | orber_debug_level
561 Value = allowed value associated with the given key
562 This function allows the user to configure Orber in, for exam‐
564 ple, an Erlang shell. It is possible to invoke configure at any
565 time the keys specified above.
566 Any other key must be set before installing and starting Orber.
568 Trying to change the configuration in any other way is NOT
570 allowed since it may affect the behavior of Orber.
571 For more information regarding allowed values, see configuration
573 settings in the User's Guide.
574 Note:
576 Configuring the IIOP timeout values will not affect already
577 existing connections. If you want a guaranteed uniform behavior,
578 you must set these parameters from the start.
579Ericsson AB orber 5.0 orber(3)