
From the perspective of client applications, there is an object which
contains methods for searching for sets of objects, and for creating new
objects. Each object has a number of methods used for accessing data within
that object, and these objects are always available. A developer may be
aware that there is a relational database somewhere behind the GEAS server,
but has no way to determine where the database is, what database is in use,
or how data is arranged in this database. (In practical terms, a class
author should specify various indexes, which will be used to improve speed.)


Object references
-----------------

An object reference is a form of pointer. In a C/C++ program, on a 32 bit
machine, a pointer is a 32bit value containing the address of the item being
pointed to. In CORBA, an object reference is an area of memory of an
arbitrary size, containing information that allows the ORB to locate the
object being 'pointed' to. While it is possible to interpret this data,
generally speaking, clients should not do so, as no useful information is
stored there. (Or, more strictly speaking, the information is only intended
to be used by the server - it may be changed, so a client can mot rely on it
having a consistent format.)


How GEAS uses object references
-------------------------------

Each object reference needs to include a 'key' that identifies the object it
is a reference to. GEAS inserts an appropriate identifier into an object
reference that identifies what business object it is associated with. Thus
when a request arrives, this key can be used to find the appropriate data.


Forging object references
-------------------------

Object references can easily be forged - there is no way to prevent a client
from writing any arbitrary data into a reference, and thus causing a request
that should not be allowed. (For example: to access another person's user
information, rather than request it from the server, simply manufacture an
appropriate reference in local RAM, and use that.)

This is not a significant security problem, and there are at least two
possible options to ensure invalid references are never created:

1) Encrypt the object key before creating an object reference. As the ORB
   only treats this as raw data, a reference to an object can only be
   created by the server, with the appropriate secret key.

2) Use the CORBA security service to validate all actions, and encrypt data
   during transmission. This allows a given user to only perform valid
   and auditable actions, no matter how they manipulate object references.

(Note: security is not yet implemented in any useful way. But it should be.)


Using Objects
-------------

All objects that a client will use during a typical session (with the
exception of the ConnectionFactory instance) use the "on demand for the
duration of a single method" activation policy. What this means is that the
server maintains no data about an object until it is actually needed. At
this point, the server looks at the object reference that was used to
identify which object should be used for servicing the request. This means
that the server only requires sufficient resources to handle currently
active operations. For performance reasons, the server may, of course,
maintain a cache, to avoid excessive database or disk accesses on data.


Example Session
---------------

1) Login

   The appropriate method is executed on the single 'ConnectionFactory'
   instance that the server published. A new 'Connection' object reference
   is created, and returned to the client.


2) Request list of all "person" instances where "name = bob"

   Using the Connection instance, the client requests a list of objects. The
   object references allows the server to identify which user is making the
   request (in future, this will be handled by the CORBA security service).

   The server performs the query on the database, finding a list of matching
   objects. It creates a "geas::listholder" object to store the list in,
   with a "geas::listitem" object for each element in the list.

   The geas::listholder object has a unique ID (just like any object) and
   an ObjectList reference is created, with the appropriate unique id
   being used as the object key.


3) Get length of list

   The object reference is decoded and the appropriate unique ID is
   extracted from the object key. This is used to locate the appropriate
   geas::listholder object, and the length of the list can then be easily
   returned to the client.


4) Get the objects in the list as an array. (using the 'objects' attribute
   of the ObjectList class.

   The client calls the __get_objects() method in the ObjectList class, which
   once again extracts the appropriate unique id from the object key.

   Geas allocates memory for an appropriate sequence (CORBA array) of
   DataObject references. It then retrieves the geas::listholder and all
   geas::listitem objects, and uses these to build a series of object
   references to DataObject instances. For these instances, it stores the
   classname (as defined in a GCD file) and the object id for the appropriate
   business object. This array is returned to the client.

5) Getting the contents of a business object

   Once the client has this array, it can use the getField() method from the
   DataObject class an any item in the array.

   Each time the getField() method is called, it extracts the classname and
   object id from the object key. This is used to retrieve the object
   (either from the cache or from the database) and produces an appropriate
   return value.


6) Accessing an already deleted object

   (Ideally transactions should prevent this, but they are not yet
   implemented, and may not be appropriate in all situations.)

   If another user deletes an object, a previously valid object will become
   unavailable, without the client being notified. (Additional code could,
   of course, be written to provide such notification.)

   When the request arrives at the GEAS server, a servant manager will
   attempt to locate a suitable object, and set up the appropriate data
   structures. The ORB will then apply the method to this object.

   If the object can not be located in the cache, or in the database, then
   it will report to the ORB that thereis no available object, and a CORBA
   exception will be generated, to report to the client that the object did
   not exist.


GEAS internal classes
---------------------

The various classes in the 'geas' module (ie geas::user, geas::listholder,
etc) are all intended to store server private information. The reason for
treating these as normal business objercts is that it allows them to use the
same caching systems as other objects, and in the future will allow
connections to easily be transferred between GEAS servers.

While currently they can be accessed from any client, in theory, future
security code should deny access to these by programs outside the server.

The geas::user class may be exposed to administrators, but this will still
be GEAS specific information, not directly used by typical applications.
This will, however, mean that the same Forms code used for applications will
be able to be used for user administration tools as well.

