From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/orber/doc/src/Module_Interface.xml | 355 +++++++++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 lib/orber/doc/src/Module_Interface.xml (limited to 'lib/orber/doc/src/Module_Interface.xml') diff --git a/lib/orber/doc/src/Module_Interface.xml b/lib/orber/doc/src/Module_Interface.xml new file mode 100644 index 0000000000..85f19ccf49 --- /dev/null +++ b/lib/orber/doc/src/Module_Interface.xml @@ -0,0 +1,355 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + Module_Interface + + + + 1999-09-03 + A +
+ Module_Interface + Orber generated stubs/skeletons. + +

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. +

+ +

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.

+ + + + + Module_Interface:typeID() -> TypeId + Return the Type ID related to this stub/skeleton + + TypeId = string(), e.g., "IDL:Module/Interface:1.0" + + +

Returns the Type ID related to this stub/skeleton

+ + + + Module_Interface:oe_create() -> ObjRef + Start a Orber server. + + ObjRef = #object reference + + +

Start a Orber server.

+ + + + Module_Interface:oe_create_link() -> ObjRef + Start a linked Orber server. + + ObjRef = #object reference + + +

Start a linked Orber server.

+ + + + Module_Interface:oe_create(Env) -> ObjRef + Start a Orber server. + + Env = term() + ObjRef = #object reference + + +

Start a Orber server passing Env to init/1.

+ + + + Module_Interface:oe_create_link(Env) -> ObjRef + Start a linked Orber server. + + Env = term() + ObjRef = #object reference + + +

Start a linked Orber server passing Env to init/1.

+ + + + Module_Interface:oe_create(Env, Options) -> ObjRef + Start a Orber stub/skeleton + + 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 + Start a Orber stub/skeleton + + 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 + User defined function which is not a part of Orber + + 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.

+
+ + + Module_Interface_impl:init(Env) -> CallReply + User defined function which is not a part of Orber + + 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 + User defined function which is not a part of Orber + + 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 + User defined function which is not a part of Orber + + OldVsn = undefined | term() + State = term() + Extra = term() + CallReply = {ok, NewState} + NewState = term() + + +

Update the internal State.

+ + + + Module_Interface_impl:handle_info(Info, State) -> CallReply + User defined function which is not a part of Orber + + 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.

+ +

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 + User defined function which is not a part of Orber + + 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 + User defined function which is not a part of Orber + + 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.

+ + + + + + -- cgit v1.2.3