The IOPC 2 library can be used in several configurations (the section called “Library architecture”). Depending on the selected configuration, corresponding initialization and termination routines must be called. These routines are listed in the Table A.1, “Library configurations and their initialization/termination routines”. Configurations are ordered by ascending complexity and so by amount of features they provide. First row of the table contains the most basic configuration - the iopccommon library. Libraries/configurations in following rows depend on libraries from previous rows and also implicitly call their initialization/termination routines. So calling the initialization/termination routine only for the selected configuration is sufficient. There exist also header files with the "Headers" suffix in their names (like iopcMetaHeaders.h or iopcDbHeaders.h), which include most commonly used header files for the selected configuration.

Basic library setup for a configuration that uses IOPC 2 as a database access library can then look like this:

// Include all commonly used headers for the
// iopcdb configuration
#include "iopcdb/iopcDbHeaders.h"

// IOPC 2 structures are defined within the iopc napespace
using namespace iopc;

int main(int argc, char *argv[])
{
  try {
    // Initializes the library and also sets the LogWriter masks
    // Throws an exception if not successful
  	IopcDb::init(LogWriter::ERROR, LogWriter::ERROR | 
      LogWriter::WARNING);
  	
  	// ... 
  
    // Library cleanup. Releases allocated resources, 
    // closes open connections.
  	IopcDb::shutdown();
  } catch (IopcException& e) {
    // Error handling
  }
}

Reflection and object persistence features will be presented on the following classes. We will start with a simple class hierarchy with which we are already familiar from the the section called “Database mapping requirements”. To present the provided reflection mechanism and later the database mapping, we need to define some test classes. Additional features will be added later.

// We use the reflection library configuration
#include "iopcmeta/iopcMetaHeaders.h"
#include <string>

using namespace std;

class Person : public iopc::Object {
public:
	EString name;
	EShort age;
};
class Employee: public Person {
private:
	EInt salary;
public:
	Employee() {};
	Employee(string name, short int age, int salary) {
		this->name = name;
		this->age = age;
		this->salary = salary;
	}
	void setSalary(int salary) {
		this->salary = salary;
	};
	int getSalary() {
		return salary;
	};
	friend class iopc::TypeDesc<Employee>;
};
class Student : public Person {
public:
	EString studcardid;
};
class PhdStudent : public Student {
public:
	EShort scholarship;
};

Classes discoverable by the IOPC 2 reflection must conform to the following rules:

Attribute definitions use enhanced data types (see the section called “Enhanced data types”). This will come in handy later in sections discussing object persistence and querying.

To see how to use the reflection interface, we will provide a set of examples which demonstrate its features. The code should be placed between the init and shutdown calls which we presented in the first example.

Following example lists all data types that are recognised by the reflection mechanism.

const map<string, const Type*>& types = 
  TypeManager::getTypesMap();
cout << "Registered types:" << endl;
for(
  map<string, const Type*>::const_iterator it = types.begin(); 
  it != types.end(); it++) {
	cout << (*it).first << endl;
}

When compiled using the supplied makefile/compile script or using the managed-build Eclipse project and when run, the program will print a list of types registered by the TypeManager singleton (see the section called “The metamodel”).

::Employee             iopc::EBool
::Person               iopc::EChar
::PhdStudent           iopc::EDouble
::Student              iopc::EFloat
::bool                 iopc::EInt
::char                 iopc::ELDouble
::double               iopc::ELong
::float                iopc::ESChar
::int                  iopc::EShort
::long                 iopc::EString
::long double          iopc::EUChar
::short                iopc::EUInt
::signed char          iopc::EULong
::unsigned char        iopc::EUShort
::unsigned int         iopc::EWCharT
::unsigned long        iopc::EWString
::unsigned short       iopc::Object
::wchar_t              
std::string            
std::wstring

The types can be divided into three categories:

All the listed types can be used as attribute types. Attributes of other types are ignored^[32]. Complex type attributes cannot be however persisted by the object persistence layer (iopclib) at the moment. In this case, complex type attributes must be marked as transient using the attribute metadata db.transient. See Appendix C, Metadata overview.

The programmer can use the reflection for more complex tasks, as it is shown in following examples.

First, we obtain an object which represents a type description. See the section called “The metamodel classes”.

const Type& t = TypeManager::getType("::Person");

The TypeManager::getType() call searches in the catalogue of registered types for the type of given name and returns its description. The type description is obtained as a reference to a Type object representing the requested type. This class provides many methods that can be used to introspect the structure of the associated type. The type description can be also obtained in a static way:

