omniIFR: readme

omniIRF2: Interface Repository for omniORB.

omniIFR2 is an implementation of the Interface Repository, for omniORB, a
free CORBA ORB for C++ and Python. For full details, see Chapter 10 "The
Interface Repository" in the CORBA specification v2.6:

omniIFR2 closely follows the specification, rather than just implementing the
IDL. It checks the types that are loaded into it, and helps to detect problems
and inconsistencies at an early stage.


1.  Building omniIFR
2.  Configuration: omniORB.cfg
3.  Using omniIFR
3.1 Running the Server
3.2 `ifr' - The omniidl Backend
3.3 `ifrclt' - The Command-line client.
3.4 Using omniIFR from C++ & Python
4.  What's Missing?
5.  Contact

1. Building omniIFR

You need omniORB in order to build omniIFR. You will also need omniORBpy in
order to use omniidl to populate the repository. Get them from Sourceforge:

** Note: You may need to patch omniORB and omniORBpy. Check in the `patches'
** directory. omniORB-4.0.3 and omniORBpy-2.3 both have know problems that
** affect the InterfaceRepository.

To build omniIFR on Unix - Follow these steps:

1. Run the `configure' script. For a full list of available parameters,
   type `./configure --help'. Common parameters are:

    --prefix=PREFIX         install files in PREFIX [/usr/local].
    --with-omniorb=PATH     set the path to the local omniORB installation
    -q, --quiet, --silent   do not print `checking...' messages.
   Check the result of the configure script, and if everything looks OK, then
   proceed on to the next step.

2. Type `make'.

3. Become root and type `make install'.


% cd omniifr
% ./configure
% make
% su root
% make install

The following files are installed:

 o PREFIX/sbin/omniIFR
     The omniIFR server.
 o PREFIX/lib/pythonX.Y/site-packages/omniidl_be/
 o PREFIX/lib/pythonX.Y/site-packages/omniidl_be/ifr.pyc
     A new backend for `omniidl' that populates the repository.

2. Configuration: omniORB.cfg

You must choose a port for omniIFR. This example assumes that you have choosen
port 11173. Once you have chosen a port, add the following entry into your
omniORB.cfg file:

InitRef = InterfaceRepository=corbaloc::hostname:11173/DefaultRepository

This line enables omniORB to find the Interface Repository by using the
`resolve_initial_reference()' method. Replace `hostname' with your machine's

3. Using omniIFR

3.1 Running the Server

The binary is in PREFIX/sbin (if you used the configure --prefix parameter), or
in /usr/local/sbin (by default). omniIFR takes no parameters of its own, but
you must specify the end point to match the port that you chose for your
omniORB.cfg file:

% omniIFR -ORBendPoint giop:tcp::11173 &

The Repository always starts empty, with no type data loaded into it. In order
to populate it with types you need to use the omniidl compiler with the new
`ifr' backend.

3.2 `ifr' - The omniidl Backend

You will be familiar with `omniidl' as the IDL compiler used to generate C++ or
Python stubs. The -b option is used to select the `backend' which generates
stubs for the target language. So, `omniidl -bcxx foo.idl' generates C++ stubs,
and `omniidl -bpython' generates python stubs.

`ifr' is a backend that does not generate language stubs. Instead it inserts the
contents of an IDL file into the Interface Repository. Here's an example:

% omniidl -bifr foo.idl

The `ifr' requires omniORBpy, in addition to omniORB.

** BUG: If your IDL includes python keywords used as IDL identifiers, then
** omniORBpy version 2.3 (and earlier) will crash. This is a bug in omniORBpy.
** The patch in `patch/omniORBpy-2.3-keywords.patch' fixes this problem.

3.3 `ifrclt' - The Command-line client.

syntax: browser/ [OPTIONS] [COMMAND] [ARGS]

  A very simple interface repository browser. Modelled on
  shell directory listing commands: cd, ls, pwd.

   -l       --long            ls: detailed output.
   -rLEVELS --recurse=LEVELS  ls: Drill down LEVELS.               [default: 0]
                              Set to -1 to recurse witout limit.
   pwd              Show the current scope
   cd SCOPED_NAME   Change the current scope, relative to the current scope.
   cd ..            Change the current scope, up one level.
   cd               Change to the root scope (the Interface Repository itself).
   ls               List the contents of the current scope.
   ls SCOPED_NAME   List the contents of the named definition.

  The current scope is stored in the file pointed to by environment
  variable IFRBROWSERSTATE [default: $HOME/.ifrbrowserstate].


% omniidl -bifr /usr/local/share/idl/omniORB/COS/CosEventComm.idl

% browser/ cd ::CosEventComm 
% browser/ pwd               
% browser/ ls                
   exception Disconnected { ... };
   interface PushConsumer ... ;
   interface PushSupplier ... ;
   interface PullSupplier ... ;
   interface PullConsumer ... ;
% browser/ -l ls PushConsumer
 interface PushConsumer {
   void push(in any data)
   void disconnect_push_consumer();

3.4 Using omniIFR from C++ & Python

An excellent introduction to the Interface Repository is available on the web
from "C/C++ Users' Journal":

That series of articles also contains useful information on DII, DSI & dynamic
CORBA in general. I've also found the dynamic CORBA sections of the omniORB3
manual very useful. I'm not sure why they haven't found their way into the
omniORB4 manual...

Of course the OMG's CORBA specification is the ultimate reference:

** BUG: The implementation of CORBA::Object::_get_interface() in omniORB 4.0.3
** and earlier DOES NOT WORK. It always returns a nil reference, even when it
** has successfully obtained a definition from the Interface Repository.
** The patch in `patch/omniORB-4.0.3-get_interface.patch' fixes this problem.

4. What's Missing?

The following interfaces are not yet implemented:


In order to be useful in a production environment, the repository really needs
to be able to persist its state to file. Currently this feature isn't
implemented, so you have to re-populate the repository each time the server is

The repository versions scheme is not implemented. Different versions of the
same type are rejected as if the version numbers did not differ. (This is
permitted by the specification, but it would be a useful feature.)

For a full list of issues, see the files BUGS and repository/TODO.

5. Contact

This is an alpha release. It's not yet properly tested. Important features are
missing. Don't rely on it, but do try it. If you find any bugs, or you have any
comments then please let me know:

-Alex Tingle (email: alex.omniifr AT