From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/orber/doc/src/orber.xml | 689 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 689 insertions(+) create mode 100644 lib/orber/doc/src/orber.xml (limited to 'lib/orber/doc/src/orber.xml') diff --git a/lib/orber/doc/src/orber.xml b/lib/orber/doc/src/orber.xml new file mode 100644 index 0000000000..da5fd05f98 --- /dev/null +++ b/lib/orber/doc/src/orber.xml @@ -0,0 +1,689 @@ + + + + +
+ + 19972009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + orber + + + + + + 1997-06-10 + A +
+ orber + The main module of the Orber application + +

This module contains the functions for starting and stopping the + application. It also has some utility functions to get some of + the configuration information from running application.

+ + + + start() -> ok + start(Type) -> ok + Start the Orber application + + Type = temporary | permanent + + +

Starts the Orber application (it also starts mnesia if it is not running). + Which Type parameter is supplied determines the behavior. If not + supplied Orber is started as temporary. + See the Reference Manual application(3) for further information.

+ + + + jump_start(Attributes) -> ok | {'EXIT', Reason} + Start the Orber application during tests + + Attributes = Port | Options + Port = integer() + Options = [{Key, Value}] + Key = any key listed in the configuration chapter + Value = allowed value associated with the given key + + +

Installs and starts the Orber and the Mnesia applications with the configuration + parameters domain and iiop_port set to "IP-number:Port" + and the supplied Port respectively. Theses settings are in most cases + sufficient to ensure that no clash with any other Orber instance occur. + If this operation fails, check if the listen port (iiop_port) is already + in use. This function MAY ONLY be used during development and + tests; how Orber is configured when using this operation may change + at any time without warning.

+ + + + stop() -> ok + Stop the Orber application + +

Stops the Orber application.

+ + + + info() -> ok + info(IoType) -> ok | {'EXIT', Reason} | string() + Generate Info Report, which contain Orber's configuration settings + + IoType = info_msg | string | io | {io, IoDevice} + + +

Generates an Info Report, which contain Orber's configuration settings. + If no IoType is supplied, info_msg is used (see the + error_logger documentation). When the atom string is supplied this + function will return a flat list. For io and {io, IoDevice}, + io:format/1 and io:format/3 is used respectively.

+ + + + exception_info(Exception) -> {ok, string()} | {error, Reason} + Return a printable string, which describes the supplied exception + +

Returns a printable string, which describes the supplied exception + in greater detail. Note, this function is mainly intended for + system exceptions.

+ + + + is_system_exception(Exception) -> true | false + Return true if the supplied exception is a system defined exception otherwise false + +

Returns true if the supplied exception is a system defined + exception, otherwise false.

+ + + + get_tables() -> [Tables] + Get the Mnesia tables Orber uses. + +

Returns a list of the Orber specific Mnesia tables. This list is + required to restore Mnesia if it has been partitioned.

+ + + + get_ORBInitRef() -> string() | undefined + Get the initial reference address. + +

This function returns undefined if we will resolve references locally, + otherwise a string describing which host we will contact if the Key given + to corba:resolve_initial_references/1 matches the Key set + in this configuration variable. For more information + see the user's guide.

+ + + + get_ORBDefaultInitRef() -> string() | undefined + Get the initial reference address. + +

This function returns undefined if we will resolve references locally, + otherwise a string describing which host, or hosts, from which we + will try to resolve the Key given to + corba:resolve_initial_references/1. For more information + see the user's guide.

+ + + + domain() -> string() + Display the Orber domain name + +

This function returns the domain name of the current Orber domain + as a string.

+ + + + iiop_port() -> int() + Display the IIOP port number + +

This function returns the port-number, which is used by the IIOP + protocol. It can be configured by setting the application variable + iiop_port, if it is not set it will have the default number + 4001.

+ + + + iiop_out_ports() -> 0 | {Min, Max} + Display the ports Orber may use when connecting to another ORB + +

The return value of this operation is what the configuration + parameter iiop_out_ports + have been set to.

+ + + + iiop_ssl_port() -> int() + Display the IIOP port number used for secure connections + +

