diff options
Diffstat (limited to 'lib/orber/doc/src/Module_Interface.xml')
| -rw-r--r-- | lib/orber/doc/src/Module_Interface.xml | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/lib/orber/doc/src/Module_Interface.xml b/lib/orber/doc/src/Module_Interface.xml new file mode 100644 index 0000000000..85f19ccf49 --- /dev/null +++ b/lib/orber/doc/src/Module_Interface.xml @@ -0,0 +1,355 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1999</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Module_Interface</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1999-09-03</date> + <rev>A</rev> + </header> + <module>Module_Interface</module> + <modulesummary>Orber generated stubs/skeletons.</modulesummary> + <description> + <p>This module contains the stub/skeleton functions generated by IC.</p> + <p>Starting a Orber server can be done in three ways:</p> + <list type="bulleted"> + <item>Normal - when the server dies Orber forgets all knowledge of the server.</item> + <item>Supervisor child - adding the configuration parameter <c>{sup_child, true}</c> + the <c>oe_create_link/2</c> function returns <c>{ok, Pid, ObjRef}</c> which + can be handled by the application <em>supervisor/stdlib-1.7</em> or later. </item> + <item>Persistent object reference - adding the configuration parameters <c>{persistent, true}</c> + and <c>{regname, {global, term()}}</c> Orber will remember the object reference until the + server terminates with reason <em>normal</em> or <em>shutdown</em>. Hence, + if the server is started as a <em>transient</em> supervisor child we do not + receive a 'OBJECT_NOT_EXIST' exception when it has crashed and is being restarted.</item> + </list> + <p>The Orber stub can be used to start a <c>pseudo object</c>, which will create a non-server implementation. + A pseudo object introduce some limitations:</p> + <list type="bulleted"> + <item>The functions <c>oe_create_link/2</c> is equal to <c>oe_create/2</c>, i.e., + no link can or will be created.</item> + <item>The <c>BIF:s self()</c> and <c>process_flag(trap_exit,true)</c> behaves incorrectly.</item> + <item>The <c>IC</c> option <c>{{impl, "M::I"}, "other_impl"}</c> has no effect. The call-back + functions must be implemented in a file called <c>M_I_impl.erl</c></item> + <item>The <c>IC</c> option <c>from</c> has no effect. </item> + <item>The call-back functions must be implemented as if the <c>IC</c> option + <c>{this, "M::I"}</c> was used.</item> + <item>Server <c>State</c> changes have no effect. The user can provide information via + the <c>Env</c> start parameter and the State returned from <c>init/2</c> will be the State + passed in following invocations.</item> + <item>If a call-back function replies with the <c>Timeout</c> parameter set it have no effect.</item> + <item>Operations defined as <c>oneway</c> are blocking until the operation replies.</item> + <item>The option <c>{pseudo, true}</c> overrides all other start options.</item> + <item>Only the functions, besides own definitions, <c>init/2</c> (called via oe_create*/2) and + <c>terminate/2</c> (called via corba:dispose/1) must be implemented.</item> + </list> + <p>By adopting the rules for <c>pseudo</c> objects described above we can use <c>oe_create/2</c> + to create <c>server</c> or <c>pseudo</c> objects, by excluding or including the + option <c>{pseudo, true}</c>, without changing the call-back module. + </p> + <p>If you start a object without <c>{regname, RegName}</c> it can only be accessed through the returned object key. + Started with a <c>{regname, RegName}</c> the name is registered locally or globally. + </p> + <warning> + <p>To avoid flooding Orber with old object references start erlang using the flag + <em>-orber objectkeys_gc_time Time</em>, which will remove all object references + related to servers being dead for Time seconds. To avoid extra overhead, i.e., performing + garbage collect if no persistent objects are started, the objectkeys_gc_time default value + is <em>infinity</em>. For more information, see the orber and corba documentation.</p> + </warning> + </description> + <funcs> + <func> + <name>Module_Interface:typeID() -> TypeId</name> + <fsummary>Return the Type ID related to this stub/skeleton</fsummary> + <type> + <v>TypeId = string(), e.g., "IDL:Module/Interface:1.0"</v> + </type> + <desc> + <p>Returns the Type ID related to this stub/skeleton</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create() -> ObjRef</name> + <fsummary>Start a Orber server.</fsummary> + <type> + <v>ObjRef = #object reference</v> + </type> + <desc> + <p>Start a Orber server.</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create_link() -> ObjRef</name> + <fsummary>Start a linked Orber server.</fsummary> + <type> + <v>ObjRef = #object reference</v> + </type> + <desc> + <p>Start a linked Orber server.</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create(Env) -> ObjRef</name> + <fsummary>Start a Orber server.</fsummary> + <type> + <v>Env = term()</v> + <v>ObjRef = #object reference</v> + </type> + <desc> + <p>Start a Orber server passing Env to <c>init/1</c>.</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create_link(Env) -> ObjRef</name> + <fsummary>Start a linked Orber server.</fsummary> + <type> + <v>Env = term()</v> + <v>ObjRef = #object reference</v> + </type> + <desc> + <p>Start a linked Orber server passing Env to <c>init/1</c>.</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create(Env, Options) -> ObjRef</name> + <fsummary>Start a Orber stub/skeleton</fsummary> + <type> + <v>Env = term()</v> + <v>ObjRef = #object reference</v> + <v>Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v> + <v>Bool = true | false</v> + <v>RegName = {global, term()} | {local, atom()}</v> + <v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v> + <v>Dbg = trace | log | statistics | {log_to_file, FileName}</v> + </type> + <desc> + <p>Start a Orber server passing Env to <c>init/1</c>.</p> + <p>If the option <c>{pseudo, true}</c> is used, all other options are overridden. + As default, this option is set to false.</p> + <p>This function cannot be used for starting a server as supervisor child. + If started as <c>persistent</c>, the options <c>[{persistent, true}, {regname, {global, term()}}]</c> must be used and + Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>.</p> + <p>The option <c>{local_typecheck, boolean()}</c>, which overrides the + <seealso marker="ch_install#flags">Local Typechecking</seealso> + environment flag, turns on or off typechecking. If activated, + parameters, replies and raised exceptions will be checked to ensure that + the data is correct, when invoking operations on CORBA Objects within + the same Orber domain. Due to the extra overhead, this option + <em>MAY ONLY</em> be used during testing and development.</p> + <p><c>{survive_exit, boolean()}</c> overrides the + <seealso marker="ch_install#flags">EXIT Tolerance</seealso> + environment flag. If activated, the server will not terminate, even though + the call-back module returns EXIT.</p> + <p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to + spend initializing. For more information about the <c>Dbg</c> options, + see the <c>sys</c> module.</p> + </desc> + </func> + <func> + <name>Module_Interface:oe_create_link(Env, Options) -> Return</name> + <fsummary>Start a Orber stub/skeleton</fsummary> + <type> + <v>Env = term()</v> + <v>Return = ObjRef | {ok, Pid, ObjRef}</v> + <v>ObjRef = #object reference</v> + <v>Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v> + <v>Bool = true | false</v> + <v>RegName = {global, term()} | {local, atom()}</v> + <v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v> + <v>Dbg = trace | log | statistics | {log_to_file, FileName}</v> + <v></v> + <v></v> + <v></v> + </type> + <desc> + <p>Start a linked Orber server passing Env to <c>init/1</c>.</p> + <p>If the option <c>{pseudo, true}</c> is used, all other options are overridden and no link will be created. + As default, this option is set to false.</p> + <p>This function can be used for starting a server as persistent or supervisor child. At the moment + <c>[{persistent, true}, {regname, {global, term()}}]</c> must be used to start + a server as persistent, i.e., if a server died and is in the process of being restarted + a call to the server will not raise <c>'OBJECT_NOT_EXIST'</c> exception. + Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>, + hence, the server must be started as <em>transient</em> (for more information see the + supervisor documentation).</p> + <p>The options <c>{local_typecheck, boolean()}</c> and <c>{survive_exit, boolean()}</c> + behaves in the same way as for <c>oe_create/2</c>.</p> + <p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to + spend initializing. For more information about the <c>Dbg</c> options, + see the <c>sys</c> module.</p> + </desc> + </func> + <func> + <name>Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply</name> + <name>Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>ObjRef = #object reference</v> + <v>Options = [Option] | Timeout</v> + <v>Option = {timeout, Timeout} | {context, [Context]}</v> + <v>Timeout = infinity | integer(milliseconds)</v> + <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v> + <v>CtxId = ?ORBER_GENERIC_CTX_ID</v> + <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v> + <v>Interface = string()</v> + <v>Options = [{Key, Value}]</v> + <v>Key = ssl_client_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile | + ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout</v> + <v>Value = allowed value associated with the given key</v> + <v>ArgX = specified in the IDL-code.</v> + <v>Reply = specified in the IDL-code.</v> + </type> + <desc> + <p>The default value for the <c>Timeout</c> option is <c>infinity</c>. + IPv4 or IPv6 addresses are accepted as local Interface.</p> + <p>The <em>configuration</em> context is used to override the global + SSL client side + <seealso marker="ch_install#config">configuration</seealso>.</p> + <p>To gain access to <c>#'IOP_ServiceContext'{}</c> record and the + <c>?ORBER_GENERIC_CTX_ID</c> macro, you must add + <c>-include_lib("orber/include/corba.hrl").</c> to your module.</p> + </desc> + </func> + </funcs> + + <section> + <title>CALLBACK FUNCTIONS</title> + <p>The following functions should be exported from a <c>CORBA</c> + callback module. Note, a complete template of the call-back module can + be generated automatically by compiling the IDL-file with the IC option + <c>{be,erl_template}</c>. One should also add + the same compile options, for example <c>this</c> or <c>from</c>, + used when generating the stub/skeleton modules.</p> + </section> + <funcs> + <func> + <name>Module_Interface_impl:init(Env) -> CallReply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>Env = term()</v> + <v>CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}</v> + <v>State = term()</v> + <v>Timeout = int() >= 0 | infinity</v> + <v>StopReason = term()</v> + </type> + <desc> + <p>Whenever a new server is started, <em>init/1</em> is the first function called in the specified call-back module.</p> + </desc> + </func> + <func> + <name>Module_Interface_impl:terminate(Reason, State) -> ok</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>Reason = term()</v> + <v>State = term()</v> + </type> + <desc> + <p>This call-back function is called whenever the server is about to terminate.</p> + </desc> + </func> + <func> + <name>Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>OldVsn = undefined | term()</v> + <v>State = term()</v> + <v>Extra = term()</v> + <v>CallReply = {ok, NewState}</v> + <v>NewState = term()</v> + </type> + <desc> + <p>Update the internal <c>State</c>.</p> + </desc> + </func> + <func> + <name>Module_Interface_impl:handle_info(Info, State) -> CallReply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>Info = term()</v> + <v>State = term()</v> + <v>CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v> + <v>Timeout = int() >= 0 | infinity</v> + <v>StopReason = normal | shutdown | term()</v> + </type> + <desc> + <p>If the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em> + is passed to IC and <em>process_flag(trap_exit,true)</em> is set in the <em>init()</em> + call-back this function must be exported. </p> + <note> + <p>To be able to handle the <c>Timeout</c> option in <c>CallReply</c> in the call-back + module the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em> must + be passed to IC. </p> + </note> + </desc> + </func> + <func> + <name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply</name> + <name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply</name> + <name>Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply</name> + <name>Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>This = the servers #object reference</v> + <v>State = term()</v> + <v>ArgX = specified in the IDL-code.</v> + <v>CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)</v> + <v>ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}</v> + <v>Reply = specified in the IDL-code.</v> + <v>Timeout = int() >= 0 | infinity</v> + <v>StopReason = normal | shutdown | term()</v> + </type> + <desc> + <p>All two-way functions must return one of the listed replies or raise any of + the exceptions listed in the IDL code (i.e. raises(...)). + If the IC compile options <em>this</em> and/or <em>from</em> are used, + the implementation must accept the <em>This</em> and/or <em>From</em> + parameters.</p> + </desc> + </func> + <func> + <name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply</name> + <name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply</name> + <fsummary>User defined function which is not a part of Orber</fsummary> + <type> + <v>This = the servers #object reference</v> + <v>State = term()</v> + <v>CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v> + <v>ArgX = specified in the IDL-code.</v> + <v>Reply = specified in the IDL-code.</v> + <v>Timeout = int() >= 0 | infinity</v> + <v>StopReason = normal | shutdown | term()</v> + </type> + <desc> + <p>All one-way functions must return one of the listed replies. + If the IC compile option <em>this</em> is used, + the implementation must accept the <em>This</em> parameter.</p> + </desc> + </func> + </funcs> + +</erlref> + |