qofreference.h File Reference


Detailed Description

Dealing with relationships between entities in partial books.

Author:
Copyright (c) 2006 Neil Williams <linux@codehelp.co.uk>

Definition in file qofreference.h.

#include "qof.h"

Go to the source code of this file.

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.

#define ENTITYREFERENCE   "QofEntityReference"
#define PARTIAL_QOFBOOK   "PartialQofBook"
 Flag indicating a partial QofBook.
typedef qof_entity_reference QofEntityReference
 External references in a partial QofBook.
void qof_session_update_reference_list (QofSession *session, QofEntityReference *reference)
 Adds a new reference to the partial book data hash.
void qof_book_set_references (QofBook *book)
 Read QofEntityReference data for this book and set values.
QofEntityReferenceqof_entity_get_reference_from (QofEntity *ent, const QofParam *param)
 Get a reference from this entity to another entity.


Define Documentation

#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 135 of file qofreference.h.

#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 144 of file qofreference.h.


Typedef Documentation

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

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 210 of file qofreference.c.

QofEntityReference* qof_entity_get_reference_from QofEntity ent,
const QofParam param
 

Get a reference from this entity to another entity.

< 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 it's own collection.
  5. Each entity can have a different *type* of collection to it's 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:

  • 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 175 of file qofreference.c.

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 328 of file qofsession.c.

00329 {
00330         QofBook  *book;
00331         GList    *book_ref_list;
00332 
00333         book = qof_session_get_book(session);
00334         book_ref_list = (GList*)qof_book_get_data(book, ENTITYREFERENCE);
00335         book_ref_list = g_list_append(book_ref_list, reference);
00336         qof_book_set_data(book, ENTITYREFERENCE, book_ref_list);
00337         qof_book_set_partial(book);
00338 }


Generated on Fri May 12 18:00:35 2006 for QOF by  doxygen 1.4.4