OracleAS Portal Developer Kit (PDK)
OmniPortlet: How to Use DataDirect JDBC Drivers

An OracleAS Portal Technical Note
July 2004

| Introduction | Installing DataDirect drivers | Configuring OmniPortlet | Using the DataDirect Driver in OmniPortlet | More Information |

Introduction

The OmniPortlet SQL data source is pre-configured to access Oracle databases using the Oracle JDBC drivers, and ODBC data sources using Sun Microsystem's JDBC-ODBC driver. OracleAS allows developers to access other relational databases using DataDirect JDBC drivers. The OracleAS Certification with DataDirect JDBC document contains the list of supported databases. Currently, OmniPortlet supports DataDirect JDBC driver 3.2 (listed under Version 9.0.4).

The DataDirect drivers and documentation are available on the Oracle Technology Network . Make sure you download the version of drivers supported in your J2EE container. See OracleAS Certification with DataDirect JDBC for more details. 

This document describes how to configure OmniPortlet to leverage these drivers, and includes the following three sections:

• Installing DataDirect drivers: explains how to install the driver into your environment.
• Configuring OmniPortlet: explains to Portal administrators how they can add the DataDirect drivers to the OmniPortlet.
• Using the DataDirect Driver in OmniPortlet: explains how page designers can use the different drivers.

Back to Top

Installing DataDirect Drivers

DataDirect JDBC drivers are packaged in a single ZIP file that contains the different drivers to access the supported databases.

1. Unzip the content of the DataDirect JDBC drivers into a temporary directory e.g., /temp/datadirect.
   • Create the directory $ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib if it does not already exist.
   • Copy the DataDirect JDBC drivers in /temp/datadirect/lib to the $ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applib directory.
     
2. Check the configuration of the OC4J instance to be sure that the Data Direct libraries are loaded.
   • Open the $ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/config/application.xml . This file is used to configure all the applications of this instance.
   • Add the XML entry <library path="../applib/" /> if it does not already exist.

Back to Top

Configuring OmniPortlet

Since OmniPortlet is implemented as a Web provider, all the configuration properties are stored in the provider.xml file. Before you can use the DataDirect JDBC drivers with OmniPortlet, you must register the new JDBC drivers in this file.

1. Create a backup of $ORACLE_HOME/j2ee/<OC4J_INSTANCE_HOME>/applications/portalTools/omniPortlet/WEB-INF/providers/omniPortlet/provider.xml
   
2. Open the provider.xml file
   
