16.3 Using a Named Object for Database Connectivity
This example assumes that you are using Rogue Wave's SourcePro DB product to obtain a database connection to an Oracle9 database. With this product, a database connection is established by calling the database() method of the class RWDBManager. For Oracle9, this method takes the following parameters:
accessLib. Names the access library for the database. The access library abstracts out the database-specific details for a particular database.
dbServiceName. Specifies the Oracle9 service name.
userName. Specifies the user name of a valid Oracle9 user.
passWord. Specifies the password for that user.
databaseName. Not needed for Oracle9, so passed as an empty string.
For more information on SourcePro DB, see the documentation on the Rogue Wave Web site at http://www.roguewave.com/support/docs. Click the link for SourcePro C++, and then the link for the DB Interface Module User's Guide.
16.3.1 Creating the Object for Accessing a Database
You first need to create the object that will be loaded into the service container. Since this is for a database connection, let's call the class MyDatabase. This class will serve as the bridge between the servlet and SourcePro DB. The class must have an init() method, which in this case is the only method needed.
class MyDatabase : public RWDBDatabase {
virtual void init(const rwsf::Config& params) {
RWCString lib = params.getInitParameter("accessLib");
RWCstring service = params.getInitParameter("dbServiceName");
RWCstring user = params.getInitParameter("userName");
RWCstring password = params.getInitParameter("passWord");
this = RWDBManager::database(lib,service,user,password,"");
}
};
As you can see, this class establishes the database connection, passing the necessary parameters, and then assigns that connection to itself (this). Pretty soon we will see where the rwsf::Config object and its initiation parameters come from.
16.3.2 Creating an Entry Point to the Object
For the HydraExpress Agent to load an object, the shared library that contains the object must have a well-defined entry point in the form of a create() method.
extern "C" {
RWSF_CORE_EXPORT rwsf::NamedObjectImp* createMyDatabase() {
MyDatabase* db = new MyDatabase;
return new rwsf::PointerNamedObjectImp<MyDatabase>(db,true);
}
}
At a minimum, the above method and the MyDatabase class must be compiled into a shared library, and the HydraExpress Agent must be able to locate this shared library at startup. You can learn more about the classes rwsf::NamedObject, the handle for rwsf::NamedObjectImp, in the HydraExpress C++ API Reference Guide.
16.3.3 Configuring the Named Object
The database object is configured in the objects.xml file. This is where the database parameters get defined.
<?xml version="1.0" encoding="ISO-8859-1"?>
<objects>
...
<naming-obj>
<naming-name>oracle9Database</naming-name> 1
<naming-class>dbconnection.createMyDatabase</naming-class> 2
<init-param> 3
<param-name>accessLib</param-name>
<param-value>ora5512d.dll</param-value>
</init-param>
<init-param> 4
<param-name>dbServiceName</param-name>
<param-value>oracle9</param-value>
<init-param>
...
</naming-obj>
...
</objects>
| //1 | Labels the object so the servlet can locate it. |
| //2 | Names the shared library (dbconnection) and create method (createMyDatabase) to be used to instantiate the object. |
| //3 | Defines the first parameter, named accessLib, whose value is the name of the Oracle9 access library shared library, as required by the RWDBManager::database() method. |
| //4 | Defines the second parameter, which is followed by others not shown. |
At HydraExpress Agent startup, the initiation parameters defined for the named object get placed into a rwsf::Config object, which gets passed to the init() method for the named object.
16.3.4 Using the Named Object
If you have done everything as described in the previous sections, an object named oracle9Database should be registered in the HydraExpress Agent global naming context. Here is how you would use it in your implementation code:
rwsf::NamingContext* c =
rwsf::NamingContext::getGlobalInstance(); //1
rwsf::NamedObject obj = c->lookup("oracle9Database"); //2
MyDatabase* db; //3
rwsf::naming_extract<MyDatabase>(obj,db); //4
// Use db just like any RWDBDatabase object ...
| //1 | Gets an instance of the global naming context. |
| //2 | Looks up the object oracle9Database in the global context. |
| //3 | Creates an instance of the object for accessing the database. |
| //4 | Calls the global template function rwrwsf::naming_extract<>() to extract an instance of the database connection object and assign it to the supplied database object. |
For descriptions of the classes rwsf::NamingContext and rwsf::NamedObject, see the HydraExpress C++ API Reference Guide.
16.3.4.1 Summary
The basic steps to creating and using a named object are:
Identify the object you want to use, coding it if necessary.
Create an entry point -- a create() method -- in the shared library that contains the object.
Configure the named object in objects.xml.
Obtain and use the object in your implementation code.
By analogy with the process described for using a database connection object, you should be able create a named object from any useful object available to you.
16.3.5 Configuring Objects that are Also Handlers
If you are creating a custom object that is considered a handler in HydraExpress, you must add initialization parameters to the <serviceName>handlers.xml configuration file, rather than to objects.xml. Parameters added to objects.xml will be ignored.
Handlers consist of any object listed in the <serviceName>handlers.xml configuration file, which includes transport handlers, request handlers, response handlers, and fault handlers.
For information on configuring handlers that are also named objects, see Section 14.6, "Adding Initialization Parameters to Handlers."
© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.