4 Object Programming

Persistent Objects

A persistent object is an object which is stored in an Oracle database. It may be fetched into the object cache and modified by an OCCI application. The lifetime of a persistent object can exceed that of the application which is accessing it. There are two types of persistent objects:

• A standalone instance is stored in a database table row, and has a unique object identifier. An OCCI application can retrieve a reference to a standalone object, pin the object, and navigate from the pinned object to other related objects. Standalone objects may also be referred to as referenceable objects.

  It is also possible to select a persistent object, in which case you fetch the object by value instead of fetching it by reference.

• An embedded instance is not stored in a database table row, but rather is embedded within another object. Examples of embedded objects are objects which are attributes of another object, or objects that exist in an object column of a database table. Embedded objects do not have object identifiers, and OCCI applications cannot get REFs to embedded instances.

  Embedded objects may also be referred to as nonreferenceable objects or value instances. You may sometimes see them referred to as values, which is not to be confused with scalar data values. The context should make the meaning clear.

Users do not have to explicitly delete persistent objects that have been materialized through references.

Users should delete persistent objects created by application when the transactions are rolled back

The SQL examples, Example 4-1 and Example 4-2, demonstrate the difference between these two types of persistent objects.

CREATE TYPE person_t AS OBJECT
   (name      varchar2(30),
    age       number(3));
CREATE TABLE person_tab OF person_t;

CREATE TABLE department
   (deptno     number,
    deptname   varchar2(30),
    manager    person_t);

Transient Objects

A transient object is an instance of an object type. Its lifetime cannot exceed that of the application. The application can also delete a transient object at any time.

The Object Type Translator (OTT) utility generates two operator new methods for each C++ class, as demonstrated in Two methods for operator new in the Object Type Translator UtilityExample 4-3:

class Person : public PObject {
   ...
public:
   dvoid *operator new(size_t size);    // creates transient instance
   dvoid *operator new(size_t size, Connection &conn, string table);
                                        // creates persistent instance
}

Example 4-4 demonstrates how to dynamically create a transient object. Transient objects cannot be converted to persistent objects. Their role is fixed at the time they are instantiated, and it is your responsibility to free memory by deleting transient objects.

Person *p = new Person();

A transient object can also be created on the stack as a local variable, as demonstrated in Example 4-5. The latter approach guarantees that the transient object is destroyed when the scope of the variable ends.

Person p;

Values

In this manual, a value refers to either:

• A scalar value which is stored in a non-object column of a database table. An OCCI application can fetch values from a database by issuing SQL statements.

• An embedded (nonreferenceable) object.

The context should make it clear which meaning is intended.

It is possible to SELECT a referenceable object into the object cache, rather than pinning it, in which case you fetch the object by value instead of fetching it by reference.

Creating Persistent and Transient Objects

This section discusses how persistent and transient objects are created.

Before you create a persistent object, you must have created the environment and opened a connection.

A persistent object is created in the database only when one of the following occurs:

• The transaction is committed (Connection::commit())

• The object cache is flushed (Connection::flushCache())

• The object itself is flushed (PObject::flush())

Example 4-6 shows how to create a persistent object, addr, in the database table, addr_tab.

CREATE TYPE ADDRESS AS OBJECT (
   state CHAR(2), 
   zip_code CHAR(5));
CREATE TABLE ADDR_TAB of ADDRESS;
ADDRESS *addr = new(conn, "ADDR_TAB") ADDRESS("CA", "94065");

Example 4-7 shows hot to create an instance of the transient object ADDRESS.

ADDRESS *addr_trans = new ADDRESS("MD", "94111");

Creating Object Representations using the OTT Utility

When your C++ application retrieves instances of object types from the database, it must have a client-side representation of the objects. The Object Type Translator (OTT) utility generates C++ class representations of database object types for you. For example, consider the following declaration of a type in your database:

CREATE TYPE address AS OBJECT (state CHAR(2), zip_code CHAR(5));

The OTT utility produces the following C++ class:

class ADDRESS : public PObject {

   protected:
      string state;
      string zip;

