Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboTransient

## Name

BonoboTransient -- Creates a server that will handle transient objects.

## Synopsis

    typedef     BonoboTransient;
    typedef     BonoboTransientClass;
    PortableServer_Servant (*BonoboTransientServantNew)
                                                (PortableServer_POA,
                                                 BonoboTransient*,
                                                 char *name,
                                                 void *data);
    void        (*BonoboTransientServantDestroy)
                                                (PortableServer_Servant servant,
                                                 void *data);
    BonoboTransient* bonobo_transient_new       (PortableServer_POA poa,
                                                 BonoboTransientServantNew new_servant,
                                                 BonoboTransientServantDestroy destroy_servant,
                                                 void *data);
    BonoboTransient* bonobo_transient_construct (BonoboTransient *transient,
                                                 PortableServer_POA poa,
                                                 BonoboTransientServantNew new_servant,
                                                 BonoboTransientServantDestroy destroy_servant,
                                                 gpointer data);
    CORBA_Object bonobo_transient_create_objref (BonoboTransient *transient,
                                                 const char *iface_name,
                                                 const char *name,
                                                 CORBA_Environment *ev);

## Object Hierarchy

      GtkObject
       +----BonoboTransient

## Description

The `BonoboTransient` is used to create transient objects. These objects only exist during the lifetime of the method execution of the interface they implement: they are created on demand and destroyed after the method invocation finishes.

Transient objects are an optimization useful when it is possible for a very large set of object to exist but there is no need to have implementations of the servers running all the time, as they can be created on the demand to satisfy the requests of client applications.

For example, consider the case in which a large list of objects needs to be returned to a client application. For example, an object reference could be returned for every file on a directory. But it would be wasteful to keep one server running for each file. And given that the program has all the information available to create the servers on demand, you want to use this system.

This can be used for implementations of the IDL:Bonobo/PropertyBag interface, as there are in theories thousands of keys that could be returned, but the method invocations on each object is short-lived, so it is efficient to just create servers to satisfy an object request on demand, and destroy them when the request is done.

To create such object, you first need to create a `BonoboTransient` object, and then for every virtual object that you want to expose to the world, you invoke the bonobo_transient_create_objref() function to create a new CORBA object reference.

bonobo_transient_new() will create a new POA inside the POA you specify (you can use CORBA_OBJECT_NIL to get the POA to be created in the default Bonobo POA). All object references created with bonobo_transient_create_objref() will live in this new POA.

The bonobo_transient_new() function takes an argument that specifies the function that will be used to create the temporary CORBA servant that will satisfy an incoming request. And a function that will be used to destroy the servant when the request processing is done.

The bonobo_transient_create_objref() function takes a number of arguments:

- The name of the object you want to create. This name will be passed to the servant creation routine when an incoming request for that object comes in. Your servant creation routine should be able to create a servant from the data you expose as the name (it can be a stringified representation of an in-process pointer for all that we care).

- The interface name implemented by the object named before. This is the CORBA interface name that your object implements, for example "IDL:Echo/echo:1.0".

Here is an example of how to use BonoboTransient:

Example 1. Using BonoboTransient

    BonoboTransient *my_transient = NULL;

    static PortableServer_Servant
    create_servant (PortableServer_POA  poa,
                    BonoboTransient    *bt,
                    char               *name,
                    void               *my_callback_data)
    {
            MyServant *servant;

    	if (!my_validate_name (name))
            	return NULL;

            servant = g_new0 (MyServant, 1);
            servant->vepv = my_servant_get_epv();
            servant->my_data = g_strdup ("Hello world!");
            POA_My_Iface__init ((PortableServer_Servant) servant, &ev);
            return servant;
    }

    void
    destroy_servant (PortableServer_Servant servant, void *my_callback_data)
    {
            CORBA_Environment ev;

            g_free (servant->my_data);
            CORBA_exception_init (&ev);
            POA_My_Iface__fini (servant, &ev);
            CORBA_exception_free (&ev);
    }

    CORBA_Object
    impl_Some_Iface (PortableServer_Servant servant, CORBA_Environment *ev)
    {
    	return bonobo_transient_create_objref (
            	my_transient, "IDL:My/Iface:1.0",
                    "hello",
                    ev);
    }

    void
    init_transient()
    {
    	my_transient = bonobo_transient_new (
    		CORBA_OBJECT_NIL,
                    create_servant,
                    destroy_servant,
                    NULL);
    }

