Logical handling of parameters, entities and books.
[QOF Command Line Interface]

Detailed Description

EXPERIMENTAL!

Objects can have complex relationships and inter-dependencies. QofLogic aims to enforce logical rules for specific aspects of a QofEntity .

Rules are expressed in any of 5 levels:

  1. Data Source constraints: Includes XML schema / DTD validation of incoming data e.g. no GUID read from the XML should fail to verify as hexadecimal - it may fail as a GUID (out of range etc.), but not as hexadecimal. Other backends can provide different constraints according to their strengths - each backend must implement a minimum standard of data constraint by preventing attempts to set invalid data into the QofBook.
  2. Discrete parameter logic: Each object parameter must enforce those rules that are necessary for itself. This includes only those rules that can be enforced with reference ONLY to the current parameter in the current entity.
  3. Entity logic: Each entity has a QofLogic mechanism to validate it's parameters *with reference to* it's other parameters. These rules are the lowest level of QofLogic. This is where an entity can verify that it has X parameter OR Y parameter and fail if the two are incompatible.
  4. Collection logic: Some objects may need to verify their own place within the QofCollection - typically these would be hierarchical objects like Account. This would implement "all accounts must have a unique name".
  5. Book logic: Rules that determine how objects of different types validate their own data and references to other objects. This is where "all splits must reference a known account" would be implemented.

Data source constraints are commonly external to QOF, e.g. XML schema, DTD's, stored procedures and other logic within the QofBackend itself. All QofBackend modules must implement sufficient data source constraints to ensure that the entire dataset is completely represented in the valid QofBook passed to QOF after loading that dataset.

Some parameter logic is implicit in the QofSetterFunc routines. Further parameter logic, entity logic, collection logic and book logic are all optional - dictated by the objects themselves.

In a similar manner to pilot-qof pack routines, QofLogic rules are defined using a static struct that sets the appropriate logic levels.


Files

file  qoflogic.h
 Logic handlers for the QOF external framework.

Data Structures

struct  QofLogicParam
struct  QofLogic

Defines

#define QOF_MOD_LOGIC   "qof_logic"
 Debug module for the logic code.
#define QOF_MAKE_LOGIC_ERR(x)   (1<<(x))
#define QOF_LOGIC_BASE   12
#define ERR_LOGIC_NOT_DONE   QOF_MAKE_LOGIC_ERR(0)
#define ERR_LOGIC_VALID   QOF_MAKE_LOGIC_ERR(1)
#define ERR_LOGIC_PARAM_FAIL   QOF_MAKE_LOGIC_ERR(2)
#define ERR_LOGIC_PARAM_UNSET   QOF_MAKE_LOGIC_ERR(3)
#define ERR_LOGIC_PARAM_NULL   QOF_MAKE_LOGIC_ERR(4)
#define ERR_LOGIC_ENTITY_INCOMPATIBLE   QOF_MAKE_LOGIC_ERR(5)
#define ERR_LOGIC_COLL_INVALID   QOF_MAKE_LOGIC_ERR(6)
#define qof_logic_collection_pair(a, b)   qof_logic_collection_check(a, (gconstpointer)b)

Typedefs

typedef guint QofLogicError
typedef QofLogicError(* QofLogicParamFunc )(QofEntity *ent, QofParam *param, gconstpointer data)
typedef QofLogicError(* QofLogicEntFunc )(QofEntity *ent, gconstpointer data)
typedef QofLogicError(* QofLogicCollFunc )(QofCollection *col, gconstpointer data)
typedef QofLogicError(* QofLogicBookFunc )(QofBook *book, gconstpointer data)
 Prototype for functions to verify links between entities in different collections.
typedef const gchar *(* QofLogicErrorFunc )(QofLogicError error)
 Prototype to retrieve a sensible error message.

Functions

gboolean qof_logic_register (QofIdTypeConst obj_name, const QofLogic *logic)
gboolean qof_logic_param_register (QofIdTypeConst obj_name, const QofLogicParam *params)
QofLogicError qof_logic_book_check (QofBook *book, gconstpointer data)
 Run logical tests on the entire book.
QofLogicError qof_logic_collection_check (QofCollection *col, gconstpointer data)
QofLogicError qof_logic_entity_check (QofEntity *ent, gconstpointer data)
QofLogicError qof_logic_param_check (QofEntity *ent, QofParam *param, gconstpointer data)
const gchar * qof_logic_error_msg (QofLogicError error, QofIdTypeConst obj_type)

