corba

19972013 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. corba 1997-06-10 A

corba The functions on CORBA module level

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

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 Create and start a new server object 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

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 children they should be transient and the objectkeys_gc_time should be modified (default equals infinity).

The option {local_typecheck, boolean()}, which overrides the Local Typechecking 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 MAY ONLY be used during testing and development.


Example: 

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

dispose(Object) -> ok Stop a server object Object = #objref

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 corba:create_nil_objref/0, always return ok. For valid object references, invoking this operation more than once, will result in a system exception.

create_nil_objref() -> Object Stop a server object 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.

create_subobject_key(Object, Key) -> Result Add an Erlang term to a private key field 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 Fetch the contents of the private key field 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 Get the process id from an object key 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) Generate an Erlang throw Exception = record()

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

reply(To, Reply) -> true Send explicit reply to client 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.

resolve_initial_references(ObjectId) -> Object resolve_initial_references(ObjectId, Contexts) -> Object Return the object reference for the given object id 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(ObjectId, Object) -> boolean() Add a new initial service and associate it with the given id ObjectId = string() Object = #objref

This operation allows us to add initial services, which can 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.

remove_initial_service(ObjectId) -> boolean() Remove association between the given id and service 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.

list_initial_services() -> [ObjectId] Return a list of supported object id's ObjectId = string()

This function returns a list of allowed object id's.

resolve_initial_references_remote(ObjectId, Address) -> Object resolve_initial_references_remote(ObjectId, Address, Contexts) -> Object Return the object reference for the given object id 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.

This operation is not supported by most ORB's. Hence, use corba:string_to_object/1 instead.

list_initial_services_remote(Address) -> [ObjectId] list_initial_services_remote(Address, Contexts) -> [ObjectId] Return a list of supported object id's 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()

This function returns a list of allowed object id's. 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.

This operation is not supported by most ORB's. Hence, avoid using it.

object_to_string(Object) -> IOR_string Convert the object reference to the external string representation 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 string_to_object(IOR_string, Contexts) -> Object Convert the external string representation to an object reference 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, corbaloc or an IOR on the external string representation and returns the object reference.

To lookup the NameService reference, simply use "corbaloc:iiop:1.2@123.0.0.12:4001/NameService"

We can also resolve an object from the NameService by using "corbaname:iiop:1.2@123.0.0.12:4001/NameService#org/Erlang/MyObj"

To lookup the NameService reference with an IPv6 address, simply use "corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService"

For more information 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.

print_object(Data [, Type]) -> ok | {'EXCEPTION', E} | {'EXIT', R} | string() Print the supplied object 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()

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 error_report and info_msg the error_logger module is used, with or without Reason or Comment. If the atom string is supplied this function will return a flat list. 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.

add_alternate_iiop_address(Object, Host, Port) -> NewObject | {'EXCEPTION', E} Add ALTERNATE_IIOP_ADDRESS component to the supplied local object 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. 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.

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

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} Configure Orber before starting it KeyValueList = [{Key, Value}] Key = any key listed in the configuration chapter Value = allowed value associated with the given key

This function allows the user to configure Orber in, for example, an Erlang shell. Orber may NOT be started prior to invoking this operation. For more information, see configuration settings in the User's Guide.