From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/orber/doc/src/ch_naming_service.xml | 461 ++++++++++++++++++++++++++++++++ 1 file changed, 461 insertions(+) create mode 100644 lib/orber/doc/src/ch_naming_service.xml (limited to 'lib/orber/doc/src/ch_naming_service.xml') 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 @@ + + + + +
+ + 19972009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + CosNaming Service + + + 1998-10-10 + + ch_naming_service.xml +
+ +
+ Overview of the CosNaming Service +

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.

+

The CosNaming service has some concepts that are important:

+ + +

name binding - a name to object association.

+ + +

naming context - 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. +

+ + +

to bind a name - is to create a name binding in a given + context.

+ + +

to resolve a name - is to determine the object associated + with the name in a given context.

+ + +

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 name and the + individual + elements in the sequence as name components. All but the + last name component are bound to naming contexts. +

+

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. +

+ + + +Figure 1: Contextual object relationships using the Naming Service. + +

The naming contexts provide a directory of contextual + reference and naming for objects (an object can appear to + have more than one name). +

+

In figure 1 the object to the right can either be + called alpha from one context or gamma from another. +

+

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 beta and epsilon, 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. +

+

We recommend reading chapter 12, CORBA Fundamentals and Programming, for detailed information regarding the + Naming Service.

+
+ +
+ The Basic Use-cases of the Naming Service +

The basic use-cases of the Naming Service are: +

+ + Fetch initial reference to the naming service. + Creating a naming context. + Binding and unbinding names to objects. + Resolving a name to an object. + Listing the bindings of a naming context. + Destroying a naming context. + + +
+ Fetch Initial Reference to the Naming Service +

In order to use the naming service you have to fetch an + initial reference to it. This is done with:

+ +\011NS = corba:resolve_initial_references("NameService"). + + +

NS in the other use-cases refers to this initial reference.

+ +
+ +
+ Creating a Naming Context +

There are two functions for creating a naming context. + The first function, which only creates a naming context object is:

+ +NC = 'CosNaming_NamingContext':new_context(NS). + +

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): +

+ +NC = 'CosNaming_NamingContext':bind_new_context(NS, lname:new(["new"])). + +
+ +
+ Binding and Unbinding Names to Objects +

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 /workgroup/services, + and that reference to the services context are in the variable + Sc.

+ + +

Use the naming library functions to create a name

+ +Name = lname:new(["object"]). + + + +

Use CosNaming::NamingContext::bind() to bind a name to an object

+ +'CosNaming_NamingContext':bind(Sc, Name, Object). + + + +

Use CosNaming::NamingContext::unbind() to remove the NameBinding from an object

+ +'CosNaming_NamingContext':unbind(Sc, Name). + + + + +

Objects can have more than one name, to indicate different paths to + the same object.

+ +
+ +
+ Resolving a Name to an Object +

The following steps show how to retrieve the object reference to the service context + above (/workgroup/services).

+ + +

Use the naming library functions to create a name path:

+ +Name = lname:new(["workgroup", "services"]). + + + +

Use CosNaming::NamingContext::resolve() to to resolve the name to an object

+ +Sc = 'CosNaming_NamingContext':resolve(NS, Name). + + + +

An alternative is to use:

+ +Sc = corba:string_to_object("corbaname:rir:/NameService#workgroup/services/"). + +

The corbaname schema is described further in the Interoperable + Naming Service section.

+
+ +
+ Listing the Bindings in a NamingContext + + +

Use CosNaming::NamingContext::list() to list all the bindings in a context

+

The following code retrieves and lists up to 10 bindings from a context.

+ +{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). + + + + +

Normally a The binding iterator (Like a book mark) indicates which objects have been read from the list.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.

+ + +

Remember that the BindingIterator (BIterator in the example) is an object and therefore + must be removed otherwise dangling processes will occur. + Use CosNaming::BindingIterator::destroy() to remove it.

+ + + 'CosNaming_NamingContext':destroy(BIterator). + +
+ +
+ Destroying a Naming Context +

The naming contexts are persistent and must be explicitly removed. + (they are also removed if all Orber nodes in the domain are stopped).

+ + +

Use CosNaming::NamingContext::destroy() to remove a NamingContext

+ +'CosNaming_NamingContext':destroy(Sc). + + + +
+
+ +
+ Interoperable Naming Service + +

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:

+ + IOR + corbaloc + corbaname + + +
+ IOR +

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.

+
+ +
+ corbaloc +

The notation of this scheme is similar to the more well known URL HTTP, and + the full corbaloc BNF is:

