Connect to HCL Domino Data in JRuby

JRuby is a high-performance, stable, fully threaded Java implementation of the Ruby programming language. The CData JDBC Driver for HCL Domino makes it easy to integrate connectivity to live HCL Domino data in JRuby. This article shows how to create a simple JRuby app that connects to HCL Domino data, executes a query, and displays the results.

Configure a JDBC Connection to HCL Domino Data

Before creating the app, note the installation location for the JAR file for the JDBC Driver (typically C:\Program Files\CData\CData JDBC Driver for HCL Domino\lib).

JRuby natively supports JDBC, so you can easily connect to HCL Domino and execute SQL queries. Initialize the JDBC connection with the getConnection function of the java.sql.DriverManager class.

Connecting to Domino

To connect to Domino data, set the following properties:

• URL: The host name or IP of the server hosting the Domino database. Include the port of the server hosting the Domino database. For example: http://sampleserver:1234/
• DatabaseScope: The name of a scope in the Domino Web UI. The driver exposes forms and views for the schema governed by the specified scope. In the Domino Admin UI, select the Scopes menu in the sidebar. Set this property to the name of an existing scope.

Authenticating with Domino

Domino supports authenticating via login credentials or an Entra ID (formerly Azure AD) OAuth application:

Login Credentials

To authenticate with login credentials, set the following properties:

• AuthScheme: Set this to "OAuthPassword"
• User: The username of the authenticating Domino user
• Password: The password associated with the authenticating Domino user

The driver uses the login credentials to automatically perform an OAuth token exchange.

EntraID (formerly AzureAD)

This authentication method uses Entra ID (formerly Azure AD) as an IdP to obtain a JWT token. You need to create a custom OAuth application in Entra ID (formerly Azure AD) and configure it as an IdP. To do so, follow the instructions in the Help documentation. Then set the following properties:

• AuthScheme: Set this to "EntraID (formerly AzureAD)"
• InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• OAuthClientId: The Client ID obtained when setting up the custom OAuth application.
• OAuthClientSecret: The Client secret obtained when setting up the custom OAuth application.
• CallbackURL: The redirect URI defined when you registered your app. For example: https://localhost:33333
• AzureTenant: The Microsoft Online tenant being used to access data. Supply either a value in the form companyname.microsoft.com or the tenant ID.

  The tenant ID is the same as the directory ID shown in the Azure Portal's Entra ID (formerly Azure AD) > Properties page.

Built-in Connection String Designer

For assistance in constructing the JDBC URL, use the connection string designer built into the HCL Domino JDBC Driver. Either double-click the JAR file or execute the jar file from the command-line.

java -jar cdata.jdbc.domino.jar

Fill in the connection properties and copy the connection string to the clipboard.

👁 Using the built-in connection string designer to generate a JDBC URL (Salesforce is shown.)

Below is a typical JDBC connection string for HCL Domino:

jdbc:domino:Server=https://domino.corp.com;AuthScheme=OAuthPassword;User=my_domino_user;Password=my_domino_password;

Create a JRuby App with Connectivity to HCL Domino Data

Create a new Ruby file (for example: DominoSelect.rb) and open it in a text editor. Copy the following code into your file:

require 'java'
require 'rubygems'
require 'C:/Program Files/CData/CData JDBC Driver for HCL Domino 2018/lib/cdata.jdbc.domino.jar'

url = "jdbc:domino:Server=https://domino.corp.com;AuthScheme=OAuthPassword;User=my_domino_user;Password=my_domino_password;"
conn = java.sql.DriverManager.getConnection(url)
stmt = conn.createStatement
rs = stmt.executeQuery("SELECT Name, Address FROM ByName")
while (rs.next) do
 puts rs.getString(1) + ' ' + rs.getString(2)
end

With the file completed, you are ready to display your HCL Domino data with JRuby. To do so, simply run your file from the command line:

jruby -S DominoSelect.rb

Writing SQL-92 queries to HCL Domino allows you to quickly and easily incorporate HCL Domino data into your own JRuby applications. Download a free trial today!