Define Documentation

#define ERR_LOGIC_ENTITY_INCOMPATIBLE   QOF_MAKE_LOGIC_ERR(5)
 

At least one entity in this collection is incompatible with at least one other. Call qof_logic_error_msg for more information.

Definition at line 100 of file qoflogic.h.

#define ERR_LOGIC_NOT_DONE   QOF_MAKE_LOGIC_ERR(0)
 

Init value. SUCCESS.

Definition at line 89 of file qoflogic.h.

Referenced by qof_logic_book_check(), qof_logic_collection_check(), qof_logic_entity_check(), and qof_logic_param_check().

#define ERR_LOGIC_PARAM_FAIL   QOF_MAKE_LOGIC_ERR(2)
 

Value could not be set for this parameter.

Definition at line 93 of file qoflogic.h.

#define ERR_LOGIC_PARAM_NULL   QOF_MAKE_LOGIC_ERR(4)
 

At least one parameter of this entity is incompatible with at least one other. Call qof_logic_error_msg for more information.

Definition at line 97 of file qoflogic.h.

#define ERR_LOGIC_PARAM_UNSET   QOF_MAKE_LOGIC_ERR(3)
 

Tried to set an unsupported NULL value.

Definition at line 95 of file qoflogic.h.

#define ERR_LOGIC_VALID   QOF_MAKE_LOGIC_ERR(1)
 

Parameter logic could not be registered.

Definition at line 91 of file qoflogic.h.

Referenced by qof_logic_collection_check(), qof_logic_entity_check(), and qof_logic_param_check().

#define QOF_LOGIC_BASE   12
 

Custom error values must be more than this.

Definition at line 86 of file qoflogic.h.

#define qof_logic_collection_pair (  a,
b   )     qof_logic_collection_check(a, (gconstpointer)b)
 

Run logical tests against entities from two collections.

The QofLogicCollFunc for col_a is called with col_b as an additional parameter. col_b should not be modified by the logic test within the col_a object.

Definition at line 165 of file qoflogic.h.

#define QOF_MAKE_LOGIC_ERR (  x   )     (1<<(x))
 

Allow bitwise comparison of error result values.

Definition at line 83 of file qoflogic.h.

Typedef Documentation

typedef QofLogicError(* QofLogicCollFunc)(QofCollection *col, gconstpointer data)
 

Prototype for functions to verify links between entities in one collection.

Definition at line 113 of file qoflogic.h.

typedef QofLogicError(* QofLogicEntFunc)(QofEntity *ent, gconstpointer data)
 

Prototype for functions to verify all parameter data of one entity.

Definition at line 110 of file qoflogic.h.

typedef guint QofLogicError
 

Prototype

Definition at line 80 of file qoflogic.h.

typedef QofLogicError(* QofLogicParamFunc)(QofEntity *ent, QofParam *param, gconstpointer data)
 

Prototype for functions to verify data in one parameter of one entity.

Definition at line 106 of file qoflogic.h.

Function Documentation

QofLogicError qof_logic_book_check (  QofBook *  book,
gconstpointer  data
) 
 

Run logical tests on the entire book.

Unlike the other routines, this calls the QofLogicBookFunc of each registered QOF type by iterating over each QofCollection.

Functions should only test logic directly related to the object being tested.

Use this routine sparingly, it can take some time to test an entire book.

Definition at line 176 of file qoflogic.c.

References logic_book_iter::data, ERR_LOGIC_NOT_DONE, and logic_book_iter::error.

00177 {
00178         struct logic_book_iter iter;
00179 
00180         if (!check_init())  return ERR_LOGIC_NOT_DONE;
00181         g_return_val_if_fail(book, ERR_LOGIC_NOT_DONE);
00182         iter.error = ERR_LOGIC_NOT_DONE;
00183         iter.data = data;
00184         qof_book_foreach_collection(book, logic_book_by_coll, &iter);
00185         return iter.error;
00186 }

QofLogicError qof_logic_collection_check (  QofCollection *  col,
gconstpointer  data
) 
 

Run logical tests on all entities in a collection.

Definition at line 189 of file qoflogic.c.

References ERR_LOGIC_NOT_DONE, and ERR_LOGIC_VALID.

