Package oracle.jdbc

Class 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 &apos;?&apos; delimiter. Name and value are separated by an &apos;=&apos; and multiple properties are separated by an &apos;&&apos;.
    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.
    service_tag To specify the value of service tag. While establishing connection to the Oracle Database, the configured value is sent as part of connect data.
    pool_connection_class Use this parameter to explicitly name the connection class for DRCP connection.
    pool_purity Use this parameter to specify if an application needs a new session that is not tainted with any prior session state or to reuse a previous session. Supported values are NEW | SELF.

    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 &apos;?&apos; 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 &apos;=&apos; and multiple properties are separated by an &apos;&&apos;

    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 userand passwordfor 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_locationthe 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.