5.6 More About isValid()

The example in Section 5.2 showed how to use the isValid() method of class RWDBStatus to check the status of an object. In this section, we add some details about this important function.

The first thing to understand is that the function isValid() returning TRUE means essentially the same as errorCode() returning RWDBStatus::ok. The major difference is that only Producer/Product classes have a status() function, while many classes, including some Producer/Product classes, have an isValid() function.

Although the DBTools.h++ error model is based on RWDBStatus, you are more likely to use isValid() for testing the validity of objects.

5.6.1 Defining a Valid Object

In DBTools.h++, a valid object is a usable object, so we often apply the terms interchangeably. The function isValid() returns TRUE if the object is valid, as shown in the next example:

RWDBConnection aConnection = goodDB.connection();             // 1
if(aConnection.isValid()) {                                   // 2
    cout << "A good connection was established." << endl;
}

In //1, a valid RWDBDatabase produces a valid RWDBConnection. Because the connection is successfully established, the function RWDBConnection::isValid() on line //2 returns TRUE. The connection is valid and usable.

If an object that provides an isValid() member is not in a usable state, its isValid() method returns FALSE, as shown in the following example:

RWDBConnection aConnection = goodDB.connection();              // 1
RWDBResult aResult = 
    aConnection.executeSql("Some Bad SQL");                    // 2
if(aResult.isValid()) {                                        // 3
    cout << "RWDBResult object is valid." << endl;
} 
else{
    cout << "RWDBResult object is not valid--bad SQL statement?" 
         << endl; 
}
if(aConnection.isValid()) {                                    // 4
    cout << "The connection is still good." << endl;  
}
else{
    cout << "The connection is bad. Why?" << endl;
}

On line //1, a connection is established from a valid RWDBDatabase. Since the connection is successfully established, line //2 sends the string "Some Bad SQL" to the database server. Of course, this is an invalid query, so the function RWDBResult::isValid() returns FALSE on //3 because this erroneous query is unusable. On line //4, however, aConnection::isValid() returns TRUE, since the RWDBConnection instance is still valid; the connection is still usable for other queries.

5.6.2 Making Unusable Objects Usable

Sometimes an unusable object can be made usable. For example, objects produced under the DBTools.h++ Producer/Product paradigm, called product objects, are unusable if they are produced by an invalid object. (See Section 2.3.) However, producing an unusable product object again, this time by a valid object, can yield a usable and valid object. This technique is shown in the following example:

RWDBConnection aConnection = badDB.connection();               // 1
if(!aConnection.isValid()) {
    cout << "aConnection isn't usable right now." << endl;
}
aConnection = goodDB.connection();                             // 2
if(aConnection.isValid()) {
    cout << "aConnection is valid and usable now." << endl;
}

In //1, an aConnection object is produced from an RWDBDatabase instance that is unusable. The method isValid() on aConnection correctly reports that the connection is unusable. In //2, an aConnection object is produced again, this time from a good RWDBDatabase instance. The invalid aConnection object is discarded, and the new object takes its place. Because the connection is successfully produced, the method isValid() on aConnection reports that the connection is in a usable, valid state.

This example is intended to show how reproducing an unusable object can make it usable, but there is a corollary as well: it is always a good idea to understand the validity requirements for the particular class you are using. In this case, it is important to know that product objects must be produced by valid objects. Some qualifications apply in other classes as well.

NOTE: Always check the Class Reference for the object validity requirements and the description of isValid() for the class you are using.