Type 4 JDBC Drivers

Using The Type 4 JDBC Drivers

The Type 4 JDBC drivers from DataDirect provide JDBC high-performance access through Oracle CEP to industry-leading data stores across the Internet and intranets. The Type 4 JDBC drivers are optimized for the Java environment, allowing you to incorporate Java technology and extend the functionality and performance of your existing system.

The Oracle CEP Type 4 JDBC drivers from DataDirect are proven drivers that:

The following sections provide more information about the Type 4 JDBC drivers:

JDBC Specification Compliance

The Type 4 JDBC drivers are compliant with the JDBC 3.0 specification In addition, the Type 4 JDBC drivers support the following JDBC 4.0 specification features:

For details, see JDBC Support.

Installation

Type 4 JDBC drivers are automatically installed with Oracle CEP and are automatically added to your classpath on the server.

Supported Databases

Table 2-1 shows the databases supported by each of the Type 4 JDBC drivers.

Connecting Through JDBC Data Sources

To use the Type 4 JDBC drivers, you create a JDBC data source in your Oracle CEP configuration and select the JDBC driver to create the physical database connections in the data source. Applications can then look up the data source on the JNDI tree and request a connection.

For information about JDBC and data sources in Oracle CEP, see Configuring Access to a Relational Database.

Specifying Connection Properties

You specify connection properties for connections in a data source Oracle CEP config.xml file. Connection properties vary by DBMS. For the list of the connection properties specific to each Type 4 JDBC driver, see the appropriate driver chapter:

Limiting Connection Creation Time with LoginTimeout

When creating database connections in a JDBC data source, if the database is unavailable, the request may hang until the default system timeout expires. On some systems this can be as long as 9 minutes. The request will hang for each connection in the JDBC data source. To minimize this hang time, you can specify a LoginTimeout value for the connection. All Type 4 JDBC Drivers support the LoginTimeout connection property. When you specify a LoginTimeout connection property and the connection is not created immediately, the request waits for the time you specify. If the connection cannot be created within the time specified, the driver throws an SQL exception.

For details on configuring connection properties, see the appropriate driver chapter:

Using IP Addresses

The Type 4 JDBC drivers support Internet Protocol (IP) addresses in IPv4 and IPv6 format. IPv6 addresses are only supported when connecting to certain database versions (as shown in Table 2-2). In addition, to connect to IPv6 addresses, the driver machine requires J2SE 5.0 or higher on Windows and J2SE 1.4 on UNIX/Linux.

If your network supports named servers, the server name specified in the connection URL or data source can resolve to an IPv4 or IPv6 address. Alternatively, you can specify addresses using IPv4 or IPv6 format in the server name portion of the connection URL. You also can specify addresses in either format using the ServerName data source property.

In addition to the normal IPv6 format, the Type 4 JDBC drivers support IPv6 alternative formats for compressed and IPv4/IPv6 combination addresses.

For complete information about IPv6, go to the following URL:

http://tools.ietf.org/html/rfc4291#section-2.2

Using Security

The Type 4 JDBC drivers support the following security features: authentication and data encryption.

Authentication

On most computer systems, a password is used to prove a user's identity. This password often is transmitted over the network and can possibly be intercepted by malicious hackers. Because this password is the one secret piece of information that identifies a user, anyone knowing a user's password can effectively be that user. Authentication methods protect the identity of the user. Type 4 JDBC drivers support the following authentication methods:

Table 2-3 shows the authentication methods supported by the Type 4 JDBC drivers.

Kerberos Authentication Requirements

Verify that your environment meets the requirements listed in Table 2-4 before you configure your driver for Kerberos authentication.

To use Kerberos authentication, some configuration is required after installation of the JDBC Type 4 drivers. See the individual driver chapters for details about configuring authentication.

NTLM Authentication Requirements

Verify that your environment meets the requirements listed in Table 2-5 before you configure the driver for NTLM authentication.

To use NTLM authentication, minimal configuration is required after installation of the JDBC Type 4 drivers. See the individual driver chapters for details about configuring authentication.

Data Encryption Across the Network

If your database connection is not configured to use data encryption, data is sent across the network in a format that is designed for fast transmission and can be decoded by interceptors given some time and effort. Because this format does not provide complete protection from interceptors, you may want to use data encryption to provide a more secure transmission of data. For example, you may want to use data encryption in the following scenarios:

Type 4 JDBC drivers support the following encryption method:

Table 2-6 shows the data encryption methods supported by the Type 4 JDBC drivers.

SSL Encryption

SSL works by allowing the client and server to send each other encrypted data that only they can decrypt. SSL negotiates the terms of the encryption in a sequence of events known as the SSL handshake. The handshake involves the following types of authentication:

See the individual driver chapters for details about configuring SSL.

SSL Server Authentication

When the client makes a connection request, the server presents its public certificate for the client to accept or deny. The client checks the issuer of the certificate against a list of trusted Certificate Authorities (CAs) that resides in an encrypted file on the client known as a truststore. Optionally, the client may check the subject (owner) of the certificate. If the certificate matches a trusted CA in the truststore (and the certificate’s subject matches the value that the application expects), an encrypted connection is established between the client and server. If the certificate does not match, the connection fails and the driver throws an exception.

To check the issuer of the certificate against the contents of the truststore, the driver must be able to locate the truststore and unlock the truststore with the appropriate password. You can specify truststore information in either of the following ways:

Alternatively, you can configure the Type 4 JDBC drivers to trust any certificate sent by the server, even if the issuer is not a trusted CA. Allowing a driver to trust any certificate sent from the server is useful in test environments because it eliminates the need to specify truststore information on each client in the test environment. If the driver is configured to trust any certificate sent from the server, the issuer information in the certificate is ignored.

