How to Embed and Distribute JDBC and ODBC Data Connectivity

From competition to product differentiation, from security to performance and scalability, independent software vendors (ISVs) face multiple challenges in today's marketplace. Data access and integration is an additional challenge that can draw resources away from core business and development objectives. However, by embedding and distributing JDBC or ODBC drivers into your application, data access and integration can be transformed into a strength. Progress DataDirect drivers provide fast, reliable and secure access to industry-leading relational, big data, NoSQL and cloud data sources. In addition, Progress DataDirect JDBC and ODBC drivers are easy to integrate into your application's data access layer as closed, password-protected components. In this tutorial, we'll begin by discussing the advantages of distributing drivers. Then we'll outline what's involved with distributing DataDirect drivers. We will then describe the steps required to integrate and distribute JDBC and ODBC drivers with your software application.

• Protection Against Driver Conflicts

  By uniquely naming files and locking the drivers, you prevent driver conflicts that can occur when customers install your application alongside other software. This means that the drivers and configurations you tested are the same ones your customers are using, guaranteeing that your application performs exactly as you designed.

• Locked Drivers

  In addition to ensuring your application is using the correct driver, locking the drivers also prohibits unauthorized applications from accessing your drivers. Using closed, password-protected drivers assures that other applications are not taking advantage of your driver's performance or competing with your application for connectivity resources.

• Integrated User Experience

  Distributing the drivers allows you to transparently integrate the drivers with your application. In addition to installing the drivers with your application, you are able to determine file name prefixes, and customize error messages, transforming the drivers into a seamless extension of your application.

• A Single Resource for Technical Support

  With Progress's comprehensive technical support services, you will no longer need to chase multiple vendors to resolve connectivity issues. Our award-winning support team is available 24 hours a day to diagnose your connectivity problem and provide solutions, regardless of the cause.

• Progress Performance

  Installing the drivers with your application provides your customers with the high-performance connectivity, advanced features, security, and reliability that Progress DataDirect offers.

• Simplified User Experience

  Embedding DataDirect drivers simplifies your users’ experience with your product. By distributing the drivers with your application, you eliminate the need for customers to research, license, and install their own drivers. This allows your customers to use the best version of your application right out of the box.

Distributing the drivers is a three-part process that consists of branding the drivers, installing them with your application's installer program, and enabling your application to unlock the drivers:

• Branding

  Branding consists of renaming the driver and license files, and, most importantly, creating locked drivers that can only be used by your product. The DataDirect installation program makes this easy by guiding you through the entire branding process.

• Installing the Driver Files

  Installing the drivers with your installation program requires modifying your product installer to load the branded driver files and, for ODBC drivers, adding the necessary entries to the system information files and environment variables.

• Unlocking the Drivers

  Your application implements a special set of calls to unlock the drivers when connecting to your data source.

Branding the standard commercial Progress DataDirect drivers allows you to distribute the drivers with your application as closed, password-protected drivers.

Branding renames the driver and license files and encodes them with a prefix of your choosing. The prefix you enter replaces default characters. For example, if you enter gg as the prefix for the 64-bit ODBC driver for Oracle, the default file name of ddora28.dll becomes ggora28.dll.

The installation program (or script, for UNIX/Linux) for Progress DataDirect drivers enables you to install and brand from downloaded files or a network directory. Using the installation program is a quick and efficient way to brand your drivers.

The examples used in this tutorial correspond to the GUI version of the installer. In addition, the installation program can be used to create a response file for a silent installation when upgrading to a new version of the product.

• Acquire the product package and a Control Number. Download information and the Control Number are provided in the OEM Welcome email.
• Register a password through the Progress DataDirect Web site. Doing this means that you always have a resource from which to retrieve it.
• Register a prefix through the Progress DataDirect Web site to avoid file name conflicts with other Progress DataDirect drivers, DataDirect Connect Series drivers, or DataDirect Cloud drivers that may be installed on a user's system.

Note: The OEM Partners section of the Progress DataDirect Web site is password-protected. As part of your OEM agreement, Progress DataDirect provides you with the appropriate location and passwords for the site.

Once you have the product package, the Control Number, a registered password, and a registered prefix, you are ready to begin the branding process.

To brand your Progress DataDirect for JDBC drivers, take the following steps:

