Bonobo foobarthing

What has become a trivial application bundled with every operating system (*sigh*) is nonetheless a pretty complex piece of software: its main components are reviewed below.

The above figure outlines the layered architecture of both the server and the client. Each layer specifies a necessary part of the langage to be used for communications:

NFS (Network File System) is one of the oldest existing distributed system: its goal is to allow many clients to access a server's filesystem, transparently, as if the files were local files for the clients.

Because Sun's engineers were no more stupid than you, they decided to layer the architecture of their filesystem: the server exports a number of low-level services and the clients use these services to access files. The low-level services available to clients consist of a number of C API functions which can be called remotely (hence the Remote Procedure Call acronym :).

RPC is a framework which can be used to export arbitrary C functions from a server and to call the exported functions from the clients. Now, before we go into the details on how RPC achieves the goals outlined above, I'd like you to think over the actual implementation needs:

To solve all the problems I just briefly described, RPC uses DCE as the binary format to serialize C function calls. This process is more generally known as marshalling: the function call is marshalled on the client and demarshalled on the server. Then, the answer is marshalled on the server and demarshalled on the client.

The marshalling code itself (this code is very tedious to write: it is straightforward given the function prototype) is automatically generated with a special compiler. This compiler processes the C function declarations to be exported and generates the client marshaller/demarshaller and the server demarshaller/marshaller.

Once the special compiler has done its job, the clients just need to link against the functions defined in the stubs generated by the compiler and the server just needs to link against the functions defined in the skeletons. The folowing diagram shows the control flow of such a RPC during execution:

A good way to approach CORBA is to see CORBA as a sort of super RPC. The goal of CORBA is to distribute Objects rather than mere functions. CORBA also aims at complete interoperability between clients and servers at numerous levels:

interface Person {
	  readonly attribute string name;

	  boolean isSingle ();
};
interface FrenchPerson : Person {
	  boolean isEvil ();
};

	  if (Person_isSingle (objectReference, &ev)) {
	          printf ("Mathieu is single!!! Can you believe this ?\n");
	  }

	  if (objectReference.isSingle ()) {
	          System.out.println ("Mathieu is single!!! Can you believe this ?\n");
	  }

Imagine you want to access the Bonobo::eat_banana method of the Bonobo object. First, you need to create the Monkeys.idl file which contains the folowing definitions.

module Monkeys {
interface Bonobo {
	void eat_banana ();
}
}
	

If you were to use ORBit, the Gnome ORB, you would folow the diagram below: use orbit-idl to generate the stub and skeleton code. Then use your C compiler to compile both your own code and the autogenerated one. Last, link them all to get the server and the client executables.

The example above maps to C very easily: the CORBA C mapping says that the client is supposed to call the Monkeys_Bonobo_eat_banana (bonobo_object, exc) function. Your client code would thus simply call this function which would be implemented in the stub and defined in Monkeys.h. Your Server code would implement this function and the skeleton would transmit all incoming calls from the stub to your code.

As we have already discussed it sooner, the IDL is used to describe your objects' interfaces. The IDL is strongly typed so that there is no semantic loss when mapping the IDL to langage dependant structures. The IDL has a number of predefined standard types which are detailed in the CORBA specification. Here folows a list of the simplest/most obvious/most widely used ones.

module calendar {
enum a_month {
     january, february, march, april, may, june,
     july, august, september, october, december
};

enum a_day {
     monday, tuesday, wednesday, thursday,
     friday, saturday, sunday
};

typedef long a_year;
struct a_date {
       a_day    the_day;
       a_month  the_month;
       a_year   the_year;
};
};
	

Now, to define Objects, you could do as follows (a minimalistic example).

module Monkeys {
/* this is a comment like in C */
// this is a comment like in C++ : both are valid
interface Bonobo {};
interface BonoboFemale : Bonobo {};
interface BonoboMale : Bonobo {};
};
	

The above example defines the Monkeys Namespace with 3 objects inside this namespace: the Bonobo, the BonoboMale and the BonoboFemale objects. BonoboMale/Female both inherit the Bonobo interface. Multiple interface inheritance is also possible. The folowing will define some methods to these objects.

module Monkeys {
interface Bonobo {
        // this is the declaration of the eat_banana method
        // which takes as parameters a boolean variable.
        void eat_banana (in boolean eat_yes_or_not);

        // returns whether the Bonobo is still hungry or not.
        boolean is_hungry ();
};
interface BonoboMale : Bonobo {
	// returns whether the almighty Bonobo is making love to
	// one of his female counterpart. If yes, it also returns
	// his partner's name and surname.
        boolean is_making_love_to ( out string who_surname, out string who_name );
}
};
	

As you can see above, methods may have zero (like the is_hungry method) or one or more parameters (like the eat_banana method). Methods have only one return value (it can be void or any other defined type) and have zero or more parameters.

Parameters can be of three kinds: in, out or inout.