const Type& t = TypeDesc<Person>::getType()

Having the Type reference we can start examinig the Person class by obtaining a list of its parents:

const Type::ParentsList& parents = t.getParents();
for(Type::ParentsIterator it = parents.begin(); 
  it != parents.end(); it++) {
	cout << (*it)->getQualifiedName() << endl;
}

If we are not using multiple inheritance, the following method can be used:

cout << t.getFirstParent().getQualifiedName() << endl;

The example prints:

iopc::Object

Similarly, we list the child types of the Person class.

const Type::ChildrenList& children = t.getChildren();
for(Type::ChildrenIterator it = children.begin(); 
  it != children.end(); it++) {
  cout << (*it)->getQualifiedName() << endl;
}

We get the following output:

::Employee
::Student

If we want to obtain even indirect parents or children, we have to use the Type::getAllParents() or Type::getAllChildren() methods instead.

Attributes can be listed using the following code:

const Type::AttributesMap& attributes = t.getAttributes();
for(Type::AttributesIterator it = attributes.begin(); 
  it != attributes.end(); it++) {
  
	const Attribute& attr = it->second;
	switch (attr.getVisibility()) {
		case Attribute::VISIBILITY_PUBLIC: cout << "public "; break;
		case Attribute::VISIBILITY_PRIVATE: cout << "private "; break;
		case Attribute::VISIBILITY_PROTECTED: cout << "protected "; break;
	}
	cout << it->second.getType().getQualifiedName() 
    << " " << it->first << endl;
}

The example iterates over a map whose keys are attribute names and values are Attribute class instances. Using Attribute methods we can obtain attribute names, their data types (which are again described by the familiar Type interface) and determine if the attributes were declared as private, protected or public. In a similar way, inherited attributes can be listed using the Type::getInheritedAttributes() method. The previous code yields the following output:

public iopc::EString name
public iopc::EShort age

Using reflection we can also create objects or manipulate with values of their attributes (regardless of their visibility). In the following example we create a new instance of the Employee class and initialise values of all of its attributes.

Employee* e = dynamic_cast<Employee*>(
  TypeManager::getType("::Employee").newObjectInstance());
*((EString*)e->getAttributeValue("name").getValue()) = 
  "Ola Nordmann";
*((EShort*)e->getAttributeValue("age").getValue()) = 45;
*((EInt*)e->getAttributeValue("salary").getValue()) = 60000;
cout << e->name << " " << e->age << " " << e->getSalary() << endl;

The Object::getAttributeValue() method returns an instance of the AttributeValue which allows us to get or set values of the attribute it represents. Using its getValue() method we obtain a void pointer to the requested field in the Employee instance. By casting it to the actual attribute data type we can manipulate with its value. Output of the example is:

Ola Nordmann 45 60000

Attribute values can be iterated similarly as attributes. The list of attribute values can be obtained using the Object::getAttributeValues() method:

const Object::AttributeValuesMap& attrVals = 
  e->getAttributeValues();
for(Object::AttributeValuesIterator it = attrVals.begin(); 
  it != attrVals.end(); it++) {
  
  const AttributeValue& val = it->second;
	cout << it->first << ": ";
	if (val.getAttribute().getType().getDataTypeClass() == Type::IOPC_TYPECLASS_ENHANCED) {
	 cout << ((EnhancedTypeBase*)val.getValue())->toString() 
    << endl;
  }
}

In the example we take advantage of the enhanced data types and of the Object::toString() method they implement. For regular objects it prints just an address on which they reside in the memory. It is however overridden by the enhanced data type implementations so that the returned string contains a value they represent. Output of the example is:

age: 45
name: Ola Nordmann
salary: 60000

Types recognised by the reflection are categorised into several groups called type classes. They help to easily determine their "nature":

Last thing we may need from the reflection interface is the ability to compare the types. For example, we may want to ask if some type is descendant of another type or if it represents the same type. The following example illustrates how such comparisons can be done in IOPC 2.

const Type& t1 = TypeDesc<Person>::getType();
const Type& t2 = TypeDesc<Student>::getType();
if (t1 == t2) { cout << "t1 is t2" << endl; }
if (t1 != t2) { cout << "t1 is not t2" << endl; }
if (t1.isTypeOf(t2)) { cout << "t1 is t2 or t1 is descendant of t2" << endl; }
if (t2.isTypeOf(t1)) { cout << "t1 is t2 or t2 is descendant of t1" << endl; }
if (t1.is<Student>()) { cout << "t1 is of type Student" << endl; }
if (t2.is<Student>()) { cout << "t2 is of type Student" << endl; }
if (t1.isTypeOf<Person>()) { cout << "t1 is of type Person or its descendant" << endl; }
if (t2.isTypeOf<Person>()) { cout << "t2 is of type Person or its descendant" << endl; }

