corba(3)

📦
version 5.2.2 · 2 versions
, in fedora 43, fedora 44

🌸 corba — Erlang Module Definition 🌸

okay so bestie, welcome to the corba manual page 💖 this is the Erlang module corba, and we're about to get very cozy with it.

💖 NAME 💖

corba — the functions on CORBA module level ✨

🦋 DESCRIPTION 🦋

so this module is where the CORBA module level functions live, fr fr. it's also got a few little guys for creating and disposing objects 🎀 like, object birth and object death, we contain multitudes.

✨ 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} |
{local_typecheck, Bool}]
Options2 = [{sup_child, Bool} | {persistent, Bool} | {regname,
RegName} | {pseudo, Bool} | {local_typecheck, Bool}]
RegName = {local, atom()} | {global, term()}
Reply = #objref | {ok, Pid, #objref}
Bool = true | false
Object = #objref

okay so these functions start a new server object 💅 if you start it without a RegName it can only be reached through the object key it hands back. start it with a RegName and the name gets registered locally or globally. iconic behavior honestly.

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

Module is the name of the interface API module. yes bestie, the actual module.

Env is the arguments that get passed along — they'll be handed to the implementation's init call-back function. so it's like, the lil welcome gift 🎁

now listen closely because this part is a vibe distinction:

A server started with create/2, create/3 or create/4 does not care about the parent — meaning the parent is not handled explicitly in the generic process part. it's giving independent main character energy 👑

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 — with the same reason as the parent. if the server traps exits, the terminate/2 call-back function is called so it can clean up before the termination 🧹 these are the ones you want if the server is a worker in a supervision tree.

if you use the option {sup_child, true}, then create_link/4 will return {ok, Pid, #objref} — otherwise #objref — and this makes 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}}. that combo is what makes it possible to tell the difference between a server that's permanently terminated and one that's in the process of restarting 🔥

the option {pseudo, true} lets us create an object which is not a server. using {pseudo, true} overrides all other start options 😳 for more info, 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 are used as supervisor children they should be transient and the objectkeys_gc_time should be modified (default equals infinity). noted bestie 📝

the option {local_typecheck, boolean()}, which overrides the Local Typechecking environment flag, turns typechecking on or off. if it's activated, parameters, replies and raised exceptions will be checked to make sure 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. do not ship it, bestie, I'm begging 😭

Example:

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

💀 dispose/1

dispose(Object) -> ok

Types:

Object = #objref

this function is for terminating the execution of a server object 🪦 invoking this operation on a NIL object reference — like, for example, the return value of corba:create_nil_objref/0 — always returns ok. for valid object references, invoking this operation more than once will result in a system exception. so like, don't double-tap 💀

🌈 create_nil_objref/0

create_nil_objref() -> Object

Types:

Object = #objref representing NIL.

creates an object reference that represents the NIL value. attempts to invoke operations using the returned object reference will return a system exception 🚫 the void, the nothingness, the absence 💜

🎀 create_subobject_key/2

create_subobject_key(Object, Key) -> Result

Types:

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

this one 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 it 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's a binary it will be stored as is, and otherwise it gets converted to a binary before storage. slay 🦋

🔍 get_subobject_key/1

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 always a binary, so if it was an Erlang term that was stored with create_subobject_key/2, one can do binary_to_term/1 to get the real value 🧚

🌸 get_pid/1

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 are started/handled in a supervisor tree. the function will throw exceptions if the key is not found or some other error occurs 😭 heads up!

📣 raise/1

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} 🔥 dramatic? yes. necessary? also yes.

💌 reply/2

reply(To, Reply) -> true

Types:

To = client reference
Reply = IDL type

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 not possible to return a reply in the call-back module 🚫

To must be the From argument provided to the callback function, which requires that the IC option from was used when compiling the IDL-file. iykyk 💅

⭐ resolve_initial_references

resolve_initial_references(ObjectId) -> Object
resolve_initial_references(ObjectId, Contexts) -> Object

Types:

ObjectId = string()
Contexts = [Context]
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_options
Value = allowed value associated with the given key
Object = #objref

this function returns the object reference associated with the given object id 🎯 initially, only "NameService" is available. to add or remove services, use add_initial_service/2 or remove_initial_service/1.

the configuration context is used to override the global SSL client side configuration 🔐

➕ add_initial_service/2

add_initial_service(ObjectId, Object) -> boolean()

Types:

ObjectId = string()
Object = #objref

this operation allows us to add initial services, which can then be accessed by using resolve_initial_references/1 or the corbaloc schema 🌈 if using an Id defined by the OMG, the given object must be of the correct type — for more information see the Interoperable Naming Service. returns false if the given id already exists. so, like, no duplicates bestie 🙈

➖ remove_initial_service/1

remove_initial_service(ObjectId) -> boolean()

Types:

ObjectId = string()

if we don not want a certain service to be accessible, invoking this function will remove the association ✂️ returns true if able to terminate the binding. if no such binding existed, false is returned. (yes the original says "don not", we love her for it 🫶)

