corba

MODULE

corba

MODULE SUMMARY

The functions on CORBA module level

DESCRIPTION

This module contains functions that are specified on the CORBA module level. It also contains some functions for creating and disposing objects.

EXPORTS

create(Module, TypeID) -> Object
create(Module, TypeID, Env) -> Object
create(Module, TypeID, Env, Optons1) -> Object
create_link(Module, TypeID) -> Object
create_link(Module, TypeID, Env) -> Object
create_link(Module, TypeID, Env, Options2) -> Reply

Types:
Module = atom()
TypeID = string()
Env = term()
Options1 = [{persistent, Bool} | {regname, RegName}]
Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname, RegName} | {pseudo, Bool}]
RegName = {local, atom()} | {global, term()}
Reply = #objref | {ok, Pid, #objref}
Bool = true | false
Object = #objref

These functions start a new server object. If you start it without RegName it can only be accessed through the returned object key. Started with a RegName the name is registered locally or globally.

TypeID is the repository ID of the server object type and could for example look like "IDL:StackModule/Stack:1.0".

Module is the name of the interface API module.

Env is the arguments passed which will be passed to the implementations init call-back function.

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.

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.

If you use the option {sup_child, true} create_link/4 will return {ok, Pid, #objref}, otherwise #objref, and make it possible to start a server as a supervisor child (stdlib-1.7 or later).

If you use the option {persistent, true} you also must use the option {regname, {global, Name}}. This combination makes it possible to tell the difference between a server permanently terminated or in the process of restarting.

The option {pseudo, true}, allow us to create an object which is not a server. Using {pseudo, true} overrides all other start options. For more information see section Module_Interface.

If a server is started using the option {persistent, true} the object key will not be removed unless it terminates with reason normal or shutdown. Hence, if persistent servers is used as supervisor childs they should be transient and the objectkeys_gc_time should be modified (default equals infinity).

Example: 
          
  corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0",
               {10, test})
        

dispose(Object) -> ok

Types:
Object = #objref

This function is used for terminating the execution of a server object.

create_subobject_key(Object, Key) -> Result

Types:
Object = #objref
Key = term()
Result = #objref

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 Result 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 get_subobject_key/1 function to get the private key value.

Key is stored in the object reference Object. If it is a binary it will be stored as is and otherwise it is converted to a binary before storage.

get_subobject_key(Object) -> Result

Types:
Object = #objref
Result = #binary

This function is used to fetch a subobject key from the object reference Object. The result is a always a binary, if it was an Erlang term that was stored with create_subobject_key/2 one can to do binary_to_term/1 to get the real value.

get_pid(Object) -> Result

Types:
Object = #objref
Result = #pid | {error, Reason} | {'EXCEPTION',E}

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.

raise(Exception)

Types:
Exception = record()

This function is used for raising corba exceptions as an Erlang user generated exit signal. It will throw the tuple {'EXCEPTION', Exception}.

resolve_initial_references(ObjectId) -> Object

Types:
ObjectId = string()
Object = #objref

This function returns the object reference for the object id asked for (just now only the "NameService").

list_initial_services() -> [ObjectId]

Types:
ObjectId = string()

This function returns a list of allowed object id's (just now only the "NameService").

resolve_initial_references_remote(ObjectId, Address) -> Object

Types:
Address = [RemoteModifier]
RemoteModifier = string()
ObjectId = string()
Object = #objref

This function returns the object reference for the object id asked for (depends on the orb, for orber it is just the "NameService"). The remote modifier string has the following format: "iiop://host:port".

list_initial_services_remote(Address) -> [ObjectId]

Types:
Address = [RemoteModifier]
RemoteModifier = string()
ObjectId = string()

This function returns a list of allowed object id's (depends on the orb, for orber it is just the "NameService"). The remote modifier string has the following format: "iiop://host:port".

object_to_string(Object) -> IOR_string

Types:
Object = #objref
IOR_string = string()

This function returns the object reference as the external string representation of an IOR.

string_to_object(IOR_string) -> Object

Types:
IOR_string = string()
Object = #objref

This function takes an IOR on the external string representation and returns the object reference.

AUTHORS

Lars Thorsén - support@erlang.ericsson.se