aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/Module_Interface.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/orber/doc/src/Module_Interface.xml')
-rw-r--r--lib/orber/doc/src/Module_Interface.xml355
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>
+