Setting up the RDBMS feature to connect to your application

The XPages RDBMS feature is installed as part of the product installation process. This topic describes how to do the initial setup required to connect your application to the RDBMS feature.

About this task

In order to connect your application to the RDBMS feature, some initial setup is required. Use these steps to complete this setup:

Procedure

  1. Download the needed JDBC driver. The XPages RDBMS feature is based on Java™ and JDBC. In order for an XPages application to interact with a relational database, your server needs to have the requisite JDBC driver for that database available on the server. To do this, download or locate the appropriate JDBC driver for your relational database. For example, in a DB2® installation, the JDBC driver is provided at <db2-install-location>\java\db2jcc.jar. As another example, for a MySQL database, you could download the JDBC driver from the MySQL web site.
  2. Install the JDBC driver to the server. Use one of the following methods to install the driver to the server:
    1. Use the JDBC Driver Plug-in Wizard (recommended method) - Once you have the correct JDBC driver, you need to make it available on your server. You use the JDBC Driver Plug-in Wizard (JDPW) tool that is provided to do this. This tool creates an OSGi plugin wrapper for a JDBC driver. To open the wizard in Designer, choose the Tools - JDBC Driver Plug-in Wizard menu option and provide the information requested by the wizard. This information includes Driver Details and Wizard Output Details. The wizard lets you generate an update site or plugin, which you are then required to install to your Domino® server. Once your server has been restarted, the JDBC driver is then available to be used by your XPages applications.
    2. Install the JDBC driver to your server by dropping the driver JAR file(s) into the /jvm/lib/ext/ folder of your server. By using this approach, your driver will be registered if you are using connection pooling. If you are not using pooling, you must register the driver yourself. By using the recommended wizard tool, however, driver registration is always automatic.
  3. Create a .jdbc file in your XPage application. As the next step, your XPage application requires a <filename>.jdbc file to be created in the /WebContent/WEB-INF/jdbc folder (visible in the Navigator view in Designer). This file defines the connection parameters to your database. The following is an example of the contents of a <filename>.jdbc file: <jdbc type="simple"> <driver>com.ibm.db2.jcc.DB2Driver</driver> <url>jdbc:db2://<host>:<port>/<DB></url> <user>usr</user> <password>pwd</password> <simple> <maxPoolSize>10</maxPoolSize> <maxConnectionSize>5</maxConnectionSize> </simple> </jdbc>. The driver value refers to the JDBC driver class, provided by the JDBC driver you have installed to your server. The URL value is a connection URL that points to your database. User and password values are stored here to access the database. In the example, the connection pooling type is set as simple in the first line, with the added parameters maxPoolSize and maxConnectionSize also set in the example. The other supported connection pool type is dbcp.
  4. Add the relational library to your application. Use one of the following methods to do this:
    1. To use the relational controls or data sources, you must add the relational library to the list of XPage libraries in the XSP Properties of your application. By dragging and dropping an XPages relational control or data source onto an XPage, the library will automatically be added to the list of XPages libraries for your application.
    2. Alternatively, you can manually add the library by opening the XSP Properties of your application. After you have done that, open the Page Generation tab and click the checkbox next to com.ibm.xsp.extlib.relational.library. After the library has been added, save your application and re-build it.
  5. Reference the.jdbc file in your data source. To get your data source to point to your database, you need to reference the <filename>.jdbc file that you created earlier. For example, if you named the file db2.jdbc, you would add a data source like the following to your XPage: <xe:this.data> <xe:jdbcRowSet var="myData" sqlTable="users" connectionName="db2"> </xe:jdbcRowSet> </xe:this.data> In the example, notice that the connectionName attribute references the name of the .jdbc file.

What to do next

Once you have completed all the steps just described, you can use the RDBMS support feature in your XPages application. When you open the application in a browser, it will then display the relational data pulled directly from your relational database.
Note: To avoid conflicts between the new relational plugin and an old ExtlibX version when they both are installed, it is recommended that you disable the old ExtlibX library on your server and in Designer when using the XPages RDBMS feature.

Additional information about using the RDBMS feature with existing applications

If you have previously developed XPages applications that used the ExtlibX relational plugin, you must update your applications to use the new relational plugin. In the XSP Properties of your application, you must update the XPage Libraries field in the Page Generation tab. For example, deselect com.ibm.xsp.extlibx.library and select com.ibm.xsp.extlib.relational.library in the XPage Libraries field in the Page Generation tab. After you have done this. save the change and rebuild your application.

If you have Java™ or JavaScript™ code in your application that references classes from the old ExtlibX relational plugin, you may get some errors in Designer after rebuilding your application. In order to correct these, update the references to the new class names, such as updating import statements in your Java™ classes. For example, to correct the following errors:
import com.ibm.xsp.extlib.jdbc.dbHelper.DatabaseHelper;
import com.ibm.xsp.extlib.util.JDBCUtil;
update the import statements to this
import com.ibm.xsp.extlib.relational.jdbc.dbHelper.DatabaseHelper;
import com.ibm.xsp.extlib.relational.util.JDBCUtil;