1Module_Interface(3)        Erlang Module Definition        Module_Interface(3)
2
3
4

NAME

6       Module_Interface - Orber generated stubs/skeletons.
7

DESCRIPTION

9       This module contains the stub/skeleton functions generated by IC.
10
11       Starting a Orber server can be done in three ways:
12
13         * Normal  -  when  the server dies Orber forgets all knowledge of the
14           server.
15
16         * Supervisor child - adding the configuration  parameter  {sup_child,
17           true} the oe_create_link/2 function returns {ok, Pid, ObjRef} which
18           can be handled by the application supervisor/stdlib-1.7 or later.
19
20         * Persistent object reference - adding the  configuration  parameters
21           {persistent,  true}  and {regname, {global, term()}} Orber will re‐
22           member the object reference until the server terminates with reason
23           normal  or shutdown. Hence, if the server is started as a transient
24           supervisor child we do not receive a  'OBJECT_NOT_EXIST'  exception
25           when it has crashed and is being restarted.
26
27       The  Orber stub can be used to start a pseudo object, which will create
28       a non-server implementation. A pseudo  object  introduce  some  limita‐
29       tions:
30
31         * The  functions  oe_create_link/2  is equal to oe_create/2, i.e., no
32           link can or will be created.
33
34         * The BIF:s self() and  process_flag(trap_exit,true)  behaves  incor‐
35           rectly.
36
37         * The  IC  option  {{impl,  "M::I"}, "other_impl"} has no effect. The
38           call-back  functions  must  be  implemented  in   a   file   called
39           M_I_impl.erl
40
41         * The IC option from has no effect.
42
43         * The  call-back  functions  must  be implemented as if the IC option
44           {this, "M::I"} was used.
45
46         * Server State changes have no effect. The user can provide  informa‐
47           tion via the Env start parameter and the State returned from init/2
48           will be the State passed in following invocations.
49
50         * If a call-back function replies with the Timeout parameter  set  it
51           have no effect.
52
53         * Operations  defined  as  oneway  are  blocking  until the operation
54           replies.
55
56         * The option {pseudo, true} overrides all other start options.
57
58         * Only the functions, besides own  definitions,  init/2  (called  via
59           oe_create*/2)  and terminate/2 (called via corba:dispose/1) must be
60           implemented.
61
62       By adopting the rules for pseudo objects described  above  we  can  use
63       oe_create/2 to create server or pseudo objects, by excluding or includ‐
64       ing the option {pseudo, true}, without changing the call-back module.
65
66       If you start a object without {regname, RegName} it  can  only  be  ac‐
67       cessed  through  the returned object key. Started with a {regname, Reg‐
68       Name} the name is registered locally or globally.
69
70   Warning:
71       To avoid flooding Orber with old object references start  erlang  using
72       the  flag  -orber objectkeys_gc_time Time, which will remove all object
73       references related to servers being dead for Time seconds. To avoid ex‐
74       tra overhead, i.e., performing garbage collect if no persistent objects
75       are started, the objectkeys_gc_time default value is infinity. For more
76       information, see the orber and corba documentation.
77
78

EXPORTS