Output of the example is:

t1 is not t2
t1 is t2 or t2 is descendant of t1
t2 is of type Student
t1 is of type Person or its descendant
t2 is of type Person or its descendant

The concept of class metadata was explained in the section called “Class metadata”. Basically, class metadata can be specified on three levels:

Metadata specified at a higher level are inherited by objects at lower levels. So if we specify metadata for a type, all attributes of that type inherit such information. If we specify the same metadata on an attribute, the type level metadata are overridden by the attribute level metadata. Global level metadata are inherited by both, the type and attribute objects.

The Type and Attribute classes inherit from the MetadataHolder. MetadataHolder::getDefaultsMeta() returns a MetadataHolder instance directly. MetadataHolder provides its descendants with a dictionary-like interface as illustrated by the following example:

// Global level metadata (all objects will use ADT mapping)
MetadataHolder& globalMeta = MetadataHolder::getDefaultsMeta();
globalMeta["db.mapping.type"].setStringValue("object");

// Type level metadata
// The ADT type associated with the Person class
// will be named Person_type. (The default is tPerson).
const Type& t = TypeDesc<Person>::getType();
t["db.type"].setStringValue("Person_type");

// Attribute level metadata
// The Person::name attribute will be a 20 characters long string
t.getAttribute("name")["db.type.length"].setIntValue(20);

Class metadata can be set in three different ways at the program start-up. First way is to set metadata in the static method iopcInit() which can be defined for each reflection-capable type. It is used to set type level and attribute level metadata for the class in which it is defined. iopcInit() methods are invoked during the iopcMeta library initialisation (IopcMeta::Init()). To demonstrate how iopcInit is used, we modify the Person class definition:

class Person : public iopc::OidObject {
public:
	EString name;
	EShort age;
	
	static void iopcInit(iopc::Type& t) {
		t["db.type"].setStringValue("Person_type");
		t.getAttribute("name")["db.type.length"].setIntValue(20);
	}
};

Second way is to implement the MetadataInitializer interface declared in iopcmeta. It defines only one method - initializeMetadata() - into which we can insert the metadata initialization code. In this case, the global level values can also be set. The instance of the MetadataInitializer implementation is then passed as first parameter to any of the iopcmeta, iopcdb or iopclib initialisation methods:

class OurMetadataInitializer : public MetadataInitializer {
public:
  virtual void initializeMetadata();
};
...
void OurMetadataInitializer::initializeMetadata()
{
  // metadata initialisation code
  // same as in the first example of this section
}
...
int main(int argc, char *argv[])
{
  Iopc::init(new OurMetadataInitializer(), LogWriter::ERROR ... );
  ...
}

The OurMetadataLoader instance is deallocated during the library initialization after its initializeMetadata() method is called. During the initialization phase, iopcInit() methods are invoked before MetadataInitializer::initializeMetadata(), so the metadata changes done in MetadataInitializer::initializeMetadata() may overwrite metadata created in the iopcInit() methods.

iopcmeta contains a MetadataInitializer implementation named TextFileMetadataLoader which represents the last way how we can set the class metadata. Its constructor takes a single parameter, a filename (may include a path as well) of a configuration file, which contains a description of metadata assignments. The class is used in the same way as the OurMetadataInitializer in previous example. When its initializeMetadata() method is invoked, it loads the configuration file and sets all global level, type level and attribute level metadata according to it.

The format of the configuration file is illustrated by the following example:

# global level
defaults[db.mapping.type];string;object
# type level
::Person[db.type];string;Person_type
# attribute level
::Person::name[db.type.length];int;20

TextFileMetadataLoader skips all empty lines or lines starting with the '#' character. The file is case-sensitive. Lines describing the metadata contain three semicolon delimited values. First value specifies the location and code of the metadata to be set. It uses the same format as metadata in queries (see the section called “Querying”). Second column denotes the data type of the metadata value. Only string, int and bool values are allowed. Last column contains the metadata value. Boolean values can be either true or false.

One additional class based on the MetadataHolder container class is the GlobalSettings class. Its global instance is defined in iopccommon/globalSettings.h. Although it is based on the MetadataHolder class, it does not contain any class metadata. It is used to provide application-wide settings. The settings can be specified using the following line in the TextFileMetadataLoader configuration file:

# global settings
globals[db.oracle.oidSequence.name];string;MyOIDSeq

Database* db = 
  DriverManager::getDriver("IopcOracle10g").getDatabase("XE");
Connection* conn = 
  db->getConnection("username=iopc;password=iopc");
conn->open();

By calling the Database::getConnection() method a physical link to the DBMS is established^[33] and a Connection object representing the link is returned. The string passed to the Database::getConnection() method is called connection string. The connection string syntax may vary between different drivers. For the Oracle10g driver the string is a semicolon delimited list of key-value pairs as shown in the example. Recognised keys are:

When the connection is no longer needed, it should be closed and returned back to the database object by calling db->returnConnection(conn). The same goes for the database and driver:

...
conn->close();
db->returnConnection(conn);
DriverManager::getDriver("IopcOracle10g").returnDatabase(db);
// alternatively:
DriverManager::returnDatabase(db);

Oracle10g driver supports transactions^[34]. First SQL statement executed after the connection is created begins first transaction. Transactions can be ended by calling Connection::commit() or Connection::rollback(). Next transaction starts again when next SQL statement is executed. In the Oracle10g database driver each transaction get committed implicitly whenever a DDL statement is issued. Closing an open connection also commits any running transaction. If autocommit is enabled, transactions are committed immediately everytime after any SQL statement is executed.

Connection::savePoint() and Connection::rollbackToSavePoint() operations are also provided by the Connection interface. They interact with the cache analogously.

Simple commands that do not return any value and that are not parameterised can be executed using the sqlNonQuery method. Let's create a new table and insert some testing values into it.

conn->sqlNonQuery("CREATE TABLE blacklist(id NUMBER PRIMARY KEY, name VARCHAR2(20))");
conn->sqlNonQuery(
  "INSERT INTO blacklist VALUES(1, 'Richard Doe')");
conn->sqlNonQuery(
  "INSERT INTO blacklist VALUES(2, 'Ola Nordmann')");
// we have to call commit() because autocommit is disabled
// for conn
conn->commit();

Now we will load and print the inserted data:

Cursor* cur = conn->sql("select id, name from blacklist");
std::string name;
int id;
cur->addOutParam(1, &id, TypeDesc<int>::getType());
cur->addOutParam(2, &name, TypeDesc<std::string>::getType());
cur->execute();
while (cur->fetchNext()) {
	cout << id << " " << name << endl;
}
cur->close();
conn->returnCursor(cur);

By calling the Connection::sql() method we obtain a Cursor which represents results of the query passed to the method. The query is not yet executed; nothing is sent to the database system until the Cursor::execute() is invoked. Before we execute the query, we may specify input and output parameters (if any). This is done by calling one of the Cursor::addXXParam(), Cursor::addEnhancedXXParam() where XX is "In" or "Out", or Cursor::addNullInParam(). Whether to call the first or the second (enhanced) method depends on if we are going to use enhanced data type or basic C++ data type (plus the STL strings) parameters. The example above uses the basic variant.

First parameter specifies the parameter position in the query^[35] and second parameter the variable to be stored/loaded. Last parameter of the Cursor::addXXParam method tells the database layer of what type the value passed as pointer in the second parameter is. In some situations, the database layer and drivers must know the memory size (sizeof) occupied by the input or output parameters. This information is also obtained from the type descriptions. However, because memory occupied by string parameters (STL or enhanced) is of variable size, a number describing memory size to be allocated for buffers needed by the database layer must be specified. This number is defined as maximum string length and defaults to 2000 characters. It can be overridden by supplying the last argument of the Cursor::addXXParam methods in this way:

MetadataHolder meta;
meta["db.type.length"].setIntValue(100);
cur->addOutParam(1, &id, TypeDesc<int>::getType());
cur->addOutParam(2, &name, TypeDesc<std::string>::getType(), meta);

The db.type.length metadata can be also specified on the type or attribute level as described in the section called “Class metadata”. Type level represents the default value for all parameters of such type (by default 2000 as mentioned above), attribute level is used by the object persistence layer - see later in this guide.

Same example as above, this time using the enhanced data types:

Cursor* cur = conn->sql("select id, name from blacklist");
EString name;
EInt id;
// OUT parameters can be added any time before fetch is invoked
// - even after execute
cur->addEnhancedOutParam(1, id);
cur->addEnhancedOutParam(2, name);
cur->execute();
while (cur->fetchNext()) {
	cout << id << " " << name << endl;
}
cur->close();
conn->returnCursor(cur);

As you see, specifying enhanced data type parameters is even simpler, the additional type description is not needed.

