Package oracle.jdbc

## Class OracleDriver

- java.lang.Object
- - oracle.jdbc.driver.OracleDriver
  - - oracle.jdbc.OracleDriver

All Implemented Interfaces:
  `Driver`, `oracle.jdbc.internal.Monitor`

    public class OracleDriver
    extends oracle.jdbc.driver.OracleDriver

The Oracle JDBC driver class that implements the `java.sql.Driver` interface.

# Register the JDBC drivers

The JDBC driver registration is automatically done via the Java Standard Edition Service Provider mechanism introduced in `JDK6`. Oracle JDBC driver implements this feature and it is automatically registered if the Oracle JDBC driver jar is present in the classpath.

# Open a Connection to a database

You can open a connection to the database with the static `getConnection()` method of the `java.sql.DriverManager` class. The type of the object returned is `java.sql.Connection`.

## Understanding the Forms of getConnection()

### Specifying a Databse URL, User Name, and Password

The following signature takes the URL, user name, and password as separate parameters:

`getConnection(String URL, String user, String password);`

### Specifying a Database URL and Properties Object

The following signature takes a URL, together with a properties object that specifies user name and password (perhaps among other things):

`getConnection(String URL, Properties info);`

Where the `URL` is of the form:
`jdbc:oracle:<drivertype>:@<database>`

In addition to the URL, use an object of the standard Java `Properties` class as input. For example:

`java.util.Properties info = new java.util.Properties();
info.put ("user", "scott");
info.put ("password","tiger");
info.put ("defaultRowPrefetch","15");
getConnection ("jdbc:oracle:thin:@",info);`

# URL Formats

Oracle JDBC Thin Driver supports the following URL formats to establish a connection with an Oracle Database. Use any of the below format to establish connection to the Oracle Database.

### EZConnect

As the name suggests the EZConnect URL is the easiest option to connect to Oracle.

#### Format :

`jdbc:oracle:thin:@[[protocol:]//]
host1[,host12,host13][:port1][,host2:port2]/service_name[:server][/instance_name]
[?[parameter-name1=parameter-value1][&parameter-name2=parameter-value2],...]
`

In the above format, the parts that are enclosed in square brackets are optional. TCP and TCPS are supported protocols. Specifying the protocol is optional and the default value is TCP. The URL must contain at least one database host name. Multiple host names are separated by a comma. The host name is followed by an optional port number. If multiple hosts share the same port number then the port number can be specified at the end of the host names list. The default port value is `1521`. Host and port information is followed by the database service name which is in turn followed by the optional server mode and the database instance name. The supported server modes are `dedicated|shared|pooled`.

An EZConnect URL can have an optional list of name-value pairs as parameters after the '?' delimiter. Name and value are separated by an '=' and multiple properties are separated by an '&'.
The Thin driver creates a TNS URL using the information provided in the EZConnect format. While resolving to the TNS format, a name-value pair specified in the EZConnect format is resolved to a TNS URL parameter. If a name-value pair can not be resolved to a TNS URL parameter then it is handled as a connection property. The list of supported name value pairs are as follows

TNS URL Parameter:

Parameter Name | Description
--- | ---
ssl_server_dn_match | Specifies if DN matching is to be enforced. Applicable only for TCPS connection and the default is ON.
ssl_server_cert_dn | Specifies the DN of the database server.
https_proxy | Specifies proxy host to be used while establishing connection to the Oracle Database.
https_proxy_port | Specifies proxy port to be used while establishing connection to the Oracle Database.
enable | The keepalive feature on the supported TCP transports can be enabled for a client by specifying `enable=broken`
failover | To enable or disable connect-time failover for multiple protocol addresses. Supported values `on | off`
load_balance | To enable or disable client load balancing for multiple protocol addresses. Supported values `on | off`
recv_buf_size | To specify, in bytes, the buffer space for receive operations of sessions
send_buf_size | To specify, in bytes, the buffer space for send operations of sessions.
sdu | To instruct JavaNet to optimize the transfer rate of data packets being sent across the network with a specified session data unit (SDU) size in bytes.
source_route | To enable routing through multiple protocol addresses. Supported values `on | off`
retry_count | To specify the number of times an ADDRESS list is traversed before the connection attempt is terminated. The default value is 0.
retry_delay | To specify the delay in seconds between subsequent retries for a connection. This parameter works in conjunction with `retry_count` parameter.

