path: root/lib/orber/doc/src/ch_stubs.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1999</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>