diff options
Diffstat (limited to 'lib/orber/doc/src/ch_naming_service.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_naming_service.xml | 465 |
1 files changed, 0 insertions, 465 deletions
diff --git a/lib/orber/doc/src/ch_naming_service.xml b/lib/orber/doc/src/ch_naming_service.xml deleted file mode 100644 index 991402ae86..0000000000 --- a/lib/orber/doc/src/ch_naming_service.xml +++ /dev/null @@ -1,465 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <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>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="erl"> -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="erl"> -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="erl"> -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="erl"> -Name = lname:new(["object"]). - </code> - </item> - <item> - <p>Use CosNaming::NamingContext::bind() to bind a name to an object</p> - <code type="erl"> -'CosNaming_NamingContext':bind(Sc, Name, Object). - </code> - </item> - <item> - <p>Use CosNaming::NamingContext::unbind() to remove the NameBinding from an object</p> - <code type="erl"> -'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="erl"> -Name = lname:new(["workgroup", "services"]). - </code> - </item> - <item> - <p>Use CosNaming::NamingContext::resolve() to to resolve the name to an object</p> - <code type="erl"> -Sc = 'CosNaming_NamingContext':resolve(NS, Name). - </code> - </item> - </list> - <p>An alternative is to use:</p> - <code type="erl"> -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="erl"> -{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="erl"> -'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="erl"> -'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="erl"> -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="erl"> -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="erl"> -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="erl"> -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> - |