You can define objects' attributes together with fixed-size arrays:

module Monkeys {
interface BonoboFemale : Bonobo {
	  attribute boolean has_children;

	  // 1 dimensional fixed-size array 
	  // which contains the children names.
	  // 20 children maximum :)
	  typedef string a_children_array[20];
	  attribute a_children_array the_children_array;

	  // 2 dimensional fixed-size array
	  // which contains the child arrays of our
	  // female's brothers and sisters.
	  typedef a_children_array a_nephew_array[20];
	  attribute a_nephew_array the_nephew_array;
};
};
	

It is also possible to define variable-sized arrays with the sequence keyword.

module Monkeys {

interface BonoboMale : Bonobo {
	  // This defines a one dimensional array
	  // of longs with a maximum size of 20.
	  typedef sequence <long,20> array_1;
	  // an unbounded one dimensional array of strings
	  typedef sequence <string> array_2;

	  // more tricky: a sequence of sequences: used
	  // to simulate multi dimensional variable size arrays
	  typedef sequence <sequence <long,20> > array_3;
};
};
	

Exceptions can be defined in IDL and used by interfaces' methods to return exception status data.

module Monkeys {
interface Bonobo {
	  // exception declaration
	  exception NotHungry {};

	  void eat_banana ()
	       raises NotHungry;

};
}
	  

Many readers not used to do straight C programming now wonder how it is possible to map the concept of interfaces which closely matches that of objects in a langage which lacks such constructs.

BonoboObject *pobject;
pobject->doThisCrazyThingWeTalkedAbout ();
	

BonoboObject *object;
BonoboObjectdoThisCrazyThingWeTalkedAbout (object);
	

module Monkeys {
interface Bonobo {
	  void eat_banana (in boolean eat_yes_or_not );
};
};
	

typedef CORBA_Object Monkeys_Bonobo;
void Monkeys_Bonobo_eat_banana (Monkeys_Bonobo object,
				CORBA_boolean eat_yes_or_not,
			        CORBA_Environment *ev);
	

module Monkeys {
interface Bonobo {
	  attribute boolean hungry;
};
};

// The following is theoretically equivalent to the first 
// definition but is illegal as IDL forbids the use of 
// identifiers preceded by an underscore.
module Monkeys {
interface Bonobo {
	  boolean _get_hungry (void);
	  void _set_hungry ( in boolean b );
};
};
	

typedef enum {
        CORBA_NO_EXCEPTION=0,
        CORBA_USER_EXCEPTION,
        CORBA_SYSTEM_EXCEPTION
} CORBA_exception_type;
struct CORBA_Environment {
        CORBA_exception_type _major;
        CORBA_char *_repo_id;
        void *_params;
        CORBA_any *_any;
};

void CORBA_exception_init(CORBA_Environment *ev);

extern CORBA_char *CORBA_exception_id(CORBA_Environment *e);

extern void *CORBA_exception_value(CORBA_Environment *ev);

extern void CORBA_exception_free(CORBA_Environment *ev);

CORBA_environment ev;
CORBA_boolean isBonoboHungry;
Monkeys_Bonobo bonobo;

CORBA_exception_init ( &ev );

isBonoboHungry = Monkeys_Bonobo__get_hungry (bonobo, &ev);

switch (ev._major){
case CORBA_NO_EXCEPTION:
    printf ( "no exception\n" );
    break;
case CORBA_SYSTEM_EXCEPTION:
    printf ( "system exception. BAD THINGS HAPPENED.\n" );
    exit (1);
    break;
case CORBA_USER_EXCEPTION:
    // This is not possible. No exceptions are defined by users on a attribute.
    exit (1);
    break;
}

The structure called CORBA_Object we used in the C code above is a reference to the CORBA server which is used by the IDL-compiler-generated-code to locate the CORBA server and send it your method invocations.

A very common mistake which all CORBA users have done at least once is to mistaken this Object reference for the real CORBA object. CORBA::Objects are pseudo objects which represent a reference to the actual CORBA server. All CORBA::Object instances have a life constrained on the client side (which is why they are called pseudo-objects): they hold information on how to access a given CORBA server.

module CORBA {

// All the folowing method definitions do not involve the
// object implementations. Only the object references.

interface Object {
	  // returns a new CORBA::Object reference.
	  Object duplicate ();
	  // frees a CORBA::Object reference.
	  Object release ();
	  // two different object references which refer to the same
	  // object should be equivalent but the standard only specifies
	  // that two identical object references are equivalent.
	  boolean is_equivalent (in Object other_object);
	  // an object reference can be tested for the CORBA_OBJECT_NIL
	  // value with this method.
	  boolean is_nil ();
};
}

