QOF: Reference: Referring to entities outside a partial book.

QOF 0.7.5

Files | Data Structures
Reference: Referring to entities outside a partial book.
Query Object Framework

## Files
file | qofreference.h
| Dealing with relationships between entities in partial books.

## Data Structures
struct | qof_entity_reference
| External references in a partial QofBook. More...

## Using a partial QofBook.
Part of the handling for partial books requires a storage mechanism for references to entities that are not within reach of the partial book. This requires a GList in the book data to contain the reference QofIdType and GUID so that when the book is written out, the reference can be included. See qof_book_get_data. When the file is imported back in, the list needs to be rebuilt. The QSF backend rebuilds the references by linking to real entities. Other backends can process the list in similar ways. The list stores the QofEntityReference to the referenced entity - a struct that contains the GUID and the QofIdType of the referenced entity as well as the parameter used to obtain the reference. Partial books need to be differentiated in the backend, the flag in the book data is used by qof_session_save to prevent a partial book being saved using a backend that requires a full book. Forcing this flag would cause data loss so always merge a partial book with the complete book (even if that book is initially empty) before trying to save the data using a backend that does not support partial books.
typedef struct qof_entity_reference | QofEntityReference
| External references in a partial QofBook. More...
void | qof_session_update_reference_list (QofSession *session, QofEntityReference *reference)
| Adds a new reference to the partial book data hash. More...
void | qof_book_set_references (QofBook *book)
| Read QofEntityReference data for this book and set values. More...
QofEntityReference * | qof_entity_get_reference_from (QofEntity *ent, const QofParam *param)
| Get a reference from this entity to another entity. More...
#define | ENTITYREFERENCE "QofEntityReference"
#define | PARTIAL_QOFBOOK "PartialQofBook"
| Flag indicating a partial QofBook. More...

## Detailed Description

Partial book is a QofBook that lacks at least one of the key elements of a fully structured (complete) book:

- Self-contained: All relationships between entities are satisfied within the book itself;
- Containing specific entities that provide an external structure to the data within the book.

Partial books are useful for query results, selective export and data mining but need to be merged back into standard books. It is not supported to construct a partial book and then convert the same book to a standard book.

Different backends have different requirements for a complete book - some (like gnucash) are highly customised to that application - however all complete QofBooks must be self-contained, only a partial book uses QofEntityReference.

To retain the relationships between entities, including between a partial and a complete book, QofEntityReference data is stored in the QofBook. This data should be read by backends that support partial books so that the exported data contains the GUID and QofIdType of the referenced entity. Even if that entity does not then exist within the partial book, it can be located when the partial book is merged back into the original, complete, book. (Remember that given the GUID and QofIdType of any QofEntity it is possible to uniquely identify that entity in another book.)

Entities in partial books may need to refer to the entities that remain within the partial book. Once all the entities you want are in the partial book, call qof_book_set_references to restore as many references as possible. Each object type is checked in turn, each entity of that type and then each parameter that can relate to another entity. Any references that cannot be found are left unset - depending on the object these may be undefined or NULL. (It is advisable to set all QOF parameters to either a default value or NULL in the create: routine for the object but QOF has no way of guaranteeing this.)

## Macro Definition Documentation

## ◆ ENTITYREFERENCE

#define ENTITYREFERENCE "QofEntityReference"

Used as the key value for the QofBook data hash.

Retrieved later by QSF (or any other suitable backend) to rebuild the references from the QofEntityReference struct that contains the QofIdType and GUID of the referenced entity of the original QofBook as well as the parameter data and the GUID of the original entity.

Definition at line 137 of file qofreference.h.

## ◆ PARTIAL_QOFBOOK

#define PARTIAL_QOFBOOK "PartialQofBook"

Flag indicating a partial QofBook.

When set in the book data with a gboolean value of TRUE, the flag denotes that only a backend that supports partial books can be used to save this session.

Definition at line 146 of file qofreference.h.

## Typedef Documentation

## ◆ QofEntityReference

typedef struct qof_entity_reference QofEntityReference

External references in a partial QofBook.

For use by any session that deals with partial QofBooks. It is used by the entity copy functions and by the QSF backend. Creates a GList stored in the Book hashtable to contain repeated references for a single entity.

## Function Documentation

## ◆ qof_book_set_references()

void qof_book_set_references | ( | QofBook * | book | ) |

Read QofEntityReference data for this book and set values.

Parameters

  book | The partial book containing the referenceList

The referenceList is a GList of QofEntityReference structures that contain the GUID of each end of a reference. e.g. where one entity refers to another.

The referenceList is used in partial books to store relationships between entities when the entities themselves might not exist in the partial book.

If the book is not marked as a partial book, an assertion error is generated.

