aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/corba.xml
blob: cae0e09b0b83d72558ce2ab78238a12962be5bd9 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2009</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.
    
    </legalnotice>

    <title>corba</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date>1997-06-10</date>
    <rev>A</rev>
  </header>
  <module>corba</module>
  <modulesummary>The functions on CORBA module level</modulesummary>
  <description>
    <p>This module contains functions that are specified on the CORBA module
      level. It also contains some functions for creating and disposing
      objects.</p>
  </description>
  <funcs>
    <func>
      <name>create(Module, TypeID) -> Object</name>
      <name>create(Module, TypeID, Env) -> Object</name>
      <name>create(Module, TypeID, Env, Optons1) -> Object</name>
      <name>create_link(Module, TypeID) -> Object</name>
      <name>create_link(Module, TypeID, Env) -> Object</name>
      <name>create_link(Module, TypeID, Env, Options2) -> Reply</name>
      <fsummary>Create and start a new server object</fsummary>
      <type>
        <v>Module = atom()</v>
        <v>TypeID = string()</v>
        <v>Env = term()</v>
        <v>Options1 = [{persistent, Bool} | {regname, RegName} | {local_typecheck, Bool}]</v>
        <v>Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool} | {local_typecheck, Bool}]</v>
        <v>RegName = {local, atom()} | {global, term()}</v>
        <v>Reply = #objref | {ok, Pid, #objref}</v>
        <v>Bool = true | false</v>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>These functions start a new server object. If you start it
          without <em>RegName</em> it can only be accessed through the 
          returned object key. Started with a <em>RegName</em> the name is
          registered locally or globally. </p>
        <p><em>TypeID</em> is the repository ID of the server object type and 
          could for example look like "IDL:StackModule/Stack:1.0". </p>
        <p><em>Module</em> is the name of the interface API module. </p>
        <p><em>Env</em> is the arguments passed which will be passed to the 
          implementations <em>init</em> call-back function.</p>
        <p>A server started with create/2, create/3 or create/4 does not care
          about the parent, which means that the parent is not handled
          explicitly in  the  generic process part. </p>
        <p>A server started with create_link2, create_link/3 or create_link/4
          is initially linked to the caller, the parent, and it will
          terminate whenever the parent process terminates, and with the same 
          reason as the parent. If the server traps exits, the terminate/2 
          call-back function is called in order to clean up before the 
          termination. These functions should be used if the server is a 
          worker in a supervision tree.</p>
        <p>If you use the option <c>{sup_child, true}</c> create_link/4 will return
          <c>{ok, Pid, #objref}</c>, otherwise <c>#objref</c>, and make it possible
          to start a server as a supervisor child (stdlib-1.7 or later).</p>
        <p>If you use the option <c>{persistent, true}</c> you also must use the option
          <c>{regname, {global, Name}}</c>. This combination makes it possible to tell
          the difference between a server permanently terminated or in the process of restarting.</p>
        <p>The option <c>{pseudo, true}</c>, allow us to create an object which is not a
          server. Using <c>{pseudo, true}</c> overrides all other start options. 
          For more information see section <c>Module_Interface</c>.</p>
        <p>If a server is started using the option <c>{persistent, true}</c> the object key
          will not be removed unless it terminates with reason <em>normal</em> or <em>shutdown</em>.
          Hence, if persistent servers is used as supervisor children they should be <em>transient</em>
          and the <em>objectkeys_gc_time</em> should be modified (default equals <c>infinity</c>).</p>
        <p>The option <c>{local_typecheck, boolean()}</c>, which overrides the
          <seealso marker="ch_install#flags">Local Typechecking</seealso>
          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 
          <em>MAY ONLY</em> be used during testing and development.</p>
        <code type="none">
Example: 

  corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", {10, test})
        </code>
      </desc>
    </func>
    <func>
      <name>dispose(Object) -> ok</name>
      <fsummary>Stop a server object</fsummary>
      <type>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>This function is used for terminating the execution of a 
          server object. Invoking this operation on a NIL object reference,
          e.g., the return value of <c>corba:create_nil_objref/0</c>, always
          return ok. For valid object references, invoking this operation
          more than once, will result in a system exception.</p>
      </desc>
    </func>
    <func>
      <name>create_nil_objref() -> Object</name>
      <fsummary>Stop a server object</fsummary>
      <type>
        <v>Object = #objref representing NIL.</v>
      </type>
      <desc>
        <p>Creates an object reference that represents the NIL value.
          Attempts to invoke operations using the returned object reference
          will return a system exception.</p>
      </desc>
    </func>
    <func>
      <name>create_subobject_key(Object, Key) -> Result</name>
      <fsummary>Add an Erlang term to a private key field</fsummary>
      <type>
        <v>Object = #objref</v>
        <v>Key = term()</v>
        <v>Result = #objref</v>
      </type>
      <desc>
        <p>This function is used to create a subobject in a server object.
          It can for example be useful when one wants unique access to 
          separate rows in a mnesia or an ETS table. The <em>Result</em> is
          an object reference that will be seen as a unique reference to 
          the outside world but will access the same server object where one 
          can use the <em>get_subobject_key/1</em> function to get the private
          key value.</p>
        <p><em>Key</em> is stored in the object reference <em>Object</em>.
          If it is a binary it will be stored as is and otherwise it is 
          converted to a binary before storage.</p>
      </desc>
    </func>
    <func>
      <name>get_subobject_key(Object) -> Result</name>
      <fsummary>Fetch the contents of the private key field</fsummary>
      <type>
        <v>Object = #objref</v>
        <v>Result = #binary</v>
      </type>
      <desc>
        <p>This function is used to fetch a subobject key from the object 
          reference <em>Object</em>. The result is a always a binary, if it 
          was an Erlang term that was stored with <em>create_subobject_key/2</em>
          one can to do <em>binary_to_term/1</em> to get the real value. </p>
      </desc>
    </func>
    <func>
      <name>get_pid(Object) -> Result</name>
      <fsummary>Get the process id from an object key</fsummary>
      <type>
        <v>Object = #objref</v>
        <v>Result = #pid | {error, Reason} | {'EXCEPTION',E}</v>
      </type>
      <desc>
        <p>This function is to get the process id  from an object, which is a 
          must when CORBA objects is started/handled in a supervisor tree. 
          The function will throw exceptions if the key is not found or 
          some other error occurs.</p>
      </desc>
    </func>
    <func>
      <name>raise(Exception)</name>
      <fsummary>Generate an Erlang throw</fsummary>
      <type>
        <v>Exception = record()</v>
      </type>
      <desc>
        <p>This function is used for raising corba exceptions as an 
          Erlang user generated exit signal. It will throw the tuple 
          <c>{'EXCEPTION', </c><em>Exception</em><c>}</c>.</p>
      </desc>
    </func>
    <func>
      <name>reply(To, Reply) -> true</name>
      <fsummary>Send explicit reply to client</fsummary>
      <type>
        <v>To = client reference</v>
        <v>Reply = IDL type</v>
      </type>
      <desc>
        <p>This function can be used by a CORBA object to explicitly send 
          a reply to a client that invoked a two-way operation. If this operation
          is used, it is <em>not</em> possible to return a reply in the call-back
          module.
                    <br></br>
<em>To</em> must be the <em>From</em> argument provided to the 
          callback function, which requires that the IC option <em>from</em> 
          was used when compiling the IDL-file.</p>
      </desc>
    </func>
    <func>
      <name>resolve_initial_references(ObjectId) -> Object</name>
      <name>resolve_initial_references(ObjectId, Contexts) -> Object</name>
      <fsummary>Return the object reference for the given object id</fsummary>
      <type>
        <v>ObjectId = string()</v>
        <v>Contexts = [Context]</v>
        <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
        <v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
        <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
        <v>Interface = string()</v>
        <v>Options = [{Key, Value}]</v>
        <v>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</v>
        <v>Value = allowed value associated with the given key</v>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>This function returns the object reference associated with the given
          object id. Initially, only <c>"NameService"</c> is available. To add or remove
          services use <c>add_initial_service/2</c> or <c>remove_initial_service/1</c>.</p>
       <p>The <em>configuration</em> context is used to override the global
           SSL client side 
           <seealso marker="ch_install#config">configuration</seealso>.</p>
       </desc>
    </func>
    <func>
      <name>add_initial_service(ObjectId, Object) -> boolean()</name>
      <fsummary>Add a new initial service and associate it with the given id</fsummary>
      <type>
        <v>ObjectId = string()</v>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>This operation allows us to add initial services, which can be accessed by 
          using <c>resolve_initial_references/1</c> or the <c>corbaloc</c> schema.
          If using an Id defined by the OMG, the given object must be of the
          correct type; for more information see the
          <seealso marker="ch_naming_service#interop_ns">Interoperable Naming Service</seealso>.
          Returns <c>false</c> if the given id already exists.</p>
      </desc>
    </func>
    <func>
      <name>remove_initial_service(ObjectId) -> boolean()</name>
      <fsummary>Remove association between the given id and service</fsummary>
      <type>
        <v>ObjectId = string()</v>
      </type>
      <desc>
        <p>If we don not want a certain service to be accessible, invoking this function
          will remove the association. Returns <c>true</c> if able to terminate the
          binding. If no such binding existed <c>false</c> is returned.</p>
      </desc>
    </func>
    <func>
      <name>list_initial_services() -> [ObjectId]</name>
      <fsummary>Return a list of supported object id's</fsummary>
      <type>
        <v>ObjectId = string()</v>
      </type>
      <desc>
        <p>This function returns a list of allowed object id's.</p>
      </desc>
    </func>
    <func>
      <name>resolve_initial_references_remote(ObjectId, Address) -> Object</name>
      <name>resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object</name>
      <fsummary>Return the object reference for the given object id</fsummary>
      <type>
        <v>ObjectId = string()</v>
        <v>Address = [RemoteModifier]</v>
        <v>RemoteModifier = string()</v>
        <v>Contexts = [Context]</v>
        <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
        <v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
        <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
        <v>Interface = string()</v>
        <v>Options = [{Key, Value}]</v>
        <v>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</v>
        <v>Value = allowed value associated with the given key</v>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>This function returns the object reference for the object id asked 
          for.
          The remote modifier string has the following format:
          <c>"iiop://host:port"</c>.</p>
        <p>The <em>configuration</em> context is used to override the global
           SSL client side 
           <seealso marker="ch_install#config">configuration</seealso>.</p>
        <warning>
          <p>This operation is not supported by most ORB's. Hence, use 
            <c>corba:string_to_object/1</c> instead.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name>list_initial_services_remote(Address) -> [ObjectId]</name>
      <name>list_initial_services_remote(Address, Contexts) -> [ObjectId]</name>
      <fsummary>Return a list of supported object id's</fsummary>
      <type>
        <v>Address = [RemoteModifier]</v>
        <v>RemoteModifier = string()</v>
        <v>Contexts = [Context]</v>
        <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
        <v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
        <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
        <v>Interface = string()</v>
        <v>Options = [{Key, Value}]</v>
        <v>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</v>
        <v>Value = allowed value associated with the given key</v>
        <v>ObjectId = string()</v>
      </type>
      <desc>
        <p>This function returns a list of allowed object id's. The remote modifier
          string has the following format: <c>"iiop://host:port"</c>.</p>
        <p>The <em>configuration</em> context is used to override the global
           SSL client side 
           <seealso marker="ch_install#config">configuration</seealso>.</p>
        <warning>
          <p>This operation is not supported by most ORB's. Hence, avoid
            using it.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name>object_to_string(Object) -> IOR_string</name>
      <fsummary>Convert the object reference to the external string representation</fsummary>
      <type>
        <v>Object = #objref</v>
        <v>IOR_string = string()</v>
      </type>
      <desc>
        <p>This function returns the object reference as the external string 
          representation of an IOR.</p>
      </desc>
    </func>
    <func>
      <name>string_to_object(IOR_string) -> Object</name>
      <name>string_to_object(IOR_string, Contexts) -> Object</name>
      <fsummary>Convert the external string representation to an object reference</fsummary>
      <type>
        <v>IOR_string = string()</v>
        <v>Contexts = [Context]</v>
        <v>Context = #'IOP_ServiceContext'{context_id = CtxId, context_data = CtxData}</v>
        <v>CtxId = ?ORBER_GENERIC_CTX_ID</v>
        <v>CtxData = {interface, Interface} | {userspecific, term()} | {configuration, Options}</v>
        <v>Interface = string()</v>
        <v>Options = [{Key, Value}]</v>
        <v>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</v>
        <v>Value = allowed value associated with the given key</v>
        <v>Object = #objref</v>
      </type>
      <desc>
        <p>This function takes a <c>corbaname</c>, <c>corbaloc</c> or an IOR on the
          external string representation and returns the object reference.</p>
        <p>To lookup the NameService reference, simply use
          <c>"corbaloc:iiop:[email protected]:4001/NameService"</c></p>
        <p>We can also resolve an object from the NameService by using
          <c>"corbaname:iiop:[email protected]:4001/NameService#org/Erlang/MyObj"</c></p>
        <p>For more information about <c>corbaname</c> and <c>corbaloc</c>, see
          the User's Guide (Interoperable Naming Service).</p>
        <p>The <em>configuration</em> context is used to override the global
           SSL client side 
           <seealso marker="ch_install#config">configuration</seealso>.</p>
        <p>How to handle the interface context is further described in the User's Guide.</p>
      </desc>
    </func>
    <func>
      <name>print_object(Data [, Type]) -> ok | {'EXCEPTION', E} |  {'EXIT', R} | string()</name>
      <fsummary>Print the supplied object</fsummary>
      <type>
        <v>Data = IOR_string | #objref (local or external) | corbaloc/corbaname string</v>
        <v>Type = IoDevice | error_report | {error_report, Reason} | info_msg | {info_msg, Comment} | string</v>
        <v>IoDevice = see the io-module</v>
        <v>Reason = Comment = string()</v>
      </type>
      <desc>
        <p>The object represented by the supplied data is dissected and presented
          in a more readable form. The Type parameter is optional; if not supplied
          standard output is used. For <c>error_report</c> and <c>info_msg</c>
          the <c>error_logger</c> module is used, with or without Reason or Comment.
          If the atom <c>string</c> is supplied this function will return a flat
          list. The <c>IoDevice</c> is passed to the operation <c>io:format/2</c>.</p>
        <p>If the supplied object is a local reference, the output is equivalent
          to an object exported from the node this function is invoked on.</p>
      </desc>
    </func>
    <func>
      <name>add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E}</name>
      <fsummary>Add ALTERNATE_IIOP_ADDRESS component to the supplied local object</fsummary>
      <type>
        <v>Object = NewObject = local #objref</v>
        <v>Host = string()</v>
        <v>Port = integer()</v>
      </type>
      <desc>
        <p>This operation creates a new instance of the supplied object
          containing an ALTERNATE_IIOP_ADDRESS component. Only the new instance
          contains the new component. When this object is passed to another
          ORB, which supports the ALTERNATE_IIOP_ADDRESS, requests will be routed
          to the alternate address if it is not possible to communicate with
          the main address.</p>
        <p>The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1.2 is used.
          Hence, make sure both Orber and the other ORB is correctly configured.</p>
        <p></p>
        <note>
          <p>Make sure that the given <c>Object</c> is accessible via the
            alternate Host/port. For example, if the object is correctly started as 
            <c>local</c> or <c>pseudo</c>, the object should be available on all
            nodes within a multi-node Orber installation. Since only one instance
            exists for other object types, it will not be possible to access it
            if the node it was started on terminates.</p>
        </note>
      </desc>
    </func>
    <func>
      <name>orb_init(KeyValueList) -> ok | {'EXIT', Reason}</name>
      <fsummary>Configure Orber before starting it</fsummary>
      <type>
        <v>KeyValueList = [{Key, Value}]</v>
        <v>Key = any key listed in the configuration chapter</v>
        <v>Value = allowed value associated with the given key</v>
      </type>
      <desc>
        <p>This function allows the user to configure Orber in, for example,
          an Erlang shell. Orber may <em>NOT</em> be started prior to invoking
          this operation. For more information, see
          <seealso marker="ch_install#config">configuration settings</seealso>
          in the User's Guide.</p>
      </desc>
    </func>
  </funcs>
  
</erlref>