1. Run the installation program found in the product package.
2. After accepting the terms of the license agreement and identifying an installation directory, select OEM or Licensed installation and then enter your product licensing information and your Control Number.
3. Select Branded Installation and enter the appropriate information in the Product Branding window.

   

   • Serial Number: Type the serial number that was provided by Progress DataDirect in the Serial Number field.
   • User Name: Type your name.
   • Company Name: Type your company name.
   • File Prefix: Type the file prefix you registered through the OEM Partners section of the Progress DataDirect Web site. This prefix is added to DataDirect file names. For example, if dx is your file prefix, mongodb.jar becomes dxmongodb.jar.
   • Package Prefix: Type a package prefix for the branded driver. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the driver jar file when you brand a driver. For example, if com.xyzcompany.xyzdivision is your package prefix, the MongoDB driver class:

     com.ddtek.jdbc.mongodb.MongoDBDriver

     becomes:

     com.xyzcompany.xyzdivision.jdbc.mongodb.MongoDBDriver

   • Subprotocol Prefix: Progress DataDirect drivers are registered with a URL subprotocol of the form datadirect:drivername, for example, datadirect:mongodb. To replace datadirect in the subprotocol of a branded driver with your company name, type a prefix in this field. For example, if xyzcompany is your subprotocol prefix, the URL:

     jdbc:datadirect:mongodb://server1:27017

     becomes:

     jdbc:xyzcompany:mongodb://server1:27017

   • Message Prefix: Type an error message prefix for the branded drivers.

     After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message:

     [DataDirect][MongoDB JDBC Driver] Object has been closed

     becomes:

     [xyzcompany][MongoDB JDBC Driver] Object has been closed

   • Password: Type the password you registered through the Partners section of the Progress DataDirect Web site. This password prevents unauthorized applications from using the branded drivers.
4. Review the pre-installation summary and make changes if needed. Click Install to generate a branded installation of the driver to the directory you have specified.

Results:

See Branding Results (JDBC Drivers) for a summary of the results produced by this branding process.

Depending on the type of driver, branding produces the following results.

ODBC Drivers

• Installs a version of the driver files using the file prefix you specified and updates the license file. For UNIX/Linux versions of the product, the installed odbc.ini and odbcinst.ini files are updated as well. The branded files appear in the directory specified during the installation process.
• Locks the branded drivers with the password you specified. Your application must supply this password to unlock the branded drivers. See Unlocking the Drivers for instructions on unlocking the branded drivers.
• Changes the message prefix for driver-generated error messages so that messages will display the message prefix you specified.
• Optionally, adds a branding suffix which consists of two numeric characters.

JDBC Drivers

• Installs a version of the product jar files using the file prefix you specified. The branded files appear in the directory specified during branding.
• Changes the package names for the branded driver using the package prefix you specified.
• Changes the URL subprotocol using the subprotocol prefix you specified.
• Changes the message prefix for driver-generated error messages so that messages display the message prefix you specified.
• Locks the branded drivers with the password you specified. Your application must supply this password to unlock the branded drivers. See Unlocking the Drivers for instructions on unlocking the branded drivers.

This section describes the general tasks for creating an installation program. OEM partners are provided with platform-specific instructions.

To load the driver files, create an installation program that:

1. Copies the branded files to the client machine. OEM partners are provided with a list of specific files that must be distributed, that may be distributed, and that must not be distributed.

   Before your installation program copies a file to a client machine, ensure that it:

   1. Checks whether the file already exists and, if so, compares the dates of both files.
   2. Asks users if they want to overwrite an existing file with a newer version.
2. (ODBC only) Includes the necessary entries to the system information files and environment variables. The entries you must make are platform-dependent. Progress DataDirect for ODBC drivers conform to the ODBC standard, and the appropriate configuration entries must be made based on this standard.
3. (Optional) Provides a way for the user to set driver configuration parameters for each installed driver.

Progress DataDirect drivers can be unlocked only by applications that supply the case-sensitive password that was locked into the driver when it was branded. The method used to unlock drivers differs based on application API, as summarized here.

ODBC Applications

Branded drivers work with ODBC-enabled applications that pass the password to the driver after establishing a connection. ODBC-enabled applications may be developed using tools such as:

• ODBC Software Developer’s Kit (SDK)
• Microsoft Visual Basic or other development tools that hide the ODBC interface (Windows platforms only)
• C++ ODBC Wrappers
• OLE DB Software Developer’s Kit (SDK) and ADO

Ideally, the driver is unlocked by making additional ODBC API calls; however, if you do not have access to the source code or use a development tool that hides the ODBC interface (Visual Basic, OLEDB), this may not be possible. In these scenarios, there are some alternative methods available to communicate the password to the driver. When appropriate, OEM partners are provided with detailed explanations and code examples to assist in this process.

JDBC Applications

To unlock a branded driver, wrap the JDBC Connection object in a special class and call the unlock method on that connection. The unlock method takes the password that was specified during the branding process as an input argument. If your application is unable to unlock the driver using Java code methods, other options are available in certain scenarios.

For more information about Progress products or becoming an OEM Partner, contact a Progress DataDirect representative.

Progress DataDirect is the worldwide leader in data connectivity supporting over 350 ISVs across 10,000 organizations. Read more about how Progress DataDirect helps ISVs with data connectivity solutions on our ISV Solutions page.

For current OEM Partners, refer to the JDBC and ODBC Progress DataDirect drivers distribution guides for detailed instructions on installing, branding, unlocking, and distributing your branded drivers.