The R13B03 release.OTP_R13B03

1 files changed, 283 insertions, 0 deletions

diff --git a/lib/orber/doc/src/ch_stubs.xml b/lib/orber/doc/src/ch_stubs.xml
new file mode 100644
index 0000000000..785805a4d6
--- /dev/null
+++ b/lib/orber/doc/src/ch_stubs.xml
@@ -0,0 +1,283 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1999</year><year>2009</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.
+    
+    </legalnotice>
+
+    <title>Orber Stubs/Skeletons</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date>1999-09-03</date>
+    <rev>A</rev>
+    <file>ch_stubs.xml</file>
+  </header>
+
+  <section>
+    <title>Orber Stubs and Skeletons Description</title>
+    <p>This example describes the API and behavior of Orber stubs and skeletons.
+      </p>
+
+    <section>
+      <title>Server Start</title>
+      <p>Orber servers can be started in several ways. The chosen start functions determines
+        how the server can be accessed and its behavior.
+        </p>
+      <p>Using <c>Module_Interface:oe_create()</c> or <c>oe_create_link()</c>:
+        </p>
+      <list type="bulleted">
+        <item>No initial data can be passed.</item>
+        <item>Cannot be used as a supervisor child start function.</item>
+        <item>Only accessible through the object reference returned by the start function.
+         The object reference is no longer valid if the server dies and is restarted.</item>
+      </list>
+      <p>Using <c>Module_Interface:oe_create(Env)</c> or <c>oe_create_link(Env)</c>:</p>
+      <list type="bulleted">
+        <item>Initial data can be passed using <c>Env</c>.</item>
+        <item>Cannot be used as a supervisor child start function.</item>
+        <item>Only accessible through the object reference returned by the start function.
+         The object reference is no longer valid if the server dies and is restarted.</item>
+      </list>
+      <p>Using <c>Module_Interface:oe_create(Env, Options)</c>:</p>
+      <list type="bulleted">
+        <item>Initial data can be passed using <c>Env</c>.</item>
+        <item>Cannot be used as a supervisor child start function.</item>
+        <item>Accessible through the object reference returned by the start function. If the option 
+        <c>{regname, RegName}</c> is used the object reference stays valid even if the 
+         server has been restarted.</item>
+        <item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used, 
+         the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' 
+         only if the object has terminated with reason 
+        <c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result 
+         will be <c>{error, Reason}</c> or a system exception is raised.</item>
+        <item>The option <c>{pseudo, true}</c> makes it possible to start create non-server objects.
+         There are, however, some limitations, which are further described in the
+        <c>Pseudo objects</c> section.</item>
+      </list>
+      <p>Using <c>Module_Interface:oe_create_link(Env, Options)</c>:</p>
+      <list type="bulleted">
+        <item>Initial data can be passed using <c>Env</c>.</item>
+        <item>Can be used as a supervisor child start function if the option <c>{sup_child, true}</c> used.</item>
+        <item>Accessible through the object reference returned by the start function. If the option 
+        <c>{regname, RegName}</c> is used the object reference stays valid even if the 
+         server has been restarted.</item>
+        <item>If the options <c>{persistent, true}</c> and <c>{regname, {global, Name}}</c> is used, 
+         the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' 
+         only if the object has terminated with reason 
+        <c>normal</c> or <c>shutdown</c>. If the object is in the process of restarting, the result 
+         will be <c>{error, Reason}</c> or a system exception is raised.</item>
+        <item>For starting a server as a supervisor child you should use the options 
+        <c>[{persistent, true}, {regname, {global, Name}}, {sup_child, true}]</c> and of type <em>transient</em>.
+         This configuration allows you to delegate restarts to the supervisor and still be able to
+         use the same object reference and be able to see if the server is permanently terminated.
+         Please note you must use <em>supervisor/stdlib-1.7</em> or later and that the it returns 
+        <c>{ok, Pid, Object}</c> instead of just <c>Object</c>.</item>
+        <item>Using the option <c>{pseudo, true}</c> have the same effect as using
+        <c>oe_create/2</c>.</item>
+      </list>
+      <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>
+      <warning>
+        <p>Orber still allow <c>oe_create(Env, {Type,RegName})</c> and <c>oe_create_link(Env, {Type,RegName})</c> to be used,
+          but may not in future releases.</p>
+      </warning>
+    </section>
+
+    <section>
+      <title>Pseudo Objects</title>
+      <p>This section describes Orber pseudo objects.
+        </p>
+      <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 call-back functions must be implemented as if the <c>IC</c> option 
+        <c>{this, "M::I"}</c> was used.</item>
+        <item>The gen_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>The server reply <c>Timeout</c> has no effect.</item>
+        <item>The compile option <c>from</c> has no effect.</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>To create a pseudo object do the following:</p>
+      <code type="none">
+fingolfin 127> erl 
+Erlang (BEAM) emulator version 4.9
+ 
+Eshell V4.9  (abort with ^G)
+1> ic:gen(myDefinition, [{this, "MyModule::MyInterface"}]).
+Erlang IDL compiler version 20
+ok
+2> make:all().
+Recompile: oe_MyDefinition
+Recompile: MyModule_MyInterface
+Recompile: MyModule_MyInterface_impl
+up_to_date
+3> PseudoObj = MyModule_MyInterface:oe_create(Env, [{pseudo, true}]).
+      </code>
+      <p>The call-back functions must be implemented as <c>MyFunction(OE_THIS, State, Args)</c>,
+        and called by <c>MyModule_MyInterface:MyFunction(PseudoObj, Args)</c>.</p>
+    </section>
+
+    <section>
+      <title>Call-back Module</title>
+      <p>This section provides an example of how a call-back module may be implemented.</p>
+      <note>
+        <p>Arguments and Replies are determined by the IDL-code and, hence, not
+          further described here.</p>
+      </note>
+      <code type="none">
+%%%-----------------------------------------------------------
+%%% File    : Module_Interface_impl.erl
+%%% Author  : 
+%%% Purpose : 
+%%% Created : 
+%%%-----------------------------------------------------------
+ 
+-module('Module_Interface_impl').
+ 
+%%--------------- INCLUDES -----------------------------------
+-include_lib("orber/include/corba.hrl").
+-include_lib(".. ..").
+ 
+%%--------------- EXPORTS-------------------------------------
+%% Arity depends on IC configuration parameters and the IDL
+%% specification.
+-export([own_function/X]).
+ 
+ 
+%%--------------- gen_server specific ------------------------
+-export([init/1, terminate/2, code_change/3, handle_info/2]).
+ 
+%%------------------------------------------------------------
+%% function : server specific
+%%------------------------------------------------------------
+init(InitialData) ->
+    %% 'trap_exit' optional (have no effect if pseudo object).
+    process_flag(trap_exit,true),
+
+    %%--- Possible replies ---
+    %% Reply and await next request
+    {ok, State}.
+
+    %% Reply and if no more requests within Time the special 
+    %% timeout message should be handled in the 
+    %% Module_Interface_impl:handle_info/2 call-back function (use the 
+    %% IC option {{handle_info, "Module::Interface"}, true}).
+    {ok, State, Timeout} 
+
+    %% Return ignore in order to inform the parent, especially if it is a 
+    %% supervisor, that the server, as an example, did not start in 
+    %% accordance with the configuration data. 
+    ignore 
+    %% If the initializing procedure fails, the reason 
+    %% is supplied as StopReason.
+    {stop, StopReason}
+
+terminate(Reason, State) ->
+    ok.
+
+code_change(OldVsn, State, Extra) ->
+    {ok, NewState}.
+
+%% If use IC option {{handle_info, "Module::Interface"}, true}. 
+%% (have no effect if pseudo object).
+handle_info(Info, State) ->
+    %%--- Possible replies ---
+    %% Await the next invocation.
+    {noreply, State}.
+    %% Stop with Reason.
+    {stop, Reason, State}.
+
+%%--- two-way ------------------------------------------------
+%% If use IC option {this, "Module:Interface"} 
+%% (Required for pseudo objects)
+own_function(This, State, .. Arguments ..) ->
+%% IC options this and from
+own_function(This, From, State, .. Arguments ..) ->
+%% IC option from
+own_function(From, State, .. Arguments ..) ->
+    %% Send explicit reply to client.
+    corba:reply(From, Reply),
+    %%--- Possible replies ---
+    {noreply, State}
+    {noreply, State, Timeout}
+
+ 
+%% If not use IC option {this, "Module:Interface"}
+own_function(State, .. Arguments ..) ->
+    %%--- Possible replies ---
+    %% Reply and await next request
+    {reply, Reply, State}
+
+    %% Reply and if no more requests within Time the special 
+    %% timeout message should be handled in the 
+    %% Module_Interface_impl:handle_info/2 call-back function (use the
+    %% IC option {{handle_info, "Module::Interface"}, true}).
+    {reply, Reply, State, Timeout}
+
+    %% Stop the server and send Reply to invoking object.
+    {stop, StopReason, Reply, State}
+
+    %% Stop the server and send no reply to invoking object.
+    {stop, StopReason, State}
+
+    %% Raise exception. Any changes to the internal State is lost.
+    corba:raise(Exception).
+
+%%--- one-way ------------------------------------------------
+%% If use IC option {this, "Module:Interface"}
+%% (Required for pseudo objects)
+own_function(This, State, .. Arguments ..) ->
+
+%% If not use IC option {this, "Module:Interface"}
+own_function(State, .. Arguments ..) ->
+    %%--- Possible results ---
+    {noreply, State}
+
+    %% Release and if no more requests within Time the special 
+    %% timeout message should be handled in the 
+    %% Module_Interface_impl:handle_info/2 call-back function (use the
+    %%  IC option {{handle_info, "Module::Interface"}, true}).
+    {noreply, State, Timeout}
+
+    %% Stop the server with StopReason.
+    {stop, StopReason, State}
+
+%%--------------- END OF MODULE ------------------------------
+      </code>
+    </section>
+  </section>
+</chapter>
+