Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
Module_Interface - Orber generated stubs/skeletons.
DESCRIPTION
This module contains the stub/skeleton functions generated by IC.
Starting a Orber server can be done in three ways:
* Normal - when the server dies Orber forgets all knowledge of the server.
* Supervisor child - adding the configuration parameter {sup_child, true} the
oe_create_link/2 function returns {ok, Pid, ObjRef} which can be handled by the
application supervisor/stdlib-1.7 or later.
* Persistent object reference - adding the configuration parameters {persistent, true}
and {regname, {global, term()}} Orber will remember the object reference until the
server terminates with reason normal or shutdown. Hence, if the server is started as a
transient supervisor child we do not receive a 'OBJECT_NOT_EXIST' exception when it
has crashed and is being restarted.
The Orber stub can be used to start a pseudo object, which will create a non-server
implementation. A pseudo object introduce some limitations:
* The functions oe_create_link/2 is equal to oe_create/2, i.e., no link can or will be
created.
* The BIF:s self() and process_flag(trap_exit,true) behaves incorrectly.
* The IC option {{impl, "M::I"}, "other_impl"} has no effect. The call-back functions
must be implemented in a file called M_I_impl.erl
* The IC option from has no effect.
* The call-back functions must be implemented as if the IC option {this, "M::I"} was
used.
* Server State changes have no effect. The user can provide information via the Env
start parameter and the State returned from init/2 will be the State passed in
following invocations.
* If a call-back function replies with the Timeout parameter set it have no effect.
* Operations defined as oneway are blocking until the operation replies.
* The option {pseudo, true} overrides all other start options.
* Only the functions, besides own definitions, init/2 (called via oe_create*/2) and
terminate/2 (called via corba:dispose/1) must be implemented.
By adopting the rules for pseudo objects described above we can use oe_create/2 to create
server or pseudo objects, by excluding or including the option {pseudo, true}, without
changing the call-back module.
If you start a object without {regname, RegName} it can only be accessed through the
returned object key. Started with a {regname, RegName} the name is registered locally or
globally.
Warning:
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.
EXPORTS
Module_Interface:typeID() -> TypeId
Types:
TypeId = string(), e.g., "IDL:Module/Interface:1.0"
Returns the Type ID related to this stub/skeleton
Module_Interface:oe_create() -> ObjRef
Types:
ObjRef = #object reference
Start a Orber server.
Module_Interface:oe_create_link() -> ObjRef
Types:
ObjRef = #object reference
Start a linked Orber server.
Module_Interface:oe_create(Env) -> ObjRef
Types:
Env = term()
ObjRef = #object reference
Start a Orber server passing Env to init/1.
Module_Interface:oe_create_link(Env) -> ObjRef
Types:
Env = term()
ObjRef = #object reference
Start a linked Orber server passing Env to init/1.
Module_Interface:oe_create(Env, Options) -> ObjRef
Types:
Env = term()
ObjRef = #object reference
Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} |
{pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} |
{create_options, [CreateOpts]}]
Bool = true | false
RegName = {global, term()} | {local, atom()}
CreateOpts = {debug, [Dbg]} | {timeout, Time}
Dbg = trace | log | statistics | {log_to_file, FileName}
Start a Orber server passing Env to init/1.
If the option {pseudo, true} is used, all other options are overridden. As default,
this option is set to false.
This function cannot be used for starting a server as supervisor child. If started
as persistent, the options [{persistent, true}, {regname, {global, term()}}] must
be used and Orber will only forget the object reference if it terminates with
reason normal or shutdown.
The option {local_typecheck, boolean()}, which overrides the Local Typechecking
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 MAY ONLY be used during testing and development.
{survive_exit, boolean()} overrides the EXIT Tolerance environment flag. If
activated, the server will not terminate, even though the call-back module returns
EXIT.
Time specifies how long time, in milliseconds, the server is allowed to spend
initializing. For more information about the Dbg options, see the sys module.
Module_Interface:oe_create_link(Env, Options) -> Return
Types:
Env = term()
Return = ObjRef | {ok, Pid, ObjRef}
ObjRef = #object reference
Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} |
{pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} |
{create_options, [CreateOpts]}]
Bool = true | false
RegName = {global, term()} | {local, atom()}
CreateOpts = {debug, [Dbg]} | {timeout, Time}
Dbg = trace | log | statistics | {log_to_file, FileName}
Start a linked Orber server passing Env to init/1.
If the option {pseudo, true} is used, all other options are overridden and no link
will be created. As default, this option is set to false.
This function can be used for starting a server as persistent or supervisor child.
At the moment [{persistent, true}, {regname, {global, term()}}] 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 'OBJECT_NOT_EXIST' exception. Orber
will only forget the object reference if it terminates with reason normal or
shutdown, hence, the server must be started as transient (for more information see
the supervisor documentation).
The options {local_typecheck, boolean()} and {survive_exit, boolean()} behaves in
the same way as for oe_create/2.
Time specifies how long time, in milliseconds, the server is allowed to spend
initializing. For more information about the Dbg options, see the sys module.
Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply
Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply
Types:
ObjRef = #object reference
Options = [Option] | Timeout
Option = {timeout, Timeout} | {context, [Context]}
Timeout = infinity | integer(milliseconds)
Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}
CtxId = ?ORBER_GENERIC_CTX_ID
CtxData = {interface, Interface} | {userspecific, term()} | {configuration,
Options}
Interface = string()
Options = [{Key, Value}]
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
Value = allowed value associated with the given key
ArgX = specified in the IDL-code.
Reply = specified in the IDL-code.
The default value for the Timeout option is infinity. IPv4 or IPv6 addresses are
accepted as local Interface.
The configuration context is used to override the global SSL client side
configuration.
To gain access to #'IOP_ServiceContext'{} record and the ?ORBER_GENERIC_CTX_ID
macro, you must add -include_lib("orber/include/corba.hrl"). to your module.
CALLBACK FUNCTIONS
The following functions should be exported from a CORBA callback module. Note, a complete
template of the call-back module can be generated automatically by compiling the IDL-file
with the IC option {be,erl_template}. One should also add the same compile options, for
example this or from, used when generating the stub/skeleton modules.
EXPORTS
Module_Interface_impl:init(Env) -> CallReply
Types:
Env = term()
CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}
State = term()
Timeout = int() >= 0 | infinity
StopReason = term()
Whenever a new server is started, init/1 is the first function called in the
specified call-back module.
Module_Interface_impl:terminate(Reason, State) -> ok
Types:
Reason = term()
State = term()
This call-back function is called whenever the server is about to terminate.
Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply
Types:
OldVsn = undefined | term()
State = term()
Extra = term()
CallReply = {ok, NewState}
NewState = term()
Update the internal State.
Module_Interface_impl:handle_info(Info, State) -> CallReply
Types:
Info = term()
State = term()
CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason,
State}
Timeout = int() >= 0 | infinity
StopReason = normal | shutdown | term()
If the configuration parameter {{handle_info, "Module::Interface"}, true} is passed
to IC and process_flag(trap_exit,true) is set in the init() call-back this function
must be exported.
Note:
To be able to handle the Timeout option in CallReply in the call-back module the
configuration parameter {{handle_info, "Module::Interface"}, true} must be passed
to IC.
Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply
Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply
Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply
Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply
Types:
This = the servers #object reference
State = term()
ArgX = specified in the IDL-code.
CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop,
StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)
ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} |
corba:reply(From, Reply), {noreply, State, Timeout}
Reply = specified in the IDL-code.
Timeout = int() >= 0 | infinity
StopReason = normal | shutdown | term()
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
this and/or from are used, the implementation must accept the This and/or From
parameters.
Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply
Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply
Types:
This = the servers #object reference
State = term()
CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason,
State}
ArgX = specified in the IDL-code.
Reply = specified in the IDL-code.
Timeout = int() >= 0 | infinity
StopReason = normal | shutdown | term()
All one-way functions must return one of the listed replies. If the IC compile
option this is used, the implementation must accept the This parameter.