Entities
[Entity: Types, Identity and Instance Framework]

---

Detailed Description

This file defines an API that adds types to the GUID's. GUID's with types can be used to identify and reference typed entities.

The idea here is that a GUID can be used to uniquely identify some thing. By adding a type, one can then talk about the type of thing identified. By adding a collection, one can then work with a handle to a collection of things of a given type, each uniquely identified by a given ID. QOF Entities can be used independently of any other part of the system. In particular, Entities can be useful even if one is not using the Query ond Object parts of the QOF system.

Identifiers are globally-unique and permanent, i.e., once an entity has been assigned an identifier, it retains that same identifier for its lifetime. Identifiers can be encoded as hex strings.

GUID Identifiers are 'typed' with strings. The native ids used by QOF are defined below.

1. An id with type QOF_ID_NONE does not refer to any entity.
2. An id with type QOF_ID_NULL does not refer to any entity, and will never refer to any entity. =# An identifier with any other type may refer to an actual entity, but that is not guaranteed as that entity does not have to exist within the current book. (See PARTIAL_QOFBOOK). Also, creating a new entity from a data source involves creating a temporary GUID and then setting the value from the data source. If an id does refer to an entity, the type of the entity will match the type of the identifier.

If you have a type name, and you want to have a way of finding a collection that is associated with that type, then you must use Books.

Entities can refer to other entities as well as to the basic QOF types, using the qofclass parameters.

Files
file	qofid.h
	QOF entity type identification system.
Collections of Entities
typedef void(*)	QofInstanceForeachCB (QofInstance *, gpointer user_data)
QofCollection *	qof_collection_new (QofIdType type)
guint	qof_collection_count (const QofCollection *col)
void	qof_collection_destroy (QofCollection *col)
QofIdType	qof_collection_get_type (const QofCollection *)
QofInstance *	qof_collection_lookup_entity (const QofCollection *, const GUID *)
void	qof_collection_foreach (const QofCollection *, QofInstanceForeachCB, gpointer user_data)
gpointer	qof_collection_get_data (const QofCollection *col)
void	qof_collection_set_data (QofCollection *col, gpointer user_data)
gboolean	qof_collection_is_dirty (const QofCollection *col)
QOF_TYPE_COLLECT: Linking one entity to many of one type
Note: These are NOT the same as the main collections in the book. QOF_TYPE_COLLECT is a secondary collection, used to select entities of one object type as references of another entity. See also: QOF_TYPE_CHOICE.
gboolean	qof_collection_add_entity (QofCollection *coll, QofInstance *ent)
	Add an entity to a QOF_TYPE_COLLECT.
void	qof_collection_remove_entity (QofInstance *ent)
gboolean	qof_collection_merge (QofCollection *target, QofCollection *merge)
	Merge two QOF_TYPE_COLLECT of the same type.
gint	qof_collection_compare (QofCollection *target, QofCollection *merge)
	Compare two secondary collections.
QofCollection *	qof_collection_from_glist (QofIdType type, const GList *glist)
	Create a secondary collection from a GList.
Defines
#define	QOF_ID_NONE   NULL
#define	QOF_ID_NULL   "null"
#define	QOF_ID_BOOK   "Book"
#define	QOF_ID_SESSION   "Session"
#define	QSTRCMP(da, db)
#define	QOF_CHECK_TYPE(obj, type)
#define	QOF_CHECK_CAST(obj, e_type, c_type)
Typedefs
typedef const gchar *	QofIdType
typedef const gchar *	QofIdTypeConst
typedef const gchar *	QofLogModule
typedef QofCollection_s	QofCollection
Functions
gboolean	qof_get_alt_dirty_mode (void)
void	qof_set_alt_dirty_mode (gboolean enabled)

---

Define Documentation

#define QOF_CHECK_CAST	(	obj,
		e_type,
		c_type		)

Value:

(                   \
  QOF_CHECK_TYPE((obj),(e_type)) ?                            \
  (c_type *) (obj) :                                          \
  (c_type *) ({                                               \
     g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL,               \
       "Error: Bad QofInstance at %s:%d", __FILE__, __LINE__);  \
     (obj);                                                   \
  }))

cast object to the indicated type, print error message if its bad

Definition at line 119 of file qofid.h.