This function returns the port-number, which is used by the secure IIOP + protocol. It can be configured by setting the application variable + iiop_ssl_port, if it is not set it will have the default number + 4002 if Orber is to configured to run in secure mode. Otherwise it returns -1.

+ + + + iiop_timeout() -> int() (milliseconds) + Display the IIOP timeout value + +

This function returns the timeout value after which outgoing IIOP requests terminate. + It can be configured by setting the application variable + iiop_timeout TimeVal (seconds), if it is not set it will have the default value + infinity. If a request times out a system exception, e.g. + TIMEOUT, is raised.

+

Note: the iiop_timeout configuration parameter (TimeVal) may only range between 0 and 1000000 seconds. + Otherwise, the default value is used.

+

Note: Earlier IC versions required that the compile option {timeout,"module::interface"}, + was used, which allow the user to add an extra timeout parameter, e.g., + module_interface:function(ObjRef, Timeout, ... Arguments ...) or + module_interface:function(ObjRef, [{timeout, Timeout}], ... Arguments ...), + instead of module_interface:function(ObjRef, ... Arguments ...). + This is no longer the case and if the extra Timeout is used, + argument will override the configuration parameter iiop_timeout. + It is, however, not possible + to use infinity to override the Timeout parameter. The Timeout + option is also valid for objects which resides within the same Orber domain.

+ + + + iiop_connection_timeout() -> int() (milliseconds) + Display the IIOP connection timeout value + +

This function returns the timeout value after which outgoing IIOP connections terminate. + It can be configured by setting the application variable + iiop_connection_timeout TimeVal (seconds), if it is not set it will have the default value + infinity. The connection will not be terminated if there are + pending requests.

+

Note: the iiop_connection_timeout configuration parameter (TimeVal) may only range between 0 and 1000000 seconds. + Otherwise, the default value is used.

+ + + + iiop_connections() -> Result + iiop_connections(Direction) -> Result + List all existing connections to/from other ORB's + + Direction = in | out | inout + Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason} + Host = string() + Port = integer() + Interface = string() + Reason = term() + + +

The list returned by this operation contain tuples of remote hosts/ports + Orber is currently connected to. If no Direction is not supplied, both + incoming and outgoing connections are included.

+

If a specific local interface has been defined for the connection, + this will be added to the returned tuple.

+ + + + iiop_connections_pending() -> Result + List all connections to another ORB currently being set up + + Result = [{Host, Port}] | [{Host, Port, Interface}] | {'EXIT',Reason} + Host = string() + Port = integer() + Interface = string() + Reason = term() + + +

In some cases a connection attempt (i.e. trying to communicate with + another ORB) may block due to a number of reasons. This operation + allows the user to check if this is the case. The returned list + contain tuples of remote hosts/ports. Normally, the list is empty.

+

If a specific local interface has been defined for the connection, + this will be added to the returned tuple.

+ + + + iiop_in_connection_timeout() -> int() (milliseconds) + Display the IIOP connection timeout value for incoming connections + +

This function returns the timeout value after which incoming IIOP + connections terminate. It can be configured by setting the application + variable iiop_in_connection_timeout TimeVal (seconds), if it is + not set it will have the default value infinity. The connection + will not be terminated if there are pending requests.

+

Note: the iiop_in_connection_timeout configuration parameter (TimeVal) may + only range between 0 and 1000000 seconds. Otherwise, the default value is + used.

+ + + + iiop_acl() -> Result + Return the ACL configuration + + Result = [{Direction, Filter}] | [{Direction, Filter, [Interface]}] + Direction = tcp_in | ssl_in | tcp_out | ssl_out + Filter = string() + Interface = string() + + +

Returns the ACL configuration. The Filter uses a extended format of + Classless Inter Domain Routing (CIDR). For example, "123.123.123.10" limits + the connection to that particular host, while "123.123.123.10/17" allows + connections to or from any host equal to the 17 most significant bits. Orber + also allow the user to specify a certain port or port range, for example, + "123.123.123.10/17#4001" and "123.123.123.10/17#4001/5001" + respectively. IPv4 or none compressed IPv6 strings are accepted.

