In this chapter, we go through three examples to illustrate the practical steps to use omniORBpy. 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.
We use an example which is similar to the one used in the omniORB manual. We define an interface, called Example::Echo, as follows:
The important difference from the omniORB Echo example is that our Echo interface is declared within an IDL module named Example. The reason for this will become clear in a moment.
If you are new to IDL, you can learn about its syntax in Chapter 3 of the CORBA specification 2.6 [OMG01a]. For the moment, you only need to know that the interface consists of a single operation, echoString(), which takes a string as an argument and returns a copy of the same string.
The interface is written in a file, called example_echo.idl. It is part of the CORBA standard that all IDL files should have the extension ‘.idl’, although omniORB does not enforce this.
From the IDL file, we use the IDL compiler, omniidl, to produce the Python stubs for that IDL. The stubs contain Python declarations for all the interfaces and types declared in the IDL, as required by the Python mapping. It is possible to generate stubs dynamically at run-time, as described in section 4.9, but it is more efficient to generate them statically.
To generate the stubs, we use a command line like
omniidl -bpython example_echo.idl
As required by the standard, that produces two Python packages derived from the module name Example. Directory Example contains the client-side definitions (and also the type declarations if there were any); directory Example__POA contains the server-side skeletons. This explains the difficulty with declarations at IDL global scope; section 2.7 explains how to access global declarations.
If you look at the Python code in the two packages, you will see that they are almost empty. They simply import the example_echo_idl.py file, which is where both the client and server side declarations actually live. This arrangement is so that omniidl can easily extend the packages if other IDL files add declarations to the same IDL modules.
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. You will get a run-time error if you use a servant where an object reference is expected, or vice-versa.
In the first example, both the client and servant are in the same address space. The next sections show how the client and servant can be split between different address spaces.
First, the code:
The example illustrates several important interactions among the ORB, the POA, the servant, and the client. Here are the details:
Explicitly specifying omniORB is useful if you have more than one Python ORB installed.
There is little constraint on how you design your implementation class, except that it has to inherit from the skeleton class and must implement all of the operations declared in the IDL. Note that since Python is a dynamic language, errors due to missing operations and operations with incorrect type signatures are only reported when someone tries to call those operations.
ORB_init() processes any command-line arguments which begin with the string ‘-ORB’, and removes them from the argument list. See section 4.1.1 for details. If any arguments are invalid, or other initialisation errors occur (such as errors in the configuration file), the CORBA.INITIALIZE exception is raised.
A POA’s behaviour is governed by its policies. The Root POA has suitable policies for many simple servers. Chapter 11 of the CORBA 2.6 specification [OMG01a] has details of all the POA policies which are available.
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 IIOP calls.
CORBA IDL is statically typed, and so in statically typed programming languages like C++, the compiler reports errors for code where the types of operation parameters and return values do not match what is defined in the IDL. Since Python is dynamically typed, it is not until run time that parameter and return types can be checked against the IDL definitions.
When operations are called, omniORBpy checks the types of parameters and return values against the IDL. If the types do not match, it raises a CORBA.BAD_PARAM exception, with the minor code omniORB.BAD_PARAM_WrongPythonType. With complex parameter types, it can be hard to work out exactly what part of a type was incorrect so in omniORBpy, the exception contains a list of information about where exactly a type check failed. The information is stored as a list of strings in the _info attribute of the exception object, and output as part of the string form of the exception:
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.
Up until line 18, this example is identical to the colocated case. On line 18, the ORB’s object_to_string() operation is called. This results in a string starting with the signature ‘IOR:’ and followed by some hexadecimal digits. All CORBA 2 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 space1. From the IOR, an object reference can be constructed.
After the POA has been activated, orb.run() is called. Since omniORB is fully multi-threaded, it is not actually necessary to call orb.run() for operation dispatch to happen—if the main program had some other work to do, it could do so, and remote invocations would be dispatched in separate threads. However, in the absence of anything else to do, orb.run() is called so the thread blocks rather than exiting immediately when the end-of-file is reached. orb.run() stays blocked until the ORB is shut down.
The stringified object reference is passed to the client as a command-line argument2. The client uses the ORB’s string_to_object() function to convert the string into a generic object reference (CORBA.Object).
On line 12, the object’s _narrow() function is called to convert the CORBA.Object reference into an Example.Echo reference. If the IOR was not actually of type Example.Echo, or something derived from it, _narrow() returns None.
In fact, since Python is a dynamically-typed language, string_to_object() is often able to return an object reference of a more derived type than CORBA.Object. See section 3.1 for details.
The keep it short, the client code shown above performs no exception handling. A robust client (and server) should do, since there are a number of system exceptions which can arise.
As already mentioned, ORB_init() can raise the CORBA.INITIALIZE exception if the command line arguments or configuration file are invalid. string_to_object() can raise two exceptions: if the string is not an IOR (or a valid URI), it raises CORBA.BAD_PARAM; if the string looks like an IOR, but contains invalid data, is raises CORBA.MARSHAL.
The call to echoString() can result in any of the CORBA system exceptions, since any exceptions not caught on the server side are propagated back to the client. Even if the implementation of echoString() does not raise any system exceptions itself, failures in invoking the operation can cause a number of exceptions. First, if the server process cannot be contacted, a CORBA.TRANSIENT exception is raised. Second, if the server process can be contacted, but the object in question does not exist there, a CORBA.OBJECT_NOT_EXIST exception is raised.
As explained later in section 3.1, the call to _narrow() may also involve a call to the object to confirm its type. This means that _narrow() can also raise CORBA.TRANSIENT, CORBA.OBJECT_NOT_EXIST, and CORBA.COMM_FAILURE.
Section 4.7 describes how exception handlers can be installed for all the various system exceptions, to avoid surrounding all code with try…except blocks.
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 manager3. 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 7 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) [OMG98], that can be used for this purpose. The next section describes an example of how to use the COS Naming Service.
In this example, the object implementation uses the Naming Service [OMG98] to pass on the object reference to the client. This method is often more practical than using stringified object references.
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 other4. In our example, the Echo object reference is bound to the stringified name ‘test.my_context/ExampleEcho.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 ExampleEcho are chosen to be ‘my_context’ and ‘Object’ respectively. This is an arbitrary choice as there is no standardised set of kind values.
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, 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.
Note that, like string_to_object(), resolve_initial_references() returns base CORBA.Object, so we should narrow it to the interface we want. In this case, we want CosNaming.NamingContext5.
It is beyond the scope of this chapter to describe in detail the Naming Service interface. You should consult the CORBA services specification [OMG98] (chapter 3).
Hopefully, the server code is self-explanatory:
Hopefully the client code is self-explanatory too:
As we have seen, the Python mapping maps IDL modules to Python packages with the same name. This poses a problem for IDL declarations at global scope. Global declarations are generally a bad idea since they make name clashes more likely, but they must be supported.
Since Python does not have a concept of a global scope (only a per-module global scope, which is dangerous to modify), global declarations are mapped to a specially named Python package. By default, this package is named _GlobalIDL, with skeletons in _GlobalIDL__POA. The package name may be changed with omniidl’s -Wbglobal option, described in section 5.2. The omniORB C++ Echo example, with IDL:
can therefore be supported with code like