Contents

Chapter 1 Introduction

omniORB is an Object Request Broker (ORB) that implements version 2.6 of the Common Object Request Broker Architecture (CORBA) [] specification. Where possible, backward compatibility has been maintained back to specification 2.0. It passed the Open Group CORBA compliant testsuite (for CORBA 2.1) and was one of the three ORBs to be granted the CORBA brand in June 1999.

This user guide tells you how to use omniORB to develop CORBA applications. It assumes a basic understanding of CORBA.

In this chapter, we give an overview of the main features of omniORB and what you need to do to set up your environment to run omniORB.

1.1 Features

omniORB is quite feature-rich, but it does not slavishly implement every last part of the CORBA specification. The goal is to provide the most generally useful parts of the specification in a clean and efficient manner. Highlights are:

• C++ and Python language bindings.
• Support for the complete Portable Object Adapter (POA) specification.
• Support for the Interoperable Naming Service (INS).
• Internet Inter-ORB Protocol (IIOP 1.2) is used as the native protocol.
• The omniORB runtime is fully multithreaded. It uses platform thread support encapsulated with a small class library, omnithread, to abstract away from differences in native thread APIs.
• TypeCode and type Any are supported.
• DynAny is supported.
• The Dynamic Invocation and Dynamic Skeleton interfaces are supported.
• Valuetype and abstract interfaces are supported.
• Asynchronous Method Invocation (AMI) supported, including both polling and callback models.
• Extensive control over connection management.
• Soft real-time features including call deadlines and timeouts.
• A COS Naming Service, omniNames.
• Many platforms are supported, including most Unix platforms and Windows.
• It has been successfully tested for interoperability via IIOP with other ORBs.

1.1.1 Multithreading

omniORB is fully multithreaded. To achieve low call overhead, unnecessary call multiplexing is eliminated. With the default policies, there is at most one call in-flight in each communication channel between two address spaces at any one time. To do this without limiting the level of concurrency, new channels connecting the two address spaces are created on demand and cached when there are concurrent calls in progress. Each channel is served by a dedicated thread. This arrangement provides maximal concurrency and eliminates any thread switching in either of the address spaces to process a call. Furthermore, to maximise the throughput in processing large call arguments, large data elements are sent as soon as they are processed while the other arguments are being marshalled. With GIOP 1.2, large messages are fragmented, so the marshaller can start transmission before it knows how large the entire message will be.

omniORB also supports a flexible thread pool policy, and supports sending multiple interleaved calls on a single connection. This policy leads to a small amount of additional call overhead, compared to the default thread per connection model, but allows omniORB to scale to extremely large numbers of concurrent clients.

1.1.2 Portability

omniORB runs on many flavours of Unix, Windows, several embedded operating systems, and relatively obscure systems such as OpenVMS and Fujitsu-Siemens BS2000. It is designed to be easy to port to new platforms. The IDL to C++ mapping for all target platforms is the same.

omniORB uses real C++ exceptions and nested classes. It keeps to the CORBA specification’s standard mapping as much as possible and does not use the alternative mappings for C++ dialects. The only small exception is the mapping of IDL modules, which can use either namespaces according to the standard, or nested classes for truly ancient C++ compilers without namespace support.

omniORB relies on native thread libraries to provide multithreading capability. A small class library (omnithread []) is used to encapsulate the APIs of the native thread libraries. In application code, it is recommended but not mandatory to use this class library for thread management. It should be easy to port omnithread to any platform that either supports the POSIX thread standard or has a thread package that supports similar capabilities.

Partly for historical reasons, and partly to support users with archaic compilers, omniORB does not use the C++ standard library.

The omniORB IDL compiler, omniidl, requires Python version 3.5 or later or, for people stuck in the past, version 2.7.

1.1.3 Missing features

omniORB is not a complete implementation of the CORBA 2.6 core. The following is a list of the most significant missing features.

