diff options
author | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
---|---|---|
committer | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
commit | 84adefa331c4159d432d22840663c38f155cd4c1 (patch) | |
tree | bff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/orber/doc/src/ch_naming_service.xml | |
download | otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2 otp-84adefa331c4159d432d22840663c38f155cd4c1.zip |
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/orber/doc/src/ch_naming_service.xml')
-rw-r--r-- | lib/orber/doc/src/ch_naming_service.xml | 461 |
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> + |