The previous example shows: how the `my_transient` object is first created, and what the implementations for the create_servant and destroy_servant look like. It does not make use of the user pointer, so it passes NULL. However, in practice, applications will most likely want to pass data here to the new_servant and destroy_servant methods.

The impl_Some_Iface is a method that we assume in the example will be part of the implementation of a CORBA server. This method will be invoked at some time to get an object reference to one of the transient objects (in this case, we have called our object "hello" and it implements the interface IDL:My/Iface:1.0).

## Details

### BonoboTransient

    typedef struct {
    	GtkObject parent;

    	BonoboTransientPriv *priv;
    } BonoboTransient;

### BonoboTransientClass

    typedef struct {
    	GtkObjectClass parent_class;
    } BonoboTransientClass;

### BonoboTransientServantNew ()

    PortableServer_Servant (*BonoboTransientServantNew)
                                                (PortableServer_POA,
                                                 BonoboTransient*,
                                                 char *name,
                                                 void *data);

`Param1` : |
`Param2` : |
`name` : |
`data` : |
Returns : |

### BonoboTransientServantDestroy ()

    void        (*BonoboTransientServantDestroy)
                                                (PortableServer_Servant servant,
                                                 void *data);

`servant` : |
`data` : |

### bonobo_transient_new ()

    BonoboTransient* bonobo_transient_new       (PortableServer_POA poa,
                                                 BonoboTransientServantNew new_servant,
                                                 BonoboTransientServantDestroy destroy_servant,
                                                 void *data);

bonobo_transient_new() creates a new CORBA server that creates a new POA entry (within the `parent_poa` POA). You can construct arbitrary object names inside this space using bonobo_transient_create_objref() and return those to client code.

The `new_servant` function will be invoked by the POA to resolve object reference to names you have created using bonobo_transient_create_objref(). The `new_servant` function should return a PortableServer_Servant that will handle the request.

Once the processing is completed, the `destroy_servant` will be invoked to release any resources allocated during the invocation of `new_servant` or during the execution of the servant that need to be released.

`poa` : |
`new_servant` : | A function pointer used to incarnate servants on demand.
`destroy_servant` : | A function pointer used to destroy the on-demand server.
`data` : | data passed to the `new_servant` and `destroy_servant` functions.
Returns : | a new BonoboTransient object.

### bonobo_transient_construct ()

    BonoboTransient* bonobo_transient_construct (BonoboTransient *transient,
                                                 PortableServer_POA poa,
                                                 BonoboTransientServantNew new_servant,
                                                 BonoboTransientServantDestroy destroy_servant,
                                                 gpointer data);

This function is only for wrappers and object derivation. For normal use, please see bonobo_transient_new.

This function will return `NULL` on failure; however it is your responsibility to destroy the failed object in that case.

`transient` : | the BonoboTransient to construct
`poa` : |
`new_servant` : | A function pointer used to incarnate servants on demand.
`destroy_servant` : | A function pointer used to destroy the on-demand server.
`data` : | data passed to the `new_servant` and `destroy_servant` functions.
Returns : | a BonoboTransient object (the `transient`)

### bonobo_transient_create_objref ()

    CORBA_Object bonobo_transient_create_objref (BonoboTransient *transient,
                                                 const char *iface_name,
                                                 const char *name,
                                                 CORBA_Environment *ev);

`transient` : | The BonoboTransient manager where the object reference is rooted.
`iface_name` : | The CORBA interface name that the returned object is supposed to implement.
`name` : | The name of the object inside the `transient` POA's name space.
`ev` : | returns possible errors from the PortableServer_POA_create_reference_with_id() call.
Returns : | a CORBA_Object reference for an object named `name` inside the `transient`'s POA naming space that implements the `iface_name` interface The return value can be CORBA_OBJECT_NIL to indicate an error in the incoming arguments.

## See Also

`BonoboPropertyBag`

<<< Previous Page | Home | Up | Next Page >>>
bonobo-property-bag-xml | Notification and EventSources