2 Design and Concepts
This chapter addresses the things that you as a programmer should know about librecord when developing it and use it implement your own address book applications. It helps to understand its architecture and implementation. Armed with this knowledge, you will be better equipped to make this library run with higher performance, avoids potential pitfalls such as deadlocks or unexpected errors and even import any new features on your needs. You will see how librecord works in relation to your code and you can be more confident that you are attacking the problem from the right direction.
2.1 Architecture
Before we get started discussing the principle data structures, let's have a basic view on the architecture of librecord.
Figure 2.1 Architecture of libabenabler
As we can see in the figure 2.1, librecord separates its implementation into independent parts: manipulation and storage. Manipulation part focuses on operations of in-memory Record and relavent structures, while storage part is responsible for how to store all in-memory structures into repository permanently.
2.2 Basic objects
librecord defines a set of basic objects include: Record, Field, FieldDescriptor, FieldTemplate, RecordDB, RecordDBElement, RecordDBRelation, Iterator. We will make a brief introduction of all of these objects.
Record is a core object in librecord library and other objects are used to consist, define or store this object. Record is opaque structure to user and provides a set of manipulation functions to set / get its field's values or other auxiliary properties. A Record is created with a FeildTemplate object which provides the Record default structure layout.
Field is an object to consist a Record object. A Field has its value, printable label and description. A Field can store a single value with specific type which is defined in corresponding FeildDescriptor.
FieldDescriptor is an object to describe a field in a Record object. A FieldDescriptor can define only one field in Record with its identifier, printable label, description, type, attributes and size limitation. A set of FieldDescriptor consist a FieldTemplate object.
FiledTemplate is an object which is consist of a set of FieldDescriptors and represents a default structure layout of Record object.
RecordDB is an object represents a data repository and controls all of the transactions take place in it. A RecordDB can manage more than one RecordDBElement or RecordDBRelation.
RecordDBElement is an object which is responsible for database operations with the specific kind of Record object. A RecordDBElement can only manage one kind of Record object.
RecordDBRelation is an object represents a relationship between record in two RecordDBElements.
Iterator is a public container which is used for passing parameters or returning the result of some interfaces in librecord.
2.3 In-memory Objects
Before stored into a data repository, Record objects are represented as a opaque structure in memory. Inside this opaque structure, there are two crucial components: Fields and fidmaps. Fields is a GHashTable which holds all Field objects in Record. The key of this hash table is field identifier(fid) and value is a pointer points to Field objects. Fidmaps is also a GHashTable which logged maps of Field objects and FieldTemplate objects. The key of this table is a field template identifier and the value is a GArray which contains all the identifiers of Feild objects created from the field template.
As we can see in Figure 2.2, an example of in-memory Record objects is consisted of Fields and Fidmaps. The Record has three fields with identifier 1001, 2001 and 2002. Through the Fidmaps, we can get the relationship between fields and field templates. The field 1001 is created from field template 001, while the field 2001 and field 2002 are created from field template 002.
Figure 2.2 Structure of Record object
2.4 Database repository
Reocrd object is stored in a data repository by using three tables:
o Template table
o Primary table
o Extend table
Here just an example to demonstrate the database structure and in-memory structure of a contact object. We define the contact has such four basic field:
UID 1 INTEGER
NAME 2 STRING
PHONE 3 STRING
ADDR 4 STRING
The FieldTemple object of a Record object will be stored in a table named "Template table" as Table 2.1 shown:
Table 2.1 FieldTemplate table
|
FTID |
LABEL |
DESC |
TYPE |
SIZE |
FLAG |
|
1 |
UID |
Unique Identifier |
INTEGER |
4 |
0x00000000 |
|
2 |
Name |
Full Name |
STRING |
40 |
0x00000000 |
|
3 |
Phone |
Phone Number |
STRING |
20 |
0x00000001 |
|
4 |
Address |
Address |
STRING |
80 |
0x00000001 |
Basic information of a Record object will be stored in a table named "Primary Table". A row in the table represents a Record object and the primary value of each field in contact object will be place in the separated columns of this row. The EXT FLAG column of each row indicates whether the contact relative to this row has any extended information in the "Extended Table". All the specific set and get function to the default field of contact object will directly affect values in table 2.2.
Table 2.2 Primary table
|
UID(FTID1) |
NAME(FTID2) |
PHONE(FTID3) |
ADDR(FTID4) |
EXT FLAG |
|
001 |
AAA |
139xxxxxxx |
OOOO |
1 |
|
002 |
BBB |
138xxxxxxx |
PPPP |
0 |
|
003 |
CCC |
136xxxxxxx |
QQQQ |
1 |
Extend information of a Record object will be stored in a table named "Extend Table" if and only if the EXT FLAG column of contact in Primary Table is set to 1. The extend information of a contact object will be stored in a set of rows in Extend Table. The rows with the same UID (FTID1) are relative to a contact object. FIDs column represent which fields in contact object the rows decribe. FID is generated with the formula (i.e. FID = FTID x 100 + Index. That means if the FTID in template is 2, the corresponding FIDs in Extend Table are 200, 201, 202, and etc). The rows with NULL LABLE and DESC column mean that these rows just describe extend values for specific fields. The rows with NULL VALUE columns mean that there rows just describe customized information of specific fields. See Table 2.4:
Table 2.3 Extend table
|
UID(FTID1) |
FID |
LABEL |
DESC |
VALUE |
|
001 |
201 |
NULL |
NULL |
138xxxxxxxx |
|
001 |
202 |
NULL |
NULL |
135xxxxxxxx |
|
001 |
300 |
Home Phone |
Home Phone Number |
NULL |
|
003 |
401 |
NULL |
NULL |
RRRR |
|
003 |
402 |
NULL |
NULL |
SSSS |
|
003 |
403 |
Home Address |
Home Address |
TTTT |
For examples, if we add new phone number 138xxxxxxxx for contact with uid 001, then we will get the row in Extend Table:
|
UID(FTID1) |
FID |
LABEL |
DESC |
VALUE |
|
001 |
201 |
NULL |
NULL |
138xxxxxxxx |
If we wnat to modify the label and description of Phone field for contact with UID 001, then we get the row in Extend Table:
|
UID(FTID1) |
FID |
LABEL |
DESC |
VALUE |
|
001 |
300 |
Home Phone |
Home Phone Number |
NULL |