If the cursor is not needed, it should be closed to free blocked database resources. If it is not needed any longer, it should be released by returning it back to its connection which also releases allocated application resources. After the cursor is closed, it can be re-opened and executed again (it even be re-executed without closing and opening). The parameters are not discarded. If a cursor is returned back to its connection in an open state, it is automatically closed.

Input pramaters are used in a similar way:

Cursor* cur = conn->sql(
  "SELECT name from blacklist where id = :id");
EString name;
EInt id = 2;
cur->addEnhancedOutParam(1, name); // first input parameter
cur->addEnhancedInParam(1, id); // first output parameter
cur->execute();
while (cur->fetchNext()) {
	cout << id << " " << name << endl;
}
cur->close();
conn->returnCursor(cur);

This example loads and print only the second row inserted ("Ola Nordmann").

All objects from the iopcdb library are thread safe except for the Cursor class, which should be used always only from one thread.

Driver features were introduced in the section called “Driver features”. A driver feature is actually an interface (abstract class) which each driver may or may not implement. Two basic features are defined by iopcdb - the TypeMappingFeature and SqlStatementsFeature. See their documentation for detailed description.

The database driver feature interface provides basically only two things - it allows us to ask whether the driver supports the feature specified and allows us to obtain a reference to its implementation. This is best illustrated by an example:

Driver& d = conn->getDriver();
if (d.supportsFeature<SqlStatementsFeature>()) {
	TypeMappingFeature& f = d.getFeature<TypeMappingFeature>();
	string sqlType = f.getTypeSql(TypeDesc<string>::getType());
	cout << sqlType << endl;
}

First, we obtain a driver reference from an existing connection. We want to use the TypeMappingFeature to obtain a SQL type definition for the std::string type. Then we ask, if the driver even supports such feature and finally we obtain a reference to its implementation. Having reference to the feature implementation we may call methods of the feature according to its interface and documentation. This example returns a VARCHAR2(2000) string representing a SQL type which corresponds to std::string. The number 2000 is taken from the db.type.length default metadata specified on the std::string type.

The most complex configuration of the IOPC 2 library we can use is iopclib. It contains all features described to this point, plus it offers object persistence using four kinds of database mapping - vertical, horizontal, filtered and ADT. Objects that can be persisted must derive from the DatabaseObject or OidObject classes. We will start with the OID objects as they are easier to handle and offer more functionality. Let's take the classes defined in the section called “Inspecting objects with reflection” and prepare them for the persistence layer.

// Use the iopclib headers
#include "iopclib/iopcHeaders.h"

using namespace iopc;
class Person : public iopc::OidObject {
public:
	EShort age;
	EString name;
};
class Employee : public Person {
public:
	EInt salary;
};
class Student : public Person {
public:
	EString studcardid;
	DbPtr<Employee> supervisor;

	static void iopcInit(iopc::Type& t) {
		t["db.mapping.type"].setStringValue("horizontal");
	}
};
class PhdStudent : public Student {
public:
	EShort scholarship;

	static void iopcInit(iopc::Type& t) {
		t["db.mapping.type"].setStringValue("filtered");
		t["db.mapping.insertto"].setStringValue("::Student");
	}
};

We changed the predecessor of the Person class to OidObject as we intend to use OID objects. We also specified some metadata that modify the default mapping type from vertical to horizontal for the Student class and filtered for the PhdStudent class. If filtered mapping is used, the db.mapping.insertto metadata must also be specified. The ::Student value tells the library that attributes of the PhdStudent class will be stored into the table associated with the Student class.

Before we can start using these classes, we must prepare required database schema. ScriptsGenerator can be used for this task as described in the section called “Database mapping”. Once more, the code snippet that creates the database schema for persistent classes in the application:

vector<string> script;
script = ScriptsGenerator::getDbCreateScript(conn->getDriver());
for(vector<string>::const_iterator it = script.begin(); 
  it != script.end(); it++) {
	conn->sqlNonQuery(*it);
}

When manipulating persistent objects, we need to use CachedConnection decorator for the standard connection usually obtained. There is also the CachedDatabase class which decorates the "basic" database and creates already decorated CachedConnections. The reason why we are using these decorators is that the caching layer is tightly integrated with the object persistence layer and object persistence cannot be used without it. The CachedConnection provides us with additional methods for cache manipulation. It can be created in the following way:

CachedDatabase* db = new CachedDatabase(
  DriverManager::getDriver("IopcOracle10g").getDatabase("XE"), 
  new VoidCache());
