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

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

<chapter>
  <header>
    <copyright>
      <year>1997</year><year>2013</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>CosNaming Service</title>
    <prepared></prepared>
    <docno></docno>
    <date>1998-10-10</date>
    <rev></rev>
    <file>ch_naming_service.xml</file>
  </header>

  <section>
    <title>Overview of the CosNaming Service</title>
    <p>The CosNaming Service is a service developed to help users and
      programmers identify objects by human readable names rather than by a
      reference.  By  binding a name to a naming context (another object), a
      contextual reference is formed. This is helpful when navigating in the
      object space. In addition, identifying objects by name allows you to evolve
      and/or relocate objects without client code modification.</p>
    <p>The CosNaming service has some concepts that are important:</p>
    <list type="bulleted">
      <item>
        <p><em>name binding</em> - a name to object association.</p>
      </item>
      <item>
        <p><em>naming context</em> - is an object that contains a set of
          name bindings in which each name is unique. Different names can be
          bound to the same object.  
          </p>
      </item>
      <item>
        <p><em>to bind a name</em> - is to create a name binding in a given
          context.</p>
      </item>
      <item>
        <p><em>to resolve a name</em> - is to determine the object associated
          with the name in a given context.</p>
      </item>
    </list>
    <p>A name is always resolved in a context, there no absolute names exist.
      Because a context is like any other object, it can also be bound to
      a name
      in a naming context. 
      This will result in a naming graph (a directed graph with notes and 
      labeled edges). The graph allows more complex names to refer to an
      object. Given a context, you can use a sequence to reference an object.
      This sequence is henceforth referred to as <em>name</em> and the
      individual
      elements in the sequence as <em>name components</em>. All but the 
      last name component are bound to naming contexts.
      </p>
    <p>The diagram in figure 1 illustrates how the Naming Service provides a
      contextual relationship between objects, NamingContexts and
      NameBindings to create an object locality, as the
      object itself, has no name.
      </p>
    <marker id="name"></marker>
    <image file="name.gif">
      <icaption>
Figure 1: Contextual object relationships using the Naming Service.</icaption>
    </image>
    <p>The naming contexts provide a directory of contextual
      reference and naming for objects (an object can appear to 
      have more than one name).
      </p>
    <p>In figure 1 the object to the right can either be
      called <c>alpha</c> from one context or <c>gamma</c> from another.  
      </p>
    <p>The Naming Service has an initial naming context, which is shown 
      in the diagram as the top-most object in the naming graph.
      It has two names <c>beta</c> and <c>epsilon</c>, which are bound to other
      naming contexts. The initial naming context is a well known location 
      used to share a common name space between multiple programs.
      You can traverse the naming graph until you reach a name, which is
      bound to an object, which is not a naming context.
      </p>
    <p>We recommend reading <em>chapter 12, CORBA Fundamentals and Programming</em>, for detailed information regarding the 
      Naming Service. </p>
  </section>

  <section>
    <title>The Basic Use-cases of the Naming Service</title>
    <p>The basic use-cases of the Naming Service are:
      </p>
    <list type="bulleted">
      <item>Fetch initial reference to the naming service.</item>
      <item>Creating a naming context.</item>
      <item>Binding and unbinding names to objects.</item>
      <item>Resolving a name to an object.</item>
      <item>Listing the bindings of a naming context.</item>
      <item>Destroying a naming context.</item>
    </list>

    <section>
      <title>Fetch Initial Reference to the Naming Service</title>
      <p>In order to use the naming service you have to fetch an 
        initial reference to it. This is done with:</p>
      <code type="none">
NS = corba:resolve_initial_references("NameService").
      </code>
      <note>
        <p>NS in the other use-cases refers to this initial reference.</p>
      </note>
    </section>

    <section>
      <title>Creating a Naming Context</title>
      <p>There are two functions for creating a naming context.
        The first function, which only creates a naming context object is:</p>
      <code type="none">
NC = 'CosNaming_NamingContext':new_context(NS).
      </code>
      <p>The other function creates a naming context and binds it to a name in 
        an already existing naming context (the initial context in this 
        example):
        </p>
      <code type="none">
NC = 'CosNaming_NamingContext':bind_new_context(NS, lname:new(["new"])).
      </code>
    </section>

    <section>
      <title>Binding and Unbinding Names to Objects</title>
      <p>The following steps illustrate how to bind/unbind an object reference 
        to/from a name. For the example below, assume that the NamingContexts 
        in the path are already bound to the name <c>/workgroup/services</c>, 
        and that reference to the services context are in the variable 
        <c>Sc</c>.</p>
      <list type="ordered">
        <item>
          <p>Use the naming library functions to create a name</p>
          <code type="none">
