.TH Module_Interface 3 "orber  3.6.9" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
Module_Interface \- Orber generated stubs/skeletons\&.
.SH DESCRIPTION
.LP
This module contains the stub/skeleton functions generated by IC\&.
.LP
Starting a Orber server can be done in three ways:
.RS 2
.TP 2
*
Normal - when the server dies Orber forgets all knowledge of the server\&.
.TP 2
*
Supervisor child - adding the configuration parameter \fI{sup_child, true}\fR the \fIoe_create_link/2\fR function returns \fI{ok, Pid, ObjRef}\fR which can be handled by the application \fIsupervisor/stdlib-1\&.7\fR or later\&.
.TP 2
*
Persistent object reference - adding the configuration parameters \fI{persistent, true}\fR and \fI{regname, {global, term()}}\fR Orber will remember the object reference until the server terminates with reason \fInormal\fR or \fIshutdown\fR\&. Hence, if the server is started as a \fItransient\fR supervisor child we do not receive a \&'OBJECT_NOT_EXIST\&' exception when it has crashed and is being restarted\&.
.RE
.LP
The Orber stub can be used to start a \fIpseudo object\fR, which will create a non-server implementation\&. A pseudo object introduce some limitations:
.RS 2
.TP 2
*
The functions \fIoe_create_link/2\fR is equal to \fIoe_create/2\fR, i\&.e\&., no link can or will be created\&.
.TP 2
*
The \fIBIF:s self()\fR and \fIprocess_flag(trap_exit, true)\fR behaves incorrectly\&.
.TP 2
*
The \fIIC\fR option \fI{{impl, "M::I"}, "other_impl"}\fR has no effect\&. The call-back functions must be implemented in a file called \fIM_I_impl\&.erl\fR
.TP 2
*
The \fIIC\fR option \fIfrom\fR has no effect\&.
.TP 2
*
The call-back functions must be implemented as if the \fIIC\fR option \fI{this, "M::I"}\fR was used\&.
.TP 2
*
Server \fIState\fR changes have no effect\&. The user can provide information via the \fIEnv\fR start parameter and the State returned from \fIinit/2\fR will be the State passed in following invocations\&.
.TP 2
*
If a call-back function replies with the \fITimeout\fR parameter set it have no effect\&.
.TP 2
*
Operations defined as \fIoneway\fR are blocking until the operation replies\&.
.TP 2
*
The option \fI{pseudo, true}\fR overrides all other start options\&.
.TP 2
*
Only the functions, besides own definitions, \fIinit/2\fR (called via oe_create*/2) and \fIterminate/2\fR (called via corba:dispose/1) must be implemented\&.
.RE
.LP
By adopting the rules for \fIpseudo\fR objects described above we can use \fIoe_create/2\fR to create \fIserver\fR or \fIpseudo\fR objects, by excluding or including the option \fI{pseudo, true}\fR, without changing the call-back module\&. 
.LP
If you start a object without \fI{regname, RegName}\fR it can only be accessed through the returned object key\&. Started with a \fI{regname, RegName}\fR the name is registered locally or globally\&. 
.SS Warning:
.LP
To avoid flooding Orber with old object references start erlang using the flag \fI-orber objectkeys_gc_time Time\fR, 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 \fIinfinity\fR\&. For more information, see the orber and corba documentation\&.


