Orber Stubs/Skeletons

10 Orber Stubs/Skeletons
10.1 Orber stubs and skeletons description.
This example describes the API and behavior of Orber stubs and skeletons.
10.1.1 Server start
Orber servers can be started in several ways. The chosen start functions determines how the server can be accessed and its behavior.
Using Module_Interface:oe_create() or oe_create_link():

No initial data can be passed.
Cannot be used as a supervisor child start function.
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.

Using Module_Interface:oe_create(Env) or oe_create_link(Env):

Initial data can be passed using Env.
Cannot be used as a supervisor child start function.
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.

Using Module_Interface:oe_create(Env, Options):

Initial data can be passed using Env.
Cannot be used as a supervisor child start function.
Accessible through the object reference returned by the start function. If the option {regname, RegName} is used the object reference stays valid even if the server has been restarted.
If the options {persistent, true} and {regname, {global, Name}} is used, the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' only if the object has terminated with reason normal or shutdown. If the object is in the process of restarting, the result will be {error, Reason} or the exception 'COMM_FAILURE'.

Using Module_Interface:oe_create_link(Env, Options):

Initial data can be passed using Env.
Can be used as a supervisor child start function if the option {sup_child, true} used.
Accessible through the object reference returned by the start function. If the option {regname, RegName} is used the object reference stays valid even if the server has been restarted.
If the options {persistent, true} and {regname, {global, Name}} is used, the result from an object invocation will be the exception 'OBJECT_NOT_EXIST' only if the object has terminated with reason normal or shutdown. If the object is in the process of restarting, the result will be {error, Reason} or the exception 'COMM_FAILURE'.
For starting a server as a supervisor child you should use the options [{persistent, true}, {regname, {global, Name}}, {sup_child, true}] and of type transient. 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 supervisor/stdlib-1.7 or later and that the it returns {ok, Pid, Object} instead of just Object.

To avoid flooding Orber with old object references start erlang using the flag -orber objectkeys_gc_time Time, 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 infinity. For more information, see the orber and corba documentation.

Orber still allow oe_create(Env, {Type,RegName}) and oe_create_link(Env, {Type,RegName}) to be used, but may not in future releases.

10.1.2 Call-back module
This section provides an example of how a call-back module may be implemented.

Arguments and Replies are determined by the IDL-code and, hence, not further described here.
%%%-----------------------------------------------------------
%%% 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
    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}
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"}
own_function(This, State, .. Arguments ..) ->

%% 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"}
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 ------------------------------

      