Name = lname:new(["object"]).
          </code>
        </item>
        <item>
          <p>Use CosNaming::NamingContext::bind() to bind a name to an object</p>
          <code type="none">
'CosNaming_NamingContext':bind(Sc, Name, Object).
          </code>
        </item>
        <item>
          <p>Use CosNaming::NamingContext::unbind() to remove the NameBinding from an object</p>
          <code type="none">
'CosNaming_NamingContext':unbind(Sc, Name).
          </code>
        </item>
      </list>
      <note>
        <p>Objects can have more than one name, to indicate different paths to 
          the same object.</p>
      </note>
    </section>

    <section>
      <title>Resolving a Name to an Object</title>
      <p>The following steps show how to  retrieve the object reference to the service context 
        above (/workgroup/services).    </p>
      <list type="ordered">
        <item>
          <p>Use the naming library functions to create a name path:</p>
          <code type="none">
Name = lname:new(["workgroup", "services"]).
          </code>
        </item>
        <item>
          <p>Use CosNaming::NamingContext::resolve() to to resolve the name to an object</p>
          <code type="none">
Sc = 'CosNaming_NamingContext':resolve(NS, Name).
          </code>
        </item>
      </list>
      <p>An alternative is to use:</p>
      <code type="none">
Sc = corba:string_to_object("corbaname:rir:/NameService#workgroup/services/").
      </code>
      <p>The <c>corbaname</c> schema is described further in the Interoperable
        Naming Service section.</p>
    </section>

    <section>
      <title>Listing the Bindings in a NamingContext</title>
      <list type="ordered">
        <item>
          <p>Use CosNaming::NamingContext::list() to list all the bindings in a context</p>
          <p>The following code retrieves and lists up to 10 bindings from a context.</p>
          <code type="none">
{BList, BIterator} = 'CosNaming_NamingContext':list(Sc, 10).

lists:foreach(fun({{Id, Kind},BindingType}) -> case BindingType of 
    nobject ->
        io:format("id: %s, kind: %s, type: object~n", [Id, Kind]);
    _ ->
        io:format("id: %s, kind: %s, type: ncontext~n", [Id, Kind])
    end end,
    Blist).
          </code>
        </item>
      </list>
      <note>
        <p>Normally a <term id="BindingIterator"><termdef>The binding iterator (Like a book mark) indicates which objects have been read from the list.</termdef></term>is helpful in situations where you have a large number of objects 
          in a list, as the programmer then can traverse it more easily.
          In Erlang it is not needed, because lists are easily handled in the 
          language itself.</p>
      </note>
      <warning>
        <p>Remember that the BindingIterator (BIterator in the example) is an object and therefore
          <em>must be removed</em> otherwise dangling processes will occur.
          Use <c>CosNaming::BindingIterator::destroy()</c> to remove it.</p>
      </warning>
      <code type="none">
      'CosNaming_NamingContext':destroy(BIterator).
      </code>
    </section>

    <section>
      <title>Destroying a Naming Context</title>
      <p>The naming contexts are persistent and must be explicitly removed.
        (they are also removed if all Orber nodes in the domain are stopped).</p>
      <list type="ordered">
        <item>
          <p>Use CosNaming::NamingContext::destroy() to remove a NamingContext</p>
          <code type="none">
