TAO/docs/INS.html

   1   <!--  -->
   2 <HTML>
   3
   4 <HEAD>
   5 <TITLE>TAO Interoperable Naming Service</TITLE>
   6
   7 <BODY text = "#000000"
   8 link="#000fff"
   9 vlink="#ff0f0f"
  10 bgcolor="#ffffff">
  11
  12 <HR><P>
  13 <H3>TAO Interoperable Naming Service</H3>
  14
  15 The CORBA <A HREF="http://www.omg.org/cgi-bin/doc?ptc/99-09-01">
  16 Interoperable Naming Service</A> (INS) service allows the ORB to be configured
  17 administratively to return object references from
  18 <CODE>CORBA::ORB::resolve_initial_references</CODE> for non-locality
  19 constrained objects.  The service also introduces the
  20 <CODE>corbaloc</CODE> and <CODE>corbaname</CODE> IOR formats, which can
  21 be used to bootstrap services not available at ORB installation time.
  22 <P>
  23
  24 This document presents an overview of how the above mentioned features are
  25 implemented in TAO and addresses some common questions. <P>
  26
  27 <HR align=left width=80% ><P>
  28 <H4>How does <CODE>resolve_initial_references</CODE> work ?</H4><P>
  29
  30 The following is the order of mechanisms checked by <CODE>resolve_initial_references</CODE>
  31 for locating a service: <P>
  32
  33 <OL>
  34 <LI><A HREF="#oir">ORBInitRef</A> <br>
  35 <LI><A HREF="#odir">ORBDefaultInitRef</A> <br>
  36 <LI>ORB Default Settings <br>
  37 <LI>Multicast to Service <p>
  38 </OL>
  39
  40 The Naming Service process acts as an IIOP Agent to respond with the
  41 IOR for the given service name. If the service being resolved is the
  42 Naming Service or the Trading Service, TAO checks the appropriate <A
  43 HREF="Options.html#EV">environment variables</A> prior to using
  44 multicast to obtain the appropriate port number or IOR.<p>
  45
  46 The following diagram illustrates the order in which these various
  47 components interact. <P>
  48
  49 <img width=200 height=5 src="space.gif">
  50 <img width=723 height=529 src="interop-naming.png"><p>
  51
  52 <HR align=left width=80% ><P>
  53
  54 <H4>ORB Parameters Used for Configuration</H4>
  55 <A NAME="oir"></A>
  56 <DL>
  57 <DT> <img alt="o" src="redball.gif">
  58 <B><FONT COLOR="#000000">-ORBInitRef :</FONT> </B>
  59 The ORB initial reference argument allows specification of an
  60     arbitrary object reference for an initial service. The format is :
  61     <p>
  62     <CODE>-ORBInitRef [ObjectID]=[ObjectURL]</CODE> <p>
  63     Examples of use are: <p>
  64     <CODE>-ORBInitRef  NameService=IOR:0002342344AB345</CODE> ...<br>
  65     <CODE>-ORBInitRef MyServiceID=corbaloc:iiop:tango.cs.wustl.edu:8777/myService </CODE><p>
  66
  67     This mechanism allows an ORB to be configured with new initial
  68     service Object IDs that were not defined when the ORB was
  69     installed. The ObjectURL can be any of the URL schemes supported
  70     by <CODE>CORBA::ORB::string_to_object</CODE>.<p>
  71
  72     <A NAME="odir"></A>
  73 <DT> <img alt="o" src="redball.gif"><B><FONT COLOR="#000000">
  74 -ORBDefaultInitRef :</FONT></B></LI>
  75 The ORB default initial reference argument assists in resolution of
  76     initial references not explicitly specified with
  77     <CODE>-ORBInitRef</CODE>. <CODE>-ORBDefaultInitRef</CODE> requires a URL that, after
  78     appending a slash '/' and a stringified object key, forms a new
  79     URL to identify an initial object reference. <p>
  80     For example: <P>
  81     <CODE>-ORBDefaultInitRef
  82     corbaloc:iiop:tango.cs.wustl.edu:8989,iiop:merengue.cs.wustl.edu:9999</CODE> <p>
  83
  84     A call to <CODE>resolve_initial_references ("NameService")</CODE> with this
  85     argument results in a new multiple profile URL equivalent to the following: <P>
  86     <CODE>corbaloc::tango.cs.wustl.edu:8989/NameService</CODE> <br>
  87     <CODE>corbaloc::merengue.cs.wustl.edu:9999/NameService</CODE> <p>
  88
  89     The URL is passed to <CODE>CORBA::ORB::string_to_object</CODE> to obtain the
  90     initial reference for the service.
  91 </DL>
  92
  93 <HR align=left width=80% ><P>
  94
  95 <H4><A NAME="corbaloc">corbaloc: IOR format</A></H4>
  96 The <CODE>CORBA::ORB::string_to_object</CODE> parses the <CODE>corbaloc:</CODE>
  97 format IORs. These are user-friendly multiple end-point IORs. For
  98 example - <p>
  99  <img width=50 height=5 src="space.gif">
 100 corbaloc:iiop:tango.cs.wustl.edu:9999,iiop:merengue.cs.wustl.edu:9999/SimpleKey <p>
 101
 102 Each of the endpoints can use any transport protocols ex: iiop, rir.
 103 The corbaloc:rir URL is defined to allow access to the ORB's
 104 configured initial references through an URL. Each of the end-points
 105 is converted into a Profile. These profiles are used to construct the
 106 Multiple Profile Object. This object is then used to construct the
 107 Object Reference.<p>
 108
 109 The object references constructed using this format have a
 110 'SimpleKey' in the Object Key field of the IOR. The server side ORB
 111 intercepts the incoming request, recognizes the Simple Key and
 112 looks up a table to get the complete IOR. It then raises a
 113 LOCATION_FORWARD or an OBJECT_NOT_EXIST exception to forward/fail the
 114 request depending on if a mapping for the given simple key exists. <p>
 115
 116 All default TAO Object keys are preceded by a special sequence of
 117 octets ^t^a^o/0. This is taken care of by the POA when it generates
 118 the Object key for the IOR. The sequence is useful for the ORB to
 119 distinguish a simple key from the usual TAO object key. <p>
 120
 121 The corbaloc::iiop URL also supports the IPv6 decimal address for the
 122 host field using the same format as for <A HREF="ORBEndpoint.html#IIOP">IIOP endpoint</A> definitions:
 123 <P><CODE>corbaloc:iiop:1.2@[01ef::1]:123/KeyName</CODE>
 124 <P>
 125 TAO only supports IPv6 endpoints in GIOP/IIOP >= 1.2.
 126 Since the CORBA spec requires (and such is implemented in TAO) that
 127 by default when no version is specified the version will be 1.0 the
 128 version has been explicitly set or not the result is that for
 129 corbalocs the version needs to be explicitly set.<BR>
 130 If not set the corbaloc parser will report an error for encountering
 131 an unresolvable hostname.
 132
 133 <HR align=left width=80% ><P>
 134
 135 <H4><A NAME="IORTable">corbaloc: server setup and the IORTable</A></H4>
 136 <p>
 137 The key name used in a corbaloc string may be a stringified object ID associated with some POA, or it might be a human-readable hint to be used to look up the fully qualified object reference.
 138 <p>
 139 Stringified ObjectIds are most easily generated by using the <code>-ORBObjRefStyle url</code> command line option. However, these are quite cumbersome to work with  For example:
 140 <p><code>corbaloc:iiop:1.2@phil.ociweb.com:32948/%14%01%0f%00RST%a5B%a5Eb%c2%04%00%00%00%00%00%01%00%00%00%01%00%00%00</code>
 141 <p>The advantage to using such strings is that server applications need no modifications in order to use such IORs. The disadvantage is that there is no way to attach tagged components to profiles presented as corbaloc strings.
 142 <p>Server applications can get around both of the problem of the unwieldy stringified object ID and the lack of tagged components by using the IOR_Table service. The IORTable service is used inside server applications to associate object key strings with full IORs.
 143 <p>Programs wishing to use the IOR Table must do the following.
 144 <ul>
 145 <li> include the header.
 146 <p><code>#include "tao/IORTable/IORTable.h"</code>
 147 <li>get a reference to the table.
 148 <pre>
 149    CORBA::Object_var table_object =
 150         orb->resolve_initial_references ("IORTable");
 151
 152    IORTable::Table_var adapter =
 153         IORTable::Table::_narrow (table_object.in ());
 154 </pre>
 155 <li>bind object references into the table. IORs are bound as strings.
 156 <pre>
 157    CORBA::String_var ior = orb->object_to_string(myobjref.in());
 158    adapter->bind ("MyObj", ior.in());
 159 </pre>
 160 </ul>
 161
 162 Since the object references are stored in the IOR table as strings, they do not have to served by this application. References in the table are passed back to the client by raising a LOCATION_FORWARD exception which then uses the full IOR to connect to the actual server.
 163
 164 </BODY>
 165 </HTML>