80       Module_Interface:typeID() -> TypeId
81
82              Types:
83
84                 TypeId = string(), e.g., "IDL:Module/Interface:1.0"
85
86              Returns the Type ID related to this stub/skeleton
87
88       Module_Interface:oe_create() -> ObjRef
89
90              Types:
91
92                 ObjRef = #object reference
93
94              Start a Orber server.
95
96       Module_Interface:oe_create_link() -> ObjRef
97
98              Types:
99
100                 ObjRef = #object reference
101
102              Start a linked Orber server.
103
104       Module_Interface:oe_create(Env) -> ObjRef
105
106              Types:
107
108                 Env = term()
109                 ObjRef = #object reference
110
111              Start a Orber server passing Env to init/1.
112
113       Module_Interface:oe_create_link(Env) -> ObjRef
114
115              Types:
116
117                 Env = term()
118                 ObjRef = #object reference
119
120              Start a linked Orber server passing Env to init/1.
121
122       Module_Interface:oe_create(Env, Options) -> ObjRef
123
124              Types:
125
126                 Env = term()
127                 ObjRef = #object reference
128                 Options  =  [{sup_child,  false} | {persistent, Bool} | {reg‐
129                 name, RegName} | {pseudo, Bool} | {local_typecheck,  Bool}  |
130                 {survive_exit, Bool} | {create_options, [CreateOpts]}]
131                 Bool = true | false
132                 RegName = {global, term()} | {local, atom()}
133                 CreateOpts = {debug, [Dbg]} | {timeout, Time}
134                 Dbg = trace | log | statistics | {log_to_file, FileName}
135
136              Start a Orber server passing Env to init/1.
137
138              If  the  option  {pseudo,  true}  is used, all other options are
139              overridden. As default, this option is set to false.
140
141              This function cannot be used for starting a server as supervisor
142              child.  If  started  as  persistent,  the  options [{persistent,
143              true}, {regname, {global, term()}}] must be used and Orber  will
144              only  forget  the  object reference if it terminates with reason
145              normal or shutdown.
146
147              The option {local_typecheck, boolean()}, which overrides the Lo‐
148              cal Typechecking environment flag, turns on or off typechecking.
149              If activated, parameters, replies and raised exceptions will  be
150              checked to ensure that the data is correct, when invoking opera‐
151              tions on CORBA Objects within the same Orber domain. Due to  the
152              extra  overhead, this option MAY ONLY be used during testing and
153              development.
154
155              {survive_exit, boolean()} overrides the EXIT Tolerance  environ‐
156              ment  flag.  If  activated,  the server will not terminate, even
157              though the call-back module returns EXIT.
158
159              Time specifies how long time, in milliseconds, the server is al‐
160              lowed  to spend initializing. For more information about the Dbg
161              options, see the sys module.
162
163       Module_Interface:oe_create_link(Env, Options) -> Return
164
165              Types:
166
167                 Env = term()
168                 Return = ObjRef | {ok, Pid, ObjRef}
169                 ObjRef = #object reference
170                 Options = [{sup_child, Bool} | {persistent, Bool} | {regname,
171                 RegName}  |  {pseudo, Bool} | {local_typecheck, Bool} | {sur‐
172                 vive_exit, Bool} | {create_options, [CreateOpts]}]
173                 Bool = true | false
174                 RegName = {global, term()} | {local, atom()}
175                 CreateOpts = {debug, [Dbg]} | {timeout, Time}
176                 Dbg = trace | log | statistics | {log_to_file, FileName}
177
178
179
180
181              Start a linked Orber server passing Env to init/1.
182
183              If the option {pseudo, true} is  used,  all  other  options  are
184              overridden  and no link will be created. As default, this option
185              is set to false.
186
187              This function can be used for starting a server as persistent or
188              supervisor  child.  At the moment [{persistent, true}, {regname,
189              {global, term()}}] must be used to start a server as persistent,
190              i.e.,  if a server died and is in the process of being restarted
191              a call to the server will not  raise  'OBJECT_NOT_EXIST'  excep‐
192              tion.  Orber  will only forget the object reference if it termi‐
193              nates with reason normal or shutdown, hence, the server must  be
194              started  as  transient  (for more information see the supervisor
195              documentation).
196
197              The  options  {local_typecheck,  boolean()}  and  {survive_exit,
198              boolean()} behaves in the same way as for oe_create/2.
199
200              Time specifies how long time, in milliseconds, the server is al‐
201              lowed to spend initializing. For more information about the  Dbg
202              options, see the sys module.
203
204       Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply
205       Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Re‐
206       ply
207
208              Types:
209
210                 ObjRef = #object reference
211                 Options = [Option] | Timeout
212                 Option = {timeout, Timeout} | {context, [Context]}
213                 Timeout = infinity | integer(milliseconds)
214                 Context  =  #'IOP_ServiceContext'{context_id  =  CtxId,  con‐
215                 text_data = CtxData}
216                 CtxId = ?ORBER_GENERIC_CTX_ID
217                 CtxData  =  {interface, Interface} | {userspecific, term()} |
218                 {configuration, Options}
219                 Interface = string()
220                 Options = [{Key, Value}]
221                 Key = ssl_client_verify | ssl_client_depth | ssl_client_cert‐
222                 file   |   ssl_client_cacertfile   |   ssl_client_password  |
223                 ssl_client_keyfile  |  ssl_client_ciphers  |   ssl_client_ca‐
224                 chetimeout
225                 Value = allowed value associated with the given key
226                 ArgX = specified in the IDL-code.
227                 Reply = specified in the IDL-code.
228
229              The  default  value  for the Timeout option is infinity. IPv4 or
230              IPv6 addresses are accepted as local Interface.
231
232              The configuration context is used to  override  the  global  SSL
233              client side configuration.
234
235              To  gain  access  to #'IOP_ServiceContext'{} record and the ?OR‐
236              BER_GENERIC_CTX_ID macro, you must  add  -include_lib("orber/in‐
237              clude/corba.hrl"). to your module.
238

CALLBACK FUNCTIONS

240       The  following  functions should be exported from a CORBA callback mod‐
241       ule. Note, a complete template of the call-back module can be generated
242       automatically by compiling the IDL-file with the IC option {be,erl_tem‐
243       plate}. One should also add the same compile options, for example  this
244       or from, used when generating the stub/skeleton modules.
245

EXPORTS

247       Module_Interface_impl:init(Env) -> CallReply
248
249              Types:
250
251                 Env = term()
252                 CallReply  =  {ok,  State}  | {ok, State, Timeout} | ignore |
253                 {stop, StopReason}
254                 State = term()
255                 Timeout = int() >= 0 | infinity
256                 StopReason = term()
257
258              Whenever a new server is started, init/1 is the  first  function
259              called in the specified call-back module.
260
261       Module_Interface_impl:terminate(Reason, State) -> ok
262
263              Types:
264
265                 Reason = term()
266                 State = term()
267
268              This  call-back  function is called whenever the server is about
269              to terminate.
270
271       Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply
272
273              Types:
274
275                 OldVsn = undefined | term()
276                 State = term()
277                 Extra = term()
278                 CallReply = {ok, NewState}
279                 NewState = term()
280
281              Update the internal State.
282
283       Module_Interface_impl:handle_info(Info, State) -> CallReply
284
285              Types:
286
287                 Info = term()
288                 State = term()
289                 CallReply = {noreply, State} | {noreply,  State,  Timeout}  |
290                 {stop, StopReason, State}
291                 Timeout = int() >= 0 | infinity
292                 StopReason = normal | shutdown | term()
293
294              If  the  configuration  parameter {{handle_info, "Module::Inter‐
295              face"}, true} is passed to IC  and  process_flag(trap_exit,true)
296              is set in the init() call-back this function must be exported.
297
298          Note:
299              To  be  able  to  handle  the Timeout option in CallReply in the
300              call-back  module  the  configuration  parameter  {{handle_info,
301              "Module::Interface"}, true} must be passed to IC.
302
303
304       Module_Interface_impl:own_functions(State,  Arg1, ..., ArgN) -> CallRe‐
305       ply
306       Module_Interface_impl:own_functions(This, State, Arg1,  ...,  ArgN)  ->
307       CallReply
308       Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN)
309       -> ExtCallReply
310       Module_Interface_impl:own_functions(From, State, Arg1,  ...,  ArgN)  ->
311       ExtCallReply
312
313              Types:
314
315                 This = the servers #object reference
316                 State = term()
317                 ArgX = specified in the IDL-code.
318                 CallReply  =  {reply,  Reply,  State} | {reply, Reply, State,
319                 Timeout} | {stop, StopReason, Reply, State} | {stop, StopRea‐
320                 son, State} | corba:raise(Exception)
321                 ExtCallReply  =  CallReply | corba:reply(From, Reply), {nore‐
322                 ply, State}  |  corba:reply(From,  Reply),  {noreply,  State,
323                 Timeout}
324                 Reply = specified in the IDL-code.
325                 Timeout = int() >= 0 | infinity
326                 StopReason = normal | shutdown | term()
327
328              All  two-way  functions must return one of the listed replies or
329              raise any of  the  exceptions  listed  in  the  IDL  code  (i.e.
330              raises(...)).  If  the  IC  compile options this and/or from are
331              used, the implementation must accept the This and/or From param‐
332              eters.
333
334       Module_Interface_impl:own_functions(State,  Arg1, ..., ArgN) -> CastRe‐
335       ply
336       Module_Interface_impl:own_functions(This, State, Arg1,  ...,  ArgN)  ->
337       CastReply
338
339              Types:
340
341                 This = the servers #object reference
342                 State = term()
343                 CastReply  =  {noreply,  State} | {noreply, State, Timeout} |
344                 {stop, StopReason, State}
345                 ArgX = specified in the IDL-code.
346                 Reply = specified in the IDL-code.
347                 Timeout = int() >= 0 | infinity
348                 StopReason = normal | shutdown | term()
349
350              All one-way functions must return one of the listed replies.  If
351              the  IC compile option this is used, the implementation must ac‐
352              cept the This parameter.
353
354
355
356Ericsson AB                       orber 5.0.2              Module_Interface(3)
Impressum