<!-- ##### SECTION Title ##### -->
BonoboTransient

<!-- ##### SECTION Short_Description ##### -->
Creates a server that will handle transient objects.

<!-- ##### SECTION Long_Description ##### -->
<para>
   The <classname>BonoboTransient</classname> 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. 
</para>

<para>
   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. 
</para>

<para>
   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.
</para>

<para>
   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.
</para>

<para>
   To create such object, you first need to create a
   <classname>BonoboTransient</classname> 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. 
</para>

<para>
   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. 
</para>

<para>
   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. 
</para>

<para>
   The bonobo_transient_create_objref() function takes a number of
   arguments:
</para>

<itemizedlist>
  <listitem>
    <para>
      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).
    </para>
  </listitem>

  <listitem>
    <para>
      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".
    </para>
  </listitem>
</itemizedlist>

<para>
   Here is an example of how to use BonoboTransient:
   <example>
     <title>Using BonoboTransient</title>
     <programlisting>
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, &amp;ev);
        return servant;
}

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

        g_free (servant->my_data);
        CORBA_exception_init (&amp;ev);
        POA_My_Iface__fini (servant, &amp;ev);
        CORBA_exception_free (&amp;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);
}


     </programlisting>
   </example>
</para>
 
<para>
   The previous example shows: how the
   <parameter>my_transient</parameter> 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.  
</para>

<para>
   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).
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
  <classname>BonoboPropertyBag</classname>
</para>

<!-- ##### TYPEDEF BonoboTransient ##### -->
<para>

</para>


<!-- ##### TYPEDEF BonoboTransientClass ##### -->
<para>

</para>


<!-- ##### USER_FUNCTION BonoboTransientServantNew ##### -->
<para>

</para>

@Param1: 
@Param2: 
@name: 
@data: 
@Returns: 


<!-- ##### USER_FUNCTION BonoboTransientServantDestroy ##### -->
<para>

</para>

@servant: 
@data: 


<!-- ##### FUNCTION bonobo_transient_new ##### -->
<para>

</para>

@poa: 
@new_servant: 
@destroy_servant: 
@data: 
@Returns: 


<!-- ##### FUNCTION bonobo_transient_construct ##### -->
<para>

</para>

@transient: 
@poa: 
@new_servant: 
@destroy_servant: 
@data: 
@Returns: 


<!-- ##### FUNCTION bonobo_transient_create_objref ##### -->
<para>
</para>

@transient: 
@iface_name: 
@name: 
@ev: 
@Returns: 


