1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>Module_Interface</title>
30
<date>1999-09-03</date>
33
<module>Module_Interface</module>
34
<modulesummary>Orber generated stubs/skeletons.</modulesummary>
36
<p>This module contains the stub/skeleton functions generated by IC.</p>
37
<p>Starting a Orber server can be done in three ways:</p>
38
<list type="bulleted">
39
<item>Normal - when the server dies Orber forgets all knowledge of the server.</item>
40
<item>Supervisor child - adding the configuration parameter <c>{sup_child, true}</c>
41
the <c>oe_create_link/2</c> function returns <c>{ok, Pid, ObjRef}</c> which
42
can be handled by the application <em>supervisor/stdlib-1.7</em> or later. </item>
43
<item>Persistent object reference - adding the configuration parameters <c>{persistent, true}</c>
44
and <c>{regname, {global, term()}}</c> Orber will remember the object reference until the
45
server terminates with reason <em>normal</em> or <em>shutdown</em>. Hence,
46
if the server is started as a <em>transient</em> supervisor child we do not
47
receive a 'OBJECT_NOT_EXIST' exception when it has crashed and is being restarted.</item>
49
<p>The Orber stub can be used to start a <c>pseudo object</c>, which will create a non-server implementation.
50
A pseudo object introduce some limitations:</p>
51
<list type="bulleted">
52
<item>The functions <c>oe_create_link/2</c> is equal to <c>oe_create/2</c>, i.e.,
53
no link can or will be created.</item>
54
<item>The <c>BIF:s self()</c> and <c>process_flag(trap_exit,true)</c> behaves incorrectly.</item>
55
<item>The <c>IC</c> option <c>{{impl, "M::I"}, "other_impl"}</c> has no effect. The call-back
56
functions must be implemented in a file called <c>M_I_impl.erl</c></item>
57
<item>The <c>IC</c> option <c>from</c> has no effect. </item>
58
<item>The call-back functions must be implemented as if the <c>IC</c> option
59
<c>{this, "M::I"}</c> was used.</item>
60
<item>Server <c>State</c> changes have no effect. The user can provide information via
61
the <c>Env</c> start parameter and the State returned from <c>init/2</c> will be the State
62
passed in following invocations.</item>
63
<item>If a call-back function replies with the <c>Timeout</c> parameter set it have no effect.</item>
64
<item>Operations defined as <c>oneway</c> are blocking until the operation replies.</item>
65
<item>The option <c>{pseudo, true}</c> overrides all other start options.</item>
66
<item>Only the functions, besides own definitions, <c>init/2</c> (called via oe_create*/2) and
67
<c>terminate/2</c> (called via corba:dispose/1) must be implemented.</item>
69
<p>By adopting the rules for <c>pseudo</c> objects described above we can use <c>oe_create/2</c>
70
to create <c>server</c> or <c>pseudo</c> objects, by excluding or including the
71
option <c>{pseudo, true}</c>, without changing the call-back module.
73
<p>If you start a object without <c>{regname, RegName}</c> it can only be accessed through the returned object key.
74
Started with a <c>{regname, RegName}</c> the name is registered locally or globally.
77
<p>To avoid flooding Orber with old object references start erlang using the flag
78
<em>-orber objectkeys_gc_time Time</em>, which will remove all object references
79
related to servers being dead for Time seconds. To avoid extra overhead, i.e., performing
80
garbage collect if no persistent objects are started, the objectkeys_gc_time default value
81
is <em>infinity</em>. For more information, see the orber and corba documentation.</p>
86
<name>Module_Interface:typeID() -> TypeId</name>
87
<fsummary>Return the Type ID related to this stub/skeleton</fsummary>
89
<v>TypeId = string(), e.g., "IDL:Module/Interface:1.0"</v>
92
<p>Returns the Type ID related to this stub/skeleton</p>
96
<name>Module_Interface:oe_create() -> ObjRef</name>
97
<fsummary>Start a Orber server.</fsummary>
99
<v>ObjRef = #object reference</v>
102
<p>Start a Orber server.</p>
106
<name>Module_Interface:oe_create_link() -> ObjRef</name>
107
<fsummary>Start a linked Orber server.</fsummary>
109
<v>ObjRef = #object reference</v>
112
<p>Start a linked Orber server.</p>
116
<name>Module_Interface:oe_create(Env) -> ObjRef</name>
117
<fsummary>Start a Orber server.</fsummary>
120
<v>ObjRef = #object reference</v>
123
<p>Start a Orber server passing Env to <c>init/1</c>.</p>
127
<name>Module_Interface:oe_create_link(Env) -> ObjRef</name>
128
<fsummary>Start a linked Orber server.</fsummary>
131
<v>ObjRef = #object reference</v>
134
<p>Start a linked Orber server passing Env to <c>init/1</c>.</p>
138
<name>Module_Interface:oe_create(Env, Options) -> ObjRef</name>
139
<fsummary>Start a Orber stub/skeleton</fsummary>
142
<v>ObjRef = #object reference</v>
143
<v>Options = [{sup_child, false} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v>
144
<v>Bool = true | false</v>
145
<v>RegName = {global, term()} | {local, atom()}</v>
146
<v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v>
147
<v>Dbg = trace | log | statistics | {log_to_file, FileName}</v>
150
<p>Start a Orber server passing Env to <c>init/1</c>.</p>
151
<p>If the option <c>{pseudo, true}</c> is used, all other options are overridden.
152
As default, this option is set to false.</p>
153
<p>This function cannot be used for starting a server as supervisor child.
154
If started as <c>persistent</c>, the options <c>[{persistent, true}, {regname, {global, term()}}]</c> must be used and
155
Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>.</p>
156
<p>The option <c>{local_typecheck, boolean()}</c>, which overrides the
157
<seealso marker="ch_install#flags">Local Typechecking</seealso>
158
environment flag, turns on or off typechecking. If activated,
159
parameters, replies and raised exceptions will be checked to ensure that
160
the data is correct, when invoking operations on CORBA Objects within
161
the same Orber domain. Due to the extra overhead, this option
162
<em>MAY ONLY</em> be used during testing and development.</p>
163
<p><c>{survive_exit, boolean()}</c> overrides the
164
<seealso marker="ch_install#flags">EXIT Tolerance</seealso>
165
environment flag. If activated, the server will not terminate, even though
166
the call-back module returns EXIT.</p>
167
<p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to
168
spend initializing. For more information about the <c>Dbg</c> options,
169
see the <c>sys</c> module.</p>
173
<name>Module_Interface:oe_create_link(Env, Options) -> Return</name>
174
<fsummary>Start a Orber stub/skeleton</fsummary>
177
<v>Return = ObjRef | {ok, Pid, ObjRef}</v>
178
<v>ObjRef = #object reference</v>
179
<v>Options = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool} | {survive_exit, Bool} | {create_options, [CreateOpts]}]</v>
180
<v>Bool = true | false</v>
181
<v>RegName = {global, term()} | {local, atom()}</v>
182
<v>CreateOpts = {debug, [Dbg]} | {timeout, Time}</v>
183
<v>Dbg = trace | log | statistics | {log_to_file, FileName}</v>
189
<p>Start a linked Orber server passing Env to <c>init/1</c>.</p>
190
<p>If the option <c>{pseudo, true}</c> is used, all other options are overridden and no link will be created.
191
As default, this option is set to false.</p>
192
<p>This function can be used for starting a server as persistent or supervisor child. At the moment
193
<c>[{persistent, true}, {regname, {global, term()}}]</c> must be used to start
194
a server as persistent, i.e., if a server died and is in the process of being restarted
195
a call to the server will not raise <c>'OBJECT_NOT_EXIST'</c> exception.
196
Orber will only forget the object reference if it terminates with reason <em>normal</em> or <em>shutdown</em>,
197
hence, the server must be started as <em>transient</em> (for more information see the
198
supervisor documentation).</p>
199
<p>The options <c>{local_typecheck, boolean()}</c> and <c>{survive_exit, boolean()}</c>
200
behaves in the same way as for <c>oe_create/2</c>.</p>
201
<p><c>Time</c> specifies how long time, in milliseconds, the server is allowed to
202
spend initializing. For more information about the <c>Dbg</c> options,
203
see the <c>sys</c> module.</p>
207
<name>Module_Interface:own_functions(ObjRef, Arg1, ..., ArgN) -> Reply</name>
208
<name>Module_Interface:own_functions(ObjRef, Options, Arg1, ..., ArgN) -> Reply</name>
209
<fsummary>User defined function which is not a part of Orber</fsummary>
211
<v>ObjRef = #object reference</v>
212
<v>Options = [Option] | Timeout</v>
213
<v>Option = {timeout, Timeout} | {context, [Context]}</v>
214
<v>Timeout = infinity | integer(milliseconds)</v>
215
<v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
216
<v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
217
<v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
218
<v>Interface = string()</v>
219
<v>Options = [{Key, Value}]</v>
220
<v>Key = ssl_client_verify | ssl_client_depth | ssl_client_certfile | ssl_client_cacertfile |
221
ssl_client_password | ssl_client_keyfile | ssl_client_ciphers | ssl_client_cachetimeout</v>
222
<v>Value = allowed value associated with the given key</v>
223
<v>ArgX = specified in the IDL-code.</v>
224
<v>Reply = specified in the IDL-code.</v>
227
<p>The default value for the <c>Timeout</c> option is <c>infinity</c>.
228
IPv4 or IPv6 addresses are accepted as local Interface.</p>
229
<p>The <em>configuration</em> context is used to override the global
231
<seealso marker="ch_install#config">configuration</seealso>.</p>
232
<p>To gain access to <c>#'IOP_ServiceContext'{}</c> record and the
233
<c>?ORBER_GENERIC_CTX_ID</c> macro, you must add
234
<c>-include_lib("orber/include/corba.hrl").</c> to your module.</p>
240
<title>CALLBACK FUNCTIONS</title>
241
<p>The following functions should be exported from a <c>CORBA</c>
242
callback module. Note, a complete template of the call-back module can
243
be generated automatically by compiling the IDL-file with the IC option
244
<c>{be,erl_template}</c>. One should also add
245
the same compile options, for example <c>this</c> or <c>from</c>,
246
used when generating the stub/skeleton modules.</p>
250
<name>Module_Interface_impl:init(Env) -> CallReply</name>
251
<fsummary>User defined function which is not a part of Orber</fsummary>
254
<v>CallReply = {ok, State} | {ok, State, Timeout} | ignore | {stop, StopReason}</v>
255
<v>State = term()</v>
256
<v>Timeout = int() >= 0 | infinity</v>
257
<v>StopReason = term()</v>
260
<p>Whenever a new server is started, <em>init/1</em> is the first function called in the specified call-back module.</p>
264
<name>Module_Interface_impl:terminate(Reason, State) -> ok</name>
265
<fsummary>User defined function which is not a part of Orber</fsummary>
267
<v>Reason = term()</v>
268
<v>State = term()</v>
271
<p>This call-back function is called whenever the server is about to terminate.</p>
275
<name>Module_Interface_impl:code_change(OldVsn, State, Extra) -> CallReply</name>
276
<fsummary>User defined function which is not a part of Orber</fsummary>
278
<v>OldVsn = undefined | term()</v>
279
<v>State = term()</v>
280
<v>Extra = term()</v>
281
<v>CallReply = {ok, NewState}</v>
282
<v>NewState = term()</v>
285
<p>Update the internal <c>State</c>.</p>
289
<name>Module_Interface_impl:handle_info(Info, State) -> CallReply</name>
290
<fsummary>User defined function which is not a part of Orber</fsummary>
293
<v>State = term()</v>
294
<v>CallReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v>
295
<v>Timeout = int() >= 0 | infinity</v>
296
<v>StopReason = normal | shutdown | term()</v>
299
<p>If the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em>
300
is passed to IC and <em>process_flag(trap_exit,true)</em> is set in the <em>init()</em>
301
call-back this function must be exported. </p>
303
<p>To be able to handle the <c>Timeout</c> option in <c>CallReply</c> in the call-back
304
module the configuration parameter <em>{{handle_info, "Module::Interface"}, true}</em> must
305
be passed to IC. </p>
310
<name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CallReply</name>
311
<name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CallReply</name>
312
<name>Module_Interface_impl:own_functions(This, From, State, Arg1, ..., ArgN) -> ExtCallReply</name>
313
<name>Module_Interface_impl:own_functions(From, State, Arg1, ..., ArgN) -> ExtCallReply</name>
314
<fsummary>User defined function which is not a part of Orber</fsummary>
316
<v>This = the servers #object reference</v>
317
<v>State = term()</v>
318
<v>ArgX = specified in the IDL-code.</v>
319
<v>CallReply = {reply, Reply, State} | {reply, Reply, State, Timeout} | {stop, StopReason, Reply, State} | {stop, StopReason, State} | corba:raise(Exception)</v>
320
<v>ExtCallReply = CallReply | corba:reply(From, Reply), {noreply, State} | corba:reply(From, Reply), {noreply, State, Timeout}</v>
321
<v>Reply = specified in the IDL-code.</v>
322
<v>Timeout = int() >= 0 | infinity</v>
323
<v>StopReason = normal | shutdown | term()</v>
326
<p>All two-way functions must return one of the listed replies or raise any of
327
the exceptions listed in the IDL code (i.e. raises(...)).
328
If the IC compile options <em>this</em> and/or <em>from</em> are used,
329
the implementation must accept the <em>This</em> and/or <em>From</em>
334
<name>Module_Interface_impl:own_functions(State, Arg1, ..., ArgN) -> CastReply</name>
335
<name>Module_Interface_impl:own_functions(This, State, Arg1, ..., ArgN) -> CastReply</name>
336
<fsummary>User defined function which is not a part of Orber</fsummary>
338
<v>This = the servers #object reference</v>
339
<v>State = term()</v>
340
<v>CastReply = {noreply, State} | {noreply, State, Timeout} | {stop, StopReason, State}</v>
341
<v>ArgX = specified in the IDL-code.</v>
342
<v>Reply = specified in the IDL-code.</v>
343
<v>Timeout = int() >= 0 | infinity</v>
344
<v>StopReason = normal | shutdown | term()</v>
347
<p>All one-way functions must return one of the listed replies.
348
If the IC compile option <em>this</em> is used,
349
the implementation must accept the <em>This</em> parameter.</p>
added
removed
lib/orber/doc/src/Module_Interface.xml