00190 {
00191         QofLogicCollFunc func;
00192 
00193         if (!check_init()) return ERR_LOGIC_NOT_DONE;
00194         g_return_val_if_fail(col, ERR_LOGIC_NOT_DONE);
00195         func = qof_logic_get_coll_func(qof_collection_get_type(col));
00196         /* If no logic is defined, the collection must be valid. */
00197         if(!func) return ERR_LOGIC_VALID;
00198         return (func)(col, data);
00199 }

QofLogicError qof_logic_entity_check (  QofEntity *  ent,
gconstpointer  data
) 
 

Run logical tests on all parameters of a specific entity.

Definition at line 202 of file qoflogic.c.

References ERR_LOGIC_NOT_DONE, and ERR_LOGIC_VALID.

00203 {
00204         QofLogicEntFunc func;
00205 
00206         if (!check_init()) return ERR_LOGIC_NOT_DONE;
00207         g_return_val_if_fail(ent, ERR_LOGIC_NOT_DONE);
00208         func = qof_logic_get_ent_func(ent->e_type);
00209         /* If no logic is defined, the entity must be valid. */
00210         if(!func) return ERR_LOGIC_VALID;
00211         return (func)(ent, data);
00212 }

const gchar* qof_logic_error_msg (  QofLogicError  error,
QofIdTypeConst  obj_type
) 
 

Get a sensible error message for the user.

Definition at line 228 of file qoflogic.c.

References logic_error_func.

00229 {
00230         QofLogic *logic;
00231         QofLogicErrorFunc func;
00232 
00233         if (!check_init()) return NULL;
00234         g_return_val_if_fail((error || obj_type), NULL);
00235         logic = g_hash_table_lookup(logic_table, obj_type);
00236         func = logic->logic_error_func;
00237         if(!func) return NULL;
00238         return (func)(error);
00239 }

QofLogicError qof_logic_param_check (  QofEntity *  ent,
QofParam *  param,
gconstpointer  data
) 
 

Test the logic of this specific parameter of this specific entity.

Definition at line 215 of file qoflogic.c.

References ERR_LOGIC_NOT_DONE, and ERR_LOGIC_VALID.

00216 {
00217         QofLogicParamFunc func;
00218 
00219         if (!check_init()) return ERR_LOGIC_NOT_DONE;
00220         g_return_val_if_fail((param || ent), ERR_LOGIC_NOT_DONE);
00221         func = qof_logic_get_param_func(ent->e_type, param);
00222         /* If no logic is defined, the param must be valid. */
00223         if(!func) return ERR_LOGIC_VALID;
00224         return (func)(ent, param, data);
00225 }

gboolean qof_logic_param_register (  QofIdTypeConst  obj_name,
const QofLogicParam *  params
) 
 

Register parameter logic for this object with QOF.

Definition at line 69 of file qoflogic.c.

References QofLogicParam::param_name.

00071 {
00072         GHashTable *pt;
00073         gint i;
00074 
00075         if(!check_init()) return FALSE;
00076         g_return_val_if_fail (obj_name || params, FALSE);
00077         pt = g_hash_table_lookup (param_table, obj_name);
00078         /* If it doesn't already exist, create a new table for this object */
00079         if (!pt)
00080         {
00081                 pt = g_hash_table_new (g_str_hash, g_str_equal);
00082                 g_hash_table_insert (param_table, (gchar *)obj_name, pt);
00083         }
00084         if (params)
00085         {
00086                 for (i = 0; params[i].param_name; i++)
00087                         g_hash_table_insert (pt,
00088                                 (gchar *)params[i].param_name,
00089                                 (gpointer)&(params[i]));
00090         }
00091         return TRUE;
00092 }

gboolean qof_logic_register (  QofIdTypeConst  obj_name,
const QofLogic *  logic
) 
 

Register object logic with QOF.

Definition at line 94 of file qoflogic.c.

00095 {
00096         if(!check_init()) return FALSE;
00097         g_return_val_if_fail(obj_name || logic, FALSE);
00098         PINFO (" registering logic for %s", obj_name);
00099         g_hash_table_insert(logic_table, (gchar*)obj_name, (gpointer)logic);
00100         return TRUE;
00101 }

Generated on Tue May 16 20:38:53 2006 for cashutil by  doxygen 1.4.6