'CosNaming_NamingContext':destroy(Sc).
          </code>
        </item>
      </list>
    </section>
  </section>

  <section>
    <title>Interoperable Naming Service</title>
    <marker id="interop_ns"></marker>
    <p>The OMG specifies URL schemes, which represent a CORBA object and a CORBA object
      bound in a NamingContext, for resolving references from other ORB:s. As of today,
      three schemes are defined:</p>
    <list type="bulleted">
      <item>IOR</item>
      <item>corbaloc</item>
      <item>corbaname</item>
    </list>

    <section>
      <title>IOR</title>
      <p>A stringified IOR is a valid URL format but difficult for humans to handle
        through non-electronic means. This URL format does not depend on a specific
        Name Service and, thus, is robust and insulates the client from the encapsulated
        transport information and object key used to reference the object.</p>
    </section>

    <section>
      <title>corbaloc</title>
      <p>The notation of this scheme is similar to the more well known URL <c>HTTP</c>, and
        the full <c>corbaloc</c> BNF is:</p>
      <code type="none"><![CDATA[
<corbaloc>            =  "corbaloc:"<obj_addr_list>["/"<key_string>] 
<obj_addr_list>       = [<obj_addr>","]*<obj_addr> 
<obj_addr>            = <prot_addr> | <future_prot_addr> 
<prot_addr>           = <rir_prot_addr> | <iiop_prot_addr> 
<rir_prot_addr>       = <rir_prot_token>":"  
<rir_prot_token>      = rir  
<future_prot_addr>    = <future_prot_id><future_prot_addr>
<future_prot_id>      = <future_prot_token>":" 
<iiop_prot_addr>      = <iiop_id><iiop_addr>
<iiop_id>             = <iiop_default> | <iiop_prot_token>":"  
<iiop_default>        = ":"  
<iiop_prot_token>     = "iiop"  
<iiop_addr>           = <version><host>[":"<port>] 
<host>                = <DNS-style Host Name> | <ip_v4_address> | "["<ip_v6_address>"]"
<version>             = <major>"."<minor>"@"  | empty_string 
<port>                = number 
<major>               = number 
<minor>               = number
<DNS-style Host Name> = string
<ip_v4_address>       = string
<ip_v6_address>       = string
<key_string>          = for example NameService
      ]]></code>
      <p>The <c>corbaloc</c> scheme consists of 3 parts:</p>
      <list type="bulleted">
        <item>Protocol - as of today <c>iiop</c> or <c>rir</c> is supported.
         Using <c>rir</c> means that we will resolve the given Key locally, i.e.,
         the same as using <c>corba:resolve_initial_references("NameService").</c></item>
        <item>IIOP address - this address can be divided into <c>Version</c>, <c>Host</c> 
         and <c>Port</c>. If the version or port are left out they will be set to the default
         values <c>1.0</c> and <c>2809</c> respectively.</item>
        <item>KeyString - an object key, e.g., "NameService". If no Key is 
         supplied the default value "NameService" will be used.</item>
      </list>
      <p>A <c>corbaloc</c> can be passed used together with 
        <c>corba:string_to_object("corbaloc::[email protected]:4001/NameService")</c> or set as the 
        configuration variables <c>orbInitilRef</c> or <c>orbDefaultInitilRef</c> and calling
        <c>corba:resolve_initial_references("NameService")</c>. For more information see the Orber
        installation chapter. <c>corbaloc</c> can also be used together with <c>corbaname</c>
        to gain an easy access to a Name Service.</p>
      <p>Currently, the OMG defines a set of reserved keys and the type of object,
        listed below, they should be associated with. The <c>NameService</c>
        key may <em>not</em> be changed in Orber. If you want to add one of the
        reserved keys as an initial service, simply use:</p>
      <code type="none">
1> Factory = cosNotificationApp:start_global_factory().
2> corba:add_initial_service("NotificationService", Factory).
      </code>
      <p>This object can then be easily resolved by any other ORB, supporting 
        the Interoperable Naming Service, by using:</p>
      <code type="none">