+ + The list of Interfaces, IPv4 or IPv6 strings, are currently only used + for outgoing connections and may only contain one address. If set and + access is granted, Orber will use that local interface when connecting to the + other ORB. The module orber_acl + provides operations for evaluating the access control for filters and addresses.

+ + + + activate_audit_trail() -> Result + activate_audit_trail(Verbosity) -> Result + Activate IIOP audit/trail + + Verbosity = stealth | normal | verbose + Result = ok | {error, Reason} + Reason = string() + + +

Activates audit/trail for all existing incoming and outgoing IIOP + connections. The Verbosity parameter, stealth, + normal or verbose, determines which of the built in + interceptors is used (orber_iiop_tracer_stealth, + orber_iiop_tracer_silent or orber_iiop_tracer respectively). + If no verbosity level is supplied, then the normal will be used.

+

In case Orber is configured to use other interceptors, the audit/trail + interceptors will simply be added to that list.

+ + + + deactivate_audit_trail() -> Result + Deactivate IIOP audit/trail + + Result = ok | {error, Reason} + Reason = string() + + +

Deactivates audit/trail for all existing incoming and outgoing IIOP + connections. In case Orber is configured to use other interceptors, + those will still be used.

+ + + + add_listen_interface(IP, Type) -> Result + add_listen_interface(IP, Type, Port) -> Result + add_listen_interface(IP, Type, ConfigurationParameters) -> Result + Add a new listen process for incoming connection + + IP = string + Type = normal | ssl + Port = integer() > 0 + ConfigurationParameters = [{Key, Value}] + Key = flags | iiop_in_connection_timeout | iiop_max_fragments | iiop_max_in_requests | interceptors | iiop_port | iiop_ssl_port + Value = as described in the User's Guide + Result = {ok, Ref} | {error, Reason} | {'EXCEPTION', #'BAD_PARAM'{}} + Ref = #Ref + Reason = string() + + +

Create a new process that handle requests for creating a new incoming + IIOP connection via the given interface and port. If the latter is + excluded, Orber will use the value of the iiop_port or + iiop_ssl_port configuration parameters. + The Type parameter determines if it is + supposed to be IIOP or IIOP via SSL. If successful, the returned + #Ref shall be passed to orber:remove_listen_interface/1 + when the connection shall be terminated.

+

