Class: Getting and setting entity values.
[Query Object Framework]


Detailed Description

This file defines a class messaging system reminiscent of traditional OO-style setter and getter interfaces to object properties. A C-language object can declare a collection of setters and getters on itself that can then be used to perform run-time (as opposed to compile-time) bindings to the object.

To put it differently, a QOF class is a set of parameter getters and setters that are associated with an object type. Given a pointer to some thing, the setters and getters can be used to get and set values out of that thing. Note that the pointer to "some thing" need not be a pointer to a QOF Entity or Instance (although QOF classes are more interesting when used with Entities/Instances). What "some thing" is defined entirely by the programmer declaring a new QOF Class.

Because a QOF Class associates getters and setters with a type, one can then ask, at run time, what parameters are associated with a given type, even if those parameters were not known at compile time. Thus, a QOF Class is sort-of like a DynAny implementation. QOF classes can be used to provide "object introspection", i.e. asking object to describe itself.

The QOF Query subsystem depends on QOF classes having been declared; the Query uses the getters to get values associated with particular instances.

A QofAccessFunc or QofSetterFunc do not need to be public functions, if you need to add functions to an object with an established API, define the additional QOF routines as static. Only the register routine needs to be public.


Files

file  qofclass.h
 API for registering paramters on objects.

Modules

 GUID
 Entity
 Instance

Data Structures

struct  _QofParam

Core types

Core data types for objects that can be used in parameters. Note that QofIdTypes may also be used and will create a single reference between two known objects.

#define QOF_TYPE_STRING   "string"
#define QOF_TYPE_TIME   "time"
#define QOF_TYPE_NUMERIC   "numeric"
#define QOF_TYPE_DEBCRED   "debcred"
#define QOF_TYPE_GUID   "guid"
#define QOF_TYPE_INT32   "gint32"
#define QOF_TYPE_INT64   "gint64"
#define QOF_TYPE_DOUBLE   "double"
#define QOF_TYPE_BOOLEAN   "boolean"
#define QOF_TYPE_KVP   "kvp"
#define QOF_TYPE_CHAR   "character"
#define QOF_TYPE_COLLECT   "collection"

Defines

#define QOF_MOD_CLASS   "qof-class"

Typedefs

typedef const gchar * QofType
typedef struct _QofParam QofParam
typedef gpointer(* QofAccessFunc )(gpointer object, const QofParam *param)
typedef void(* QofSetterFunc )(gpointer, gpointer)
typedef gint(* QofSortFunc )(gconstpointer, gconstpointer)
typedef void(* QofClassForeachCB )(QofIdTypeConst, gpointer)
typedef void(* QofParamForeachCB )(QofParam *, gpointer user_data)

Functions

void qof_class_register (QofIdTypeConst obj_name, QofSortFunc default_sort_fcn, const QofParam *params)
 registers a new object class with the Qof subsystem.
gboolean qof_class_is_registered (QofIdTypeConst obj_name)
QofType qof_class_get_parameter_type (QofIdTypeConst obj_name, const gchar *param_name)
const QofParamqof_class_get_parameter (QofIdTypeConst obj_name, const gchar *parameter)
QofAccessFunc qof_class_get_parameter_getter (QofIdTypeConst obj_name, const gchar *parameter)
QofSetterFunc qof_class_get_parameter_setter (QofIdTypeConst obj_name, const gchar *parameter)
void qof_class_foreach (QofClassForeachCB, gpointer user_data)
void qof_class_param_foreach (QofIdTypeConst obj_name, QofParamForeachCB, gpointer user_data)
GList * qof_class_get_referenceList (QofIdTypeConst type)
 List of the parameters that could be references.


Define Documentation

#define QOF_TYPE_COLLECT   "collection"

secondary collections are used for one-to-many references between entities and are implemented using QofCollection. These are NOT the same as the main collections in the QofBook.

  1. Each QofCollection contains one or many entities - *all* of a single type.
  2. The entity type within the collection can be determined at run time.
  3. Easy conversions to GList or whatever in the param_setfcn handler.
  4. Each parameter can have its own collection.
  5. Each entity can have a different *type* of collection to its siblings, provided that it is acceptable to the set function.
  6. Each object decides which types are acceptable for which parameter in the set functions. This is then part of the API for that object.

QOF_TYPE_COLLECT has two functions, both related to one-to-many links:

If the set function can handle it, it could also be used for true one-to-many links: one object linked to many entities of many types.

n.b. Always subject to each collection holding only one type at runtime. (otherwise use books).