📋 list_initial_services/0

list_initial_services() -> [ObjectId]

Types:

ObjectId = string()

this function returns a list of allowed object id's 💖 a lil menu of what's available.

🌍 resolve_initial_references_remote

resolve_initial_references_remote(ObjectId, Address) -> Object
resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object

Types:

ObjectId = string()
Address = [RemoteModifier]
RemoteModifier = string()
Contexts = [Context]
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_options
Value = allowed value associated with the given key
Object = #objref

this function returns the object reference for the object id asked for 👑 the remote modifier string has the following format:

"iiop://"<host>":"<port>

where <host> = <DNS hostname> | <IPv4 address> | "["<IPv6 address>"]".

the configuration context is used to override the global SSL client side configuration 🔐

⚠️ Warning: This operation is not supported by most ORB's. Hence, use corba:string_to_object/1 instead. fr fr, use the other one bestie 😭

🗺️ list_initial_services_remote

list_initial_services_remote(Address) -> [ObjectId]
list_initial_services_remote(Address, Contexts) -> [ObjectId]

Types:

Address = [RemoteModifier]
RemoteModifier = string()
Contexts = [Context]
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_options
Value = allowed value associated with the given key
ObjectId = string()

…and that's part one, bestie — there's more coming so don't go anywhere 💅✨

okay so this function hands you back a list of allowed object id's. ✨ The remote modifier string it deals with looks like this:

"iiop://"<host>":"<port>

where <host> = <DNS hostname> | <IPv4 address> | "["<IPv6 address>"]".

And the configuration context? That's the girl that overrides the global SSL client side configuration. 💅

Warning: bestie, this operation is NOT supported by most ORB's. So like… avoid using it. fr fr. 🙈

object_to_string(Object) -> IOR_string

Types:

Object = #objref
IOR_string = string()

This one returns the object reference as the external string representation of an IOR. that's it, that's the whole vibe 🦋

string_to_object(IOR_string) -> Object

string_to_object(IOR_string, Contexts) -> Object

Types:

IOR_string = string()
Contexts = [Context]
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_options
Value = allowed value associated with the given key
Object = #objref

This function takes a corbaname, a corbaloc or an IOR on the external string representation and gives you back the object reference. 🎀

Wanna look up the NameService reference? Simply:

corbaloc:iiop:1.2@123.0.0.12:4001/NameService

And we can also resolve an object from the NameService by using:

corbaname:iiop:1.2@123.0.0.12:4001/NameService#org/Erlang/MyObj

Look up the NameService reference with an IPv6 address? Simply:

corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService

For more tea about corbaname and corbaloc, see the User's Guide (Interoperable Naming Service). 📖

The configuration context is used to override the global SSL client side configuration.

How to handle the interface context is further described in the User's Guide. 👑

Types:

Data = IOR_string | #objref (local or external) |
corbaloc/corbaname string
Type = IoDevice | error_report | {error_report, Reason} |
info_msg | {info_msg, Comment} | string
IoDevice = see the io-module
Reason = Comment = string()

So the object represented by the supplied data gets dissected and presented in a more readable form — it's giving autopsy but make it ✨aesthetic✨.

The Type parameter is optional; if you don't supply it, standard output is used. For error_report and info_msg the error_logger module is used, with or without Reason or Comment. If you supply the atom string, this function will return a flat list. And the IoDevice is passed to the operation io:format/2.

If the supplied object is a local reference, the output is equivalent to an object exported from the node this function is invoked on. no cap. 💯

add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E}

Types:

Object = NewObject = local #objref
Host = string()
Port = integer()

This operation creates a new instance of the supplied object containing an ALTERNATE_IIOP_ADDRESS component. Only the new instance contains the new component — the original is unbothered, untouched, living her life. 💅

When this object is passed to another ORB that supports the ALTERNATE_IIOP_ADDRESS, requests will be routed to the alternate address if it's not possible to communicate with the main address. main character is the main address, alternate is the understudy, iykyk. 🎭

The ALTERNATE_IIOP_ADDRESS component requires that IIOP-1.2 is used. Hence, make sure both Orber and the other ORB is correctly configured.

Note: Make sure that the given Object is accessible via the alternate Host/port. For example, if the object is correctly started as local or pseudo, 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. 💀

orb_init(KeyValueList) -> ok | {'EXIT', Reason}

Types:

KeyValueList = [{Key, Value}]
Key = any key listed in the configuration chapter
Value = allowed value associated with the given key

This function lets you configure Orber in, for example, an Erlang shell. 🐚

Big one: Orber may NOT be started prior to invoking this operation. like, don't even. 🙅‍♀️

For more info, see configuration settings in the User's Guide. 🌈

and that's the whole page, bestie 💖

This one's brought to you by Ericsson AB, it's orber 5.2.2, and it lives at corba(3). go forth and slay ✨👑🫶

📦 where this page comes from