This routine tries to lookup each entity in the referenceList for the book and then tries to lookup the reference - to find the child entity that was originally linked to this parent. The child entity is then set in the parent so that it can be located as normal.

If the child entity does not exist in this partial book, the parent entity is not updated. The referenceList is unchanged (in case the child is added later).

Definition at line 177 of file qofreference.c.

178 {
179 gboolean partial;
180
181 partial =
182 (gboolean)
183 GPOINTER_TO_INT (qof_book_get_data (book, PARTIAL_QOFBOOK));
184 g_return_if_fail (partial);
185 qof_object_foreach_type (set_each_type, book);
186 }
qof_book_get_data
gpointer qof_book_get_data(QofBook *book, const gchar *key)
Definition: qofbook.c:212
qof_object_foreach_type
void qof_object_foreach_type(QofForeachTypeCB cb, gpointer user_data)
Definition: qofobject.c:140
PARTIAL_QOFBOOK
#define PARTIAL_QOFBOOK
Flag indicating a partial QofBook.
Definition: qofreference.h:146

## ◆ qof_entity_get_reference_from()

QofEntityReference* qof_entity_get_reference_from | ( | QofEntity * | ent,
|  | const QofParam * | param
| ) |  |

Get a reference from this entity to another entity.

Note
  Only to be used in situations where the QofParam has already been checked NOT to be QOF_TYPE_COLLECT or other known QOF types because this function expects to return a single reference and a collect parameter would need to return a list of references, other parameters would not return a viable QofEntity. (A string cannot be cast to an entity.)

Used in the preparation of a partial QofBook when the known entity (the one currently being copied into the partial book) refers to any other entity, usually as a parent or child. The routine calls the param_getfcn of the supplied parameter, which must return an object (QofEntity*), not a known QOF data type, to retrieve the referenced entity and therefore the GUID. The GUID of both entities are stored in the reference which then needs to be added to the reference list which is added to the partial book data hash. The reference itself is used to preserve the relationship between entities within and outside the partial book.

See also qof_class_get_referenceList to obtain the list of parameters that provide references to the known entity whilst excluding parameters that return known QOF data types.

Note that even if the referenced entity exists in the partial book (or will exist later), a reference must still be obtained and added to the reference list for the book itself. This maintains the integrity of the partial book during sequential copy operations.

Parameters

  ent | The known entity.
  param | The parameter to use to get the referenced entity.

Returns
  FALSE on error, otherwise a pointer to the QofEntityReference.

< 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. -# Each QofCollection contains one or many entities - all of a single type. -# The entity type within the collection can be determined at run time. -# Easy conversions to GList or whatever in the param_setfcn handler. -# Each parameter can have its own collection. -# Each entity can have a different type of collection to its siblings, provided that it is acceptable to the set function. -# 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: - Represent a reference between 2 entities with a list of acceptable types. (one object linked to many types of single entities) - Represent a reference between one entity and many entities of another type. (one object linked to many entities of a single type.) 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 167 of file qofreference.c.

168 {
169 g_return_val_if_fail (param, NULL);
170 param = qof_class_get_parameter (ent->e_type, param->param_name);
171 g_return_val_if_fail (0 !=
172 safe_strcmp (param->param_type, QOF_TYPE_COLLECT), NULL);
173 return create_reference (ent, param);
174 }
QOF_TYPE_COLLECT
#define QOF_TYPE_COLLECT
Definition: qofclass.h:93
qof_class_get_parameter
const QofParam * qof_class_get_parameter(QofIdTypeConst obj_name, const gchar *parameter)
Definition: qofclass.c:146
safe_strcmp
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:72

## ◆ qof_session_update_reference_list()

void qof_session_update_reference_list | ( | QofSession * | session,
|  | QofEntityReference * | reference
| ) |  |

Adds a new reference to the partial book data hash.

Retrieves any existing reference list and appends the new reference.

If the book is not already marked as partial, it will be marked as partial.

Definition at line 237 of file qofsession.c.

239 {
240 QofBook *book;
241 GList *book_ref_list;
242
243 book = qof_session_get_book (session);
244 book_ref_list = (GList *) qof_book_get_data (book, ENTITYREFERENCE);
245 book_ref_list = g_list_append (book_ref_list, reference);
246 qof_book_set_data (book, ENTITYREFERENCE, book_ref_list);
247 qof_book_set_partial (book);
248 }
qof_book_get_data
gpointer qof_book_get_data(QofBook *book, const gchar *key)
Definition: qofbook.c:212
qof_book_set_data
void qof_book_set_data(QofBook *book, const gchar *key, gpointer data)
Definition: qofbook.c:191
ENTITYREFERENCE
#define ENTITYREFERENCE
Definition: qofreference.h:137
_QofBook
Definition: qofbook-p.h:48