The R13B03 release.OTP_R13B03

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>
+