It is also possible to supply configuration parameters that override + the global configuration. The iiop_in_connection_timeout, + iiop_max_fragments, iiop_max_in_requests and + interceptors parameters simply overrides the global + counterparts (See the + Configuration chapter + in the User's Guide). + But the following parameters there are a few restrictions:

+ + flags - currently it is only possible to override the global + setting for the Use Current Interface in IOR and + Exclude CodeSet Component flags. + iiop_port - requires that Use Current Interface in IOR + is activated and the supplied Type is normal. If so, + exported IOR:s will contain the IIOP port defined by this configuration + parameter. Otherwise, the global setting will be used. + iiop_ssl_port - almost equivalent to iiop_port. + The difference is that Type shall be ssl and that + exported IOR:s will contain the IIOP via SSL port defined by this configuration + parameter. + +

If it is not possible to add a listener based on the supplied interface + and port, the error message is one of the ones described in inet + and/or ssl documentation.

+ + + + remove_listen_interface(Ref) -> ok + Terminate listen process for incoming connection + + Ref = #Ref + + +

Terminates the listen process, associated with the supplied #Ref, + for incoming a connection. The Ref parameter is the return value from + the orber:add_listen_interface/2/3 operation. When terminating + the connection, all associated requests will not deliver a reply to + the clients.

+ + + + close_connection(Connection) -> Result + close_connection(Connection, Interface) -> Result + Terminate outgoing connection(s) + + Connection = Object | [{Host, Port}] + Object = #objref (external) + Host = string() + Port = string() + Interface = string() + Result = ok | {'EXCEPTION', #'BAD_PARAM'{}} + + +

Will try to close all outgoing connections to the host/port combinations + found in the supplied object reference or the given list of hosts/ports. + If a #'IOP_ServiceContext'{} containing a local interface has been + used when communicating with the remote object + (see also Module_Interface), + that interface shall be passed as the second argument. Otherwise, connections + via the default local interface, will be terminated.

+

+ +

Since several clients maybe communicates via the same connection, + they will be affected when invoking this operation. Other clients may + re-create the connection by invoking an operation on the target object.

+ + + + + secure() -> no | ssl + Display the security mode Orber is running in + +

This function returns the security mode Orber is running in, which is either no if it is an + insecure domain or the type of security mechanism used. For the moment the only security + mechanism is ssl. This is configured by setting the application variable + secure.

+ + + + ssl_server_certfile() -> string() + Display the path to the server certificate + +

This function returns a path to a file containing a chain of PEM encoded + certificates for the Orber domain as server. + This is configured by setting the application variable + ssl_server_certfile.

+ + + + ssl_client_certfile() -> string() + Display the path to the client certificate + +

This function returns a path to a file containing a chain of PEM encoded + certificates used in outgoing calls in the current process. + The default value is configured by setting the application variable + ssl_client_certfile.

+ + + + set_ssl_client_certfile(Path) -> ok + Set the value of the client certificate + + Path = string() + + +

This function takes a path to a file containing a chain of PEM encoded + certificates as parameter and sets it for the current process.

+ + + + ssl_server_verify() -> 0 | 1 | 2 + Display the SSL verification type for incoming calls + +

This function returns the type of verification used by SSL during authentication of the other + peer for incoming calls. + It is configured by setting the application variable + ssl_server_verify.

+ + + + ssl_client_verify() -> 0 | 1 | 2 + Display the SSL verification type for outgoing calls + +

This function returns the type of verification used by SSL during authentication of the other + peer for outgoing calls. + The default value is configured by setting the application variable + ssl_client_verify.

+ + + + set_ssl_client_verify(Value) -> ok + Set the value of the SSL verification type for outgoing calls + + Value = 0 | 1 | 2 + + +

This function sets the SSL verification type for the other peer of outgoing calls.

+ + + + ssl_server_depth() -> int() + Display the SSL verification depth for incoming calls + +

This function returns the SSL verification depth for incoming calls. + It is configured by setting the application variable + ssl_server_depth.

+ + + + ssl_client_depth() -> int() + Display the SSL verification depth for outgoing calls + +

This function returns the SSL verification depth for outgoing calls. + The default value is configured by setting the application variable + ssl_client_depth.

+ + + + set_ssl_client_depth(Depth) -> ok + Sets the value of the SSL verification depth for outgoing calls + + Depth = int() + + +

This function sets the SSL verification depth for the other peer of outgoing calls.

+ + + + objectkeys_gc_time() -> int() (seconds) + Display the Object Keys GC time value + +

This function returns the timeout value after which after which terminated object keys, + related to servers started with the configuration parameter {persistent, true}, + will be removed. + It can be configured by setting the application variable objectkeys_gc_time TimeVal (seconds), + if it is not set it will have the default value infinity.

+

Objects terminating with reason normal or shutdown are removed automatically.

+

Note: the objectkeys_gc_time configuration parameter (TimeVal) may only range between 0 and 1000000 seconds. + Otherwise, the default value is used.

+ + + + orber_nodes() -> RetVal + Displays which nodes that this orber domain consist of. + + RetVal = [node()] + + +

This function returns the list of node names that this orber + domain consists of.

+ + + + install(NodeList) -> ok + install(NodeList, Options) -> ok + Install the Orber application + + NodeList = [node()] + Options = [Option] + Option = {install_timeout, Timeout} | {ifr_storage_type, TableType} | {nameservice_storage_type, TableType} | {initialreferences_storage_type, TableType} | {load_order, Priority} + Timeout = infinity | integer() + TableType = disc_copies | ram_copies + Priority = integer() + + +

This function installs all the necessary mnesia tables and + load default data in some of them. If one or more Orber tables + already exists the installation fails. The function\011 + uninstall may be used, if it is safe, i.e., no other + application is running Orber.

+

Preconditions:

+ + a mnesia schema must exist before the installation + mnesia is running on the other nodes if the new installation + shall be a multi node domain + +

Mnesia will be started by the function if it is not already running on + the installation node and if it was started it will be stopped + afterwards.

+

The options that can be sent to the installation program is:

+ + {install_timeout, Timeout} - this timeout is how long we + will wait for the tables to be created. The Timeout value can be + infinity or an integer number in milliseconds. + Default is infinity. + {ifr_storage_type, TableType} - this option sets the + type of tables used for the interface repository. + The TableType can be disc_copies or ram_copies. Default is + disc_copies. + {initialreferences_storage_type, TableType} - this option + sets the type of table used for storing initial references. + The TableType can be disc_copies or ram_copies. Default is + ram_copies. + {nameservice_storage_type, TableType} - the default + behavior of Orber is to install the NameService as ram_copies. + This option makes it possible to change this to disc_copies. But + the user should be aware of that if a node is restarted, all + local object references stored in the NameService is not valid. + Hence, you cannot switch to disc_copies and expect exactly the same + behavior as before. + {load_order, Priority} - per default the priority is set to 0. + Using this option it will change the priority of in which order + Mnesia will load Orber internal tables. For more information, + consult the Mnesia documentation. + + + + + uninstall() -> ok + Uninstall the Orber application + +

This function stops the Orber application, terminates all server + objects and removes all Orber related mnesia tables.

+

Note: Since other applications may be running on the same node + using mnesia uninstall will not stop the mnesia application.

+ + + + add_node(Node, Options) -> RetVal + Add a new node to a group of Orber nodes. + + Node = node() + Options = IFRStorageType | [KeyValue] + IFRStorageType = StorageType + StorageType = disc_copies | ram_copies + KeyValue = {ifr_storage_type, StorageType} | {initialreferences_storage_type, StorageType} | {nameservice_storage_type, StorageType} | {type, Type} + Type = temporary | permanent + RetVal = ok | exit() + + +

This function add given node to a existing Orber node group and starts + Orber on the new node. orber:add_node is called from a member in the Orber + node group.

+

Preconditions for new node:

+ + Erlang started on the new node using the option -mnesia extra_db_nodes, e.g., + erl -sname new_node_name -mnesia extra_db_nodes ConnectToNodes_List + The new node's domain name is the same for the nodes we want to connect to. + Mnesia is running on the new node (no new schema created). + If the new node will use disc_copies the schema type must be changed using: + mnesia:change_table_copy_type(schema, node(), disc_copies). + +

Orber will be started by the function on the new node.

+

Fails if:

+ + Orber already installed on given node. + Mnesia not started as described above on the new node. + Impossible to copy data in Mnesia tables to the new node. + Not able to start Orber on the new node, due to, for example, the + iiop_port is already in use. + +

The function do not remove already copied tables after a failure. + Use orber:remove_node to remove these tables.

+ + + + remove_node(Node) -> RetVal + Removes a node from a group of Orber nodes. + + Node = node() + RetVal = ok | exit() + + +

This function removes given node from a Orber node group. The Mnesia + application is not stopped.

+ + + + configure(Key, Value) -> ok | {'EXIT', Reason} + Change Orber configuration. + + Key = orbDefaultInitRef | orbInitRef | giop_version | iiop_timeout | iiop_connection_timeout | iiop_setup_connection_timeout | iiop_in_connection_timeout | objectkeys_gc_time | orber_debug_level + Value = allowed value associated with the given key + + +

This function allows the user to configure Orber in, for example, + an Erlang shell. It is possible to invoke configure at any time + the keys specified above.

+

Any other key must be set before installing and starting Orber.

+

Trying to change the configuration in any other way is NOT + allowed since it may affect the behavior of Orber.

+

For more information regarding allowed values, see + configuration settings + in the User's Guide.

+

+ +

Configuring the IIOP timeout values will not affect already + existing connections. If you want a guaranteed uniform behavior, you + must set these parameters from the start.

+ + + + + + + -- cgit v1.2.3