   public:
      void *operator new(size_t size); 
      void *operator new(size_t size, 
         const Connection* conn, 
         const string& table);
      string  getSQLTypeName() const;
      void getSQLTypeName(oracle::occi::Environment *env, void **schemaName,
                          unsigned int &schemaNameLen, void **typeName,
                          unsigned int &typeNameLen) const;
      ADDRESS(void *ctx) : PObject(ctx) { };
      static void *readSQL(void *ctx);
      virtual void readSQL(AnyData& stream);
      static void writeSQL(void *obj, void *ctx);
      virtual void writeSQL(AnyData& stream);
}

These class declarations are automatically written by OTT to a header (.h) file that you name. This header file is included in the source files for an application to provide access to objects. Instances of a PObject (and also instances of classes derived from PObjects) can be either transient or persistent. The methods writeSQL() and readSQL() are used internally by the OCCI object cache to linearize and delinearize the objects and are not to be used or modified by OCCI clients.

Basic Object Program Structure

The basic structure of an OCCI application that uses objects is similar to a relational OCCI application, the difference being object functionality. The steps involved in an OCCI object program include:

1. Initialize the Environment. Initialize the OCCI programming environment in object mode. Your application must include C++ class representations of database objects in a header file. You can create these classes by using the Object Type Translator (OTT) utility, as described in Chapter 8, "Object Type Translator Utility".

2. Establish a Connection. Use the environment handle to establish a connection to the database server.

3. Prepare a SQL statement. This is a local (client-side) step, which may include binding placeholders. In an object-relational application, this SQL statement should return a reference (REF) to an object.

4. Access the object.

   1. Associate the prepared statement with a database server, and execute the statement.

   2. By using navigational access, retrieve an object reference (REF) from the database server and pin the object. You can then perform some or all of the following:

      • Manipulate the attributes of an object and mark it as dirty (modified)

      • Follow a reference to another object or series of objects

      • Access type and attribute information

      • Navigate a complex object retrieval graph

      • Flush modified objects to the database server

   3. By using associative access, you can fetch an entire object by value by using SQL. Alternately, you can select an embedded (nonreferenceable) object. You can then perform some or all of the following:

      • Insert values into a table

      • Modify existing values

5. Commit the transaction. This step implicitly writes all modified objects to the database server and commits the changes.

6. Free statements and handles; the prepared statements should not be used or executed again.

   See Also:

   • Chapter 3, " Relational Programming" for information about using OCCI to connect to a database server, process SQL statements, and allocate handles

   • Chapter 8, "Object Type Translator Utility" for information about the OTT utility

   • Chapter 13, "OCCI Application Programming Interface" for descriptions of OCCI relational functions and the Connect class and the getMetaData() method

Basic Object Operational Flow

Figure 3-1 shows a simple program logic flow for how an application might work with objects. For simplicity, some required steps are omitted.

Figure 4-1 Basic Object Operational Flow

Description of "Figure 4-1 Basic Object Operational Flow"

The steps shown in Figure 3-1 are discussed in the following sections:

Environment *env;
Connection *con;
Statement *stmt;

env = Environment::createEnvironment(Environment::OBJECT);
con = Connection(userName, password, connectString);

Steps for Migration

• Determine object model and class hierarchy

• Use JDeveloper9i to map to Oracle object schema

• Generate C++ header files using Oracle Type Translator

• Modify old C++ access classes as required to work with new object type definitions

• Add functionality for transient and persistent object management, as required.

Using SQL to Access Objects

In the previous sections we discussed navigational access, where SQL is used only to fetch the references of an initial set of objects and then navigate from them to the other objects. Here we discuss how to fetch the objects using SQL.

The following example shows how to use the ResultSet::getObject() method to fetch objects through associative access where it gets each object from the table, addr_tab, using SQL:

string sel_addr_val = "SELECT VALUE(address) FROM ADDR_TAB address";

ResultSet *rs = stmt->executeQuery(sel_addr_val);

while (rs->next())
{
   ADDRESS *addr_val = rs->getObject(1); 
   cout << "state: " << addr_val->getState();
}

