Oracle Type 4 JDBC drivers from DataDirect provide JDBC high-performance access through WebLogic Server to industry-leading data stores across the Internet and intranets. The Oracle 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 Type 4 JDBC drivers from DataDirect are proven drivers that:
Support performance-oriented and enterprise functionality such as distributed transactions, savepoints, multiple open result sets and parameter metadata.
Are Java EE Compatibility Test Suite (CTS) certified and tested with the largest JDBC test suite in the industry.
Include tools for testing and debugging JDBC applications.
The following sections provide more information about the Oracle Type 4 JDBC drivers:
Oracle Type 4 JDBC drivers are compliant with the JDBC 3.0 specification In addition, the Oracle Type 4 JDBC drivers support the following JDBC 4.0 specification features:
Connection validation
Client information storage and retrieval
Auto-load driver classes (when using Java SE 6)
For details, see Appendix A, "JDBC Support."
Note:
When comparing WebLogic Server behavior when using drivers from different vendors, it is important to remember that even though the drivers are JDBC specification compliant, a vendor may interpret the specification differently or provide different implementations for a given situation.For example: When using the Oracle Type 4 JDBC SQL Server driver, if you enter a negative value (-100) into a TINYINT column where the schema defines the range as 0 to 256, the driver throws an exception, whereas the Microsoft SQL Server driver ignores the minus sign.
Oracle Type 4 JDBC drivers are installed with WebLogic Server in the WL_HOME\server\lib folder, where WL_HOME is the directory in which you installed WebLogic Server. Driver class files are included in the manifest classpath in weblogic.jar, so the drivers are automatically added to your classpath on the server.
Note:
The Oracle Type 4 JDBC drivers are installed by default when you perform a complete installation of WebLogic Server. If you choose a custom installation, ensure that the WebLogic JDBC Drivers option is selected (checked). If this option is unchecked, the drivers are not installed.The Oracle Type 4 JDBC drivers are not included in the manifest classpath of the WebLogic client jar files (for example: wlclient.jar). To use the drivers with a WebLogic client, you must copy the following files to the client and add them to the classpath on the client:
For DB2: wldb2.jar
For Informix: wlinformix.jar
For MS SQL Server: wlsqlserver.jar
For Sybase: wlsybase.jar
For information on database support, see http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html.
To use the Oracle Type 4 JDBC drivers, you create a JDBC data source in your WebLogic Server 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.
See the following related information:
For information about JDBC and data sources in WebLogic Server, see Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.
For information about requesting a connection from a data source, see "Obtaining a Client Connection Using a DataSource" in Programming JDBC for Oracle WebLogic Server.
You specify connection properties for connections in a data source using the WebLogic Server Administration Console, command line interface, or JMX API. Connection properties vary by DBMS. For the list of the connection properties specific to each Oracle Type 4 JDBC driver, see the appropriate driver chapter:
For the DB2 driver, see DB2 Connection Properties.
For the Informix driver, see Informix Connection Properties.
For the MS SQL Server driver, see SQL Server Connection Properties.
For the Sybase driver, see Sybase Connection Properties.
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 Oracle 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:
The Oracle 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-1). 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.
Table 2-1 IP Address Formats Supported by the Oracle Type 4 JDBC Drivers
| Driver | IPv4 | IPv6 |
|---|---|---|
|
DB2 |
All supported versions |
DB2 v9.1 for z/OS DB2 V9.1 for Linux/UNIX/Windows and higher DB2 V5R2 for iSeries and higher |
|
Informix |
All supported versions |
Informix 10 and higher |
|
Microsoft SQL Server |
All supported versions |
Microsoft SQL Server 2005 and higher |
|
Sybase |
All supported versions |
Sybase 12.5.2 and higher |
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. For example, the server name DB2Server in the following URL can resolve to either type of address:
jdbc:weblogic:db2://DB2Server:50000;DatabaseName=jdbc;User=test; Password=secret
Alternatively, you can specify addresses using IPv4 or IPv6 format in the server name portion of the connection URL. For example, the following connection URL specifies the server using IPv4 format:
jdbc:weblogic:db2://123.456.78.90:50000;DatabaseName=jdbc;User=test; Password=secret
You also can specify addresses in either format using the ServerName data source property. The following example shows a data source definition that specifies the server name using IPv6 format:
DB2DataSource mds = new DB2DataSource();
mds.setDescription("My DB2DataSource");
mds.setServerName("[ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]");
mds.setPortNumber(50000);
...
Note:
When specifying IPV6 addresses in a connection URL or data source property, the address must be enclosed by brackets.In addition to the normal IPv6 format, the Oracle Type 4 JDBC drivers support IPv6 alternative formats for compressed and IPv4/IPv6 combination addresses. For example, the following connection URL specifies the server using IPv6 format, but uses the compressed syntax for strings of zero bits:
jdbc:weblogic:db2://[2001:DB8:0:0:8:800:200C:417A]:50000;DatabaseName=jdbc; User=test;Password=secret
Similarly, the following connection URL specifies the server using a combination of IPv4 and IPv6:
jdbc:weblogic:db2://[0000:0000:0000:0000:0000:FFFF:123.456.78.90]:50000; DatabaseName=jdbc;User=test;Password=secret
For complete information about IPv6, go to the following URL:
The Oracle Type 4 JDBC drivers support the following security features: authentication and data encryption.
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. Oracle Type 4 JDBC drivers support the following authentication methods:
User ID/password authentication authenticates the user to the database using a database user name and password.
Kerberos is a trusted third-party authentication service. The drivers support both Windows Active Directory Kerberos and MIT Kerberos implementations for DB2, and Sybase. For SQL Server, the driver supports Windows Active Directory Kerberos only.
Client authentication uses the user ID of the user logged onto the system on which the driver is running to authenticate the user to the database. The database server relies on the client to authenticate the user and does not provide additional authentication.
NTLM authentication is a single sign-on authentication method for Windows environments. This method provides authentication from Windows clients only.
Table 2-2 shows the authentication methods supported by the Oracle Type 4 JDBC drivers.
Table 2-2 Authentication Methods Supported by the Oracle Type 4 JDBC Drivers
| Driver | UserID/Password | Kerberos | Client | NTLM |
|---|---|---|---|---|
|
DB2 for Linux/UNIX/Windows |
X |
X |
X |
N/A |
|
DB2 for z/OS |
X |
X |
X |
N/A |
|
DB2 for iSeries |
X |
N/A |
X |
N/A |
|
Informix |
X |
N/A |
N/A |
N/A |
|
Microsoft SQL Server |
X |
N/A |
X |
|
|
Sybase |
X |
X |
N/A |
N/A |
Footnote 1 Supported for Microsoft SQL Server 2000 and higher.
Verify that your environment meets the requirements listed in Table 2-3 before you configure your driver for Kerberos authentication.
Table 2-3 Kerberos Authentication Requirements for the Drivers
| Component | Requirements |
|---|---|
|
Database server |
The database server must be running one of the following databases: DB2:
Microsoft SQL Server:
Sybase:
|
|
Kerberos server |
The Kerberos server is the machine where the user IDs for authentication are administered. The Kerberos server is also the location of the Kerberos Key Distribution Center (KDC). If using Windows Active Directory, this machine is also the domain controller. DB2 and Sybase: Network authentication must be provided by one of the following methods:
Microsoft SQL Server: Network authentication must be provided by Windows Active Directory on one of the following operating systems:
|
|
Client |
J2SE 1.4.2 or higher must be installed. |
To use Kerberos authentication, some configuration is required after installation of the WebLogic JDBC Type 4 drivers. See the individual driver chapters for details about configuring authentication.
Verify that your environment meets the requirements listed in Table 2-4 before you configure the driver for NTLM authentication.
Table 2-4 NTLM Authentication Requirements for the Drivers
| Component | Requirements |
|---|---|
|
Database server |
The database server must be administered by the same domain controller that administers the client and must be running one of the following databases: Microsoft SQL Server:
|
|
Domain controller |
The domain controller must administer both the database server and the client. Network authentication must be provided by NTLM on one of the following operating systems:
|
|
Client |
The client must be administered by the same domain controller that administers the database server and must be running on one of the following operating systems:
In addition, J2SE 1.3 or higher must be installed. |
To use NTLM authentication, minimal configuration is required after installation of the WebLogic JDBC Type 4 drivers. See the individual driver chapters for details about configuring authentication.
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:
You have offices that share confidential information over an intranet.
You send sensitive data, such as credit card numbers, over a database connection.
You need to comply with government or industry privacy and security requirements.
Note:
Data encryption may adversely affect performance because of the additional overhead (mainly CPU usage) required to encrypt and decrypt data.Oracle Type 4 JDBC drivers support the following encryption methods:
Database-specific encryption (DB2 for Linux/UNIX/Windows and DB2 for z/OS only). DB2 defines its own encryption protocol for these databases. See Data Encryption for information about configuring DB2 encryption.
Secure Sockets Layer (SSL). SSL is an industry-standard protocol for sending encrypted data over database connections. SSL secures the integrity of your data by encrypting information and providing client/server authentication.
Table 2-5 shows the data encryption methods supported by the Oracle Type 4 JDBC drivers.
Table 2-5 Data Encryption Methods Supported by the Oracle Type 4 JDBC Drivers
| Driver | Database-Specific | SSL |
|---|---|---|
|
DB2 for Linux/UNIX/Windows |
X |
|
|
DB2 for z/OS |
X |
NA |
|
DB2 for iSeries |
NA |
NA |
|
Informix |
N/A |
N/A |
|
Microsoft SQL Server |
N/A |
|
|
Sybase |
N/A |
X |
Footnote 1 Supported for DB2 V5R3 and higher for iSeries
Footnote 2 Supported for Microsoft SQL Server 2000 and higher.
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:
SSL server authentication requires the server to authenticate itself to the client.
SSL client authentication is optional and requires the client to authenticate itself to the server after the server has authenticated itself to the client.
Note:
SSL client authentication is supported with DB2 only.See the individual driver chapters for details about configuring SSL.
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:
Specify values for the Java system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword. For example:
java -Djavax.net.ssl.trustStore=C:\Certificates\MyTruststore
and
java -Djavax.net.ssl.trustStorePassword=MyTruststorePassword
This method sets values for all SSL sockets created in the JVM.
Specify values for the connection properties TrustStore and TrustStorePassword. For example:
TrustStore=C:\Certficates\MyTruststore
and
TrustStorePassword=MyTruststorePassword
Any values specified by the TrustStore and TrustStorePassword properties override values specified by the Java system properties. This allows you to choose which truststore file you want to use for a particular connection.
Alternatively, you can configure the Oracle 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.
If the server is configured for SSL client authentication, the server asks the client to verify its identity after the server has proved its identity. Similar to SSL server authentication, the client sends a public certificate to the server to accept or deny. The client stores its public certificate in an encrypted file known as a keystore.
The driver must be able to locate the keystore and unlock the keystore with the appropriate keystore password. Depending on the type of keystore used, the driver also may need to unlock the keystore entry with a password to gain access to the certificate and its private key.
The Oracle Type 4 JDBC drivers can use the following types of keystores:
Java Keystore (JKS) contains a collection of certificates. Each entry is identified by an alias. The value of each entry is a certificate and the certificate's private key. Each keystore entry can have the same password as the keystore password or a different password. If a keystore entry has a password different than the keystore password, the driver must provide this password to unlock the entry and gain access to the certificate and its private key.
PKCS #12 keystore contains only one certificate. To gain access to the certificate and its private key, the driver must provide only the keystore password. The file extension of the keystore must be .pfx or .p12.
You can specify this information in either of the following ways:
Specify values for the Java system properties javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword. For example:
java -Djavax.net.ssl.keyStore=C:\Certificates\MyKeystore
and
java -Djavax.net.ssl.keyStorePassword=MyKeystorePassword
This method sets values for all SSL sockets created in the JVM.
Note:
If the keystore specified by thejavax.net.ssl.keyStore Java system property is a JKS and the keystore entry has a password different than the keystore password, the KeyPassword connection property must specify the password of the keystore entry. For example: KeyPassword=MyKeyPasswordSpecify values for the connection properties KeyStore and KeyStorePassword. For example:
KeyStore=C:\Certficates\MyKeyStore
and
KeyStorePassword=MyKeystorePassword
Note:
If the keystore specified by the KeyStore connection property is a JKS and the keystore entry has a password different than the keystore password, the KeyPassword connection property must specify the password of the keystore entry. For example:KeyPassword=MyKeyPasswordAny values specified by the KeyStore and KeyStorePassword properties override values specified by the Java system properties. This allows you to choose which keystore file you want to use for a particular connection.
Using the Oracle 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. 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.
Note:
Web browser applets running in the Java 2 plug-in are always running in a JVM with the Java Security Manager enabled.For more information about using the Java Security Manager with WebLogic Server, see "Using Java Security to Protect WebLogic Resources" in Programming Security for Oracle WebLogic Server.
To establish a connection to the database server, the Oracle Type 4 JDBC drivers must be granted the permissions as shown in the following examples. You must grant permissions to 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:
//For DB2: grant codeBase "file:WL_HOME${/}server${/}lib${/}wldb2.jar" { permission java.net.SocketPermission "*", "connect"; }; //For Informix: grant codeBase "file:WL_HOME${/}server${/}lib${/}wlinformix.jar" { permission java.net.SocketPermission "*", "connect"; }; //For MS SQL Server: grant codeBase "file:WL_HOME${/}server${/}lib${/}wlsqlserver.jar" { permission java.net.SocketPermission "*", "connect"; }; //For Sybase: grant codeBase "file:WL_HOME${/}server${/}lib${/}wlsybase.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";
};
To allow the Oracle 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.
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.
To use Kerberos authentication with the Oracle 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 Oracle Type 4 JDBC drivers, see the appropriate driver chapters.
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 example.
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 "principal_name/db_hostname@your_realm", "initiate"; };
where:
WL_HOME is the directory in which you installed WebLogic Server.
principal_name is the service principal name registered with the Kerberos Key Distribution Center (KDC) that identifies the database service.
your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.
db_hostname is the host name of the machine running the database.
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 example.
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:
WL_HOME is the directory in which you installed WebLogic Server.
your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.
db_hostname is the host name of the machine running the database.
SQLServer_port is the TCP/IP port on which the Microsoft SQL Server instance is listening.
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 example.
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 "principal_name/db_hostname@your_realm", "initiate"; };
where:
WL_HOME is the directory in which you installed WebLogic Server.
your_realm is the Kerberos realm (or Windows Domain) to which the database host machine belongs.
principal_name is the service principal name registered with the KDC that identifies the database service.
db_hostname is the host name of the machine running the database.
Although the Oracle Type 4 JDBC drivers support XA, you may need to configure your database to support XA with the drivers. See the following sections for more details:
For DB2, see JTA Support.
For Microsoft SQL Server, see Installing Stored Procedures for JTA.
For Sybase, see Sybase JTA Support.
Multi-lingual applications can be developed on any operating system platform with JDBC using the Oracle 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 Oracle 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.
The Oracle Type 4 JDBC drivers report errors to the calling application by throwing SQLExceptions. Each SQLException contains the following information:
Description of the probable cause of the error, prefixed by the component that generated the error
Native error code (if applicable)
String containing the XOPEN SQLstate
An error generated by a Oracle Type 4 JDBC driver has the following format:
[OWLS][Oracle Type 4 JDBC driver name]message
For example:
[OWLS][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.
An error generated by the database has the following format:
[OWLS][Oracle Type 4 JDBC driver name][DBMS name] message
For example:
[OWLS][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.