IOPC2

Even though the library can be divided to several functional units, it compiles as one shared library. The architecture of the library is outlined in the Figure 3.1, “Architecture of the POLiTe library”. The main functional units are discussed in the following sections.

Figure 3.1. Architecture of the POLiTe library

POLiTe contains several classes that provide database access. At the time, the library supports the Oracle 7 database and the code uses OCI^[11] 7 interface to access it. The classes are accessed via common interface that can be used for implementing other RDBMs to the library.

The interface consists of a set of abstract classes - Database, Connection and Cursor. Communication with the database flows exclusively through this interface and its implementation (OracleDatabase, OracleConnection and OracleCursor). The interface Database provides a logical representation of a database (e.g. an Oracle instance), Database can create one or more connections (Connection) to the database. The Connection interface represents the communication channel with the database. Using the implementations of the Connection interface it is possible to send SQL statements to database and receive responses in the form of cursors (Cursor). The response consists of a set of one or more rows that can be iterated through the Cursor.

Every persistent class maintainable by the POLiTe library has to be described by a set of pre-processor macro calls. These calls are included directly into the class definitions or near them. Description of the class attributes and the necessary mapping information has to be provided together with declaration of every persistent class. Metainformation covers class name, associated database table, parents, all persistent attributes with their data types and corresponding table columns and more. For complete list see [08]. Example 3.1, “Definition of a class in the POLiTe library” displays definition of our classes Person and Student in the POLiTe library.

class Person : public PersistentObject {
	// Declare the class, its direct predecessor(s) ...
	CLASS(Person);
	PARENTS("PersistentObject");
	// ... and its associated table
	FROM("PERSON");
	// Define member attributes
	dbString(name);
	dbShort(age);
	// Primary key OID is inherited from PersistentObject
	// Map other attributes
	MAP_BEGIN
		mapString(name,"#THIS.NAME",50);
		mapShort(age,"#THIS.AGE");
	MAP_END;
};
// Define method returning pointer to the prototype
CLASS_PROTOTYPE(Person);
// Define the solitary prototype instance Person_class
PROTOTYPE(Person);

class Student : public Person {
	CLASS(Student);
	PARENTS("Person");
	FROM("STUDENT");
	dbString(studcardid);
	MAP_BEGIN
		mapString(studcardid,"#THIS.STUDCARDID",20);
	MAP_END;
};
CLASS_PROTOTYPE(Student);
PROTOTYPE(Student); // Student_class