The objects fetched through associative access are termed value instances and they behave just like transient objects. Methods such as markModified(), flush(), and markDeleted() are applicable only for persistent objects.

Any changes made to these objects are not reflected in the database.

Since the object returned is a value instance, it is the user's responsibility to free memory by deleting the object pointer.

Inserting and Modifying Values

We have just seen how to use SQL to access objects. OCCI also provides the ability to use SQL to insert new objects or modify existing objects in the database server through the Statement::setObject method interface.

The following example creates a transient object Address and inserts it into the database table addr_tab:

ADDRESS *addr_val = new address("NV", "12563");  // new a transient instance
stmt->setSQL("INSERT INTO ADDR_TAB values(:1)");
stmt->setObject(1, addr_val);
stmt->execute();

Retrieving an Object Reference (REF) from the Database Server

To work with objects, your application must first retrieve one or more objects from the database server. You accomplish this by issuing a SQL statement that returns references (REFs) to one or more objects.

It is also possible for a SQL statement to fetch value instances, rather than REFs, from a database.

The following SQL statement retrieves a REF to a single object address from the database table addr_tab:

string sel_addr = "SELECT REF(address) 
   FROM addr_tab address 
   WHERE zip_code = '94065'";

The following code example illustrates how to execute the query and fetch the REF from the result set.

ResultSet *rs = stmt->executeQuery(sel_addr);
rs->next();
Ref<address> addr_ref = rs->getRef(1);

At this point, you could use the object reference to access and manipulate the object or objects from the database.

Pinning an Object

This section deals with a simple pin operation involving a single object at a time. For information about retrieving multiple objects through complex object retrieval, see the section Overview of Complex Object Retrieval.

Upon completion of the fetch step, your application has a REF to an object. The actual object is not currently available to work with. Before you can manipulate an object, it must be pinned. Pinning an object loads the object into the object cache, and enables you to access and modify the object's attributes and follow references from that object to other objects. Your application also controls when modified objects are written back to the database server.

OCCI requires only that you dereference the REF in the same way you would dereference any C++ pointer. Dereferencing the REF transparently materializes the object as a C++ class instance.

Continuing the Address class example from the previous section, assume that the user has added the following method:

string  Address::getState()
{
   return state;
}

To dereference this REF and access the object's attributes and methods:

string state = addr_ref->getState();     // -> pins the object

The first time Ref<T> (addr_ref) is dereferenced, the object is pinned, which is to say that it is loaded into the object cache from the database server. From then on, the behavior of operator -> on Ref<T> is just like that of any C++ pointer (T *). The object remains in the object cache until the REF (addr_ref) goes out of scope. It then becomes eligible for garbage collection.

Now that the object has been pinned, your application can modify that object.

Manipulating Object Attributes

Manipulating object attributes is no different from that of accessing them as shown in the previous section. Let us assume the Address class has the following user defined method that sets the state attribute to the input value:

void Address::setState(string new_state)
{
   state = new_state;
}

The following example shows how to modify the state attribute of the object, addr:

addr_ref->setState("PA");

As explained earlier, the first invocation of the operator -> on Ref<T> loads the object, if it is not in the object cache.

Marking Objects and Flushing Changes

In the example in the previous section, an attribute of an object was changed. This change exists only in the client-side cache; you must implement specific programmatic steps to write the changes to the database.

Marking an Object as Modified (Dirty)

The first step is to indicate that the object has been modified. This is done by calling the markModified() method on the object (derived method of PObject). This method marks the object as dirty (modified).

Continuing the previous example, after object attributes are manipulated, the object referred to by addr_ref can be marked dirty as follows:

addr_ref->markModified();

Recording Changes in the Database

Objects that have had their dirty flag set must be flushed to the database server for the changes to be recorded in the database. This can be done in three ways:

• Flush a single object marked dirty by calling the method flush, a derived method of PObject.

• Flush the entire object cache using the Connection::flushCache() method. In this case, OCCI traverses the dirty list maintained by the object cache and flushes all the dirty objects.

