Objects as Handles

All of the classes in the C++ Class Library that derive from OOracleObject (that is, ODatabase, ODynaset, OSession, and so forth, but not OBound, OBinder, and OValue) are implemented using handle-reference semantics. This style is often used to implement such things as strings, where the String class that you use is actually a lightweight handle referencing another object that contains the actual memory allocated string. A reference count is kept on the object that contains the actual string, and as long as there is at least one reference to it, it is kept. Using semantics like this allows you to copy String objects quickly (all that is copied is the reference to the underlying object) and saves storage because multiple uses of the same string all refer to a single store.

Each Oracle C++ class (named Oentity) is a handle referring to an underlying Oracle Objects for OLE object (called entity in this documentation), which is implemented in the OLE in-process server. When you use the C++ Class Library, you have no access to the underlying implementation objects. In Windows the underlying objects are implemented in OLE. Using the Class Library frees you from the details of OLE itself, and from concerns about reference counting.

Consider an OSession object. The OSession object itself is actually a handle referring to an underlying session object. Consequently, the OSession object is lightweight. It can be copied, assigned, passed back from routines, and so forth with little concern for the cost. A simple assignment results in two OSession objects, each of which refers to the same underlying session object. This is generally desirable. Keep in mind, however, that the operations on the OSession, such as a Commit, are actually taking place on the underlying session object. As a result, executing a Commit method on one OSession is the same as executing a Commit on any of the OSessions that refer to the same session.

The ODatabase object is a more complicated case. The ODatabase object refers to an underlying database object. But that implementation object is not the database itself; it is actually a reference to the database. This is what you would probably expect. Executing the ODatabase destructor decrements the reference count on the database object, which can then be destroyed. But destroying the database object does not destroy the actual Oracle database!

The use of classes entails the concept of an "open" object or a "closed" object. Open objects have a current, valid reference to an underlying implementation object. Closed objects do not have a valid reference to an underlying implementation object. In addition, closed objects have freed any auxiliary storage, such as copies of strings passed from callers or back to callers. Closed objects cannot do very much except be opened.