
CORBA notes:
============
    Except for initialising a connection to the server, a client application
should require any CORBA specific knowledge. The initialisation code will be
essentially the same for all applications, and can easily be pasted into new
code.

    The IDL files that define the various data structures and classes should
be self explanatory, but tips will be given in this documentation for those
not familier with IDL.


General notes:
==============

    A GEAS::ConnectionFactory instance is used for establishing an initial
connection to the server.

   A GEAS::Connection object is the main interface to the object creation
and searching methods. Additional methods provide information about the
available business classes.

   A GEAS::DataObject represents a single business object, and a
GEAS::ObjectList contains an ordered list of business objects.


Exceptions:
===========

In the IDL files, the raises(...) after a method indicates what exceptions may
be raised by the method. Additionally, various CORBA system exceptions may
also be raised by any operation (the most common such exceptions indicate
communication failures, accessing a non-existant/deleted object, or
attempting an operation on the wrong type (eg: a DataObject method applied
to a Connection instance.)

Example:

try:
   ... code that raises an exception ...
except (GEAS.ServerError),ex1:
   ... exception handling code ...
except (other_python_exception,yet_another_exception),ex2:
   ... other exception handling code ...


If an exception is raised, the return value of the function must be ignored.
There is absolutely no guarantee that it is set to a useful value.

Example:

    CORBA_char *str = GEAS_DataObject_getField(obj,"fieldname",ev);
    if( ev->_major != CORBA_NO_EXCEPTION )
    {
        /* an exception occured... */
	/* at this point, 'str' does not point to a valid string, but is
	   not guaranteed to be set to NULL, or any other value. it must not be
	   used or freed (doing so may cause a segfault, or otherwise corrupt
	   memory) */
	printf( "Error: %s\n" , CORBA_exception_id(ev) );
    }
    else
    {
        /* no exception... */
	/* 'str' points to a string, and may be used. it must then be freed
	   with the CORBA_free() function */
	printf( "Result: %s\n" , str );
	CORBA_free( str );
    }

Memory Management:
==================

Only the GEAS::ObjectList class requires any special handling on the part of
client applications. In particular, the GEAS::ObjectList.release() method
must be called when the client has finished using the list.

Note that returned values from methods (ie: references to
Connection/DataObject/ObjectList instances, schema information, field
values, etc) result in memory allocation on the client side, and these must
be freed appropriately. Python deals with this automatically, but C
developers will need to remember to manage asll such memory, in order to
prevent leaks.