Definition at line 93 of file qofclass.h.


Typedef Documentation

typedef gpointer(* QofAccessFunc)(gpointer object, const QofParam *param)

The QofAccessFunc defines an arbitrary function pointer for access functions. This is needed because C doesn't have templates, so we just cast a lot. Real functions must be of the form:

param_type getter_func (object_type *self); or param_type getter_func (object_type *self, QofParam *param);

The additional argument 'param' allows generic getter functions to be implemented, because this argument provides for a way to identify the expected getter_func return type at runtime. It also provides a place for the user to hang additional user-defined data.

Definition at line 142 of file qofclass.h.

typedef void(* QofClassForeachCB)(QofIdTypeConst, gpointer)

Type definition for the class callback function.

Definition at line 248 of file qofclass.h.

typedef void(* QofParamForeachCB)(QofParam *, gpointer user_data)

Type definition for the paramter callback function.

Definition at line 257 of file qofclass.h.

typedef void(* QofSetterFunc)(gpointer, gpointer)

The QofSetterFunc defines an function pointer for parameter setters. Real functions must be of the form:

void setter_func (object_type *self, param_type *param);

Definition at line 149 of file qofclass.h.

typedef gint(* QofSortFunc)(gconstpointer, gconstpointer)

This function is the default sort function for a particular object type

Definition at line 179 of file qofclass.h.

typedef const gchar* QofType

Type of Paramters (String, Date, Numeric, GUID, etc.)

Definition at line 123 of file qofclass.h.


Function Documentation

void qof_class_foreach ( QofClassForeachCB  ,
gpointer  user_data 
)

Call the callback once for each object class that is registered with the system. The 'user_data' is passed back to the callback.

Definition at line 233 of file qofclass.c.

00234 {
00235     struct class_iterate qiter;
00236 
00237     if (!cb)
00238         return;
00239     if (!classTable)
00240         return;
00241 
00242     qiter.fcn = cb;
00243     qiter.data = user_data;
00244 
00245     g_hash_table_foreach (classTable, class_foreach_cb, &qiter);
00246 }

const QofParam* qof_class_get_parameter ( QofIdTypeConst  obj_name,
const gchar *  parameter 
)

Return the registered Parameter Definition for the requested parameter

Definition at line 146 of file qofclass.c.

00147 {
00148     GHashTable *ht;
00149 
00150     g_return_val_if_fail (obj_name, NULL);
00151     g_return_val_if_fail (parameter, NULL);
00152     if (!check_init ())
00153         return NULL;
00154 
00155     ht = g_hash_table_lookup (classTable, obj_name);
00156     if (!ht)
00157     {
00158         PWARN ("no object of type %s", obj_name);
00159         return NULL;
00160     }
00161 
00162     return (g_hash_table_lookup (ht, parameter));
00163 }

QofAccessFunc qof_class_get_parameter_getter ( QofIdTypeConst  obj_name,
const gchar *  parameter 
)

Return the object's parameter getter function

Definition at line 166 of file qofclass.c.

00168 {
00169     const QofParam *prm;
00170 
00171     g_return_val_if_fail (obj_name, NULL);
00172     g_return_val_if_fail (parameter, NULL);
00173 
00174     prm = qof_class_get_parameter (obj_name, parameter);
00175     if (prm)
00176         return prm->param_getfcn;
00177 
00178     return NULL;
00179 }

QofSetterFunc qof_class_get_parameter_setter ( QofIdTypeConst  obj_name,
const gchar *  parameter 
)

Return the object's parameter setter function

Definition at line 182 of file qofclass.c.

00184 {
00185     const QofParam *prm;
00186 
00187     g_return_val_if_fail (obj_name, NULL);
00188     g_return_val_if_fail (parameter, NULL);
00189 
00190     prm = qof_class_get_parameter (obj_name, parameter);
00191     if (prm)
00192         return prm->param_setfcn;
00193 
00194     return NULL;
00195 }

QofType qof_class_get_parameter_type ( QofIdTypeConst  obj_name,
const gchar *  param_name 
)

Return the core datatype of the specified object's parameter

Definition at line 198 of file qofclass.c.

00200 {
00201     const QofParam *prm;
00202 
00203     if (!obj_name || !param_name)
00204         return NULL;
00205 
00206     prm = qof_class_get_parameter (obj_name, param_name);
00207     if (!prm)
00208         return NULL;
00209 
00210     return (prm->param_type);
00211 }

GList* qof_class_get_referenceList ( QofIdTypeConst  type  ) 

List of the parameters that could be references.

