path: root/lib/orber/doc/src/corba.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2017</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.
    
    </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_options</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_options</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://"&lt;host&gt;":"&lt;port&gt;</c> where <c>&lt;host&gt; = &lt;DNS hostname&gt; | 
	  &lt;IPv4 address&gt; | "["&lt;IPv6 address&gt;"]"</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_options</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://"&lt;host&gt;":"&lt;port&gt;</c> where <c>&lt;host&gt; = &lt;DNS hostname&gt; | 
	  &lt;IPv4 address&gt; | "["&lt;IPv6 address&gt;"]"</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_options</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:</p>
        <code>corbaloc:iiop:[email protected]:4001/NameService</code>
        <p>We can also resolve an object from the NameService by using:</p>
        <code>corbaname:iiop:[email protected]:4001/NameService#org/Erlang/MyObj</code>
        <p>To lookup the NameService reference with an IPv6 address, simply use:</p>
        <code>corbaloc:iiop:1.2@[FEC1:0:3:0:0312:44AF:FAB1:3D01]:4001/NameService</code>
        <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>