#define QOF_CHECK_TYPE	(	obj,
		type		)

Value:

(((obj) != NULL) && \
  (0 == QSTRCMP((type),(((QofInstance *)(obj))->e_type))))

return TRUE if object is of the given type

Definition at line 114 of file qofid.h.

#define QSTRCMP	(	da,
		db		)

Value:

({                \
  gint val = 0;                          \
  if ((da) && (db)) {                    \
    if ((da) != (db)) {                  \
      val = strcmp ((da), (db));         \
    }                                    \
  } else                                 \
  if ((!(da)) && (db)) {                 \
    val = -1;                            \
  } else                                 \
  if ((da) && (!(db))) {                 \
    val = 1;                             \
  }                                      \
  val; /* block assumes value of last statement */  \
})

Inline string comparision; compiler will optimize away most of this

Definition at line 97 of file qofid.h.

---

Typedef Documentation

typedef const gchar* QofIdType

QofIdType declaration

Definition at line 80 of file qofid.h.

typedef const gchar* QofIdTypeConst

QofIdTypeConst declaration

Definition at line 82 of file qofid.h.

typedef void(*) QofInstanceForeachCB(QofInstance *, gpointer user_data)

Callback type for qof_collection_foreach

Definition at line 174 of file qofid.h.

typedef const gchar* QofLogModule

QofLogModule declaration

Definition at line 84 of file qofid.h.

---

Function Documentation

gboolean qof_collection_add_entity	(	QofCollection *	coll,
		QofInstance *	ent
	)

Add an entity to a QOF_TYPE_COLLECT.

Note:

These are NOT the same as the main collections in the book.

Entities can be freely added and merged across these secondary collections, they will not be removed from the original collection as they would by using qof_instance_insert_entity or qof_instance_remove_entity.

Definition at line 162 of file qofid.c.

{
        QofInstance *e;
        const GUID *guid;

        e = NULL;
        if (!coll || !ent) { return FALSE; }
        guid = qof_instance_get_guid(ent);
        if (guid_equal(guid, guid_null())) { return FALSE; }
        g_return_val_if_fail (coll->e_type == ent->e_type, FALSE);
        e = qof_collection_lookup_entity(coll, guid);
        if ( e != NULL ) { return FALSE; }
        g_hash_table_insert (coll->hash_of_entities, (gpointer)guid, ent);
        if (!qof_alt_dirty_mode)
          qof_collection_mark_dirty(coll);
        return TRUE;
}

gint qof_collection_compare	(	QofCollection *	target,
		QofCollection *	merge
	)

Compare two secondary collections.

Performs a deep comparision of the collections. Each QofInstance in each collection is looked up in the other collection, via the GUID.

Returns:

0 if the collections are identical or both are NULL otherwise -1 if target is NULL or either collection contains an entity with an invalid GUID or if the types of the two collections do not match, or +1 if merge is NULL or if any entity exists in one collection but not in the other.

Definition at line 231 of file qofid.c.

{
        gint value;

        value = 0;
        if (!target && !merge) { return 0; }
        if (target == merge) { return 0; }
        if (!target && merge) { return -1; }
        if (target && !merge) { return 1; }
        if(target->e_type != merge->e_type) { return -1; }
        qof_collection_set_data(target, &value);
        qof_collection_foreach(merge, collection_compare_cb, target);
        value = *(gint*)qof_collection_get_data(target);
        if(value == 0) {
                qof_collection_set_data(merge, &value);
                qof_collection_foreach(target, collection_compare_cb, merge);
                value = *(gint*)qof_collection_get_data(merge);
        }
        return value;
}

guint qof_collection_count

(

const QofCollection *

col

)

return the number of entities in the collection.

Definition at line 282 of file qofid.c.

{
        guint c;

        c = g_hash_table_size(col->hash_of_entities);
        return c;
}

void qof_collection_destroy

(

QofCollection *

col

)

destroy the collection

XXX there should be a destroy notifier for this

Definition at line 108 of file qofid.c.

{
  CACHE_REMOVE (col->e_type);
  g_hash_table_destroy(col->hash_of_entities);
  col->e_type = NULL;
  col->hash_of_entities = NULL;
  col->data = NULL;   
  g_free (col);
}