• For some very dynamic uses of CORBA, you may need an Interface Repository. omniORB does not have its own one, but it can act as a client to an IfR. The omniifr project (https://github.com/omniorb/omniifr) aims to create an IfR for omniORB.
• omniORB supports interceptors, but not the standard Portable Interceptor API.

1.2 Setting up your environment

To get omniORB running, you first need to install omniORB according to the instructions in the installation notes for your platform. See README.FIRST.txt at the top of the omniORB tree for instructions. Most Unix platforms can use the Autoconf configure script to automate the configuration process.

Once omniORB is installed in a suitable location, you must configure it according to your required setup. The configuration can be set with a configuration file, environment variables, command-line arguments or, on Windows, the Windows registry.

• On Unix platforms, the omniORB runtime looks for the environment variable OMNIORB_CONFIG. If this variable is defined, it contains the pathname of the omniORB configuration file. If the variable is not set, omniORB will use the compiled-in pathname to locate the file (by default /etc/omniORB.cfg).
• On Win32 / Win64 platforms, omniORB first checks the environment variable OMNIORB_CONFIG to obtain the pathname of the configuration file. If this is not set, it then attempts to obtain configuration data in the system registry. It searches for the data under the key HKEY_LOCAL_MACHINE\SOFTWARE\omniORB.

omniORB has a large number of parameters than can be configured. See chapter ?? for full details. The files sample.cfg and sample.reg contain an example configuration file and set of registry entries respectively.

To get all the omniORB examples running, the main thing you need to configure is the Naming service, omniNames. To do that, the configuration file or registry should contain an entry of the form

  InitRef = NameService=corbaname::my.host.name

See section ?? for full details of corbaname URIs.

1.3 Platform specific variables

To compile omniORB programs correctly, several C++ preprocessor defines must be specified to identify the target platform. On Unix platforms where omniORB was configured with Autoconf, the omniconfig.h file sets these for you. On other platforms, and Unix platforms when Autoconf is not used, you must specify the following defines:

The preprocessor defines for new platform ports not listed above can be found in the corresponding platform configuration files. The preprocessor defines to identify a platform are in the make variable IMPORT_CPPFLAGS.

In a single source multi-target environment, you can put the preprocessor defines as the command-line arguments for the compiler. If you are building for a single platform, you can edit include/omniconfig.h to add the definitions.

Chapter 2 The Basics

In this chapter, we go through three examples to illustrate the practical steps to use omniORB. By going through the source code of each example, the essential concepts and APIs are introduced. If you have no previous experience with using CORBA, you should study this chapter in detail. There are pointers to other essential documents you should be familiar with.

If you have experience with using other ORBs, you should still go through this chapter because it provides important information about the features and APIs that are necessarily omniORB specific. With the Portable Object Adapter, there are very few omniORB specific details.

2.1 The Echo Object Example

Our example is an object which has only one method. The method simply echos the argument string. We have to:

1. define the object interface in IDL
2. use the IDL compiler to generate the stub code, which provides the object mapping as defined in the CORBA specification
3. provide the servant object implementation
4. write the client code.

These examples are in the src/examples/echo directory of the omniORB distribution; there are several other examples in src/examples.

2.2 Specifying the Echo interface in IDL

We define an object interface, called Echo, as follows:

If you are new to IDL, you can learn about its syntax in Chapter 3 of the CORBA 2.6 specification []. For the moment, you only need to know that the interface consists of a single operation, echoString(), which takes a string as an input argument and returns a copy of the same string.

The interface is written in a file, called echo.idl. It is part of the CORBA standard that all IDL files must have the extension ‘.idl’, although omniORB does not enforce this. In the omniORB distribution, this file is in idl/echo.idl.

For simplicity, the interface is defined in the global IDL namespace. You should normally avoid this practice for the sake of object reusability. If every CORBA developer defines their interfaces in the global IDL namespace, there is a danger of name clashes between two independently defined interfaces. Therefore, it is better to qualify your interfaces by defining them inside module names. Of course, this does not eliminate the chance of a name clash unless some form of naming convention is agreed globally. Nevertheless, a well-chosen module name can help a lot.

2.3 Generating the C++ stubs

From the IDL file, we use the IDL compiler to produce the C++ mapping of the interface. The IDL compiler for omniORB is called omniidl. Given the IDL file, omniidl produces two stub files: a C++ header file and a C++ source file. For example, from the file echo.idl, the following files are produced:

• echo.hh
• echoSK.cc

omniidl must be invoked with the -bcxx argument to tell it to generate C++ stubs. The following command line generates the stubs for echo.idl:

Note that the names echo.hh and echoSK.cc are not defined in the C++ mapping standard. Other CORBA implementations may use different file names. To aid migration omniidl from other implementations, omniidl has options to override the default output file names. See section ?? for details.

If you are using our make environment, you don’t need to invoke omniidl explicitly. In the example file dir.mk, we have the following line:

That is all we need to instruct the build system to generate the stubs. You won’t find the stubs in your working directory because all stubs are written into the stub directory at the top level of your build tree.

The full arguments to omniidl are detailed in chapter ??.

2.4 Object References and Servants

We contact a CORBA object through an object reference. The actual implementation of a CORBA object is termed a servant.

Object references and servants are quite separate entities, and it is important not to confuse the two. Client code deals purely with object references, so there can be no confusion; object implementation code must deal with both object references and servants. omniORB uses distinct C++ types for object references and servants, so the C++ compiler will complain if you use a servant when an object reference is expected, or vice-versa.

2.5 A quick look at the C++ mapping

The C++ stubs conform to the standard mapping defined in the CORBA specification []. Sadly, since it pre-dates the C++ standard library, the C++ language mapping is quite hard to use, especially because it has complex memory management rules.

The best way to understand the mapping is to read either the specification or, better, a book about using CORBA from C++. Reading the code generated by omniidl is hard-going, and it is difficult to distinguish the parts you need to know from the implementation details.

2.5.1 Mapping overview

For interface Echo, omniidl generates four things of note:

• class Echo, containing static functions and type definitions
• Echo_ptr, an object reference type with pointer semantics
• Echo_var, a memory management helper for Echo_ptr
• class POA_Echo, the server-side skeleton class

2.5.2 Interface scope type

A C++ class Echo is defined to hold a number of static functions and type definitions. It looks like this:

The _ptr_type and _var_type typedefs are there to facilitate template programming. The static functions are described below.

2.5.3 Object reference pointer type

For interface Echo, the mapping defines the object reference type Echo_ptr which has pointer semantics. The _ptr type provides access to the interface’s operations. The concrete type of an object reference is opaque, i.e. you must not make any assumptions about how an object reference is implemented. You can imagine it looks something like this:

To use an object reference, you use the arrow operator ‘->’ to invoke its operations, but you must not use it as a C++ pointer in any other respect. It is non-compliant to convert it to void*, perform arithmetic or relational operations including testing for equality using operator==.

In some CORBA implementations, Echo_ptr is a typedef to Echo*. In omniORB, it is not—the object reference type is distinct from class Echo.

2.5.3.1 Nil object reference

Object references can be nil. To obtain a nil object reference for interface Echo, call Echo::_nil(). To test if an object reference is nil, use CORBA::_is_nil():

Echo::_nil() is the only compliant way to obtain a nil Echo reference, and CORBA::is_nil() is the only compliant way to check if an object reference is nil. You should not use the equality operator==. Many C++ ORBs use the null pointer to represent a nil object reference, but omniORB does not.

2.5.3.2 Object reference lifecycle

Object references are reference counted. That is, the opaque C++ objects on the client side that implement Echo_ptr are reference counted, so they are deleted when the count goes to zero. The lifetime of an object reference has no bearing at all on the lifetime of the CORBA object to which it is a reference—when an object reference is deleted, it has no effect on the object in the server.

Reference counting for Echo object references is performed with Echo::_duplicate() and CORBA::release().

The _duplicate() function returns a new object reference of the Echo interface. The new object reference can be used interchangeably with the old object reference to perform an operation on the same object.

To indicate that an object reference will no longer be accessed, you must call the CORBA::release() operation. Its signature is as follows:

Once you have called CORBA::release() on an object reference, you may no longer use that reference. This is because the associated resources may have been deallocated. Remember that we are referring to the resources associated with the object reference and not the servant object. Servant objects are not affected by the lifetimes of object references. In particular, servants are not deleted when all references to them have been released—CORBA does not perform distributed garbage collection.

Nil object references are not reference counted, so there is no need to call _duplicate() and release() with them, although it does no harm.

Since object references must be released explicitly, their usage is prone to error and can lead to memory leaks or invalid memory accesses. The mapping defines the object reference variable type Echo_var to make life somewhat easier.

The Echo_var is more convenient to use because it automatically releases its object reference when it goes out of scope or when assigned a new object reference. For many operations, mixing data of type Echo_var and Echo_ptr is possible without any explicit operations or casting. For instance, the echoString() operation can be called using the arrow (‘->’) on a Echo_var, as one can do with a Echo_ptr.

The usage of Echo_var is illustrated below:

The mappings of many other IDL data types include _var types with similar semantics.

2.5.3.3 Object reference inheritance

All CORBA objects inherit from the generic object CORBA::Object. CORBA::Object_ptr is the object reference type for base CORBA::Object. Object references can be implicitly widened to base interface types, so this is valid:

An object reference such as Echo_ptr can be used in places where a CORBA::Object_ptr is expected. Conversely, the Echo::_narrow() function takes an argument of type CORBA::Object_ptr and returns a new object reference of the Echo interface. If the actual (runtime) type of the argument object reference can be narrowed to Echo_ptr, _narrow() will return a valid object reference. Otherwise it will return a nil object reference. Note that _narrow() performs an implicit duplication of the object reference, so the result must be released. Note also that _narrow() may involve a remote call to check the type of the object, so it may throw CORBA system exceptions such as TRANSIENT or OBJECT_NOT_EXIST.

2.5.3.4 Object reference equivalence

As described above, the equality operator== should not be used on object references. To test if two object references are equivalent, the member function _is_equivalent() of the generic object CORBA::Object can be used. Here is an example of its usage:

_is_equivalent() does not contact the object to check for equivalence—it uses purely local knowledge, meaning that it is possible to construct situations in which two object references refer to the same object, but _is_equivalent() does not consider them equivalent. If you need a strong sense of object identity, you must implement it with explicit IDL operations.

2.5.4 Servant Object Implementation

For each object interface, a skeleton class is generated. In our example, the POA specification says that the skeleton class for interface Echo is named POA_Echo. A servant implementation can be written by creating an implementation class that derives from the skeleton class.

The skeleton class POA_Echo is defined in echo.hh. The relevant section of the code is reproduced below.

The code fragment shows the only member functions that can be used in the object implementation code. Other member functions are generated for internal use only. As with the code generated for object references, other POA-based ORBs will generate code which looks different, but is functionally equivalent to this.

echoString()

It is through this abstract function that an implementation class provides the implementation of the echoString() operation. Notice that its signature is the same as the echoString() function that can be invoked via the Echo_ptr object reference. This will be the case most of the time, but object reference operations for certain parameter types use special helper classes to facilitate correct memory management.

_this()

The _this() function returns an object reference for the target object, provided the POA policies permit it. The returned value must be deallocated via CORBA::release(). See section ?? for an example of how this function is used.

2.6 Writing the servant implementation

You define a class to provide the servant implementation. There is little constraint on how you design your implementation class except that it has to inherit from the skeleton class¹ and to implement all the abstract functions defined in the skeleton class. Each of these abstract functions corresponds to an operation of the interface. They are the hooks for the ORB to perform upcalls to your implementation. Here is a simple implementation of the Echo object.

There are four points to note here:

Storage Responsibilities

String, which is used both as an in argument and the return value of echoString(), is a variable sized data type. Other examples of variable sized data types include sequences, type ‘any’, etc. For these data types, you must be clear about whose responsibility it is to allocate and release the associated storage. As a rule of thumb, the client (or the caller to the implementation functions) owns the storage of all in arguments, the object implementation (or the callee) must copy the data if it wants to retain a copy. For out arguments and return values, the object implementation allocates the storage and passes the ownership to the client. The client must release the storage when the variables will no longer be used. For details, see the C++ mapping specification.

Multi-threading

As omniORB is fully multithreaded, multiple threads may perform the same upcall to your implementation concurrently. It is up to your implementation to synchronise the threads’ accesses to shared data. In our simple example, we have no shared data to protect so no thread synchronisation is necessary.

Alternatively, you can create a POA which has the SINGLE_THREAD_MODEL Thread Policy. This guarantees that all calls to that POA are processed sequentially.

Reference Counting

All servant objects are reference counted. The base PortableServer::ServantBase class from which all servant skeleton classes derive defines member functions named _add_ref() and _remove_ref()². The reference counting means that an Echo_i instance will be deleted when no more references to it are held by application code or the POA itself. Note that this is totally separate from the reference counting which is associated with object references—a servant object is never deleted due to a CORBA object reference being released.

Instantiation

Servants are usually instantiated on the heap, i.e. using the new operator. However, they can also be created on the stack as automatic variables. If you do that, it is vital to make sure that the servant has been deactivated, and thus released by the POA, before the variable goes out of scope and is destroyed.

2.7 Writing the client

Here is an example of how an Echo_ptr object reference is used.

The hello() function accepts a generic object reference. The object reference (obj) is narrowed to Echo_ptr. If the object reference returned by Echo::_narrow() is not nil, the operation echoString() is invoked. Finally, both the argument to and the return value of echoString() are printed to cout.

The example also illustrates how T_var types are used. As was explained in the previous section, T_var types take care of storage allocation and release automatically when variables are reassigned or when the variables go out of scope.

In line 4, the variable e takes over the storage responsibility of the object reference returned by Echo::_narrow(). The object reference is released by the destructor of e. It is called automatically when the function returns. Lines 6 and 15 show how a Echo_var variable is used. As explained earlier, the Echo_var type can be used interchangeably with the Echo_ptr type.

The argument and the return value of echoString() are stored in CORBA::String_var variables src and dest respectively. The strings managed by the variables are deallocated by the destructor of CORBA::String_var. It is called automatically when the variable goes out of scope (as the function returns). Line 15 shows how CORBA::String_var variables are used. They can be used in place of a string (for which the mapping is char*)³. As used in line 12, assigning a constant string (const char*) to a CORBA::String_var causes the string to be copied. On the other hand, assigning a char* to a CORBA::String_var, as used in line 15, causes the latter to assume the ownership of the string⁴.

Under the C++ mapping, T_var types are provided for all the non-basic data types. One should use automatic variables whenever possible both to avoid memory leaks and to maximise performance. However, when one has to allocate data items on the heap, it is a good practice to use the T_var types to manage the heap storage.

2.8 Example 1 — Colocated Client and Servant

Having introduced the client and the object implementation, we can now describe how to link up the two via the ORB and POA. In this section, we describe an example in which both the client and the object implementation are in the same address space. In the next two sections, we shall describe the case where the two are in different address spaces.

The code for this example is reproduced below:

The example illustrates several important interactions among the ORB, the POA, the servant, and the client. Here are the details:

2.8.1 ORB initialisation

Line 4

The ORB is initialised by calling the CORBA::ORB_init() function. The function uses the optional 3rd argument to determine which ORB should be returned. Unless you are using omniORB specific features, it is usually best to leave it out, and get the default ORB. To explicitly ask for omniORB 4.x, this argument must be ‘omniORB4’⁵.

CORBA::ORB_init() takes the list of command line arguments and processes any that start ‘-ORB’. It removes these arguments from the list, so application code does not have to deal with them.

If any error occurs during ORB initialisation, such as invalid ORB arguments, or an invalid configuration file, the CORBA::INITIALIZE system exception is raised.

2.8.2 Obtaining the Root POA

Lines 6–7

To activate our servant object and make it available to clients, we must register it with a POA. In this example, we use the Root POA, rather than creating any child POAs. The Root POA is found with orb->resolve_initial_references(), which returns a plain CORBA::Object. In line 7, we narrow the reference to the right type for a POA.

A POA’s behaviour is governed by its policies. The Root POA has suitable policies for many simple servers, and closely matches the ‘policies’ used by omniORB 2’s BOA. See Chapter 11 of the CORBA 2.6 specification[] for details of all the POA policies which are available.

2.8.3 Object initialisation

Line 9

An instance of the Echo servant is initialised using the new operator. The PortableServer::Servant_var<> template is analogous to the T_var types generated by the IDL compiler. It releases our reference to the servant when it goes out of scope.

Line 10

The servant object is activated in the Root POA using poa->activate_object(), which returns an object identifier (of type PortableServer::ObjectId*). The object id must be passed back to various POA operations. The caller is responsible for freeing the object id, so it is assigned to a _var type.

Line 12

The object reference is obtained from the servant object by calling its _this() method. Like all object references, the return value of _this() must be released by CORBA::release() when it is no longer needed. In this case, we assign it to a _var type, so the release is implicit at the end of the function.

One of the important characteristics of an object reference is that it is completely location transparent. A client can invoke on the object using its object reference without any need to know whether the servant object is colocated in the same address space or is in a different address space.

In the case of colocated client and servant, omniORB is able to short-circuit the client calls so they do not involve IIOP. The calls still go through the POA, however, so the various POA policies affect local calls in the same way as remote ones. This optimisation is applicable not only to object references returned by _this(), but to any object references that are passed around within the same address space or received from other address spaces via remote calls.

2.8.4 Activating the POA

Lines 14–15

POAs are initially in the holding state, meaning that incoming requests are blocked. Lines 15 and 16 acquire a reference to the POA’s POA manager, and use it to put the POA into the active state. Incoming requests are now served. Failing to activate the POA is one of the most common programming mistakes. If your program appears deadlocked, make sure you activated the POA!

2.8.5 Performing a call

Line 17

At long last, we can call hello() with this object reference. The argument is widened implicitly to the generic object reference CORBA::Object_ptr.

2.8.6 ORB destruction

Line 19

Shutdown the ORB permanently. This call causes the ORB to release all its resources, e.g. internal threads, and also to deactivate any servant objects which are currently active. When it deactivates the Echo_i instance, the servant’s reference count drops to zero, so the servant is deleted.

2.9 Example 2 — Different Address Spaces

In this example, the client and the object implementation reside in two different address spaces. The code of this example is almost the same as the previous example. The only difference is the extra work which needs to be done to pass the object reference from the object implementation to the client.

The simplest (and quite primitive) way to pass an object reference between two address spaces is to produce a stringified version of the object reference and to pass this string to the client as a command-line argument. The string is then converted by the client into a proper object reference. This method is used in this example. In the next example, we shall introduce a better way of passing the object reference using the CORBA Naming Service.

2.9.1 Making a Stringified Object Reference

The main() function of the server side is reproduced below. The full listing (eg2_impl.cc) can be found at the end of this chapter.

The stringified object reference is obtained by calling the ORB’s object_to_string() function (line 13). This results in a string starting with the signature ‘IOR:’ and followed by quite a lot of hexadecimal digits. All CORBA compliant ORBs are able to convert the string into its internal representation of a so-called Interoperable Object Reference (IOR). The IOR contains the location information and a key to uniquely identify the object implementation in its own address space. From the IOR, an object reference can be constructed.

2.9.2 Client: Using a Stringified Object Reference

The stringified object reference is passed to the client as a command-line argument. The client uses the ORB’s string_to_object() function to convert the string into a generic object reference (CORBA::Object_ptr). The relevant section of the code is reproduced below. The full listing (eg2_clt.cc) can be found at the end of this chapter.

2.9.3 Catching System Exceptions

When omniORB detects an error condition, it may raise a system exception. The CORBA specification defines a series of exceptions covering most of the error conditions that an ORB may encounter. The client may choose to catch these exceptions and recover from the error condition⁶. For instance, the code fragment, shown in section ??, catches the TRANSIENT system exception which indicates that the object could not be contacted at the time of the call, usually meaning the server is not running.

All system exceptions inherit from CORBA::SystemException. Unless you have a truly ancient C++ compiler, a single catch of CORBA::SystemException will catch all the different system exceptions.

2.9.4 Lifetime of a CORBA object

CORBA objects are either transient or persistent. The majority are transient, meaning that the lifetime of the CORBA object (as contacted through an object reference) is the same as the lifetime of its servant object. Persistent objects can live beyond the destruction of their servant object, the POA they were created in, and even their process. Persistent objects are, of course, only contactable when their associated server processes are running, and their servants are active or can be activated by their POA with a servant manager⁷. A reference to a persistent object can be published, and will remain valid even if the server process is restarted.

To support persistent objects, the servants must be activated in their POA with the same object identifier each time. Also, the server must be configured with the same endpoint details so it is contactable in the same way as previous invocations. See chapter ?? for details.

A POA’s Lifespan Policy determines whether objects created within it are transient or persistent. The Root POA has the TRANSIENT policy.

An alternative to creating persistent objects is to register object references in a naming service and bind them to fixed path names. Clients can bind to the object implementations at run time by asking the naming service to resolve the path names to the object references. CORBA defines a standard naming service, which is a component of the Common Object Services (COS) [], that can be used for this purpose. The next section describes an example of how to use the COS Naming Service.

2.10 Example 3 — Using the Naming Service

In this example, the object implementation uses the Naming Service [] to pass on the object reference to the client. This method is often more practical than using stringified object references. The full listing of the object implementation (eg3_impl.cc) and the client (eg3_clt.cc) can be found at the end of this chapter.

The names used by the Naming service consist of a sequence of name components. Each name component has an id and a kind field, both of which are strings. All name components except the last one are bound to naming contexts. A naming context is analogous to a directory in a filing system: it can contain names of object references or other naming contexts. The last name component is bound to an object reference.

Sequences of name components can be represented as a flat string, using ‘.’ to separate the id and kind fields, and ‘/’ to separate name components from each other⁸. In our example, the Echo object reference is bound to the stringified name ‘test.my_context/Echo.Object’.

The kind field is intended to describe the name in a syntax-independent way. The naming service does not interpret, assign, or manage these values. However, both the name and the kind attribute must match for a name lookup to succeed. In this example, the kind values for test and Echo are chosen to be ‘my_context’ and ‘Object’ respectively. This is an arbitrary choice as there is no standardised set of kind values.

2.10.1 Obtaining the Root Context Object Reference

The initial contact with the Naming Service can be established via the root context. The object reference to the root context is provided by the ORB and can be obtained by calling resolve_initial_references(). The following code fragment shows how it is used:

Remember from section ??, omniORB constructs its internal list of initial references at initialisation time using the information provided in the configuration file omniORB.cfg, or given on the command line. If this file is not present, the internal list will be empty and resolve_initial_references() will raise a CORBA::ORB::InvalidName exception.

2.10.2 The Naming Service Interface

It is beyond the scope of this chapter to describe in detail the Naming Service interface. You should consult the CORBA services specification [] (chapter 3). The code listed in eg3_impl.cc and eg3_clt.cc are good examples of how the service can be used.

2.11 Example 4 — Using tie implementation templates

omniORB supports tie implementation templates as an alternative way of providing servant classes. If you use the -Wbtp option to omniidl, it generates an extra template class for each interface. This template class can be used to tie a C++ class to the skeleton class of the interface.

The source code in eg3_tieimpl.cc at the end of this chapter illustrates how the template class can be used. The code is almost identical to eg3_impl.cc with only a few changes.

Firstly, the servant class Echo_i does not inherit from any skeleton classes. This is the main benefit of using the template class because there are applications in which it is difficult to require every servant class to derive from CORBA classes.

Secondly, the instantiation of a CORBA object now involves creating an instance of the implementation class and an instance of the template. Here is the relevant code fragment:

For interface Echo, the name of its tie implementation template is POA_Echo_tie. The template parameter is the servant class that contains an implementation of each of the operations defined in the interface. As used above, the tie template takes ownership of the Echo_i instance, and deletes it when the tie object goes out of scope. The tie constructor has an optional boolean argument (defaulted to true) which indicates whether or not it should delete the servant object. For full details of using tie templates, see the CORBA C++ mapping specification.

2.12 Source Listings

2.12.1 eg1.cc

2.12.2 eg2_impl.cc

2.12.3 eg2_clt.cc

2.12.4 eg3_impl.cc

2.12.5 eg3_clt.cc