Required Permissions for the Java Security Manager

Using the Type 4 JDBC drivers with the Java Security Manager enabled requires certain permissions to be set in the security policy file of the domain. WebLogic Server provides a sample security policy file that you can edit and use. The file is located at WL_HOME\server\lib\weblogic.policy. The weblogic.policy file includes all necessary permissions for the drivers except for access to temporary files and access to tnsnames.ora. If you use the weblogic.policy file without changes, you may not need to grant any further permissions. If you use another security policy file or if you use driver features that require additional permissions, see the following sections for details about required permissions.

Permissions for Establishing Connections

To establish a connection to the database server, the Type 4 JDBC drivers must be granted the permissions as shown in the following examples. You must grant permissions to the wlbase.jar and wlutil.jar files as well as the jar for your specific database management system. You can grant the permissions to all JAR files in the directory or just to the specific files.

For all JAR files in the directory:

   grant codeBase "file:WL_HOME${/}server${/}lib${/}-" {
      permission java.net.SocketPermission "*", "connect";
   };

For individual JAR files:

   grant codeBase "file:WL_HOME${/}server${/}lib${/}wlbase.jar" {
      permission java.net.SocketPermission "*", "connect";
   };

   grant codeBase "file:WL_HOME${/}server${/}lib${/}wlutil.jar" {
      permission java.net.SocketPermission "*", "connect";
   };

And one or more of the following:

   //For MS SQL Server:
   grant codeBase "file:WL_HOME${/}server${/}lib${/}wlsqlserver.jar" {
      permission java.net.SocketPermission "*", "connect";
   };

where WL_HOME is the directory in which you installed WebLogic Server.

In addition, if Microsoft SQL Server named instances are used, permission must be granted for the listen and accept actions as shown in the following example:

   grant codeBase "file:WL_HOME${/}server${/}lib${/}-" {
      permission java.net.SocketPermission "*", "listen, connect, accept";
   };

Granting Access to Java Properties

To allow the Type 4 JDBC drivers to read the value of various Java properties to perform certain operations, permissions must be granted as shown in the following example:

   grant codeBase "file:WL_HOME${/}server${/}lib${/}-" {
      permission java.util.PropertyPermission "false", "read";
      permission java.util.PropertyPermission "user.name", "read";
      permission java.util.PropertyPermission "user.language", "read";
      permission java.util.PropertyPermission "user.country", "read";
      permission java.util.PropertyPermission "os.name", "read";
      permission java.util.PropertyPermission "os.arch", "read";
      permission java.util.PropertyPermission "java.specification.version",
         "read";
   };

where WL_HOME is the directory in which you installed WebLogic Server.

You can also grant these permissions to individual files as shown in Permissions for Establishing Connections.

Granting Access to Temporary Files

Access to the temporary directory specified by the JVM configuration must be granted in the security policy file, typically in the security policy file used by the JVM in the JAVA_HOME/jre/lib/security folder. To use insensitive scrollable cursors or to perform client-side sorting of DatabaseMetaData result sets, all code bases must have access to temporary files. The following example shows permissions that have been granted for the C:\TEMP directory:

   // permissions granted to all domains
   grant codeBase "file:WL_HOME${/}server${/}lib${/}-" {
   // Permission to create and delete temporary files.
   // Adjust the temporary directory for your environment.
   permission java.io.FilePermission "C:\\TEMP\\-", "read,write,delete";
   };

where WL_HOME is the directory in which you installed WebLogic Server.

You can also grant these permissions to individual files as shown in Permissions for Establishing Connections.

Permissions for Kerberos Authentication

To use Kerberos authentication with the Type 4 JDBC drivers that support it, the application and driver code bases must be granted security permissions in the security policy file of the Java 2 Platform as shown in the following examples.

For more information about using Kerberos authentication with the Type 4 JDBC drivers, see the appropriate driver chapters.

Microsoft SQL Server

grant codeBase "file:/WL_HOME/server/lib/-" {
   permission javax.security.auth.AuthPermission
      "createLoginContext.DDTEK-JDBC";
   permission javax.security.auth.AuthPermission "doAs";
   permission javax.security.auth.kerberos.ServicePermission 
      "krbtgt/your_realm@your_realm", "initiate";
   permission javax.security.auth.kerberos.ServicePermission 
      "MSSQLSvc/db_hostname:SQLServer_port@your_realm", "initiate";
};

where:

Unicode Support

Multi-lingual applications can be developed on any operating system platform with JDBC using the Type 4 JDBC drivers to access both Unicode and non-Unicode enabled databases. Internally, Java applications use UTF-16 Unicode encoding for string data. When fetching data, the Type 4 JDBC drivers automatically perform the conversion from the character encoding used by the database to UTF-16. Similarly, when inserting or updating data in the database, the drivers automatically convert UTF-16 encoding to the character encoding used by the database.

The JDBC API provides mechanisms for retrieving and storing character data encoded as Unicode (UTF-16) or ASCII. Additionally, the Java string object contains methods for converting UTF-16 encoding of string data to or from many popular character encodings.

Error Handling

The Type 4 JDBC drivers report errors to the calling application by throwing SQLExceptions. Each SQLException contains the following information:

Driver Errors

An error generated by a Type 4 JDBC driver has the following format:

   [BEA][Type 4 JDBC driver name]message

For example:

   [BEA][SQLServer JDBC Driver]Timeout expired.

You may need to check the last JDBC call your application made and refer to the JDBC specification for the recommended action.

Database Errors

An error generated by the database has the following format:

   [BEA][Type 4 JDBC driver name][DBMS name] message

For example:

   [BEA][SQL Server JDBC Driver][SQL Server] Invalid Object Name.

Use the native error code to look up details about the possible cause of the error. For these details, refer to your database documentation.