Simple check to return a GList of all parameters of this object type that are not known QOF data types. Used for partial QofBook support, see QofEntityReference

Definition at line 332 of file qofclass.c.

00333 {
00334     GList *ref_list;
00335     struct param_ref_list b;
00336 
00337     ref_list = NULL;
00338     b.list = NULL;
00339     qof_class_param_foreach (type, find_reference_param_cb, &b);
00340     ref_list = g_list_copy (b.list);
00341     return ref_list;
00342 }

gboolean qof_class_is_registered ( QofIdTypeConst  obj_name  ) 

An example:

define MY_OBJ_MEMO "memo" define MY_OBJ_VALUE "value" define MY_OBJ_TIME "time" define MY_OBJ_ACCOUNT "account" define MY_OBJ_TRANS "trans"

static QofParam myParams[] = { { MY_OBJ_MEMO, QOF_TYPE_STRING, myMemoGetter, NULL }, { MY_OBJ_VALUE, QOF_TYPE_NUMERIC, myValueGetter, NULL }, { MY_OBJ_TIME, QOF_TYPE_TIME, myTimeGetter, NULL }, { MY_OBJ_ACCOUNT, GNC_ID_ACCOUNT, myAccountGetter, NULL }, { MY_OBJ_TRANS, GNC_ID_TRANS, myTransactionGetter, NULL }, NULL };

qof_class_register ("myObjectName", myObjectCompare, &myParams); Return true if the the indicated type is registered, else return FALSE.

Definition at line 132 of file qofclass.c.

00133 {
00134     if (!obj_name)
00135         return FALSE;
00136     if (!check_init ())
00137         return FALSE;
00138 
00139     if (g_hash_table_lookup (classTable, obj_name))
00140         return TRUE;
00141 
00142     return FALSE;
00143 }

void qof_class_param_foreach ( QofIdTypeConst  obj_name,
QofParamForeachCB  ,
gpointer  user_data 
)

Call the callback once for each parameter on the indicated object class. The 'user_data' is passed back to the callback.

Definition at line 267 of file qofclass.c.

00269 {
00270     struct parm_iterate qiter;
00271     GHashTable *param_ht;
00272 
00273     if (!obj_name || !cb)
00274         return;
00275     if (!classTable)
00276         return;
00277     param_ht = g_hash_table_lookup (classTable, obj_name);
00278     if (!param_ht)
00279         return;
00280 
00281     qiter.fcn = cb;
00282     qiter.data = user_data;
00283 
00284     g_hash_table_foreach (param_ht, param_foreach_cb, &qiter);
00285 }

void qof_class_register ( QofIdTypeConst  obj_name,
QofSortFunc  default_sort_fcn,
const QofParam params 
)

registers a new object class with the Qof subsystem.

In particular, it registers the set of setters and getters for controlling the object. The getters are typically used by the query subsystem to query type specific data. Note that there is no particular requirement for there to be a setter for every getter or even vice-versa, nor is there any requirement for these to map 'cleanly' or orthogonally to the underlying object. The parameters are really just a set of value setting and getting routines.

The "params" argument must be a NULL-terminated array of QofParam with a constant storage size. It may be NULL if there are no parameters to be registered. When creating dynamic QofObjects, ensure the array is long enough for all objects. Registration will stop at the first NULL parameter.

Definition at line 93 of file qofclass.c.

00095 {
00096     GHashTable *ht;
00097     int i;
00098 
00099     if (!obj_name)
00100         return;
00101     if (!check_init ())
00102         return;
00103 
00104     if (default_sort_function)
00105     {
00106         g_hash_table_insert (sortTable, (gchar *) obj_name,
00107             default_sort_function);
00108     }
00109 
00110     ht = g_hash_table_lookup (classTable, obj_name);
00111 
00112     /* If it doesn't already exist, create a new table for this object */
00113     if (!ht)
00114     {
00115         ht = g_hash_table_new (g_str_hash, g_str_equal);
00116         g_hash_table_insert (classTable, (gchar *) obj_name, ht);
00117     }
00118 
00119     /* At least right now, we allow dummy, parameterless objects,
00120      * for testing purposes.  Although I suppose that should be
00121      * an error..  */
00122     /* Now insert all the parameters */
00123     if (params)
00124     {
00125         for (i = 0; params[i].param_name; i++)
00126             g_hash_table_insert (ht,
00127                 (char *) params[i].param_name, (gpointer) & (params[i]));
00128     }
00129 }


Generated on Thu Jan 31 22:50:27 2008 for QOF by  doxygen 1.5.4