CachedConnection* conn = 
  (CachedConnection*)db->getConnection("username=iopc;password=iopc");
conn->open();

CachedConnection needs to have an associated cache. In this scenario we use the basic cache implementation - the VoidCache - see the section called “The cache layer”.

Now, we have all the prerequisites we need to be able to manipulate persistent objects. First, we create some persistent objects and store them in the database.

DbPtr<Person> person;
person->name = "Mary Major";
person->age = 60;
person.bePersistent(conn);

DbPtr<Employee> employee;
employee->name = "Ola Nordmann";
employee->age = 45;
employee->salary = 60000;
employee.bePersistent(conn);

DbPtr<Student> student;
student->name = "Richard Doe";
student->age = 22;
student->studcardid = "WCD-3223";
student->supervisor = employee;
student.bePersistent(conn);;

DbPtr<PhdStudent> phd;
phd->name = "Joe Bloggs";
phd->age = 27;
phd->studcardid = "PHD-1234";
phd->scholarship = 12000;
phd->supervisor = employee;
phd.bePersistent(conn);
conn->commit();

Transient instance of a persistent class is automatically created by declaring a variable of a database pointer type as shown in the example. Its attributes are accessible using the ->. The DbPtr::bePersistent() method then transfers the ownership of the transient instance to the cache associated with the connection conn. In this case, the VoidCache immediately inserts the object into corresponding database table.

If we used another cache, the objects might be inserted into the database later. However, the CachedConnection::commit() method call forces the associated cache to store all changes (including new objects) into the database before the actual commit is issued to the database. This update can be invoked manually by calling CachedConnection::updateDirty(). Actually, commit calls CachedConnection::updateDirty() to perform the update. Analogously, CachedConnection::removeAll() is called before CachedConnection::rollback() to discard all changes or new objects by emptying the associated cache. (The objects will be loaded from database into the cache again as soon as they are accessed).

Note that when we assign a database pointer to the supervisor reference attribute, the database pointer must already point to an instance which is managed by a cache. That means that DbPtr::bePersistent() must have already been called on the database pointer before.

Every time we access attributes of a persistent object managed by a cache using the -> operator, the object is looked up in the cache and returned as a cache pointer - CachePtr. Then the attribute is accessed and the cache pointer instance is destroyed. If we use the VoidCache, the object is even loaded from the database every time when the CachePtr is created and stored back when destroyed. If the object is transient, just the CachePtr is created and destroyed repeatedly, cache is not used.

If we want to prevent such behaviour to speed up repeated access to the persistent object attributes, we need to store the CachePtr instance into a variable. This can be done in two ways:

// Using the getCachePtr() method
CachePtr<PhdStudent> phdPtr = phd.getCachePtr();

// or by dereferencing the DbPtr using the * operator:
CachePtr<PhdStudent> phdPtr = *phd;

We may now modify the attributes, the persistent object is locked in the cache. If we want the cache to take back the control of the persistent object, we must release the cache pointer. Cache pointer can be released either explicitly by calling the CachePtr::release() or implicitly by destroying its instance:

 // explicitly
CachePtr<PhdStudent> phdPtr = *phd;
phdPtr->scholarship = 13000;
phdPtr->supervisor = employee;
phdPtr.release();

// implicitly:
{
	CachePtr<PhdStudent> phdPtr = *phd;
	phdPtr->scholarship = 13000;
	phdPtr->supervisor = employee;
}

Persistent objects can be locked for read-only access using the DbPtr::getConstCachePtr() call. We cannot modify the object attributes, but the advantage is that the cache lock used in this case is not exclusive and the object can be locked in this way by more threads at a time.

Cache pointers may be copied. The lock is released as soon as last instance of the cache pointers is released or destroyed. Database pointers may also be copied, the behaviour of the copies depends on whether we are copying a pointer to a transient object or to an object managed by a cache. Copies of the transient objects are reference counted. We are not allowed to call the DbPtr::bePersistent() method if more than one reference pointing exists. In such case an exception would be thrown.

By creating a copy of a database pointer pointing to a cache managed object, only its identity (PersistentIdentification) and connection information are copied. If we delete the object using one of the pointers from cache and from the database and then access its attributes using different pointer, we get an exception saying that such object could not be found in the database.

// Copying cache pointers
CachePtr<PhdStudent> phdPtr2 = phdPtr;

// Copying database pointers
DbPtr<PhdStudent> phd2 = phd;

DbPtr provides two additional noteworthy methods - DbPtr::dbDelete() and DbPtr::cacheDelete(). The first method deletes the persistent object from the database as well as from the cache, the second one hints the cache to drop its cached local copy (the hint may be ignored).