Connection Property Name-Value pairs:

Parameter Name | Description
--- | ---
wallet_location | Specifies the location of the wallet file. More Info..
ssl_ciphers | Use this to specify the set of cipher suites to be used while SSL protocol negotiation. More Info..
connect_timeout | To specify the timeout duration in seconds for a client to establish an Oracle Net session to an Oracle database. More Info..
transport_connect_timeout | To specify the transportation timeout duration in seconds for a client to establish an network connection to an Oracle Database. More Info..
encryption_client | Specifies the encryption level supported by client. Supported values are `accepted | rejected | requested | required` More Info..
encryption_types_client | Specifies the list of encryption algorithms supported by client. Supported algorithms are `AES128, AES192, AES256, RC4_40, RC4_56, RC4_128, RC4_256, DES, DES40, 3DES112, 3DES168.` More Info..
crypto_checksum_client | Specifies the data integrity level supported by client. Supported values are `accepted | rejected | requested | required` More Info..
crypto_checksum_types_client | Specifies the list of data integrity algorithms supported by client. Supported algorithms are `SHA256, SHA384, SHA512, SHA1, MD5` More Info..

Other connection properties specified in `oracle.jdbc.OracleConnection` can also be configured through EZConnect format. Please use the value of the connection property constant name declared in oracle.jdbc.OracleConnection for configuring the property. Connection property constant names start with `CONNECTION_PROPERTY_`.

#### Examples :

- jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com
- jdbc:oracle:thin:@//salesserver1,salesserver2:1521/sales.us.example.com
- jdbc:oracle:thin:@//salesserver1:1521,salesserver2,salesserver3:1522/sales.us.example.com
- jdbc:oracle:thin:@tcps://salesserver1:1521/sales.us.example.com
- jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com?connect_timeout=60&retry_count=3
- jdbc:oracle:thin:@tcps://salesserver1:1521/sales.us.example.com?wallet_location=/work/wallet/
- jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com?oracle.net.networkCompression=on

### TNS

This is a descriptive format. Each section is enclosed in parenthesis. Please refer to the Oracle Net Services documentation to know more about the TNS formats and the details of all the supported parameters.

#### Format :

      jdbc:oracle:thin:@(DESCRIPTION=
                        (ADDRESS=(protocol_address_information))
                        (CONNECT_DATA= (SERVICE_NAME=service_name)))

#### Examples :