The above API defined in the CORBA spec is thus a way to access methods defined and implemented on the client-side object reference. I urge all readers to think about the folowing carefuly: if you invoke the duplicate method on a CORBA::Object instance, you will receive a new CORBA::Object instance. This new instance points to the same CORBA server the original one pointed to. It is now possible to destroy the original instance by invoking release. The call to release or duplicate resulted in client-side activity to instantiate or destroy client-side objects.

The reason why I have tried to make the above point clear is because everyone, at least once, thought that calling duplicate would return a new instance of a CORBA::Object pointing to a new instance of a CORBA server. duplicate and release can be used to manage the lifetime of a CORBA Object reference, not the actual CORBA server.

Users who want to be able to destroy on the fly CORBA servers when they are not used anymore should design their own API and implement it.

module Bonobo {
interface Unknown {
	      void ref ();
	      void unRef ();
};
};
	  

Finally, interested readers will be happy to look into ORBit/src/orb/corba_object.h which contains the definition of the real CORBA Object used by ORBit.

Since the beginning of this introduction to CORBA, we have overlooked quite a lot of "details". Basically, we have seen how to call an object's method, how to read and set its attributes. However, all these actions explicitely require you to hold a reference to the CORBA object you want to invoke.

Here comes a classic initialization problem: how do you get its reference? There are (at least) two solutions to this problem. The simplest one from the programmer's point of view is to ask the user to enter the object reference directly. This can be done with IOR strings.

IOR:01f2ffbf1c00000049444c3a4f41462f4f626a6563744469726563746f72793a312e300002000000
caaedfba54000000010100402b0000002f746d702f6f726269742d6d6174686965752f6f72622d313730
353733333932383535343231323431370000000005081800000000000000137a4a747f9b995e01000000
88cd9ccf1a4b7629000000003c00000001010040160000006d6174686965752e72657a656c2e656e7374
2e66720061051800000000000000137a4a747f9b995e0100000088cd9ccf1a4b7629
	

int main (int argc, char **argv)
{
CORBA_Object orb;
CORBA_Environment ev;

orb = CORBA_ORB_init (&argc, argv, "orbit-local-orb", &ev);

};
	  

CORBA has many other nice features which we have not discussed. One of the cutest ones, is the dynamic framework. Until then, you have seen how to build a server and a client using the IDL to generate the Stubs and Skeletons for your application. While this method is useful in itself, it leads to a lot of code duplication. Everytime you link statically against the stubs or the skeletons, you add some code to your application and most of this code is very similar from one Stub to another.

The idea is to be able to automatically generate the GIOP messages during runtime. You could of course have a special IDL compiler which reads the IDL files during startup and which generates the Stub and Skeleton code on the fly and which compiles it... However, this method is a little heavyweight...

Which is why CORBA offers three mechanisms to replace all this.

Before dealing with the implementation of a CORBA client and server, it important to focus on the functionality you want the server to offer. Therefore, a good technique is to start by defining the interface of the server. In more realistic situations, defining interfaces is a process that may take careful consideration and discussion. For the sake of simplicity, our example will be very simple.

The interface for our 'calculator'-server looks like this (calculator.idl):

interface calculator {

  // add two numbers, return the result
  long add ( in long x, in long y );
  
  // calculate the sum of a sequence of numbers
  typedef sequence<long> Numbers;
  long sum ( in Numbers numbers );

  // divide a number 
  exception DivideByZero {};
  double divide ( in long x, in long y ) raises ( DivideByZero );
    
};
	  

To create a CORBA server, we can use ORBit's idl-compiler to generate the necessary plumbing code implementing the proxy code for us. Thus, we can do: $ orbit-idl-2 --skelimpl --nostubs calculator.idl The '--nostubs' tells the idl-compiler not to create any files needed for the client. The '--skelimpl' tells the idl-compiler to create a skeleton implementation as well. If you use this option, all you have to do is fill in the functions.

If we haven't left any error in the .idl-file, the idl-compiler will generate the following files

In calculator-skelimpl.c we can now fill in the necessary code. Most boilerplate code has been written for us by the idl-compiler.

The simplest function long add ( in long x, in long y ) we defined in IDL can be implemented as follows:

static CORBA_long
impl_calculator_add(impl_POA_calculator * servant,
		    CORBA_long x, CORBA_long y, CORBA_Environment * ev)
{	
	return x + y;
}
	  

You may notice that the implementation has four parameters, instead of only two in IDL. As we already discussed it previously, the C mapping added two special parameters: the first parameter denotes the object being called ^[9] while the last parameter denotes the exception data structure. Obviously, 'x' and 'y' parameters correspond to the parameters with the same name in IDL.

We assume you can figure out how the function is actually implemented, so we won't discuss that. Note that we don't do anything with the servant, nor does it set any exception.

static CORBA_long
impl_calculator_sum(impl_POA_calculator * servant,
		    calculator_Numbers * numbers, CORBA_Environment * ev)
{
	CORBA_long retval = 0;
	unsigned int i;

	for ( i = 0; i < numbers->_length; i++ ) 
		retval += numbers->_buffer[i];
	
	return retval;
}