• Commit a transaction by calling the Connection::commit() method. Doing so also traverses the dirty list and flushes the objects to the database server. The dirty list includes newly created persistent objects.

Garbage Collection in the Object Cache

The object cache has two important associated parameters:

• The maximum cache size percentage

• The optimal cache size

These parameters refer to levels of cache memory usage, and they help determine when the cache automatically 'ages out' eligible objects to free up memory.

If the memory occupied by the objects currently in the cache reaches or exceeds the maximum cache size, the cache automatically begins to free (or age out) unmarked objects which have a pin count of zero. The cache continues freeing such objects until memory usage in the cache reaches the optimal size, or until it runs out of objects eligible for freeing. Note that the cache can grow beyond the specified maximum cache size.

The maximum object cache size (in bytes) is computed by incrementing the optimal cache size (optimal_size) by the maximum cache size percentage (max_size_percentage), as follows:

Maximum cache size = optimal_size + optimal_size * max_size_percentage / 100;

The default value for the maximum cache size percentage is 10%. The default value for the optimal cache size is 8MB. When a persistent object is created through the overloaded PObject::new() operator, the newly created object is marked dirty and its pin count is set to 0.

These parameters can be set or retrieved using the following member functions of the Environment class:

• void setCacheMaxSize(unsigned int maxSize);

• unsigned int getCacheMaxSize() const;

• void setCacheOptSize(unsigned int OptSize);

• unsigned int getCacheOptSize() const;

"Pin Object" describes how pin count of an object functions as a reference count and how an unmarked object with a 0 pin count can become eligible for garbage collection. For a newly created persistent object, the object is unmarked after the transaction is committed or aborted, and if the object has a 0 pin count. Because nothing is referencing this object, it becomes a candidate for ageing out.

If you are working with several object that have a large number of string or collection attributes, most of the memory is allocated from the C++ heap; this is because OCCI uses STLs. You should therefore set the cache size to a low value to avoid high memory use before garbage collection activates.

Transactional Consistency of References

As described in the previous section, dereferencing a Ref<T> for the first time results in the object being loaded into the object cache from the database server. From then on, the behavior of operator -> on Ref<T> equals any C++ pointer, and it provides access to the object copy in the cache. But when the transaction commits or aborts, the object copy in the cache can no longer be valid because it could be modified by any other client. Therefore, after the transaction ends, when the Ref<T> is again dereferenced, the object cache recognizes the fact that the object is no longer valid and fetches the most recent copy from the database server.

Retrieving Complex Objects

An OCCI application can achieve COR by setting the appropriate attributes of a Ref<T> before dereferencing it using the following methods:

// prefetch attributes of the specified type name up to the specified depth
Ref<T>::setPrefetch(const string &typeName, unsigned int depth);
// prefetch all the attribute types up to the specified depth.
Ref<T>::setPrefetch(unsigned int depth);

The application can also choose to fetch all objects reachable from the root object by way of REFs (transitive closure) to a certain depth. To do so, set the level parameter to the depth desired. For the preceding two examples, the application could also specify (PO object REF, OCCI_MAX_PREFETCH_DEPTH) and (PO object REF, 1) respectively to prefetch required objects. Doing so results in many extraneous fetches but is quite simple to specify, and requires only one database server round-trip.

As an example for this discussion, consider the following type declaration:

CREATE TYPE customer(...);
CREATE TYPE line_item(...);
CREATE TYPE line_item_varray as VARRAY(100) of REF line_item;
CREATE TYPE purchase_order AS OBJECT
   ( po_number         NUMBER, 
    cust              REF customer,
    related_orders    REF purchase_order,
    line_items        line_item_varray);

The purchase_order type contains a scalar value for po_number, a VARRAY of line_items, and two references. The first is to a customer type and the second is to a purchase_order type, indicating that this type can be implemented as a linked list.

When fetching a complex object, an application must specify the following:

• A reference to the desired root object

• One or more pairs of type and depth information to specify the boundaries of the complex object. The type information indicates which REF attributes should be followed for COR, and the depth level indicates how many levels deep those links should be followed.

In the case of the purchase_order object in the preceding example, the application must specify the following:

• The reference to the root purchase_order object

• One or more pairs of type and depth information for customer, purchase_order, or line_item

An application prefetching a purchase order needs access to the customer information for that purchase order. Using simple navigation, this would require two database server accesses to retrieve the two objects.

Through complex object retrieval, customer can be prefetched when the application pins the purchase_order object. In this case, the complex object would consist of the purchase_order object and the customer object it references.

In the previous example, if the application wanted to prefetch a purchase order and the related customer information, the application would specify the purchase_order object and indicate that customer should be followed to a depth level of one as follows:

Ref<PURCHASE_ORDER> poref;
poref.setPrefetch("CUSTOMER",1);

If the application wanted to prefetch a purchase order and all objects in the object graph it contains, the application would specify the purchase_order object and indicate that both customer and purchase_order should be followed to the maximum depth level possible as follows:

Ref<PURCHASE_ORDER> poref;
poref.setPrefetch("CUSTOMER", OCCI_MAX_PREFETCH_DEPTH);
poref.setPrefetch("PURCHASE_ORDER", OCCI_MAX_PREFETCH_DEPTH);

where OCCI_MAX_PREFETCH_DEPTH specifies that all objects of the specified type reachable through references from the root object should be prefetched.

If an application wanted to prefetch a purchase order and all the line items associated with it, the application would specify the purchase_order object and indicate that line_items should be followed to the maximum depth level possible as follows:

Ref<PURCHASE_ORDER> poref;
poref.setPrefetch("LINE_ITEM", 1);

Prefetching Complex Objects

After specifying and fetching a complex object, subsequent fetches of objects contained in the complex object do not incur the cost of a network round-trip, because these objects have been prefetched and are in the object cache. Keep in mind that excessive prefetching of objects can lead to a flooding of the object cache. This flooding, in turn, may force out other objects that the application had pinned, leading to a performance degradation instead of performance improvement.

Note that if there is insufficient memory in the object cache to hold all prefetched objects, some objects may not be prefetched. The application then incurs a network round-trip when those objects are accessed later.

You must have the SELECT privilege for all prefetched objects. Objects in the complex object for which the application does not have SELECT privilege cannot prefetched.

An entire vector of Refs can be prefetched into object cache in a single round-trip by using the global pinVectorOfRefs() method of the Connection Class. This method reduces the number of round-trips for an n-sized vector of Refs from n to 1, and tracks the newly pinned objects through an OUT parameter vector.

Fetching Embedded Objects

If your application must fetch an embedded object, which is an object stored in a column of a regular table rather than an object table, you cannot use the REF retrieval mechanism. Embedded instances do not have object identifiers, so it is not possible to get a reference to them. Therefore, they cannot serve as the basis for object navigation. There are still many situations, however, in which an application fetches embedded instances.

For example, assume that an address type has been created.

CREATE TYPE address AS OBJECT
(  street1             varchar2(50),
   street2             varchar2(50),
   city                varchar2(30),
   state               char(2),
   zip                 number(5));

You could then use that type as the data type of a column in another table:

CREATE TABLE clients
( name          varchar2(40),
   addr          address);

Your OCCI application could then issue the following SQL statement:

SELECT addr FROM clients
WHERE name='BEAR BYTE DATA MANAGEMENT';

This statement would return an embedded address object from the clients table. The application could then use the values in the attributes of this object for other processing. The application should execute the statement and fetch the object in the same way as described in the section "Overview of Associative Access".

Nullness

If a column in a row of a database table has no value, then that column is said to be NULL, or to contain a NULL. Two different types of NULLs can apply to objects:

• Any attribute of an object can have a NULL value. This indicates that the value of that attribute of the object is not known.

• An object may be atomically NULL. Therefore, the value of the entire object is unknown.

Atomic NULLness is different from nonexistence. An atomically NULL object still exists, its value is just not known. It may be thought of as an existing object with no data.

For every type of object attribute, OCCI provides a corresponding class. For instance, NUMBER attribute type maps to the Number class, REF maps to RefAny, and so on. Each and every OCCI class that represents a data type provides two methods:

• isNull() — returns whether the object is NULL

• setNull() — sets the object to NULL

Similarly, these methods are inherited from the PObject class by all the objects and can be used to access and set atomically NULL information about them.

Substitutability

The benefits of polymorphism derive partially from the property substitutability. Substitutability allows a value of some subtype to be used by code originally written for the supertype, without any specific knowledge of the subtype being needed in advance. The subtype value behaves to the surrounding code just like a value of the supertype would, even if it perhaps uses different mechanisms within its specializations of methods.

Instance substitutability refers to the ability to use an object value of a subtype in a context declared in terms of a supertype. REF substitutability refers to the ability to use a REF to a subtype in a context declared in terms of a REF to a supertype.

REF type attributes are substitutable, that is, an attribute defined as REF T can hold a REF to an instance of T or any of its subtypes.

Object type attributes are substitutable, that is, an attribute defined to be of (an object) type T can hold an instance of T or any of its subtypes.

Collection element types are substitutable, that is, if we define a collection of elements of type T, then it can hold instances of type T and any of its subtypes. Here is an example of object attribute substitutability:

CREATE TYPE Book_t AS OBJECT 
(  title VARCHAR2(30),
   author Person_t     /* substitutable */);

Thus, a Book_t instance can be created by specifying a title string and a Person_t (or any subtype of Person_t) object:

Book_t('My Oracle Experience',
   Employee_t(12345, 'Joe', 'SF', 1111, NULL))

NOT INSTANTIABLE Types and Methods

A type can be declared NOT INSTANTIABLE, which means that there is no constructor (default or user defined) for the type. Thus, it is not be possible to construct instances of this type. The typical usage would be to define instantiable subtypes for such a type. Here is how this property is used:

CREATE TYPE Address_t AS OBJECT(...) NOT INSTANTIABLE NOT FINAL;
CREATE TYPE USAddress_t UNDER Address_t(...);
CREATE TYPE IntlAddress_t UNDER Address_t(...);

A method of a type can be declared to be NOT INSTANTIABLE. Declaring a method as NOT INSTANTIABLE means that the type is not providing an implementation for that method. Further, a type that contains any NOT INSTANTIABLE methods must necessarily be declared as NOT INSTANTIABLE. For example:

CREATE TYPE T AS OBJECT
(  x NUMBER,
   NOT INSTANTIABLE MEMBER FUNCTION func1() RETURN NUMBER 
) NOT INSTANTIABLE;

A subtype of NOT INSTANTIABLE can override any of the NOT INSTANTIABLE methods of the supertype and provide concrete implementations. If there are any NOT INSTANTIABLE methods remaining, the subtype must also necessarily be declared as NOT INSTANTIABLE.

A NOT INSTANTIABLE subtype can be defined under an instantiable supertype. Declaring a NOT INSTANTIABLE type to be FINAL is not useful and is not allowed.

OCCI Support for Type Inheritance

The following calls support type inheritance.

OTT Support for Type Inheritance

Class declarations for objects with inheritance are similar to the simple object declarations except that the class is derived from the parent type class and only the fields corresponding to attributes not in the parent class are included. The structure for these declarations is listed in Example 4-8:

class <typename> : public <parentTypename> 
{
   protected:
      <OCCItype1> <attributename1>;
      ...
      <OCCItypen> <attributenamen>;

   public:
      void *operator new(size_t size); 
      void *operator new(size_t size, const Connection* conn, 
                          const string& table); 
      string  getSQLTypeName() const;
      void getSQLTypeName(oracle::occi::Environment *env, void **schemaName,
                          unsigned int &schemaNameLen, void **typeName,
                          unsigned int &typeNameLen) const;
      <typename> (void *ctx) : <parentTypename>(ctx) { };
      static void *readSQL(void *ctx);
      virtual void readSQL(AnyData& stream);
      static void writeSQL(void *obj, void *ctx);
      virtual void writeSQL(AnyData& stream);
}

In this structure, all variables are the same as in the simple object case. parentTypename refers to the name of the parent type, that is, the class name of the type from which typename inherits.