<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06">
<TITLE>
Interoperable Naming Service
</TITLE>
</HEAD>
<BODY >
<A HREF="omniORBpy005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="omniORBpy007.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1><A NAME="htoc64">Chapter 6</A> Interoperable Naming Service</H1>
<A NAME="chap:ins"></A>
omniORB 3 supports the Interoperable Naming Service (INS), which will
be part of CORBA 2.4. The following is a summary of the new facilities
described in the INS edited chapters document [<A HREF="omniORBpy009.html#inschapters"><CITE>OMG00</CITE></A>].
These facilities are not available when using omniORBpy with omniORB
2.8.<BR>
<BR>
<A NAME="toc26"></A>
<H2><A NAME="htoc65">6.1</A> Object URIs</H2>
As well as accepting IOR-format strings, <TT>ORB::string_to_object()</TT>
now also supports two new Uniform Resource Identifier
(URI) [<A HREF="omniORBpy009.html#rfc2396"><CITE>BLFIM98</CITE></A>] formats, which can be used to specify objects in
a convenient human-readable form. The existing IOR-format strings are
now also considered URIs.<BR>
<BR>
<H3><A NAME="htoc66">6.1.1</A> corbaloc</H3>
<TT>corbaloc</TT> URIs allow you to specify object references which
can be contacted by IIOP, or found through
<TT>ORB::resolve_initial_references()</TT>. To specify an IIOP object
reference, you use a URI of the form:
<BLOCKQUOTE>
<TT>corbaloc:iiop:</TT><<I>host</I>><TT>:</TT><<I>port</I>><TT>/</TT><<I>object key</I>>
</BLOCKQUOTE>
for example:
<BLOCKQUOTE>
<TT>corbaloc:iiop:myhost.example.com:1234/MyObjectKey</TT>
</BLOCKQUOTE>
which specifies an object with key `MyObjectKey' within a
process running on myhost.example.com listening on port 1234. Object
keys containing non-ASCII characters can use the standard URI %
escapes:
<BLOCKQUOTE>
<TT>corbaloc:iiop:myhost.example.com:1234/My</TT><TT>%</TT><TT>efObjectKey</TT>
</BLOCKQUOTE>
denotes an object key with the value 239 (hex ef) in the
third octet.<BR>
<BR>
The protocol name `<TT>iiop</TT>' can be abbreviated to the empty
string, so the original URI can be written:
<BLOCKQUOTE>
<TT>corbaloc::myhost.example.com:1234/MyObjectKey</TT>
</BLOCKQUOTE>
The IANA has assigned port number 2809<SUP><A NAME="text9" HREF="#note9"><FONT SIZE=2>1</FONT></A></SUP> for use by <TT>corbaloc</TT>, so if
the server is listening on that port, you can leave the port number
out. The following two URIs refer to the same object:
<BLOCKQUOTE>
<TT>corbaloc::myhost.example.com:2809/MyObjectKey</TT><BR>
<TT>corbaloc::myhost.example.com/MyObjectKey</TT>
</BLOCKQUOTE>
You can specify an object which is available at more than
one location by separating the locations with commas:
<BLOCKQUOTE>
<TT>corbaloc::myhost.example.com,:localhost:1234/MyObjectKey</TT>
</BLOCKQUOTE>
Note that you must restate the protocol for each address,
hence the `<TT>:</TT>' before `<TT>localhost</TT>'. It could
equally have been written `<TT>iiop:localhost</TT>'.<BR>
<BR>
You can also specify an IIOP version number, although omniORB only
supports IIOP 1.0 at present:
<BLOCKQUOTE>
<TT>corbaloc::1.2@myhost.example.com/MyObjectKey</TT>
</BLOCKQUOTE>
Alternatively, to use <TT>resolve_initial_references()</TT>, you
use a URI of the form:
<BLOCKQUOTE>
<TT>corbaloc:rir:/NameService</TT>
</BLOCKQUOTE>
<H3><A NAME="htoc67">6.1.2</A> corbaname</H3>
<A NAME="sec:corbaname"></A>
<TT>corbaname</TT> URIs cause <TT>string_to_object()</TT> to look-up a
name in a CORBA Naming service. They are an extension of the
<TT>corbaloc</TT> syntax:
<BLOCKQUOTE>
<TT>corbaname:</TT><<I>corbaloc location</I>><TT>/</TT><<I>object key</I>><TT>#</TT><<I>stringified name</I>>
</BLOCKQUOTE>
for example:
<BLOCKQUOTE>
<TT>corbaname::myhost/NameService#project/example/echo.obj</TT><BR>
<TT>corbaname:rir:/NameService#project/example/echo.obj</TT>
</BLOCKQUOTE>
The object found with the <TT>corbaloc</TT>-style portion
must be of type <TT>CosNaming::NamingContext</TT>, or something
derived from it. If the object key (or <TT>rir</TT> name) is
`<TT>NameService</TT>', it can be left out:
<BLOCKQUOTE>
<TT>corbaname::myhost#project/example/echo.obj</TT><BR>
<TT>corbaname:rir:#project/example/echo.obj</TT>
</BLOCKQUOTE>
The stringified name portion can also be left out, in which
case the URI denotes the <TT>CosNaming::NamingContext</TT> which would
have been used for a look-up:
<BLOCKQUOTE>
<TT>corbaname::myhost.example.com</TT><BR>
<TT>corbaname:rir:</TT>
</BLOCKQUOTE>
The first of these examples is the easiest way of specifying
the location of a naming service.<BR>
<BR>
<A NAME="toc27"></A>
<H2><A NAME="htoc68">6.2</A> Configuring resolve_initial_references</H2>
<A NAME="sec:insargs"></A>
The INS adds two new command line arguments which provide a portable
way of configuring <TT>ORB::resolve_initial_references()</TT>:<BR>
<BR>
<H3><A NAME="htoc69">6.2.1</A> ORBInitRef</H3>
<TT>-ORBInitRef</TT> takes an argument of the form
<<I>ObjectId</I>><TT>=</TT><<I>ObjectURI</I>>. So, for example,
with command line arguments of:
<BLOCKQUOTE>
<TT>-ORBInitRef NameService=corbaname::myhost.example.com</TT>
</BLOCKQUOTE>
<TT>resolve_initial_references("NameService")</TT> will
return a reference to the object with key `NameService' available on
myhost.example.com, port 2809. Since IOR-format strings are considered
URIs, you can also say things like:
<BLOCKQUOTE>
<TT>-ORBInitRef NameService=IOR:00ff...</TT>
</BLOCKQUOTE>
<H3><A NAME="htoc70">6.2.2</A> ORBDefaultInitRef</H3>
<TT>-ORBDefaultInitRef</TT> provides a prefix string which is used to
resolve otherwise unknown names. When
<TT>resolve_initial_references()</TT> is unable to resolve a name which
has been specifically configured (with <TT>-ORBInitRef</TT>), it
constructs a string consisting of the default prefix, a `<TT>/</TT>'
character, and the name requested. The string is then fed to
<TT>string_to_object()</TT>. So, for example, with a command line of:
<BLOCKQUOTE>
<TT>-ORBDefaultInitRef corbaloc::myhost.example.com</TT>
</BLOCKQUOTE>
a call to <TT>resolve_initial_references("MyService")</TT>
will return the object reference denoted by
`<TT>corbaloc::myhost.example.com/MyService</TT>'.<BR>
<BR>
Similarly, a <TT>corbaname</TT> prefix can be used to cause
look-ups in the naming service. Note, however, that since a
`<TT>/</TT>' character is always added to the prefix, it is
impossible to specify a look-up in the root context of the naming
service---you have to use a sub-context, like:
<BLOCKQUOTE>
<TT>-ORBDefaultInitRef corbaname::myhost.example.com#services</TT>
</BLOCKQUOTE>
<H3><A NAME="htoc71">6.2.3</A> omniORB configuration file</H3>
As an extension to the standard facilities of the INS, omniORB
supports configuration file entries named <TT>ORBInitRef</TT> and
<TT>ORBDefaultInitRef</TT>. The syntax is identical to the command
line arguments. <TT>omniORB.cfg</TT> might contain:
<BLOCKQUOTE>
<PRE>
ORBInitRef NameService=corbaname::myhost.example.com
ORBDefaultInitRef corbaname:rir:#services
</PRE></BLOCKQUOTE>
<H3><A NAME="htoc72">6.2.4</A> Resolution order</H3>
With all these options for specifying object references to be returned
by <TT>resolve_initial_references()</TT>, it is important to
understand the order in which the options are tried. The resolution
order, as required by the CORBA specification, is:
<OL type=1><LI>Check for special names such as `<TT>RootPOA</TT>'<SUP><A NAME="text10" HREF="#note10"><FONT SIZE=2>2</FONT></A></SUP>.<BR>
<BR>
<LI>Resolve with an <TT>-ORBInitRef</TT> argument.<BR>
<BR>
<LI><A NAME="itm:defaultgotcha"></A> Resolve with the
<TT>-ORBDefaultInitRef</TT> prefix, if present.<BR>
<BR>
<LI>Resolve with an <TT>ORBInitRef</TT>
(or old-style <TT>NAMESERVICE</TT>) entry in the configuration file.<BR>
<BR>
<LI>Resolve with the <TT>ORBDefaultInitRef</TT> entry in the
configuration file, if present.<BR>
<BR>
<LI>Resolve with the deprecated <TT>ORBInitialHost</TT> boot agent.</OL>
This order mostly has the expected consequences---in
particular that command line arguments override entries in the
configuration file. However, you must be careful with the default
prefixes. Suppose you have configured a `<TT>NameService</TT>' entry
in the configuration file, and you specify a default prefix on the
command line with:
<BLOCKQUOTE>
<TT>-ORBDefaultInitRef corbaname:rir:#services</TT>
</BLOCKQUOTE>
expecting unknown services to be looked up in the configured
naming service. Now, step <A HREF="#itm:defaultgotcha">344Resolution orderItem.14</A> above means that
<TT>resolve_initial_references("MyService")</TT> should be processed
with the steps:
<OL type=1><LI>Construct the URI `<TT>corbaname:rir:#services/MyService</TT>'
and give it to <TT>string_to_object()</TT>.<BR>
<BR>
<LI>Resolve the first part of the <TT>corbaname</TT> URI by
calling<BR>
<TT>resolve_initial_references("NameService")</TT>.<BR>
<BR>
<LI>Construct the URI
`<TT>corbaname:rir:#services/NameService</TT>' and give it to
<TT>string_to_object()</TT>.<BR>
<BR>
<LI>Resolve the first part of the <TT>corbaname</TT> URI by
calling<BR>
<TT>resolve_initial_references("NameService")</TT>.<BR>
<BR>
<LI>... and so on for ever...</OL>
omniORB detects loops like this and throws either
<TT>CORBA.ORB.InvalidName</TT> if the loop started with a call to
<TT>resolve_initial_references()</TT>, or <TT>CORBA.BAD_PARAM</TT>
if it started with a call to <TT>string_to_object()</TT>. To avoid the
problem you must either specify the <TT>NameService</TT> reference on
the command line, or put the <TT>DefaultInitRef</TT> in the
configuration file.<BR>
<BR>
<A NAME="toc28"></A>
<H2><A NAME="htoc73">6.3</A> omniNames</H2>
<H3><A NAME="htoc74">6.3.1</A> NamingContextExt</H3>
omniNames now supports the <TT>CosNaming::NamingContextExt</TT>
interface:
<PRE>
module CosNaming {
interface NamingContextExt : NamingContext {
typedef string StringName;
typedef string Address;
typedef string URLString;
StringName to_string(in Name n) raises(InvalidName);
Name to_name (in StringName sn) raises(InvalidName);
exception InvalidAddress {};
URLString to_url(in Address addr, in StringName sn)
raises(InvalidAddress, InvalidName);
Object resolve_str(in StringName n)
raises(NotFound, CannotProceed, InvalidName, AlreadyBound);
};
};
</PRE>
<TT>to_string()</TT> and <TT>to_name()</TT> convert from <TT>CosNaming::Name</TT>
sequences to flattened strings and vice-versa. Calling these
operations involves remote calls to the naming service, so they are
not particularly efficient. The <TT>omniORB.URI</TT> module contains
equivalent <TT>nameToString()</TT> and <TT>stringToName()</TT> functions, which do
not involve remote calls.<BR>
<BR>
A <TT>CosNaming::Name</TT> is stringified by separating name components
with `<TT>/</TT>' characters. The <TT>kind</TT> and <TT>id</TT> fields of
each component are separated by `<TT>.</TT>' characters. If the
<TT>kind</TT> field is empty, the representation has no trailing
`<TT>.</TT>'; if the <TT>id</TT> is empty, the representation starts
with a `<TT>.</TT>' character; if both <TT>id</TT> and <TT>kind</TT>
are empty, the representation is just a `<TT>.</TT>'. The backslash
`<TT>\</TT>' is used to escape the meaning of
`<TT>/</TT>', `<TT>.</TT>' and `<TT>\</TT>' itself.<BR>
<BR>
<TT>to_url()</TT> takes a <TT>corbaloc</TT> style address and key string
(but without the <TT>corbaloc:</TT> part), and a stringified name,
and returns a <TT>corbaname</TT> URI (incorrectly called a URL)
string, having properly escaped any invalid characters. The
specification does not make it clear whether or not the address string
should also be escaped by the operation; omniORB does not escape
it. For this reason, it is best to avoid calling <TT>to_url()</TT> if the
address part contains escapable characters. The local function
<TT>omniORB.URI.addrAndNameToURI()</TT> is equivalent.<BR>
<BR>
<TT>resolve_str()</TT> is equivalent to calling <TT>to_name()</TT> followed by
the inherited <TT>resolve()</TT> operation. There are no string-based
equivalents of the various bind operations.<BR>
<BR>
<H3><A NAME="htoc75">6.3.2</A> Use with corbaname</H3>
To make it easy to use omniNames with <TT>corbaname</TT> URIs, it
now starts with the default port of 2809, and an object key of
`<TT>NameService</TT>' for the root naming context. This is only
possible when it is started `fresh', rather than with a log file from
an older omniNames version.<BR>
<BR>
If you have a previous omniNames log, configured to run on a different
port, and with a different object key for its root context, all is not
lost. If the root context's object key is not `<TT>NameService</TT>',
omniNames creates a forwarding agent with that key. Effectively, this
means that there are two object keys which refer to the root
context---`<TT>NameService</TT>' and whatever the original key was.<BR>
<BR>
For the port number, there are two options. The first is to run
omniNames with a command line argument like:
<BLOCKQUOTE>
<TT>omniNames -logdir /the/log/dir -ORBpoa_iiop_port 2809</TT>
</BLOCKQUOTE>
This causes it to listen on both port 2809 <EM>and</EM>
whatever port it listened on before. The disadvantage with this is
that the IORs to all naming contexts now contain two IIOP profiles,
one for each port, which, amongst other things, increases the size of
the omniNames log.<BR>
<BR>
The second option is to use omniMapper, as described below.<BR>
<BR>
<A NAME="toc29"></A>
<H2><A NAME="htoc76">6.4</A> omniMapper</H2>
omniMapper is a simple daemon which listens on port 2809 (or any other
port), and redirects IIOP requests for configured object keys to
associated persistent IORs. It can be used to make a naming service
(even an old non-INS aware version of omniNames or other ORB's naming
service) appear on port 2809 with the object key
`<TT>NameService</TT>'. The same goes for any other service you may
wish to specify, such as an interface repository. omniMapper is
started with a command line of:
<BLOCKQUOTE>
<TT>omniMapper [-port </TT><<I>port</I>><TT>] [-config </TT><<I>config file</I>><TT>] [-v]</TT>
</BLOCKQUOTE>
The <TT>-port</TT> option allows you to choose a port other
than 2809 to listen on<SUP><A NAME="text11" HREF="#note11"><FONT SIZE=2>3</FONT></A></SUP>. The <TT>-config</TT> option specifies a location for the
configuration file. The default name is <TT>/etc/omniMapper.cfg</TT>, or
<CODE>C:\omniMapper.cfg</CODE>
on Windows. omniMapper does not normally print anything; the
<TT>-v</TT> option makes it verbose so it prints configuration
information and a record of the redirections it makes, to standard
output.<BR>
<BR>
The configuration file is very simple. Each line contains a string to
be used as an object key, some white space, and an IOR (or any valid
URI) that it will redirect that object key to. Comments should be
prefixed with a `<TT>#</TT>' character. For example:
<BLOCKQUOTE>
<PRE>
# Example omniMapper.cfg
NameService IOR:000f...
InterfaceRepository IOR:0100...
</PRE></BLOCKQUOTE>
omniMapper can either be run on a single machine, in much the same way
as omniNames, or it can be run on <EM>every</EM> machine, with a common
configuration file. That way, each machine's omniORB configuration
file could contain the line:
<BLOCKQUOTE>
<PRE>
ORBDefaultInitRef corbaloc::localhost
</PRE></BLOCKQUOTE>
<A NAME="toc30"></A>
<H2><A NAME="htoc77">6.5</A> Creating objects with simple object keys</H2>
In normal use, omniORB creates object keys containing various
information including POA names and various non-ASCII characters.
Since object keys are supposed to be opaque, this is not usually a
problem. The INS breaks this opacity and requires servers to create
objects with human-friendly keys.<BR>
<BR>
If you wish to make your objects available with human-friendly URIs,
there are two options. The first is to use omniMapper as described
above, in conjunction with a <TT>PERSISTENT</TT> POA. The second is to
create objects with the required keys yourself. You do this with a
special POA with the name `<TT>omniINSPOA</TT>', acquired from
<TT>resolve_initial_references()</TT>. This POA has the <TT>USER_ID</TT>
and <TT>PERSISTENT</TT> policies, and the special property that the
object keys it creates contain only the object ids given to the POA,
and no other data. It is a normal POA in all other respects, so you
can activate/deactivate it, create children, and so on, in the usual
way.<BR>
<BR>
<HR WIDTH="50%" SIZE=1><DL><DT><A NAME="note9" HREF="#text9"><FONT SIZE=5>1</FONT></A><DD>Not 2089 as
printed in [<A HREF="omniORBpy009.html#inschapters"><CITE>OMG00</CITE></A>]!
<DT><A NAME="note10" HREF="#text10"><FONT SIZE=5>2</FONT></A><DD>In
fact, a strict reading of the specification says that it should be
possible to override `<TT>RootPOA</TT>' etc. with
<TT>-ORBInitRef</TT>, but since POAs are locality constrained that is
ridiculous.
<DT><A NAME="note11" HREF="#text11"><FONT SIZE=5>3</FONT></A><DD>You can also play the
<TT>-ORBpoa_iiop_port</TT> trick to make it listen on more than one
port.
</DL>
<HR>
<A HREF="omniORBpy005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="omniORBpy007.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
6e619d98ab27dc37261afe9e8317cae2
>
files
>
16
