Notes on the singleds scenario

This is a short overview of the com.xaraya.core.jamaica.singleds scenario.

The singleds scenario was created primarily to explore the idea of 
limiting dataobjects to a single datastore. "Datastore" in this context 
means a type of storage such as fixed table, variable table etc. The 
underlying assumption for this idea is a tradeoff, namely that by 
limiting the datastores of an object we achieve a simplification of the 
code for manipulating the object that more than compensates for the loss 
of being able to access more than one datastore. In particular SQL 
queries associated with the dataobject become simpler and more flexible, 
and performance should improve.

In the scenario the focus is almost exclusively on the flat table 
datastore. To handle this a new "relational" datasource object has been 
created (lib/xaraya/datastores/sql/relational.php). The other datastores 
the scenario recognizes at this point, namely variable and "none", are 
largely relegated to exceptionak cases for now (even though they raise 
some interesting possibilities). The remarks that follow refer to the 
flat table datastore.

Each dataobject has at any given time an internal "dataquery" that is 
particular to its definition. The components of the defintion which 
defines the dataquery is created in the dataobject's Edit page, which in 
addition to previously familiar properties contains:

- a configuration property: for adding particulars such as "where" or 
"sort" clauses
- a sources property: for defining the tables the object recognizes as 
sources for its properties.
- a relations property: for defining how the source tables are linked
- an objects property for defining links to related objects, such as 
subitem objects (one-to many)

In the simplest case all the properties of the dataobject have their 
datasource in a single flat table, for instance the roles table. When a 
roles object is then instantiated a dataquery is automatically added to 
the object that would resolve as e.g.

SELECT * FROM xar_roles

As the dataobject is then modified:
- by adding "where" clauses to it if it is an object list
- by enabling or disabling properties
- by adding or changing the object's field list etc.

the query is appropriately modified. The modifications happen when a 
getItem or getItems method of the dataobject is called. Similarly, when 
a createItem, updateItem or deleteItem method is called, the dataquery 
is changed appropriately into an INSERT, UPDATE or DELETE query 
respectively. The goal here is to have UI and API manipulation of the 
dataobject, which happens with reference to its properties (usually 
through the property name), automatically be translated via the 
dataquery definition into apprropriate actions at the database level.

Dataobjects can be linked to other dataobjects (exclusively) through the 
subitems property. The subitems property has the "none" datastore for 
its source. Instead, it contains a dataobject (which in turn has its own 
datasource(s)).

The basic rules:

- Dataobjects can have one or more datasources from the same datastore. 
In other words an object's properties can access several flat tables. 
Ideally these are linked (see next point).
- One-to-one relationships are modeled either as in the previous point, 
in which case all the properties involved are part of the same object, 
or through a subitems property, in which case some of the properties are 
"linked".
- One-to-many relationships are modeled through the subitems property. 
At the SQL level the related object is linked through an outer join 
(hard coded for now).
- If no datasource is defined the datasource defaults to variable table..

Overall, manipulaton of dataobjects is the same as in the Jamaica core. 
There is no change to the API calls .What changes is the dataobject's 
"configuration", which in turn influences the definition of its 
properties and its dataquery.

Some limitations:

- the scenario at present has only been tested with mysql. it is likely 
to fail in other databases due to variations in SQL syntax or requirements.
- complex "where" clauses (getItems method) are not supported

Some further ideas:
- The "none" datastore is probably too general and should be subdivided 
into 2 types: no local storage (i.e. for things like categories that 
store in their own table) and "no storage, just display what you have" 
which would show say a default value. However this sort of intrudes into 
an area that has up to now been governed by the properties' status.