-       jdbc:oracle:thin:@(DESCRIPTION=
                     (ADDRESS=(PROTOCOL=tcp)(HOST=sales-svr)(PORT=1521))
                     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

-       jdbc:oracle:thin:@(DESCRIPTION=
                         (ADDRESS_LIST= (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
                                        (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
                         (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

-       jdbc:oracle:thin:@(DESCRIPTION=
                          (LOAD_BALANCE=on)
                          (FAILOVER=on)
                          (ADDRESS_LIST=
                             (SOURCE_ROUTE=yes)
                             (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))
                             (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=1521)))
                          (ADDRESS_LIST=
                             (SOURCE_ROUTE=yes)
                             (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=1630))
                             (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=1521)))
                             (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

### Alias

An alias declared in a tnsnames.ora file present in the TNS ADMIN directory can also be used in the URL. At runtime the JDBC Thin Driver resolves the specified alias by referring to the tnsnames.ora file. The TNS ADMIN directory can be specified through the URL or through the connection property `oracle.net.tns_admin`. Any environmental variables in the specified TNS ADMIN path will be resolved automatically.

#### Format :

`jdbc:oracle:thin:@<alias-name>
` `jdbc:oracle:thin:@<alias-name>?TNS_ADMIN=/work/tnsadmin/
`

#### Examples :

- `jdbc:oracle:thin:@inst1
  `
- `jdbc:oracle:thin:@inst1?TNS_ADMIN=/work/tnsadmin/`
- `jdbc:oracle:thin:@inst1?TNS_ADMIN=$ORACLE_HOME/tnsadmin/`
- `jdbc:oracle:thin:@inst1?TNS_ADMIN=%ORACLE_HOME%/tnsadmin/`

### LDAP

The JDBC Thin driver can retrive the TNS URL from an LDAP server. Use the following format for configuring the LDAP server details. JDBC Thin Driver uses the value of the `orclnetdescstring` attribute under the specified DN. If the LDAP connection is established using TCPS (ldaps) connection then the `wallet / keystore` properties can be specified through connection properties. Please see the LDAP connection properties in the below table. Optionally you can configure LDAP authentication details through connection properties or through wallet secret store.

Property Name | Description
--- | ---
oracle.net.ldap.ssl.walletLocation | Use this property to specify the wallet location. The driver will use this wallet while SSL negotiation with LDAP server. More Info..
oracle.net.ldap.ssl.walletPassword | Use this property to specify the password of the wallet file which will be used while SSL negotiation with LDAP Server. More Info..
oracle.net.ldap.security.authentication | Specifies the authentication mechanism to be used by the LDAP service provider in the JDK. Supported values `none | simple` . More Info..
oracle.net.ldap.security.principal | Use this property to specify the value of the username(DN) which will be used while authenticating with the LDAP server. This property can also be configured via wallet secret store entry `oracle.ldap.client.dn` More Info..
oracle.net.ldap.security.credentials | Use this property to configure the password which will be used while authenticating with the LDAP server. This property can also be configured via wallet secret store entry `oracle.ldap.client.password` More Info..

#### Format :

`jdbc:oracle:thin:@ldap://<ldap-host>:<ldap-port>/<dn>
` `jdbc:oracle:thin:@ldaps://<ldap-host>:<ldap-port>/<dn>
`

#### Examples :

- `jdbc:oracle:thin:@ldap://myldapserver:2636/cn=orcl,cn=OracleContext,dc=example,dc=com
  `
- `jdbc:oracle:thin:@ldaps://myldapserver:1636/cn=orcl,cn=OracleContext,dc=example,dc=com`

# Setting JDBC Connection Properties

`oracle.jdbc.OracleConnection` contains constant fields for almost all the properties supported by the JDBC Driver. The name of the constants start with `CONNECTION_PROPERTY_`. In Java code, the constants fields can be used directly. Use the String value of a constant field to configure the property through a URL or through a properties file. The following are the different methods of configuring JDBC connection properties.

### URL

While using the EZConnect URL format, the connection properties can be configured via URL. After the '?' delimiter, Easy Connect supports a list of parameters as name-value pairs which can be optionally specified. The name and value of a connection property is separated by an '=' and multiple properties are separated by an '&'

#### Examples :

- `jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com?oracle.net.networkCompression=on`
- `jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com?oracle.net.networkCompression=on&oracle.net.networkCompressionThreshold=1024`

### Properties File

Connection properties can also be configured via a properties file named `ojdbc.properties`. This properties file should be present under the TNS ADMIN directory. The TNS ADMIN directory can be configured through the URL.

#### Examples :

- `jdbc:oracle:thin:@//salesserver1:1521/sales.us.example.com?TNS_ADMIN=$ORACLE_HOME/tnsadmin/`
- `jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-svr)(PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))?TNS_ADMIN=$ORACLE_HOME/tnsadmin/`

For more information, see

### System Properties

Connection properties can be configured through System properties as well. The below example shows how to configure a system property for a standalone Java application.

`java -Doracle.net.networkCompression=on MyApp`

# Configuring Credentials

The JDBC Driver supports multiple authentication mechanisms:

- Username and Password
- TCPS
- Kerberos
- Radius

### Username and Password

A username and password pair is used to authenticate to the Oracle Database Server. The username and password are specified using the following options.

Driver Manager API :
java.sql.DriverManager.getConnection(String url, String user, String password)
Connection Properties :
Use the connection properties user and password for configuring the username and password respectively.
URL :
A username and password can be configured through URL.
Example: `jdbc:oracle:thin:myuser/mypassword@//salesserver1:1521/sales.us.example.com`
Wallet :
With a wallet location configured using the connection property `oracle.net.wallet_location` the JDBC Thin driver retrives the username and password from the wallet. Please refer to Oracle documentation on how to store the username and password to the wallet file.

### TCPS

The JDBC Driver can authenticate to the Oracle Database using a certificate from a wallet / keystore. For this, the Oracle Database Server has to be configured to support the TCPS authentication. And, the JDBC driver must be configured with the connection property `oracle.net.authentication_services = (TCPS)` along with `wallet / keystore` properties.

### Kerberos

The JDBC Driver can authenticate to the Oracle Database using Kerberos. For this, the Oracle Database Server has to be configured to support Kerberos authentication. Please refer to Oracle documentation on how to configure the Oracle Database for Kerberos authentication. Configure the following connection properties to enable Kerberos authentication in the JDBC Driver. `oracle.net.authentication_services=(KERBEROS5)
oracle.net.kerberos5_mutual_authentication=true
oracle.net.kerberos5_cc_name=<path to the kerberos credentials cache file>
` Additional configuration can be specified in a configuration file indicated by the system property `java.security.krb5.conf`. Please refer to JDK documentation for more information.

### RADIUS

The JDBC Driver can authenticate to the Oracle Database using RADIUS. For this, the Oracle Database Server has to be configured to support RADIUS authentication. Please refer to Oracle documentation on how to configure the Oracle Database for RADIUS authentication. Configure the following connection properties to enable RADIUS authentication in the JDBC driver.

      oracle.net.authentication_services=(RADIUS)
      user=<username>
      password=<passcode>

## Select your driver type : thin, oci, kprb...

Oracle provides four types of JDBC driver.

- Thin Driver, a 100% Java driver for client-side use without an Oracle installation, particularly with applets. The Thin driver type is `thin`. To connect user `scott` with password `tiger` to a database with `SID` (system identifier) `orcl` through port 1521 of host `myhost`, using the Thin driver, you would write :

        Connection conn = DriverManager.getConnection
        ("jdbc:oracle:thin:@myhost:1521:orcl", "scott", "tiger");

- OCI Driver for client-side use with an Oracle client installation. The OCI driver type is `oci`. To connect user `scott` with password `tiger` to a database with `SID` (system identifier) `orcl` through port 1521 of host `myhost`, using the OCI driver, you would write :

        Connection conn = DriverManager.getConnection
        ("jdbc:oracle:oci:@myhost:1521:orcl", "scott", "tiger");

  Note that you can also specify the database by a `TNSNAMES` entry. You can find the available `TNSNAMES` entries listed in the file `tnsnames.ora` on the client computer from which you are connecting. For example, if you want to connect to the database on host `myhost` as user `scott` with password `tiger` that has a `TNSNAMES` entry of `MyHostString`, enter:

        Connection conn = DriverManager.getConnection
        ("jdbc:oracle:oci8:@MyHostString","scott","tiger");

  If your JDBC client and Oracle server are running on the same machine, the OCI driver can use IPC (InterProcess Communication) to connect to the database instead of a network connection. An IPC connection is much faster than a network connection.

        Connection conn = DriverManager.getConnection
        ("jdbc:oracle:oci8:@","scott","tiger");

- Server-Side Thin Driver, which is functionally the same as the client-side Thin driver, but is for code that runs inside an Oracle server and needs to access a remote server, including middle-tier scenarios. The Server-Side Thin driver type is `thin` and there is no difference in your code between using the Thin driver from a client application or from inside a server.
- Server-Side Internal Driver for code that runs inside the target server, that is, inside the Oracle server that it must access. The Server-Side Internal driver type is `kprb` and it actually runs within a default session. You are already "connected". Therefore the connection should never be closed.
  To access the default connection, write:

        DriverManager.getConnection("jdbc:oracle:kprb:");
        or:
        DriverManager.getConnection("jdbc:default:connection:");

  You can also use the Oracle-specific defaultConnection() method of the OracleDriver class which is generally recommended:

        OracleDriver ora = new OracleDriver();
        Connection conn = ora.defaultConnection();

  Note: You are no longer required to register the `OracleDriver` class for connecting with the Server-Side Internal driver, although there is no harm in doing so. This is true whether you are using `getConnection()` or `defaultConnection()` to make the connection.
  Any user name or password you include in the URL string is ignored in connecting to the server default connection. The `DriverManager.getConnection()` method returns a new Java `Connection` object every time you call it. Note that although the method is not creating a new physical connection (only a single implicit connection is used), it is returning a new object.
  Again, when JDBC code is running inside the target server, the connection is an implicit data channel, not an explicit connection instance as from a client. It should never be closed.

### Nested Class Summary

### Nested classes/interfaces inherited from interface oracle.jdbc.internal.Monitor

`oracle.jdbc.internal.Monitor.CloseableLock, oracle.jdbc.internal.Monitor.WaitableMonitor`

### Field Summary

### Fields inherited from class oracle.jdbc.driver.OracleDriver

`access_string, accumulate_batch_result, batch_string, convert_nchar_literals_string, database_string, dataSizeBytes, dataSizeChars, dataSizeUnitsPropertyName, DEFAULT_CONNECTION_PROPERTIES, default_execute_batch_string, default_row_prefetch_string, defaultConn, defaultnchar_string, defaultncharprop_string, disable_defineColumnType_string, dll_string, execute_batch_string, fixed_string_string, include_synonyms_string, j2ee_compliance, jdbc_string, logon_as_internal_str, nls_lang_backdoor, no_caching_buffers, oracle_string, password_string, permit_timestamp_date_mismatch_string, prefetch_string, prelim_auth_string, process_escapes_string, protocol_string, protocolFullName_string, proxy_client_name, read_timeout, remarks_string, report_remarks_string, restrict_getTables_string, retain_v9_bind_behavior_string, row_prefetch_string, server_string, set_new_password_string, SetFloatAndDoubleUseBinary_string, synonyms_string, systemTypeMap, tcp_no_delay, useFetchSizeWithLongColumn_prop_string, useFetchSizeWithLongColumn_string, user_string, v8compatible_string, xa_trans_loose`

### Constructor Summary

Constructors
`OracleDriver()`

### Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
`static String` `getBuildDate()` Returns a String that specifies exactly when the jar file was built.
`static String` `getDriverVersion()` Returns a String that specifies the Oracle version number of the driver.
`static String` `getJDBCVersion()` Returns a String that specifies the version of the JDBC spec supporte by the driver.
`static boolean` `isDebug()` Returns true if this jar includes debug code.
`static boolean` `isDMS()` Returns true if this jar includes DMS instrumentaion.
`static boolean` `isInServer()` Returns true if this jar was built to run in the Oracle Java VM.
`static boolean` `isJDK14()` Deprecated.
`static boolean` `isPrivateDebug()` Returns true if this jar includes Oracle internal debug code.
`static void` `main​(String[] args)` Prints a description of the Oracle JDBC driver .jar file to System.out.

### Methods inherited from class oracle.jdbc.driver.OracleDriver

`_INTERNAL_ORACLE_connectAsync, acceptsURL, connect, connect, defaultConnection, getCompileTime, getMajorVersion, getMinorVersion, getMonitorLock, getParentLogger, getPropertyInfo, getSystemPropertyDateZeroTime, getSystemPropertyDateZeroTimeExtra, getSystemPropertyFastConnectionFailover, jdbcCompliant, processSqlEscapes, registerMBeans, unRegisterMBeans`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface oracle.jdbc.internal.Monitor

`acquireCloseableLock, acquireLock, newDefaultLock, releaseLock`

### Constructor Detail

#### OracleDriver

    public OracleDriver()

### Method Detail

#### isDMS

    public static final boolean isDMS()

Returns true if this jar includes DMS instrumentaion.

Returns:
  true if DMS jar

#### isInServer

    public static final boolean isInServer()

Returns true if this jar was built to run in the Oracle Java VM.

Returns:
  true if server jar

#### isJDK14

    public static final boolean isJDK14()

Deprecated.
Returns true if this is a JDK 1.4 or later compliant jar. Since JDK 1.3 is desupported, always returns true.

Returns:
  true

#### isDebug

    public static final boolean isDebug()

Returns true if this jar includes debug code.

Returns:
  true if debug jar

#### isPrivateDebug

    public static final boolean isPrivateDebug()

Returns true if this jar includes Oracle internal debug code.

Returns:
  true if private debug jar

#### getJDBCVersion

    public static final String getJDBCVersion()

Returns a String that specifies the version of the JDBC spec supporte by the driver.

Returns:
  JDBC spec version

#### getDriverVersion

    public static final String getDriverVersion()

Returns a String that specifies the Oracle version number of the driver.

Returns:
  version number

#### getBuildDate

    public static final String getBuildDate()

Returns a String that specifies exactly when the jar file was built.

Returns:
  build date

#### main

    public static void main​(String[] args)
                     throws Exception

Prints a description of the Oracle JDBC driver .jar file to System.out.

Parameters:
  `args` - Ignored
Throws:
  `Exception`