
CORBA in GEAS
=============

	* Introduction
	* Notes
	* Handling of object references
	* Servant locators and object references
	* POA objects and Servant Managers
	* Functions


Introduction:
-------------

This document describes the CORBA code in GEAS, with reference to the C
binding and ORBit server used. Some CORBA knowledge will be useful, as
this is not a CORBA or ORBit introduction. Hopefully it will still be
reasonably readable for other developers.

Notes:
------

The handling of the 'user' field in object references (see below) is
subject to discussion. However, compatability between different versions of
GEAS is not an issue until a large number of servers are in use, and
multiple servers are working in a single system. Normally object references
are not passed to other servers. The exception is in a load balanaced
system, which GEAS will not support for some time. Additionally, any object
references generated by the current system would not be automatically
transferred to another server - therefore the change should cause no problems.

The 'ConnectionFactory' class may be phased out at a later stage, as the
CORBA security service offers features that will make the current login
system unnecessary. Should this happen, the 'ConnectionFactory' class will
become a subclass of the 'Connection' class. The guestLogin() method that
currently returns a reference to a Connection object will instead return a
reference to that object. (A client that has not obtained a credentials
object will automatically be assigned an appropriate one - effectively, a
default security access ID that is ideal for implementing 'guest' access.

As a result, no change will be necessary for any application - no client
is supposed to interpret or modify object references directly. the
guestLogin() function would effectively be transformed into a null
operation. Future applications, with knowledge of CORBA security, would
still need to call an appropriate method to obtain a Connection object,
if using a non secure server. This may require a decision about appropriate
upgrade options, as this will affect clients using a combination of secure
and non-secure servers. Also, the secure system is not required to operate
this way: a getConnection() or guestLogin() method may be required, even
with CORBA security implemented.

This is, however, a security issue: It is possible for a client to modify an
object reference, and thus pretend to be from a different user - the
username associated with a request can not be considered suitable for an
audit trail. (Of course, a high degree of technical knowledge is required to
actually do this, so in many cases, it will be acceptable.)


Handling of object references:
------------------------------
There are two 'types' of object reference currentl in use: the CORBA
defined object reference, used for making calls to an object's
methods, and a GEAS specific ID, used for tracking references to
business objects.

The GEAS object reference is little more than a structure of pointers,
where each pointer contains a string with a particular piece of data.
eg: for a business object, the refernce will contain the classname, object
key, and the owner of the reference.

A GEAS object identifier is encoded into a simple asterisk ('*') delimited
string and then used for creating a CORBA object reference. When the server
receives an object reference, it can decode this, and rebuild the original
GEAS object identifier.

Currently object references contain a username associated with the object
(multiple users accessing the same object will have a different username
field) and information that identifies the object in use. As the object id
is an otherwise meaningless set of bytes, and the classname must be known in
order to access the object, there should be no security issue involved with
this data. However, the username field must not be able to be modified by
the client, and in the future will be removed from all object references.
(The CORBA Current interface will be implemented in ORBit in the near
future, at which point the CORBA security service will be able to be used
for associating a user with a request.


Servant locator and object references:
--------------------------------------

GEAS uses a servant locator based system to interpret references to
objects. The objects are stateless, and instead use information in the
CORBA object identifier to locate what GEAS data object is being referred
to.

Using on demand activation for a single method call allows GEAS to only have
a stateful object while it is actually being used. A cache is not strictly
necessary, but is included for performance reasons. The objects being used
regularly would be kept in the cache for quick access, while other objects
can be flushed to the database until they are needed again.

The ORBit IDL compiler creates a set of skeletons for each class, with the
function prototypes placed in geas-skelimpl.c. This function is processed
to remove the functions, but leave the remainder of the ORBit data
structures in place. The actual functions are placed in geas-skeleton.c

The functions in geas-skeleton.c process the CORBA object identifier, and
create a GEAS specific data structure from information that was originally
placed in the object identifier by the server when the reference was
created. (Note: the 'user' field stores the user that requested the
reference. When the security system is implemented, ORBit will provide this
information in a non-forgeable format.) These function in turn call the actual
object implementation functions that perform the desired operation.

CORBA object references are created by a small number of functions, also
in geas-skeleton.h. Each function produces a reference to a particular
class (e.g. GEAS::DataObject) and takes as arguments the specific items to
be stored in the object reference.


POA objects and Servant Managers
--------------------------------

One POA is created for each main CORBA class (DataObject, ObjectList,
Connection and Admin) except for ConnectionFactory. A single
ConnectionFactory instance is explicitly activated when the server
starts up, and all other objects are handled as necessary by the
appropriate servant manager.

A servant manager is created for each class, and each one 'locates' a
single object (pre-allocated when GEAS is started) of the appropriate
type for every request. This object will have no state, but is needed
for processing a CORBA object identifier. One unexpected benefit of this
is that the servant manager is able to verify the availability of a
business object, and return NULL if it does not exist, causing the
appropriate CORBA exception to be thrown immediately.

Once the servant is 'located', ORBit will have a pointer to the function
that implements the requested operation, with the function being one of
those in geas-skeleton.c. (see above for details on these functions.)

This approach may have issues in a multi threaded server, and this will
need to be checked. However, the general process of obtaining the object
identifier associated with the current request, and then calling the
appropriate function will not change. Should this section be changed, the
implemementation functions should never be changed - the GEAS object
reference is allocated dynamically, and the actual implementation functions
do not need to know about CORBA object references.


Functions
---------

main() in geas-server.c calls initialise_object_servants() to prepare the
CORBA system. It is passed the root POA, and is responsible for
initialising all new POAs, the servant manager objects, and any additional
data required (such as the 'fake' objects used for identifier management.)

The main POA manager is activated after this function is called. Currently,
all POAs use the same POA manager.


geas-server.c contains the functions make_*_reference wich create CORBA object
references to the appropriate classes. These references may be used anywhere a
CORBA::Object is acceptable (such as return values from functions that return
an object.)

corba_id_to_geas_reference() and corba_object_to_geas_reference() are intended
to reverse this, extracting the appropriate data from a CORBA identifier or
object reference that was passed to a make_*_reference() function.
corba_object_to_geas_reference() currently appears broken, and should not be
used. (It was intended for use when an object is passed as an argument. The
work around is to use the GEAS::DataObject methods to extract the objects
identifier data.

The get_server_connection_object() function (in geas-server.c) is used when
GEAS functions need to pass a request to the server. eg: List handling
functions need to be able to search for list data objects. When the security
model is implemented, these functions will by default use the calling user's
security rights, and will have to add their own credentials to access server
only classes.