class Employee : public Person {
	CLASS(Employee);
	PARENTS("Person");
	FROM("EMPLOYEE");
	dbInt(salary);
	MAP_BEGIN
		mapInt(salary,"#THIS.SALARY);
	MAP_END;
};
CLASS_PROTOTYPE(Employee);
PROTOTYPE(Employee); // Employee_class

Because the library needs to keep track of the dirty status of persistent objects, the programmer has to maintain this flag either by himself or better he should restrict manipulation with persistent attributes to the use of getter and setter methods defined by the macros. For every class T described by these macros the library creates an associated template class prototype Proto<T>. The solitary instance of this prototype class holds information about the metamodel described by the macros and provides the actual database mapping. Prototypes are registered within the ClassRegister. Using ClassRegister, the library and/or application can search for prototypes by their names, and access methods needed for CRUD^[12] operations.

Persistent classes inherit their behaviour from one of four base classes defined in the library - the Object, ImmutableObject, DatabaseObject or PersistentObject class. Depending on what the parent is, different features of the persistence are supported:

As mentioned before, the library offers vertical mapping for descendants of the PersistentObject. Tables related to mapped inheritance hierarchies are joined using the surrogate OID key. If using DatabaseObject descendants, the object model can be created upon an existing (and in case of ImmutableObject descendants even upon the read-only) database tables with arbitrary keys. In this case, however, no inheritance between classes is allowed.

Associations in the POLiTe library are not modelled primarily as references but as instances of the Relation class. There are five subclasses of this class - OneToOneRelation, OneToManyRelation, ManyToOneRelation, ManyToManyRelation and ChainedRelation according to cardinality of the association. Their names describe which kind of relation between the underlying tables they manage. ChainedRelation is built from other relations and it can be used to define relation for indirectly associated objects. Example 3.2, “Associations in the POLiTe library” demonstrates how a one-to-many relation between the Employee and Student classes can be created and used.

OneToManyRelation<Employee, Student> Employee_Student_Supervisor(
  "EMPLOYEE_STUDENT_SUPERVISOR", dbConnection
);

// Let's suggest that the Supervisor variable represents 
// a reference to a "Ola Nordmann" Employee persistent object 
// and Student represents a reference to a "Richard Doe" 
// persistent object.
// Create a supervisor relation between "Ola Nordmann" 
// and "Richard Doe".
Employee_Student_Supervisor.InsertCouple(
  *Supervisor, *Student
);

...
dbPtr(supervisor);
dbString(studcardid);
MAP_BEGIN
mapPtr(supervisor,"SUPERVISOR");
...

Persistent objects can enter one of the following states (see the state diagram in Figure 3.2, “POLiTe persistent object states”):

Figure 3.2. POLiTe persistent object states

e->salary(65000);

does not invoke the setter method on the Ref<Employee> instance, but it looks for the object in the object cache, loads it eventually, and invokes the setter method on it. The process is illustrated by the Figure 3.3, “POLiTe references”.

Figure 3.3. POLiTe references

Object manipulation is illustrated by the Example 3.3, “Persistent object manipulation”. Two objects - an employee and a student which is supervised by that employee are created as transient instances and inserted into the database. The BePersistent() call returns references to unlocked local copies of created objects. Then the salary of the employee is modified and the change propagated to the database. In the end, the student object is deleted from the database and also from the memory.

// Create a new employee
Employee* e = new Employee();
e->name("Ola Nordmann");
e->age(45);
e->salary(60000);
Ref<Employee> employee = e->BePersistent(dbConnection);

// Create a new student supervised by the employee created
Student* s = new Student();
s->name("Richard Doe");
s->age(22);
s->studcardid("WCD-3223");
s->supervisor(empl);
Ref<Student> student = s->BePersistent(dbConnection);

// Update the employee's salary
e->salary(65000);
e->Update(); // Propagates the change to the database
// The change could be propagated immediately if the
// updating strategy was set to the "immediate" setting.

// Delete the new student from the database
s->Delete();
);

Queries in the POLiTe library search for objects of a specified class. Search criteria restricting the result set can be specified. Queries are represented as instances of the Query class which contains only two data fields: The search criteria (in fact the WHERE clause of the final SELECT statement together with the ORDER BY clause specification) determines what object will be returned and how the result will be ordered. The search criteria can be written using SQL (referencing physical table and column names) or using a C++-like syntax. The C++-like syntax hides the O/R mapping complexity and allows the users to use more convenient class and attribute names. The query objects can be then combined using the C++ !, && and || logical operators. Results of the query execution are accessed using instances of the Result<T> template class. The template is used similarly to the Ref<T> template. Example 3.4, “Queries in the POLiTe library” illustrates how the queries are created, combined and executed.

// All employees with salary > 40000
Query q1("Employee::salary > 40000")

// All employees with the first name Ola
Query q2("Person::name LIKE 'Ola %');

// All employees with salary > 40000 having the first name Ola
Query q3 = q1 && q2; 

// Order the result by the salary descending.
q3.OrderBy("Employee::salary DESC");

// Execute q3 and iterate through the result
Result<Employee>* result = Employee_class(q3, dbConnection);
while (++(*result)!=DBNULL) {
  // members of the current object are accessible
  // using (*result)->
};
result->Close();
delete result;

The library provides solid and rich-featured ORM solution. However, there are several areas in which the library can be improved:

These disadvantages are addressed mostly by the IOPC library [04] and its descendant described further in this thesis. But first, we will look at the performance enhancement provided by the succeeding library POLiTe 2.