The implementation of the sum is also quite simple. The only novelty compared to impl_calculator_add is the C-mapping of a CORBA sequence. In the mapping, the sequence becomes a structure with the three members:

	  typedef struct {
		CORBA_unsigned_long _maximum;
		CORBA_unsigned_long _length;
		CORBA_long*         _buffer;
	  } calculator_Numbers;
	

The _buffer member is a pointer to a number of CORBA_longs, and the actual number is stored in the _length member. The other parameter, _maximum, denotes the maximum number of elements that the client has allocated memory for (in _buffer). The _maximum is used when you need to deal with inout parameters, where the caller sends you a number a values (in _buffer), and you need to return a different number of values.

The type of the _buffer parameter is a CORBA_long in this case, but corresponds to the kind of sequence you have in the IDL file.

Again, the actual implementation of the function is quite obvious, so we won't discuss it any further.

static CORBA_double
impl_calculator_divide(impl_POA_calculator * servant,
		       CORBA_long x, CORBA_long y, CORBA_Environment * ev)
{
	CORBA_double retval = 0;

	if ( 0 == y ) {
		retval = 0;
		CORBA_exception_set ( ev, CORBA_USER_EXCEPTION, 
	                              ex_calculator_DivideByZero, NULL );
	} else 
		retval = x / y;

	return retval;
}
	

The last function we need to implement is impl_calculator_divide, which of course corresponds to the divide in the IDL description. The interesting thing this function adds to the previous discussion, is exceptions. We already discussed the way the CORBA C-binding deals with exceptions, and here we can see the implementation.

When the caller of impl_calculator_divide tries to do a divide-by-zero, we raise an exception. We can raise an exception by using the CORBA_exception_set function. The first parameter, ev, is the out-parameter that will convey the exception to the client. The second parameter denotes the type of exception, CORBA_SYSTEM_EXCEPTION or CORBA_USER_EXCEPTION. The first mainly deals with problems at the lower levels, in this case a CORBA_USER_EXCEPTION is the right type. Then, the ex_calculator_DivideByZero is the repository id of the exception: because we have declared the exception in the IDL description, we can identify it by it's repository id, In fact, if you look in calculator.h, you will find:

	    #define ex_calculator_DivideByZero "IDL:calculator/DivideByZero:1.0"
	

The last parameter, the NULL, can be used to convey the actual exception to the client, and may contain for example error messages. As our our exception is empty (as shown in IDL), this parameter is NULL.

After we have built a CORBA server, of course we would like to use it. So, let's write a client for this server. We'll use C for the client as well.

When writing a client, the first thing we need to do is compile the IDL description for the client: $ orbit-idl-2 --noskels calculator.idl We use the '--noskels' flag to inhibit the creation of the files needed for implementing the server, mirroring the '--nostubs' flags we used when compiling the IDL file for the server implementation. If we didn't left any errors in the IDL file, the following files are created:

For our server, we create a new file calculator_client.c which will contain our code to access the server. Note that the order in which we disuss this code is not necessarily the order of appearance in the source code.

First we need to initialize the ORB and the environment parameter ev we will use in our CORBA calls to gather exception information from the server.

	CORBA_Environment ev;
	CORBA_ORB orb;

	CORBA_exception_init ( &ev );
	orb = CORBA_ORB_init ( &argc, argv, "orbit-local-orb", &ev );
	if ( ev._major != CORBA_NO_EXCEPTION ) {
		printf ( "initializing ORB failed\n" );
		return 1;
	}
	