.SH EXPORTS
.LP
.B
Module_Interface:typeID() -> TypeId
.br
.RS
.TP
Types
TypeId = string(), e\&.g\&., "IDL:Module/Interface:1\&.0"
.br
.RE
.RS
.LP
Returns the Type ID related to this stub/skeleton
.RE
.LP
.B
Module_Interface:oe_create() -> ObjRef
.br
.RS
.TP
Types
ObjRef = #object reference
.br
.RE
.RS
.LP
Start a Orber server\&.
.RE
.LP
.B
Module_Interface:oe_create_link() -> ObjRef
.br
.RS
.TP
Types
ObjRef = #object reference
.br
.RE
.RS
.LP
Start a linked Orber server\&.
.RE
.LP
.B
Module_Interface:oe_create(Env) -> ObjRef
.br
.RS
.TP
Types
Env = term()
.br
ObjRef = #object reference
.br
.RE
.RS
.LP
Start a Orber server passing Env to \fIinit/1\fR\&.
.RE
.LP
.B
Module_Interface:oe_create_link(Env) -> ObjRef
.br
.RS
.TP
Types
Env = term()
.br
ObjRef = #object reference
.br
.RE
.RS
.LP
Start a linked Orber server passing Env to \fIinit/1\fR\&.
.RE
.LP
.B
Module_Interface:oe_create(Env, Options) -> ObjRef
.br
.RS
.TP
Types
Env = term()
.br
ObjRef = #object reference
.br
Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]
.br
Bool = true | false
.br
RegName = {global, term()} | {local, atom()}
.br
CreateOpts = {debug, [Dbg]} | {timeout, Time}
.br
Dbg = trace | log | statistics | {log_to_file, FileName}
.br
.RE
.RS
.LP
Start a Orber server passing Env to \fIinit/1\fR\&.
.LP
If the option \fI{pseudo, true}\fR is used, all other options are overridden\&. As default, this option is set to false\&.
.LP
This function cannot be used for starting a server as supervisor child\&. If started as \fIpersistent\fR, the options \fI[{persistent, true}, {regname, {global, term()}}]\fR must be used and Orber will only forget the object reference if it terminates with reason \fInormal\fR or \fIshutdown\fR\&.
.LP
The option \fI{local_typecheck, boolean()}\fR, 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 \fIMAY ONLY\fR be used during testing and development\&.
.LP
\fI{survive_exit, boolean()}\fR overrides the EXIT Tolerance environment flag\&. If activated, the server will not terminate, even though the call-back module returns EXIT\&.
.LP
\fITime\fR specifies how long time, in milliseconds, the server is allowed to spend initializing\&. For more information about the \fIDbg\fR options, see the \fIsys\fR module\&.
.RE
.LP
.B
Module_Interface:oe_create_link(Env, Options) -> Return
.br
.RS
.TP
Types
Env = term()
.br
Return = ObjRef | {ok, Pid, ObjRef}
.br
ObjRef = #object reference
.br
Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]
.br
Bool = true | false
.br
RegName = {global, term()} | {local, atom()}
.br
CreateOpts = {debug, [Dbg]} | {timeout, Time}
.br
Dbg = trace | log | statistics | {log_to_file, FileName}
.br

.br

.br

