diff options
Diffstat (limited to 'lib/orber/doc/src/corba.xml')
| -rw-r--r-- | lib/orber/doc/src/corba.xml | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/lib/orber/doc/src/corba.xml b/lib/orber/doc/src/corba.xml new file mode 100644 index 0000000000..6c89279733 --- /dev/null +++ b/lib/orber/doc/src/corba.xml @@ -0,0 +1,451 @@ +<?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: +\011 + corba:create('StackModule_Stack', "IDL:StackModule/Stack:1.0", +\011 {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> + |