+ = "corbaloc:"["/"] + = [","]* + = | + = | + = ":" + = rir + = + = ":" + = + = | ":" + = ":" + = "iiop" + = [":"] + = DNS-style Host Name | ip_address + = ".""@" | empty_string + = number + = number + = number + = for example NameService + ]]> +

The corbaloc scheme consists of 3 parts:

+ + Protocol - as of today iiop or rir is supported. + Using rir means that we will resolve the given Key locally, i.e., + the same as using corba:resolve_initial_references("NameService"). + IIOP address - this address can be divided into Version, Host + and Port. If the version or port are left out they will be set to the default + values 1.0 and 2809 respectively. + KeyString - an object key, e.g., "NameService". If no Key is + supplied the default value "NameService" will be used. + +

A corbaloc can be passed used together with + corba:string_to_object("corbaloc::1.0@erlang.org:4001/NameService") or set as the + configuration variables orbInitilRef or orbDefaultInitilRef and calling + corba:resolve_initial_references("NameService"). For more information see the Orber + installation chapter. corbaloc can also be used together with corbaname + to gain an easy access to a Name Service.

+

Currently, the OMG defines a set of reserved keys and the type of object, + listed below, they should be associated with. The NameService + key may not be changed in Orber. If you want to add one of the + reserved keys as an initial service, simply use:

+ +1> Factory = cosNotificationApp:start_global_factory(). +2> corba:add_initial_service("NotificationService", Factory). + +

This object can then be easily resolved by any other ORB, supporting + the Interoperable Naming Service, by using:

+ +3> NF = corba:string_to_object("corbaloc::1.0@erlang.org:4001/NotificationService"). + + + + String Name + Object Type + + + RootPOA + PortableServer::POA + + + POACurrent + PortableServer::Current + + + InterfaceRepository + CORBA::Repository + + + NameService + CosNaming::NamingContext + + + TradingService + CosTrading::Lookup + + + SecurityCurrent + SecurityLevel1::Current/SecurityLevel2::Current + + + TransactionCurrent + CosTransaction::Current + + + DynAnyFactory + DynamicAny::DynAnyFactory + + + ORBPolicyManager + CORBA::PolicyManager + + + PolicyCurrent + CORBA::PolicyCurrent + + + NotificationService + CosNotifyChannelAdmin::EventChannelFactory + + + TypedNotificationService + CosTypedNotifyChannelAdmin::TypedEventChannelFactory + + + CodecFactory + IOP::CodecFactory + + + PICurrent + PortableInterceptors::Current + + Currently reserved key strings +
+
+ +
+ corbaname +

The corbaname URL scheme is an extension of the corbaloc scheme, and + the full corbaname BNF is:

+ = "corbaname:"["/"]["#"] + = as described above. + = as described above. + ]]> +

The string_name, concatenated to the corbaloc string, identifies + a binding in a naming context. A name component consists of two parts, i.e., + id and kind, which is represented as follows:

+ + + String Name + Name Sequence + Comment + + + "id1/./id3.kind3" + [{"id1",""},{"",""},{"id3","kind3"}] + The first component has no kind defined while the second component's both fields are empty. + + + "id1//id3.kind3" + ERROR + Not allowed, must insert a '.' between the '//'. + + + "id1.kind1/." + [{"id1","kind1"},{"",""}] + The first component's fields are both set while the second component's both fields are empty. + + + "id1.kind1/id2." + ERROR + An Id with a trailing '.' is not allowed. + + + "i\\\\/d1/i\\\\.d2" + [{"i/d1",""},{"i.d2",""}] + Since '.' and '/' are used to separate the components, these tokens must be escaped to be correctly converted. + + Stringified Name representation +
+

After creating a stringified Name we can either use:

+ +NameStr = "org.erlang", +NS = corba:resolve_initial_references("NameService"), +Obj = 'CosNaming_NamingContextExt':resolve_str(NS, NameStr), + +

or concatenate the Name String using:

+ +NameStr = "Swedish/Soccer/Champions", +Address = "corbaname:iiop:1.0@www.aik.se:2000/NameService", +NS = corba:resolve_initial_references("NameService"), +URLStr = 'CosNaming_NamingContextExt':to_url(NS, Address, NameStr), +Obj = corba:string_to_object(URLStr), + +

Using the first alternative, the configuration variables orbInitilRef and + orbDefaultInitilRef, 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.

+

The function to_url/3 will perform any necessary escapes compliant with + IETF/RFC 2396. US-ASCII alphanumeric characters and + + are not escaped.

+
+
+ + -- cgit v1.2.3