3> NF = corba:string_to_object("corbaloc::[email protected]:4001/NotificationService").
      </code>
      <table>
        <row>
          <cell align="center" valign="middle"><em>String Name</em></cell>
          <cell align="center" valign="middle"><em>Object Type</em></cell>
        </row>
        <row>
          <cell align="left" valign="middle">RootPOA</cell>
          <cell align="left" valign="middle">PortableServer::POA</cell>
        </row>
        <row>
          <cell align="left" valign="middle">POACurrent</cell>
          <cell align="left" valign="middle">PortableServer::Current</cell>
        </row>
        <row>
          <cell align="left" valign="middle">InterfaceRepository</cell>
          <cell align="left" valign="middle">CORBA::Repository</cell>
        </row>
        <row>
          <cell align="left" valign="middle">NameService</cell>
          <cell align="left" valign="middle">CosNaming::NamingContext</cell>
        </row>
        <row>
          <cell align="left" valign="middle">TradingService</cell>
          <cell align="left" valign="middle">CosTrading::Lookup</cell>
        </row>
        <row>
          <cell align="left" valign="middle">SecurityCurrent</cell>
          <cell align="left" valign="middle">SecurityLevel1::Current/SecurityLevel2::Current</cell>
        </row>
        <row>
          <cell align="left" valign="middle">TransactionCurrent</cell>
          <cell align="left" valign="middle">CosTransaction::Current</cell>
        </row>
        <row>
          <cell align="left" valign="middle">DynAnyFactory</cell>
          <cell align="left" valign="middle">DynamicAny::DynAnyFactory</cell>
        </row>
        <row>
          <cell align="left" valign="middle">ORBPolicyManager</cell>
          <cell align="left" valign="middle">CORBA::PolicyManager</cell>
        </row>
        <row>
          <cell align="left" valign="middle">PolicyCurrent</cell>
          <cell align="left" valign="middle">CORBA::PolicyCurrent</cell>
        </row>
        <row>
          <cell align="left" valign="middle">NotificationService</cell>
          <cell align="left" valign="middle">CosNotifyChannelAdmin::EventChannelFactory</cell>
        </row>
        <row>
          <cell align="left" valign="middle">TypedNotificationService</cell>
          <cell align="left" valign="middle">CosTypedNotifyChannelAdmin::TypedEventChannelFactory</cell>
        </row>
        <row>
          <cell align="left" valign="middle">CodecFactory</cell>
          <cell align="left" valign="middle">IOP::CodecFactory</cell>
        </row>
        <row>
          <cell align="left" valign="middle">PICurrent</cell>
          <cell align="left" valign="middle">PortableInterceptors::Current</cell>
        </row>
        <tcaption>Currently reserved key strings</tcaption>
      </table>
    </section>

    <section>
      <title>corbaname</title>
      <p>The <c>corbaname</c> URL scheme is an extension of the <c>corbaloc</c> scheme, and
        the full <c>corbaname</c> BNF is:</p>
      <code type="none"><![CDATA[
<corbaname>     = "corbaname:"<obj_addr_list>["/"<key_string>]["#"<string_name>] 
<obj_addr_list> = as described above.
<key_string>    = as described above.
      ]]></code>
      <p>The <c>string_name</c>, concatenated to the <c>corbaloc</c> string, identifies
        a binding in a naming context. A name component consists of two parts, i.e.,
        <c>id</c> and <c>kind</c>, which is represented as follows:</p>
      <table>
        <row>
          <cell align="center" valign="middle"><em>String Name</em></cell>
          <cell align="center" valign="middle"><em>Name Sequence</em></cell>
          <cell align="center" valign="middle"><em>Comment</em></cell>
        </row>
        <row>
          <cell align="left" valign="middle">"id1/./id3.kind3"</cell>
          <cell align="left" valign="middle">[{"id1",""},{"",""},{"id3","kind3"}]</cell>
          <cell align="left" valign="middle">The first component has no kind defined while the second component's both fields are empty.</cell>
        </row>
        <row>
          <cell align="left" valign="middle">"id1//id3.kind3"</cell>
          <cell align="left" valign="middle">ERROR</cell>
          <cell align="left" valign="middle">Not allowed, must insert a '.' between the '//'.</cell>
        </row>
        <row>
          <cell align="left" valign="middle">"id1.kind1/."</cell>
          <cell align="left" valign="middle">[{"id1","kind1"},{"",""}]</cell>
          <cell align="left" valign="middle">The first component's fields are both set while the second component's both fields are empty.</cell>
        </row>
        <row>
          <cell align="left" valign="middle">"id1.kind1/id2."</cell>
          <cell align="left" valign="middle">ERROR</cell>
          <cell align="left" valign="middle">An Id with a trailing '.' is not allowed.</cell>
        </row>
        <row>
          <cell align="left" valign="middle">"i\\/d1/i\\.d2"</cell>
          <cell align="left" valign="middle">[{"i/d1",""},{"i.d2",""}]</cell>
          <cell align="left" valign="middle">Since '.' and '/' are used to separate the components, these tokens must be escaped to be correctly converted.</cell>
        </row>
        <tcaption>Stringified Name representation</tcaption>
      </table>
      <p>After creating a stringified Name we can either use:</p>
      <code type="none">
NameStr = "org.erlang",
NS      = corba:resolve_initial_references("NameService"),
Obj     = 'CosNaming_NamingContextExt':resolve_str(NS, NameStr),
      </code>
      <p>or concatenate the Name String using:</p>
      <code type="none">
NameStr = "Swedish/Soccer/Champions",
Address = "corbaname:iiop:[email protected]:2000/NameService",
NS      = corba:resolve_initial_references("NameService"),
URLStr  = 'CosNaming_NamingContextExt':to_url(NS, Address, NameStr),
Obj     = corba:string_to_object(URLStr),
      </code>
      <p>Using the first alternative, the configuration variables <c>orbInitilRef</c> and
        <c>orbDefaultInitilRef</c>, will determine which other ORB's or the local
        Name Service Orber will try to resolve the given string from. The second
        alternative allows us to override any settings of the configuration variables.</p>
      <p>The function <c>to_url/3</c> will perform any necessary escapes compliant with
        IETF/RFC 2396. US-ASCII alphanumeric characters and 
        <c><![CDATA["," | "/" | ":" | "?" | "@" | "&" | "=" | "+" | "$" | ";" | "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"]]></c>
        are not escaped.</p>
    </section>
  </section>
</chapter>