CREATE TABLE blacklist(id NUMBER PRIMARY KEY, name VARCHAR2(20));
INSERT INTO blacklist VALUES(1, 'Richard Doe');
INSERT INTO blacklist VALUES(2, 'Ola Nordmann');

class BlacklistEntry : public iopc::DatabaseObject {
public:
	EInt externalId;
	EString name;

	static void iopcInit(iopc::Type& t) {
		t["db.table"].setStringValue("blacklist");
		t.getAttribute("externalId")["db.column"].setStringValue("id");
		t.getAttribute("externalId")["db.primaryKey"].setBoolValue(true);
		t.getAttribute("name")["db.type.length"].setIntValue(20);
		// not necessary, attribute name and column name are the same:
		t.getAttribute("name")["db.column"].setStringValue("name");
	}
};

Because the name of the class and the names of its attributes differ from the schema, we must specify class metadata which describe mapping between this class and the blacklist table. The metadata can be specified in a configuration file as well (see the section called “Class metadata”). Metadata used in this example are listed in the following table:

The simplest way to load an object is to pass its OID or key values to the DbPtr constructor. In the following example, we will load a blacklist entry with id 2:

KeyValues key;
key.add("externalId", 2);
DbPtr<BlacklistEntry> entry(conn, key);
cout << entry->externalId << ": " << entry->name << endl;

Output of the example is:

2: Ola Nordmann

Because the class has identity defined, we can modify the loaded object or even create a new one:

DbPtr<BlacklistEntry> newEntry;
newEntry->externalId = 3;
newEntry->name = "Mary Major";
newEntry.bePersistent(conn);

Now, to the objects wihtout identity. We create a class that will represent USER_TABLES view from the Oracle Data Dictionary, and we will use it to list all tables in the current schema.

class UserTable : public iopc::DatabaseObject {
public:
	EString tableName;
	EString tablespaceName;

	static void iopcInit(iopc::Type& t) {
		t["db.transient"].setBoolValue(true);
		t["db.table"].setStringValue("USER_TABLES");
		t.getAttribute("tableName")["db.column"].setStringValue("TABLE_NAME");
		t.getAttribute("tableName")["db.type.length"].setIntValue(30);
		t.getAttribute("tablespaceName")["db.column"].setStringValue("TABLESPACE_NAME");
		t.getAttribute("tablespaceName")["db.type.length"].setIntValue(30);
	}
};

The db.transient metadata tells the library that the class is transient and that it does not have an identity. If we did not specify this metadata, an exception would be thrown during the library initialisation routine saying that the class needs at least one primary key to be defined.

Basic query that just returns all rows from a table associated with the specified class is very simple. We do not need to construct any Query objects:

Result<UserTable> userTables(conn);
userTables.open();
for (Result<UserTable>::iterator it = userTables.begin(); 
  it != userTables.end(); it++) {
	cout << it->tableName << "   " << it->tablespaceName << endl;
}
userTables.close();

The example lists all tables from the current schema along with tablespaces containing the tables. Query is executed by calling the Result<T>::open() method, a database cursor is created. The results can be then iterated as shown in the example. To free the allocated database cursor, Result<T>::close() must be called when the result is not needed any more.

If we want to filter or to sort the query results, we must create a SimpleQuery instance and specify our needs. The following example lists the table names in ascending order and restricts the table results to tables from the USERS tablespace.

SimpleQuery q(
  "$::UserTable::tablespaceName$ = 'USERS'", "$::UserTable::tableName$ ASC");
Result<UserTable> userTables(conn, q);
userTables.open();
for (Result<UserTable>::iterator it = userTables.begin(); 
  it != userTables.end(); it++) {
	cout << it->tableName << " " << it->tablespaceName << endl;
}
userTables.close();

First parameter of the SimpleQuery constructor filters the query result, it is inserted into the WHERE part of the resulting SQL query. Second parameter represents the ORDER BY part. For the query format description please refer to the section called “Querying”.

Finally, database object classes even need not to be bound to one table, they can represent results of any query. In the following example, we add a columnCount attribute to the UserTable class to represent number of columns of each table. If we join the USER_TABLES and USER_TAB_COLS tables, we may calculate the column count by grouping the results by TABLE_NAME (and TABLESPACE_NAME) and by adding a COUNT(*) column. The modified UserTable class would look like this:

class UserTable : public iopc::DatabaseObject {
public:
	EString tableName;
	EString tablespaceName;
	EInt columnCount;

