Previous Contents Next

Chapter 4   Interoperable Naming Service

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 [OMG00a]. These facilities are not available when using omniORBpy with omniORB 2.8.

4.1   Object URIs

As well as accepting IOR-format strings, ORB::string_to_object() now also supports two new Uniform Resource Identifier (URI) [BLFIM98] formats, which can be used to specify objects in a convenient human-readable form. The existing IOR-format strings are now also considered URIs.

4.1.1   corbaloc

corbaloc URIs allow you to specify object references which can be contacted by IIOP, or found through ORB::resolve_initial_references(). To specify an IIOP object reference, you use a URI of the form:

corbaloc:iiop:<host>:<port>/<object key>
for example:

corbaloc:iiop:myhost.example.com:1234/MyObjectKey
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:

corbaloc:iiop:myhost.example.com:1234/My%efObjectKey
denotes an object key with the value 239 (hex ef) in the third octet.

The protocol name `iiop' can be abbreviated to the empty string, so the original URI can be written:

corbaloc::myhost.example.com:1234/MyObjectKey
The IANA has assigned port number 28091 for use by corbaloc, 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:

corbaloc::myhost.example.com:2809/MyObjectKey
corbaloc::myhost.example.com/MyObjectKey
You can specify an object which is available at more than one location by separating the locations with commas:

corbaloc::myhost.example.com,:localhost:1234/MyObjectKey
Note that you must restate the protocol for each address, hence the `:' before `localhost'. It could equally have been written `iiop:localhost'.

You can also specify an IIOP version number, although omniORB only supports IIOP 1.0 at present:

corbaloc::[email protected]/MyObjectKey
Alternatively, to use resolve_initial_references(), you use a URI of the form:

corbaloc:rir:/NameService

4.1.2   corbaname

corbaname URIs cause string_to_object() to look-up a name in a CORBA Naming service. They are an extension of the corbaloc syntax:

corbaname:<corbaloc location>/<object key>#<stringified name>
for example:

corbaname::myhost/NameService#project/example/echo.obj
corbaname:rir:/NameService#project/example/echo.obj
Note that the object found with the corbaloc-style portion must be of type CosNaming::NamingContext, or something derived from it. If the object key (or rir name) is `NameService', it can be left out:

corbaname::myhost#project/example/echo.obj
corbaname:rir:#project/example/echo.obj
The stringified name portion can also be left out, in which case the URI denotes the CosNaming::NamingContext which would have been used for a look-up:

corbaname::myhost.example.com
corbaname:rir:
The first of these examples is the easiest way of specifying the location of a naming service.

4.2   Configuring resolve_initial_references

The INS adds two new command line arguments which provide a portable way of configuring ORB::resolve_initial_references():

4.2.1   ORBInitRef

-ORBInitRef takes an argument of the form <ObjectId>=<ObjectURI>. So, for example, with command line arguments of:

-ORBInitRef NameService=corbaname::myhost.example.com
resolve_initial_references("NameService") 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:

-ORBInitRef NameService=IOR:00ff...

4.2.2   ORBDefaultInitRef

-ORBDefaultInitRef provides a prefix string which is used to resolve otherwise unknown names. When resolve_initial_references() is unable to resolve a name which has been specifically configured (with -ORBInitRef), it constructs a string consisting of the default prefix, a `/' character, and the name requested. The string is then fed to string_to_object(). So, for example, with a command line of:

-ORBDefaultInitRef corbaloc::myhost.example.com
a call to resolve_initial_references("MyService") will return the object reference denoted by `corbaloc::myhost.example.com/MyService'.