3. Add the drivers you want to use to the SQL data source configuration entry by:

   • Searching for the XML tag driverInfo, then
   • Adding a new entry after the last driverInfo

   For example, the Microsoft SQL Server entry would look like the following:

   For OmniPortlet version 9.0.4.1 and higher:

   <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
   <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
     <name>Microsoft SQL Server</name>
     <sourceDataBase>other</sourceDataBase>
     <subProtocol>sqlserver</subProtocol>
     <connectString>mainProtocol:subProtocol://databaseName</connectString>
     <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver</driverClassName>
     <dataSourceClassName>com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource</dataSourceClassName>
     <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler</connHandlerClass>
     <connPoolSize>5</connPoolSize>
     <loginTimeOut>30</loginTimeOut>
   </driverInfo>
   

   For OmniPortlet prior to version 9.0.4.1:

   <!-- registration of DataDirect Connect for JDBC SQL Server driver -->
   <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
     <name>Microsoft SQL Server</name>
     <sourceDataBase>other</sourceDataBase>
     <subProtocol>sqlserver</subProtocol>
     <connectString>mainProtocol:subProtocol://databaseName</connectString>
     <driverClassName>com.oracle.ias.jdbc.sqlserver.SQLServerDriver</driverClassName>
     <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler</connHandlerClass>
     <connPoolSize>5</connPoolSize>
     <loginTimeOut>30</loginTimeOut>
   </driverInfo>
   

   Another example is the Sybase entry:

   For OmniPortlet version 9.0.4.1 and higher:

   <!-- registration of DataDirect Connect for JDBC Sybase driver -->
   <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
     <name>Sybase</name>
     <sourceDataBase>other</sourceDataBase>
     <subProtocol>sybase</subProtocol>
     <connectString>mainProtocol:subProtocol://databaseName</connectString>
     <driverClassName>com.oracle.ias.jdbc.sybase.SybaseDriver</driverClassName>
     <dataSourceClassName>com.oracle.ias.jdbcx.sybase.SybaseDataSource</dataSourceClassName>
     <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler</connHandlerClass>
     <connPoolSize>5</connPoolSize>
     <loginTimeOut>30</loginTimeOut>
   </driverInfo>
   

   For OmniPortlet prior to version 9.0.4.1:

   <!-- registration of DataDirect Connect for JDBC Sybase driver -->
   <driverInfo class="oracle.webdb.reformlet.data.jdbc.JDBCDriverInfo">
     <name>Sybase</name>
     <sourceDataBase>other</sourceDataBase>
     <subProtocol>sybase</subProtocol>
     <connectString>mainProtocol:subProtocol://databaseName</connectString>
     <driverClassName>com.oracle.ias.jdbc.sybase.SybaseDriver</driverClassName>
     <connHandlerClass>oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler</connHandlerClass>
     <connPoolSize>5</connPoolSize>
     <loginTimeOut>30</loginTimeOut>
   </driverInfo>
   

   This table lists the different values of the driverClassName and dataSourceClassName properties of supported DataDirect drivers:

   Microsoft SQL Server	driverClassName com.oracle.ias.jdbc.sqlserver.SQLServerDriver dataSourceClassName com.oracle.ias.jdbcx.sqlserver.SQLServerDataSource
   Sybase	driverClassName com.oracle.ias.jdbc.sybase.SybaseDriver dataSourceClassName com.oracle.ias.jdbcx.sybase.SybaseDataSource
   DB2	driverClassName com.oracle.ias.jdbc.db2.DB2Driver dataSourceClassName com.oracle.ias.jdbcx.db2.DB2DataSource
   Informix	driverClassName com.oracle.ias.jdbc.informix.InformixDriver dataSourceClassName com.oracle.ias.jdbcx.informix.InformixDataSource

    

   This table lists the different values of the driverInfo properties:

   name	Contains the name of the database you want to use. This name will be used on the Source tab of the OmniPortlet wizard.
   sourceDataBase	Internal value. Set the value to other.
   subProtocol	JDBC sub-protocol named use by OmniPortlet to create the connection string, e.g., sqlserver, sybase, db2. Refer to the DataDirect Driver documentation to get the list of the subProtocol names.
   connectString	Description of the connectString format. For DataDirect drivers, the format is always: mainProtocol:subProtocol://databaseName
   driverClassName	The name of the driver class name. Check the DataDirect Driver documentation to get the different values.
   dataSourceClassName	(9.0.4.1 and higher) The name of the data source class that implements connection pooling. See above table for the right dataSourceClassName for your driver.
   connHandlerClass	The connectionHandlerClass is the class used by OmniPortlet to manage the driver and the connection pooling. The value is oracle.webdb.reformlet.data.jdbc.JDBCConnectionHandler (9.0.4.1 and higher), or oracle.webdb.reformlet.data.jdbc.JDBCODBCConnectionHandler (prior to 9.0.4.1).
   connPoolSize	Minimum number of connection open by the connection pool.
   loginTimeOut	Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.

4. Save the provider.xml file.
   
5. Stop and start the application server.

Note: If you are using OmniPortlet in a multi-nodes configuration (clustering or load balancing environment), you must manually copy the provider.xml file onto the different nodes.

Back to Top

Using the DataDirect Driver in OmniPortlet

You have configured the OmniPortlet SQL data source to support DataDirect JDBC drivers, which allow connectivity to various relational databases.

When you launch OmniPortlet and choose the SQL data source on the Type screen, you will see the following new information on the Connection dialog box on the Source tab.

Driver Name with the new entries. (Sybase, MS SQL Server)

When you want to use one of the DataDirect drivers, you must use a new connect string format that is currently not documented in the wizard. The format of the connection string for DataDirect driver is: hostname:port, where hostname is the name of the server where the database is running, and port the listening port of the database.

Connection information to connect to a Microsoft SQL Server database

OmniPortlet is now ready to connect to the database (SQL Server in the example) and retrieve the data.

Back to Top

More Information

For more information on this and related topics, please refer to the following:

• OracleAS Certification with DataDirect JDBC
• OC4J Services Guide Page 5.29 Installing DataDirect JDBC Drivers
• OC4J download page that contains the DataDirect drivers

Back to Top