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