Similarly, a corbaname prefix can be used to cause look-ups in the naming service. Note, however, that since a `/' 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:

-ORBDefaultInitRef corbaname::myhost.example.com#services

4.2.3   omniORB configuration file

As an extension to the standard facilities of the INS, omniORB supports configuration file entries named ORBInitRef and ORBDefaultInitRef. The syntax is identical to the command line arguments. omniORB.cfg might contain:

ORBInitRef NameService=corbaname::myhost.example.com
ORBDefaultInitRef corbaname:rir:#services

4.2.4   Resolution order

With all these options for specifying object references to be returned by resolve_initial_references(), it is important to understand the order in which the options are tried. The resolution order, as required by the CORBA specification, is:

  1. Check for special names such as `RootPOA'2.

  2. Resolve with an -ORBInitRef argument.

  3. Resolve with the -ORBDefaultInitRef prefix, if present.

  4. Resolve with an ORBInitRef (or old-style NAMESERVICE) entry in the configuration file.

  5. Resolve with the ORBDefaultInitRef entry in the configuration file, if present.

  6. Resolve with the deprecated ORBInitialHost boot agent.
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 `NameService' entry in the configuration file, and you specify a default prefix on the command line with:

-ORBDefaultInitRef corbaname:rir:#services
expecting unknown services to be looked up in the configured naming service. Now, step 3 above means that resolve_initial_references("MyService") should be processed with the steps:

  1. Construct the URI `corbaname:rir:#services/MyService' and give it to string_to_object().

  2. Resolve the first part of the corbaname URI by calling
    resolve_initial_references("NameService").

  3. Construct the URI `corbaname:rir:#services/NameService' and give it to string_to_object().

  4. Resolve the first part of the corbaname URI by calling
    resolve_initial_references("NameService").

  5. ... and so on for ever...
omniORB detects loops like this and throws either CORBA.ORB.InvalidName if the loop started with a call to resolve_initial_references(), or CORBA.BAD_PARAM if it started with a call to string_to_object(). To avoid the problem you must either specify the NameService reference on the command line, or put the DefaultInitRef in the configuration file.

4.3   omniNames

4.3.1   NamingContextExt

omniNames now supports the CosNaming::NamingContextExt interface:

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);
  };
};
to_string() and to_name() convert from CosNaming::Name sequences to flattened strings and vice-versa. Note that calling these operations involves remote calls to the naming service, so they are not particularly efficient. The omniORB.URI module contains equivalent nameToString() and stringToName() functions, which do not involve remote calls.

A CosNaming::Name is stringified by separating name components with `/' characters. The kind and id fields of each component are separated by `.' characters. If the kind field is empty, the representation has no trailing `.'; if the id is empty, the representation starts with a `.' character; if both id and kind are empty, the representation is just a `.'. The backslash `\' is used to escape the meaning of `/', `.' and `\' itself.

to_url() takes a corbaloc style address and key string (but without the corbaloc: part), and a stringified name, and returns a corbaname 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 to_url() if the address part contains escapable characters. The local function omniORB.URI.addrAndNameToURI() is equivalent.

resolve_str() is equivalent to calling to_name() followed by the inherited resolve() operation. There are no string-based equivalents of the various bind operations.

4.3.2   Use with corbaname

To make it easy to use omniNames with corbaname URIs, it now starts with the default port of 2809, and an object key of `NameService' 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.

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 `NameService', omniNames creates a forwarding agent with that key. Effectively, this means that there are two object keys which refer to the root context---`NameService' and whatever the original key was.

For the port number, there are two options. The first is to run omniNames with a command line argument like:

omniNames -logdir /the/log/dir -ORBpoa_iiop_port 2809
This causes it to listen on both port 2809 and 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.

The second option is to use omniMapper, as described below.

4.4   omniMapper

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 `NameService'. 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:

omniMapper [-port <port>] [-config <config file>] [-v]
The -port option allows you to choose a port other than 2809 to listen on3. The -config option specifies a location for the configuration file. The default name is /etc/omniMapper.cfg, or C:\omniMapper.cfg on Windows. omniMapper does not normally print anything; the -v option makes it verbose so it prints configuration information and a record of the redirections it makes, to standard output.

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 `#' character. For example:

# Example omniMapper.cfg
NameService         IOR:000f...
InterfaceRepository IOR:0100...
omniMapper can either be run on a single machine, in much the same way as omniNames, or it can be run on every machine, with a common configuration file. That way, each machine's omniORB configuration file could contain the line:

ORBDefaultInitRef corbaloc::localhost

4.5   Creating objects with simple object keys

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.

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 PERSISTENT POA. The second is to create objects with the required keys yourself. You do this with a special POA with the name `omniINSPOA', acquired from resolve_initial_references(). This POA has the USER_ID and PERSISTENT 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.

1
Not 2089 as printed in [OMG00a]!
2
In fact, a strict reading of the specification says that it should be possible to override `RootPOA' etc. with -ORBInitRef, but since POAs are locality constrained that is ridiculous.
3
You can also play the -ORBpoa_iiop_port trick to make it listen on more than one port.
Previous Contents Next