	static void iopcInit(iopc::Type& t) {
		t["db.transient"].setBoolValue(true);
		t.getAttribute("tableName")["db.column"].setStringValue("TABLE_NAME");
		t.getAttribute("tableName")["db.type.length"].setIntValue(30);
		t.getAttribute("tablespaceName")["db.column"].setStringValue("TABLESPACE_NAME");
		t.getAttribute("tablespaceName")["db.type.length"].setIntValue(30);
		t.getAttribute("columnCount")["db.column.sql"].setStringValue("COUNT(*)");
		// Not necessary:
		t.getAttribute("columnCount")["db.column"].setStringValue("COLUMN_COUNT");
	}
};

The db.table metadata was removed. The db.column.sql metadata specifies the column expression used to select value for this attribute. It is rendered as COUNT(*) AS column_name.

Instead of SimpleQuery we now use a FreeQuery instance because it allows us to specify everything after the FROM keyword in the SQL SELECT statement:

FreeQuery q("USER_TABLES JOIN USER_TAB_COLS USING (TABLE_NAME) GROUP BY TABLESPACE_NAME, TABLE_NAME");
Result<UserTable> userTables(conn, q);
userTables.open();
for (Result<UserTable>::iterator it = userTables.begin(); 
  it != userTables.end(); it++) {
	cout << it->tableName << " " << it->tablespaceName << " " 
    << it->columnCount << endl;
}
userTables.close();

The resulting SELECT statement will be:

SELECT 
  COUNT(*) AS COLUMN_COUNT, 
  TABLE_NAME, 
  TABLESPACE_NAME 
FROM 
  USER_TABLES JOIN USER_TAB_COLS USING (TABLE_NAME) 
GROUP BY 
  TABLESPACE_NAME, 
  TABLE_NAME

OID objects are queried in a similar way. To illustrate it, we list all persons in our database who are older than 30:

SimpleQuery q("$::Person::age$ >= 30");
Result<Person> r(conn, q);
r.open();
for (Result<Person>::iterator it = r.begin(); it != r.end(); it++) {
	cout << "name: " << it->name << " age: " << it->age << endl;
}
r.close();

Output of the example is:

name: Mary Major age: 60
name: Ola Nordmann age: 45

As you see, the query selects from the polymorphic views, so even the Person descendants are returned. To select only the Person instances we must change the query to FreeQuery and specify the corresponding simple view name from which to select:

FreeQuery q2("$::Person[db.view.sv]$ WHERE $::Person[db.view.sv]::age$ >= 30");

// SQL executed:
SELECT OID FROM Person_SV WHERE Person_SV.Person_age >= 30

Only OID column is selected for OID objects because selected objects may be present in the cache. Full object is then either obtained from the cache or loaded from database when accessed^[36].

Setting up the cache layer is quite complicated topic. Because it was already described in user guide in [03] we will provide only a few basic examples.

In the previous sections we learned how to use the VoidCache. Similarly we could use the single-threaded variants of the other two cache implementations provided - the ArcCacheST and LruCacheST caches:

db = new CachedDatabase(
  DriverManager::getDriver("IopcOracle10g").getDatabase("XE"), 
  new HashArcCacheST());
db = new CachedDatabase(
  DriverManager::getDriver("IopcOracle10g").getDatabase("XE"), 
  new HashLruCacheST());

To take advantage of the cache/strategy selector facade and asynchronous cache maintenance provided by CacheKeeper we must first associate the ComposedCache (no other cache) with the connections. Then we will define cache and strategy selection rules (see the section called “The cache layer”) on each connection and start the maintainer thread:

db = new CachedDatabase(
  DriverManager::getDriver("IopcOracle10g").getDatabase("XE"), 
  new ComposedCache());
conn = (CachedConnection*)db->getConnection(
  "username=iopc;password=iopc;autocommit=false");
CacheKeeper cacheKeeper(-15000, 100, 200);
cacheKeeper.setCache(conn, TypeDesc<Employee>::getType(), new HashArcCache());
cacheKeeper.setCache(conn, new HashLruCache());
cacheKeeper.setStrategy(conn, Strategy::lazy);
cacheKeeper.runMaintainer();

In the example, we associated the HashArcCache (multithreaded variant) with the Employee class. Instances of this class manipulated on the conn connection will use this cache. All other persistent objects will use the default HashLruCache. The lazy strategy will be used for objects of all types. For other strategy types and their descriptions see [03]. CacheKeeper constructor allows to specify maximum cache capacities and other parameters that influence the cache maintenance.