The R13B03 release.OTP_R13B03

1 files changed, 461 insertions, 0 deletions

diff --git a/lib/orber/doc/src/ch_naming_service.xml b/lib/orber/doc/src/ch_naming_service.xml
new file mode 100644
index 0000000000..510ccf2543
--- /dev/null
+++ b/lib/orber/doc/src/ch_naming_service.xml
@@ -0,0 +1,461 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <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>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">
+\011NS = 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 
+\011nobject ->
+\011\011io:format("id: %s, kind: %s, type: object~n", [Id, Kind]);
+\011 _ ->
+\011\011io:format("id: %s, kind: %s, type: ncontext~n", [Id, Kind])
+\011end end,
+\011Blist).
+          </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\011number 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_address 
+<version>          = <major>"."<minor>"@"  | empty_string 
+<port>             = number 
+<major>            = number 
+<minor>            = number
+<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>
+