The call to CORBA_exception_init will set the members of the ev (which is actually a C-struct) to their default values. The call to CORBA_ORB_init does a lot of things. Depending on the settings in your /etc/orbitrc or ~/.orbitrc, it will connect to the naming service, the interface repository or the implementation repository. Also, it will connect to the Portable Object Adaptor (POA). After calling CORBA_ORB_init, we must check the ev to make sure the call succeeded (if a call succeeds, the ev will be equal to CORBA_NO_EXCEPTION.

Finaly, when we are done with our client, we must free the ev and orb variables:

	  CORBA_Object_release((CORBA_Object)orb, &ev);
	  CORBA_exception_free ( &ev );
	

When we have a valid orb, we can connect to the server object:

	  calculator calculator_client;

	  calculator_client = CORBA_ORB_string_to_object( orb, argv[1], &ev );
	  if ( !calculator_client ) {
		printf( "Cannot bind to %s\n", argv[1] );
		return 1;
	  }
	

Note that the calculator is just a CORBA_Object in disguise.

The call to CORBA_ORB_string_to_object is actually a rather primitive way to get a reference to a remote CORBA server ^[10] . The second argument is a string (a char*) containing an IOR, in which information about the CORBA server is encoded. Using this string, the ORB will bind to the corresponding CORBA server (over boundaries of mountains, oceans, machines and operating systems), and return a reference in calculator_client.

No, let's take a look at some the useful thing we can do with the CORBA server.

	CORBA_long nums[5]         = { 2, 3, 5, 7, 11 };
	calculator_Numbers numbers = { 5L, 5L, (CORBA_long*)nums }; 
 
	printf ( "3 + 4                  = %d\n", calculator_add ( calculator_client, 3, 4, &ev));
	printf ( "sum ( 2, 3, 5, 7, 11 ) = %d\n", calculator_sum ( calculator_client, &numbers, &ev));

	printf ( "3/4                    = %f ", calculator_divide ( calculator_client, 3, 4, &ev));
	if ( ev._major == CORBA_NO_EXCEPTION ) 
		printf ( "(no exception)\n");
	else 
		printf ( "(exception occured)\n");
	
	printf ( "3/0                    = %f ", calculator_divide ( calculator_client, 3, 0, &ev));
	if ( ev._major == CORBA_NO_EXCEPTION ) 
		printf ( "(no exception)\n");
	else 
		printf ( "(exception occured)\n");
	

The client-side mapping is pretty straight-forward. The client-side mapping for sequences is identical to the server side mapping we already discussed.

Needless to say, for production code you should really check the ev for all calls. Compared to normal function calls, there are a lot of things that can go wrong for any CORBA call, even the trivial ones.

Bonobo Activation is a replacement for the limited libgnorba library developed for the GNOME 1.x platform. Gnorba had a number of shortcommings:

The Bonobo Activation architecture is based around the ActivationContext and the ObjectDirectory interfaces. Only one ActivationContext exists for a given user on a given machine. This ActivationContext is responsible for managing all the user's ObjectDirectories. Each ObjectDirectory is supposed to have knowledge about some potential CORBA servers. Each CORBA server is uniquely identified within the ObjectDirectory by an IID (Implementation Identification). The folowing diagram makes these relationships clear.

	OAFIID:program_name:UUID
	

where UUID is a string as generated by the uuidgen utility (more information on this can be found in the Bonobo Activation reference documentation)^[11].

ObjectDirectories can activate a server given an IID.

module Bonobo {
        interface ObjectDirectory : Bonobo :: Unknown {
                Object activate (in ImplementationID iid, in ActivationContext ac, in ActivationFlags flags)
                        context ("username", "hostname", "domain", "display");

                RegistrationResult register_new (in ImplementationID iid, in Object obj);

                void unregister (in ImplementationID iid, in Object obj, in UnregisterType notify);

	};
};
	  

An application which wants to start a server has no knowledge of the ObjectDirectories which reference the actual CORBA servers. The application requests a certain server to the ActivationContext object and the ActivationContext object requests one of its ObjectDirectories for the given server. The ActivationContext object server knows which of its Objectdirectory contains the requested server because it can query all of them through the Bonobo::ObjectDirectory::get_servers method which returns the list of all the CORBA servers a given ObjectDirectroy knows about.

module Bonobo {
        interface ObjectDirectory : Bonobo :: Unknown {
                ServerInfoListCache get_servers (in CacheTime only_if_newer);
                ServerStateCache get_active_servers (in CacheTime only_if_newer);
	};
};
	  

The concept of ObjectDirectory is very important for the distributed case If you want your application to be able to use a server running on a distant machine, you just need to make sure there is an ObjectDirectory running on that distant machine and tell your local ActivationContext about it so that it calls the distant ObjectDirectory's get_servers method.

module Bonobo {
        module Activation {
                exception NotListed {};
                exception AlreadyListed {};
	};

        interface ActivationContext : Bonobo::Unknown {

                readonly attribute ObjectDirectoryList directories;

                void add_directory (in ObjectDirectory dir) 
	             raises (Bonobo::Activation::AlreadyListed);

                void remove_directory (in ObjectDirectory dir) 
	             raises (Bonobo::Activation::NotListed);
	};
};
	

All you need to do to setup your system for the above scenario is to use the Bonobo::ActivationContext::add_directory method. An activation sample case is described below.

The only thing left for you to become a real Bonobo Activation master is to figure out how to query the ActivationContext for real objects and how to activate them.

module Bonobo {
        interface ActivationContext : Bonobo::Unknown {
                ActivationResult activate (in string requirements,
                                           in Bonobo::StringList selection_order,
                                           in ActivationFlags flags)
                        raises (Bonobo::Activation::ParseFailed, 
	                        Bonobo::Activation::IncompleteContext, 
	                        Bonobo::GeneralError)
                        context ("username", "hostname", "domain", "display");

                ServerInfoList query (in string requirements,
                                      in Bonobo::StringList selection_order)
                        raises (Bonobo::Activation::ParseFailed,
	                        Bonobo::Activation::IncompleteContext)
                        context ("username", "hostname", "domain");

                ActivationResult activate_from_id (in ActivationID aid, in ActivationFlags flags)
                        raises (Bonobo::Activation::ParseFailed, 
	                        Bonobo::Activation::IncompleteContext, 
	                        Bonobo::GeneralError)
                        context ("username", "hostname", "domain", "display");
	};
};
	

The above declaration is what was left for you to discover. Three methods are of importance:

       OAFAID:[IID,user,host,domain]
	  

query and activate are very similar: both run a query given the requirements string. query will return the result of the query while activate will actually activate the best-matching server.

The result of this query is a Bonobo::ServerInfoList which is nothing but a sequence (ie: variable-sized array) of Bonobo::ServerInfo structures. Each Bonobo::ServerInfo contains a variable sized array of Bonobo::ActivationProperty structures each of which contains the name and value of one of the corresponding server properties.

module Bonobo {
        struct ActivationProperty {
                string name;
                ActivationPropertyValue v;
        };

        /* Server */
        struct ServerInfo {
                ImplementationID iid;
                
                string server_type;
                string location_info;
                string username, hostname, domain;
		
                sequence<ActivationProperty> props;
        };

        typedef sequence<ServerInfo> ServerInfoList;
};
	  

for (i = 0; i < result->_length; i++) {
	 Bonobo_ServerInfo *server;
	 server = &result->_buffer[i];
}
	  

Running a query on the Activation daemon is possible provided the daemon learns about the servers available on the system. Our implementation of the Activation interfaces (as provided in the Bonobo Activation package) provides a nice way to do so. Each CORBA server is supposed to provide an xml-based configuration file which describes its fields for the Bonobo Activation database. When installing your CORBA server, you are supposed to make sure the activation daemon implementation can read this file by editing the ${prefix}/etc/bonobo-activation/bonobo-activation-config.xml file ^[12] which lists the directories to browse to find the per-server configuration .server files.

Here is an example of this bonobo-activation-config.xml file:

<?xml version="1.0"?>

<oafconfig>

<searchpath>
<item>/opt/gnome/share/oaf</item>
<item>/usr/local/gnome/share/oaf</item>
<item>/usr/local/share/oaf</item>
<item>/opt/gnome/oaf/share/oaf</item>
</searchpath>

<searchpath>
<item>/opt/gnome/oaf/share/oaf</item>
</searchpath>

</oafconfig>

The .server format is extremly simple:

<oaf_server iid="OAFIID:oaf_naming_service:7e2b90ef-eaf0-4239-bb7c-812606fcd80d"
            type="exe" location="oafd">
	<oaf_attribute name="repo_ids" type="stringv">
		<item value="IDL:CosNaming/NamingContext:1.0"/>
	</oaf_attribute>
	<oaf_attribute name="name" type="string" value="Name service"/>
	<oaf_attribute name="description" type="string" value="CORBA CosNaming service."/>
</oaf_server>
	  

Accessing all the CORBA interfaces we described by hand is of course possible (you might want to write some Java CORBA servers or clients... or C++ ??) but since we know the pain CORBA is (yes, you already hate CORBA ;-), the Bonobo Activation authors have written a nice C API which you can use to ease your life.

The client side of the library is extremly simple: there are 4 functions exported:

CORBA_ORB      bonobo_activation_orb_init   (int   *argc, 
                                             char **argv);

Bonobo_ServerInfoList *bonobo_activation_query   (const char *requirements,
                                                  char *const *selection_order,
                                                  CORBA_Environment * ev);

CORBA_Object bonobo_activation_activate          (const char *requirements,
                                                  char *const *selection_order,
                                                  Bonobo_ActivationFlags flags,
                                                  Bonobo_ActivationID * ret_aid,
                                                  CORBA_Environment * ev);

CORBA_Object bonobo_activation_activate_from_id  (const Bonobo_ActivationID aid,
                                                  Bonobo_ActivationFlags flags,
                                                  Bonobo_ActivationID * ret_aid,
                                                  CORBA_Environment * ev);
	  

#include <orbit/orbit.h>
#include <stdio.h>
#include <bonobo-activation/bonobo-activation.h>

int
main (int argc, char *argv[])
{
        CORBA_Object obj_ref;
        CORBA_Environment ev;

        CORBA_exception_init(&ev);
        bonobo_activation_init (argc, argv);

        obj_ref = bonobo_activation_activate ("server_type == 'shlib'", 
	                                      NULL, 0, NULL, &ev);
        if (CORBA_OBJECT_NIL == obj_ref 
            || ev._major != CORBA_NO_EXCEPTION) {
                printf ("Could not bind to server\n" );
                return 1;
        }

        /* from here on, obj_ref holds a valid object reference */
        CORBA_Object_release( obj_ref, &ev);
        CORBA_exception_free ( &ev );

        return 0;
}
	  

static char *nautilus_sort_criteria[] = {
        /* Prefer anything else over the loser view. */
        "iid != 'OAFIID:nautilus_content_loser:95901458-c68b-43aa-aaca-870ced11062d'",
        /* Prefer anything else over the sample view. */
        "iid != 'OAFIID:nautilus_sample_content_view:45c746bc-7d64-4346-90d5-6410463b43ae'",
        /* Sort alphabetically */
        "name",
        NULL
};
	    

obj_ref = bonobo_activation_activate ("server_type == 'shlib'", NULL, 0, NULL, &ev);
	    

      result = bonobo_activation_query (...);

      for (i = 0; i < result->_length; i++) {
             Bonobo_ServerInfo *server;
	     server = &result->_buffer[i];
      }
	    

How to setup Bonobo Activation to use remote objects. We need to look at the code in gnome-libs HEAD which implements something to do this. hints ?

Writing your own CORBA server activated by the activation daemon is not very complex from an API point of view. A simple example of this is available in c-server-activate-exe/calculator-exe-server.c and c-server-activate-shlib/calculator-shlib-server.c. To run and test this example, you should use the small client provided in c-client-activate/calculator-client.c: calculator-client --exe or calculator-client --shlib will start either the executable version of the calculator server or the shared library version. Please, read README for details on using this example.

To implement the CORBA server proper, we reuse the code from c-server/calculator-skelimpl.c which exports only one function: impl_create.

This function is used by both calculator-exe-server.c and calculator-shlib-server.c. The former, when compiled, will generate an executable which can be activated by Bonobo Activation and the latter a library which can be also activated by Bonobo Activation.

Bonobo_RegistrationResult bonobo_activation_active_server_register (const char  *iid,
                                                                 CORBA_Object obj);

void        bonobo_activation_active_server_unregister (const char  *iid, 
                                                        CORBA_Object obj);

	    

#include <stdio.h>
#include <bonobo-activation/bonobo-activation.h>
#include "calculator.h"

extern calculator impl_create (PortableServer_POA poa,  CORBA_Environment * ev);

int
main (int argc, char* argv[])
{
	PortableServer_POA poa;
	calculator objref;

	CORBA_Environment ev;
	CORBA_ORB orb;

	CORBA_exception_init (&ev);
	orb = bonobo_activation_init (argc, argv);

	/* bootstrap the poa */
	poa = (PortableServer_POA) CORBA_ORB_resolve_initial_references ( orb, "RootPOA", &ev );
	PortableServer_POAManager_activate (PortableServer_POA__get_the_POAManager ( poa, &ev ), &ev);
	
	/* create the implementation */
	objref = impl_create (poa, &ev);
	if (objref == CORBA_OBJECT_NIL
	    || ev._major != CORBA_NO_EXCEPTION) {
		printf ( "Cannot get objref\n" );
		return 1;
	}
	
	/* tell bonobo-activation about this new implementation */
	bonobo_activation_active_server_register ("OAFIID:calculator:20000527", objref);

	/* get into glib main loop so that the server can actually receive requests */
	while (1)
		g_main_iteration (TRUE);
	
	/* destroy this implementation. We will never do this in this particuliar 
	   code because the server will never know when to destroy itself but if he 
	   wanted to do it, this is what he should do.

	   bonobo_activation_active_server_unregister ("OAFIID:calculator:20000527", objref);
	   impl_calculator__destroy (poa, obj_ref, &ev);
	*/
	return 0;
}
	    

void  bonobo_activation_plugin_use    (PortableServer_Servant servant, 
                                       gpointer impl_ptr);

void  bonobo_activation_plugin_unuse  (gpointer impl_ptr);
	    

typedef struct {
	const char *iid;

        CORBA_Object (*activate) (PortableServer_POA poa,
                                  const char *iid, 
                                  gpointer impl_ptr,
				  CORBA_Environment *ev);
} BonoboActivationPluginObject;

typedef struct {
	const BonoboActivationPluginObject *plugin_object_list;
	const char *description;
} BonoboActivationPlugin;
	    

static CORBA_Object
calculator_shlib_make_object (PortableServer_POA poa,
		      const char *iid,
		      gpointer impl_ptr,
		      CORBA_Environment *ev)
{
	return CORBA_OBJECT_NIL;
}


/*
  This structure contains the list of plugins 
  bonobo-activation can load from this library.
  Each plugin has an IID and a _factory_ function.
*/
static const BonoboActivationPluginObject calculator_plugin_list[] = {
	{
  		"OAFIID:calculator:20000923",
		calculator_shlib_make_object
	},
  	{
  		NULL
  	}
};


/* exported symbol which bonobo-activation tries to find to 
   bootstrap the library */
const BonoboActivationPlugin Bonobo_Plugin_info = {
	calculator_plugin_list,
	"Calculator example"
};
	    

<oaf_info>
<oaf_server iid="OAFIID:calculator:20000923" type="shlib" location="calculator.so">
    <oaf_attribute name="repo_ids" type="stringv">
        <item value="IDL:calculator:1.0"/>
    </oaf_attribute>
    <oaf_attribute name="name" type="string" value="calculator"/>
    <oaf_attribute name="description" type="string" value="Example of an shlib"/>
</oaf_server>
</oaf_info>
	    

static CORBA_Object
calculator_shlib_make_object (PortableServer_POA poa,
		      const char *iid,
		      gpointer impl_ptr,
		      CORBA_Environment *ev)
{
	CORBA_Object object_ref;

	/* FIXME: is this necessary ? */
	PortableServer_POAManager_activate (PortableServer_POA__get_the_POAManager (poa, ev), ev);

	object_ref = impl_create (poa, ev);
	if (object_ref == CORBA_OBJECT_NIL 
	    || ev->_major != CORBA_NO_EXCEPTION) {
		printf ("Server cannot get objref\n");
		return CORBA_OBJECT_NIL;
	}

	bonobo_activation_plugin_use (poa, impl_ptr);

	return object_ref;
}
	    

All readers are expected to know what reference counting is and how it works. ref, which increases the server's reference count, and unref, which decreases the server's reference count, are used by the client to notify the server when it needs to use it and when it does not need it anymore. Servers are allowed to destroy themselves when their reference count reaches zero. Server's reference count is supposed to be initialized to one.

module Bonobo {
	interface Unknown {
		/**
		 * ref:
		 *
		 * increments the reference count
		 */
		void ref ();

		/**
		 * unref:
		 * 
		 * decrements the reference count
		 */
		void unref ();

		/**
		 * queryInterface:
		 * @repoid: A string identifying an interface.
		 *
		 * Returns: A CORBA object exposing the interface
		 * specified by @repoid, or a nil object if the
		 * interface cannot be queried.
		 */
		Unknown queryInterface (in string repoid);
	};
};	
	  

These two methods allow us to solve a problem we briefly discussed in the previous chapter. Namely, how a server can detect that it is not used anymore by clients and that it can safely decide to stop processing client's requests.

The folowing IDL shows how we modified the calculator example we discussed in the previous chapters to include ref and unref support. This IDL can be found in idl/calculator-unknown.idl.

#include <Bonobo_Unknown.idl>

interface calculator : Bonobo::Unknown {

  // increment version number
  #pragma version calculator 2.0

  // add two numbers, return the result
  long add ( in long x, in long y );
  
  // calculate the sum of a sequence of numbers
  typedef sequence<long> Numbers;
  long sum ( in Numbers numbers );

  // divide a number 
  exception DivideByZero {};
  double divide ( in long x, in long y ) raises ( DivideByZero );
    
};

	  

As previously, we generated the skelimpl.c file with orbit-idl-2 and edited it to add the needed implementations. This time, we modified the impl_calculator__create function so that it returns a servant rather than an object reference:

static impl_POA_calculator *
impl_calculator__create(PortableServer_POA poa, CORBA_Environment * ev)
{
   impl_POA_calculator *newservant;
   PortableServer_ObjectId *objid;

   newservant = g_new0(impl_POA_calculator, 1);
   newservant->servant.vepv = &impl_calculator_vepv;
   newservant->poa = poa;
   POA_calculator__init((PortableServer_Servant) newservant, ev);
   objid = PortableServer_POA_activate_object(poa, newservant, ev);
   CORBA_free(objid);

   return newservant;
}
	  

calculator 
impl_create (PortableServer_POA poa, void (*destroy_callback) (calculator), CORBA_Environment * ev)
{
  calculator retval;
  impl_POA_calculator *servant;

  servant = impl_calculator__create (poa, ev);

  servant->destroy_callback = destroy_callback;
  servant->refcount = 1;

  retval = PortableServer_POA_servant_to_reference(servant->poa, servant, ev);

  return retval;
}
	  

typedef struct
{
   POA_calculator servant;
   PortableServer_POA poa;
   /* folowing lines added */
   int refcount;
   void (*destroy_callback) (calculator object);
}
impl_POA_calculator;
	  

The implementations of impl_calculator_ref and impl_calculator_unref are straightforward:

static void
impl_calculator_ref(impl_POA_calculator * servant, CORBA_Environment * ev)
{
  /* folowing line added */
  servant->refcount++;
}
	  

static void
impl_calculator_unref(impl_POA_calculator * servant, CORBA_Environment * ev)
{
  calculator object;

  /* folowing lines added */
  servant->refcount--;

  if (servant->refcount == 0) {
    object = PortableServer_POA_servant_to_reference(servant->poa, servant, ev);
    (*servant->destroy_callback) (object);
    CORBA_Object_release (object, ev);
    impl_calculator__destroy (servant, ev);
  }

}
	  

static void destroy_callback (calculator object)
{
	bonobo_activation_active_server_unregister (IID, object);
}

The server process itself will be killed by Bonobo Activation later. (XXX: is this true ?)