void qof_collection_foreach	(	const QofCollection *	,
		QofInstanceForeachCB	,
		gpointer	user_data
	)

Call the callback for each entity in the collection.

Definition at line 348 of file qofid.c.

{
  struct _iterate iter;

  g_return_if_fail (col);
  g_return_if_fail (cb_func);

  iter.fcn = cb_func;
  iter.data = user_data;

  g_hash_table_foreach (col->hash_of_entities, foreach_cb, &iter);
}

QofCollection* qof_collection_from_glist	(	QofIdType	type,
		const GList *	glist
	)

Create a secondary collection from a GList.

Parameters:

	type	The QofIdType of the QofCollection and of all entities in the GList.
	glist	GList of entities of the same QofIdType.

Returns:

NULL if any of the entities fail to match the QofCollection type, else a pointer to the collection on success.

Definition at line 263 of file qofid.c.

{
        QofCollection *coll;
        QofInstance *ent;
        const GList *list;

        coll = qof_collection_new(type);
        for(list = glist; list != NULL; list = list->next)
        {
                ent = QOF_INSTANCE(list->data);
                if(FALSE == qof_collection_add_entity(coll, ent))
                {
                        return NULL;
                }
        }
        return coll;
}

gpointer qof_collection_get_data

(

const QofCollection *

col

)

Store and retreive arbitrary object-defined data

XXX We need to add a callback for when the collection is being destroyed, so that the user has a chance to clean up anything that was put in the 'data' member here.

Definition at line 321 of file qofid.c.

{
   return col ? col->data : NULL;
}

QofIdType qof_collection_get_type

(

const QofCollection *

)

return the type that the collection stores

Definition at line 122 of file qofid.c.

{
  return col->e_type;
}

gboolean qof_collection_is_dirty

(

const QofCollection *

col

)

Return value of 'dirty' flag on collection

Definition at line 293 of file qofid.c.

{
   return col ? col->is_dirty : FALSE;
}

QofInstance* qof_collection_lookup_entity	(	const QofCollection *	,
		const GUID *
	)

Find the entity going only from its guid

Definition at line 253 of file qofid.c.

{
  QofInstance *ent;
  g_return_val_if_fail (col, NULL);
  if (guid == NULL) return NULL;
  ent = g_hash_table_lookup (col->hash_of_entities, guid);
  return ent;
}

gboolean qof_collection_merge	(	QofCollection *	target,
		QofCollection *	merge
	)

Merge two QOF_TYPE_COLLECT of the same type.

Note:

NOT the same as the main collections in the book.

QOF_TYPE_COLLECT uses a secondary collection, independent of those in the book. Entities will not be removed from the original collection as when using qof_instance_insert_entity or qof_instance_remove_entity.

Definition at line 190 of file qofid.c.

{
        if(!target || !merge) { return FALSE; }
        g_return_val_if_fail (target->e_type == merge->e_type, FALSE);
        qof_collection_foreach(merge, collection_merge_cb, target);
        return TRUE;
}

QofCollection* qof_collection_new

(

QofIdType

type

)

create a new collection of entities of type

Definition at line 97 of file qofid.c.

{
  QofCollection *col;
  col = g_new0(QofCollection, 1);
  col->e_type = CACHE_INSERT (type);
  col->hash_of_entities = g_hash_table_new (id_hash, id_compare);
  col->data = NULL;
  return col;
}

gboolean qof_get_alt_dirty_mode

(

void

)

Is QOF operating in "alternate" dirty mode. In normal mode, whenever an instance is dirtied, the collection (and therefore the book) is immediately marked as dirty. In alternate mode, the collection is only marked dirty when a dirty instance is committed. If a dirty instance is freed instead of committed, the dirty state of collection (and therefore the book) is never changed.

Definition at line 48 of file qofid.c.

{
  return qof_alt_dirty_mode;
}

void qof_set_alt_dirty_mode

(

gboolean

enabled

)

Set QOF into "alternate" dirty mode. In normal mode, whenever an instance is dirtied, the collection (and therefore the book) is immediately marked as dirty. In alternate mode, the collection is only marked dirty when a dirty instance is committed. If a dirty instance is freed instead of committed, the dirty state of collection (and therefore the book) is never changed.

Definition at line 54 of file qofid.c.

{
  qof_alt_dirty_mode = enabled;
}

---