.br
.RE
.RS
.LP
Start a linked Orber server passing Env to \fIinit/1\fR\&.
.LP
If the option \fI{pseudo, true}\fR is used, all other options are overridden and no link will be created\&. As default, this option is set to false\&.
.LP
This function can be used for starting a server as persistent or supervisor child\&. At the moment \fI[{persistent, true}, {regname, {global, term()}}]\fR 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 \fI\&'OBJECT_NOT_EXIST\&'\fR exception\&. Orber will only forget the object reference if it terminates with reason \fInormal\fR or \fIshutdown\fR, hence, the server must be started as \fItransient\fR (for more information see the supervisor documentation)\&.
.LP
The options \fI{local_typecheck, boolean()}\fR and \fI{survive_exit, boolean()}\fR behaves in the same way as for \fIoe_create/2\fR\&.
.LP
\fITime\fR specifies how long time, in milliseconds, the server is allowed to spend initializing\&. For more information about the \fIDbg\fR options, see the \fIsys\fR module\&.
.RE
.LP
.B
Module_Interface:own_functions(ObjRef, Arg1, \&.\&.\&., ArgN) -> Reply
.br
.B
Module_Interface:own_functions(ObjRef, Options, Arg1, \&.\&.\&., ArgN) -> Reply
.br
.RS
.TP
Types
ObjRef = #object reference
.br
Options = [Option] | Timeout
.br
Option = {timeout, Timeout} | {context, [Context]}
.br
Timeout = infinity | integer(milliseconds)
.br
Context = #\&'IOP_ServiceContext\&'{context_id = CtxId, context_data = CtxData}
.br
CtxId = ?ORBER_GENERIC_CTX_ID
.br
CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}
.br
Interface = string()
.br
Options = [{Key, Value}]
.br
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
.br
Value = allowed value associated with the given key
.br
ArgX = specified in the IDL-code\&.
.br
Reply = specified in the IDL-code\&.
.br
.RE
.RS
.LP
The default value for the \fITimeout\fR option is \fIinfinity\fR\&. IPv4 or IPv6 addresses are accepted as local Interface\&.
.LP
The \fIconfiguration\fR context is used to override the global SSL client side configuration\&.
.LP
To gain access to \fI#\&'IOP_ServiceContext\&'{}\fR record and the \fI?ORBER_GENERIC_CTX_ID\fR macro, you must add \fI-include_lib("orber/include/corba\&.hrl")\&.\fR to your module\&.
.RE
.SH CALLBACK FUNCTIONS
.LP
The following functions should be exported from a \fICORBA\fR callback module\&. Note, a complete template of the call-back module can be generated automatically by compiling the IDL-file with the IC option \fI{be, erl_template}\fR\&. One should also add the same compile options, for example \fIthis\fR or \fIfrom\fR, used when generating the stub/skeleton modules\&.
.SH EXPORTS
.LP
.B
Module_Interface_impl:init(Env) -> CallReply
.br
.RS
.TP
Types
Env = term()
.br
CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}
.br
State = term()
.br
Timeout = int() >= 0 | infinity
.br
StopReason = term()
.br
.RE
.RS
.LP
Whenever a new server is started, \fIinit/1\fR is the first function called in the specified call-back module\&.
.RE
.LP
.B
Module_Interface_impl:terminate(Reason, State) -> ok
.br
.RS
.TP
Types
Reason = term()
.br
State = term()
.br
.RE
.RS
.LP
This call-back function is called whenever the server is about to terminate\&.
.RE
.LP
.B
Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply
.br
.RS
.TP
Types
OldVsn = undefined | term()
.br
State = term()
.br
Extra = term()
.br
CallReply = {ok, NewState}
.br
NewState = term()
.br
.RE
.RS
.LP
Update the internal \fIState\fR\&.
.RE
.LP
.B
Module_Interface_impl:handle_info(Info, State) -> CallReply
.br
.RS
.TP
Types
Info = term()
.br
State = term()
.br
CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RS
.LP
If the configuration parameter \fI{{handle_info, "Module::Interface"}, true}\fR is passed to IC and \fIprocess_flag(trap_exit,true)\fR is set in the \fIinit()\fR call-back this function must be exported\&. 
.SS Note:
.LP
To be able to handle the \fITimeout\fR option in \fICallReply\fR in the call-back module the configuration parameter \fI{{handle_info, "Module::Interface"}, true}\fR must be passed to IC\&. 

.RE
.LP
.B
Module_Interface_impl:own_functions(State, Arg1, \&.\&.\&., ArgN) -> CallReply
.br
.B
Module_Interface_impl:own_functions(This, State, Arg1, \&.\&.\&., ArgN) -> CallReply
.br
.B
Module_Interface_impl:own_functions(This, From, State, Arg1, \&.\&.\&., ArgN) -> ExtCallReply
.br
.B
Module_Interface_impl:own_functions(From, State, Arg1, \&.\&.\&., ArgN) -> ExtCallReply
.br
.RS
.TP
Types
This = the servers #object reference
.br
State = term()
.br
ArgX = specified in the IDL-code\&.
.br
CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)
.br
ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}
.br
Reply = specified in the IDL-code\&.
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RS
.LP
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 \fIthis\fR and/or \fIfrom\fR are used, the implementation must accept the \fIThis\fR and/or \fIFrom\fR parameters\&.
.RE
.LP
.B
Module_Interface_impl:own_functions(State, Arg1, \&.\&.\&., ArgN) -> CastReply
.br
.B
Module_Interface_impl:own_functions(This, State, Arg1, \&.\&.\&., ArgN) -> CastReply
.br
.RS
.TP
Types
This = the servers #object reference
.br
State = term()
.br
CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}
.br
ArgX = specified in the IDL-code\&.
.br
Reply = specified in the IDL-code\&.
.br
Timeout = int() >= 0 | infinity
.br
StopReason = normal | shutdown | term()
.br
.RE
.RS
.LP
All one-way functions must return one of the listed replies\&. If the IC compile option \fIthis\fR is used, the implementation must accept the \fIThis\fR parameter\&.
.RE