7.3.1 Using the getConnection method of the DriverManager class to connect to the HADB server

Connect to the HADB server by executing the getConnection method of the DriverManager class. Before the getConnection method is executed, the Driver class is automatically registered on the Java Virtual Machine (JVM). (You can also manually perform registration. For details, see (1) How to register the Driver class into the Java Virtual Machine (JVM).) You can then execute the getConnection method to connect to the HADB server.

The following subsections explain the steps.

Organization of this subsection

(1) How to register the Driver class into the Java Virtual Machine (JVM)
(2) Connecting to the HADB server with the getConnection method

(1) How to register the Driver class into the Java Virtual Machine (JVM)

Register the Driver class into the Java Virtual Machine (JVM). Note that when you register the Driver class into the Java Virtual Machine (JVM), you need a driver name (package-name.class-name). The package name and class name of the JDBC driver are as follows:

Package name: com.hitachi.hadb.jdbc
Class name: HADBDriver

Note

HADB and hadb are acronyms for Hitachi Advanced Database.

There are three ways to register the Driver class, as shown below.

■ Method 1 (using the forName method of the Class class)

Execute the forName method of the Class class within the application as follows:

Class.forName("com.hitachi.hadb.jdbc.HADBDriver");

■ Method 2 (using the system properties)

Specify the following value in the Java Virtual Machine's (JVM) system property (jdbc.drivers):

System.setProperty("jdbc.drivers", "com.hitachi.hadb.jdbc.HADBDriver");

■ Method 3 (using the operation settings file for the Java Virtual Machine)

This method is applicable only to Java Applets.

Specify the information provided below in the JAVA_HOME\.hotjava\properties file (JAVA_HOME depends on the Java execution environment). If you register multiple JDBC drivers, delimit then with the colon (:).

jdbc.drivers="com.hitachi.hadb.jdbc.HADBDriver"

To Page Top

(2) Connecting to the HADB server with the getConnection method

Connect to the HADB server by executing the getConnection method of the DriverManager class. When a connection to the HADB server is established successfully, the JDBC driver returns a reference to a Connection class instance as the result of executing the method. If connection establishment with the HADB server fails, as in the following cases, the method throws an SQLException:

Required connection information is not specified in the arguments.
Specified connection information is invalid.
Connection cannot be established (for example, because the HADB server at the connection destination has not been started).

The getConnection method is provided in the following three formats, each with its own set of arguments (url, user, password, and info) that specify information about the connection to the HADB server:

public static Connection getConnection(String url)
public static Connection getConnection(String url, String user, String password)
public static Connection getConnection(String url, Properties info)

The following subsections explain the values to be specified in these arguments.

(a) Values to be specified in the url argument (specifying the URL for the connection)

You specify in the url argument the URL to be used for the connection. The following shows the URL specification format:

jdbc:hadb[://[host][:port]/[?property=value[&property=value]...]]

Note: HADB and hadb are acronyms for Hitachi Advanced Database.

Examples of URL specification

Example 1: Omitting the property
```
jdbc:hadb://localhost:23650/
```

Example 2: Specifying one property

jdbc:hadb://localhost:23650/?adb_clt_ap_name=AP001

Example 3: Specifying multiple properties

jdbc:hadb://localhost:23650/?methodtrace=ON&tracenum=600
&sqlwarningkeep=FALSE&user=ADBUSER01&password=password01&adb_clt_ap_name=AP001

URL specification rules

Spaces are not allowed within an item or between items in the URL argument.
Each item name is case sensitive.
Specification of an item enclosed in square brackets ([ ]) is optional.
Specify a question mark (?) before specifying the first property (property) and use the ampersand (&) as the delimiter between properties.
If the same property is specified more than once, the first value specified takes effect.
Ampersands (&) cannot be used as property values. If a password contains an ampersand, use another connection method because the password property cannot be specified in a URL. For details about passwords in HADB, see the topic Password specification rules in the HADB Setup and Operation Guide.
When an invalid value is specified in a property in a URL, SQLException will not be thrown if the correct value is specified for a user property of the same name.

Explanation of each URL item

• jdbc:hadb

This item consists of the protocol name and subprotocol name. You must specify this item. This item is case sensitive.

• host

Specifies the host name of the HADB server at the connection destination. This host name is used for communication between the HADB client and the HADB server.

You can use other methods of specifying the HADB server's host name. For details about other specification methods and priorities, see 7.3.3 Connection information priorities.

If the getConnection method is executed with no host name specified, the method throws an SQLException.

In a cold standby configuration, specify the alias IP address used for communication between the HADB server and HADB client.

Multi-node function:: When you use the multi-node function, specify the alias IP address that is used for communication between the HADB server and the HADB client.

• port

Specifies the port number of the HADB server that is used for communication between the HADB client and the HADB server.

You can use other methods of specifying the HADB server's port number. For details about other specification methods and priorities, see 7.3.3 Connection information priorities.

If the getConnection method is executed with no port number specified, the method throws an SQLException.

• property=value

Specifies a property (property) and a value (value) for that property.

The following table lists and describes the properties that can be specified in the url argument.

Table 7‒2: Properties that can be specified in the url argument
No.	Property name	Description
1	`user`	Specifies the authorization identifier to be used to connect to the HADB server. For the naming rules for authorization identifiers, see the topic Specifying names in the manual HADB SQL Reference. You can use other methods of specifying the authorization identifier to be used to connect to the HADB server. For the specification priorities, see 7.3.3 Connection information priorities. If the `getConnection` method is executed with no authorization identifier specified, the method throws an `SQLException`.
2	`password`	Specifies a password for the authorization identifier that is to be used to connect to the HADB server.
3	`encodelang`	Specifies the conversion character set to be used for character encoding conversion processing when the `String` class is used to transfer data with the HADB server. Select a supported conversion character set from the list of Supported encodings in Internationalization support in the JavaTM Platform, Standard Edition JDK document. If this specification is omitted, the character encoding will be converted using the supported conversion character set indicated in Table 7‒15: Names of the character sets supported for the HADB server's character encoding. Note that Java Virtual Machine's (JVM) default conversion character set is used to convert the following values: Application identifiers (such as those specified with the `adb_clt_ap_name` user property) Authorization identifiers or passwords (such as those specified with the `getConnection` method) Specify this property only if you want to use a character set other than the supported conversion character set shown in Table 7‒15: Names of the character sets supported for the HADB server's character encoding. If you already use the supported conversion character set indicated in Table 7‒15: Names of the character sets supported for the HADB server's character encoding for conversion, you do not need to specify this property.
4	`methodtrace`	Specifies whether JDBC interface method traces are to be obtained. `ON`: Obtain JDBC interface method traces. `OFF`: Do not obtain JDBC interface method traces. For details about the JDBC interface method traces, see 7.7.1 JDBC interface method traces. If any other value is specified, the JDBC driver throws an `SQLException`. If this specification is omitted, `OFF` is assumed. If no valid log writer is specified with the `setLogWriter` method, JDBC interface method traces are not obtained, even if `ON` is specified.
5	`tracenum`	Specifies the number of entries for a JDBC interface method trace, in the range from 10 to 1,000. The default value is `500`. This property value takes effect when both of the following conditions are satisfied: A valid log writer is specified with the `setLogWriter` method. `ON` is specified in `methodtrace`. Even if this property value is to take effect, the JDBC driver throws an `SQLException` if the specified value is not within the range of 10 to 1,000.
6	`sqlwarningkeep`	Specifies whether warning information returned from the HADB server is to be retained. `TRUE`: Retain warning information. `FALSE`: Do not retain warning information. If this specification is omitted, `TRUE` is assumed. If any other value is specified, the JDBC driver throws an `SQLException`. For details about the warning information retention level for the `Connection` object, see 8.9.1 Creating an SQLWarning object.
7	`adb_clt_rpc_con_wait_time`	Specifies the maximum amount of time to wait for HADB server connection processing to be completed. Functionally, this property is the same as the `adb_clt_rpc_con_wait_time` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_con_wait_time` operand in the client definition.
8	`adb_clt_rpc_sql_wait_time`	Specifies the following wait times: How long a HADB client waits for the HADB server to respond to a processing request. How long to wait to secure processing real threads if a shortage occurs when multiple `SELECT` statements are executed concurrently in the same connection. Functionally, this property is the same as the `adb_clt_rpc_sql_wait_time` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_sql_wait_time` operand in the client definition.
9	`adb_clt_ap_name`	Specifies the identification information (application identifier) for the application program that is to connect to the HADB server. Because application identifiers are converted to the Java Virtual Machine's (JVM) default conversion character set, we recommend that you use a name consisting of only single-byte alphanumeric characters that do not depend on the conversion character set. You can use other methods of specifying the application identifier. For the specification priorities, see 7.3.3 Connection information priorities. If the application program has connected to the HADB server without its application identifier having been specified anywhere, `********` will be set as the application identifier. Functionally, this property is the same as the `adb_clt_ap_name` operand in the client definition. For details about this property and its permitted values, see the description of the adb_clt_ap_name operand in the client definition.
10	`adb_clt_group_name`	Specifies the name of the client group to which the application belongs. Functionally, this property is the same as the `adb_clt_group_name` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_group_name` operand in the client definition.
11	`adb_clt_fetch_size`	Specifies the maximum number of rows that are to be sent as retrieval results from the HADB server to the HADB client by a single `FETCH` process. Functionally, this property is the same as the `adb_clt_fetch_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_fetch_size` operand in the client definition.
12	`adb_dbbuff_wrktbl_clt_blk_num`	Specifies the number of local work table buffer pages. Functionally, this property is the same as the `adb_dbbuff_wrktbl_clt_blk_num` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_dbbuff_wrktbl_clt_blk_num` operand in the client definition.
13	`adb_sql_exe_max_rthd_num`	Specifies the maximum number of SQL processing real threads. Functionally, this property is the same as the `adb_sql_exe_max_rthd_num` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_max_rthd_num` operand in the client definition.
14	`adb_sql_exe_hashgrp_area_size`	Specifies the size (in kilobytes) of the hash grouping area. Functionally, this property is the same as the `adb_sql_exe_hashgrp_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashgrp_area_size` operand in the client definition.
15	`adb_sql_exe_hashtbl_area_size`	Specifies the size (in megabytes) of the hash table area. Functionally, this property is the same as the `adb_sql_exe_hashtbl_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashtbl_area_size` operand in the client definition.
16	`adb_sql_exe_hashflt_area_size`	Specifies the size (in megabytes) of the hash filter area. Functionally, this property is the same as the `adb_sql_exe_hashflt_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashflt_area_size` operand in the client definition.
17	`adb_sql_prep_delrsvd_use_srvdef`	Specifies whether reserved words are to be unregistered if specified as such in the `adb_sql_prep_delrsvd_words` operand in the server definition. Functionally, this property is the same as the `adb_sql_prep_delrsvd_use_srvdef` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_prep_delrsvd_use_srvdef` operand in the client definition.
18	`adb_clt_trn_iso_lv`	Specifies the transaction isolation level. Functionally, this property is the same as the `adb_clt_trn_iso_lv` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_trn_iso_lv` operand in the client definition.
19	`adb_clt_trn_access_mode`	Specifies the transaction access mode. Functionally, this property is the same as the `adb_clt_trn_access_mode` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_trn_access_mode` operand in the client definition.
20	`adb_clt_sql_text_out`	Specifies whether SQL statements issued by the HADB client are to be output to the client message log files and the server message log files. Functionally, this property is the same as the `adb_clt_sql_text_out` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_sql_text_out` operand in the client definition.
21	`adb_clt_sql_order_mode`	Specifies the sort order for character string data in a `SELECT` statement in which the `ORDER BY` clause is specified. Functionally, this property is the same as the `adb_clt_sql_order_mode` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_sql_order_mode` operand in the client definition.
22	`adb_sql_prep_dec_div_rs_prior`	Specify the minimum scaling value of the result of a division operation (arithmetic operation) specified in an SQL statement when the data type of the result is `DECIMAL`. Functionally, this property is the same as the `adb_sql_prep_dec_div_rs_prior` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_prep_dec_div_rs_prior` operand in the client definition.
23	`adb_jdbc_exc_trc_out_path`	Specifies the absolute path of the directory to which exception trace logs are to be output.	For details about these properties and their permitted values, see (b) Setup for acquisition of the exception trace log (setting properties) in (1) Methods to be acquired and setup for log acquisition in 7.7.2 Exception trace log.
24	`adb_jdbc_info_max`	Specifies the maximum number of information items to be output to one file.
25	`adb_jdbc_cache_info_max`	Specifies the maximum number of information items to be stored in memory.
26	`adb_jdbc_trc_out_lv`	Specifies the trace acquisition level.

Note: You can use other methods of specifying these properties. For details about other specification methods and priorities, see 7.3.3 Connection information priorities.

Note

The property names that are specified in the connection URL were changed in HADB 03-00, as shown below. The previous property names are still supported, but if you have upgraded your HADB to version 03-00 or later, we recommend that you change the property names.

No.	Property name before change (property name used in HADB versions earlier than 03-00)	Property name after change (property name used in HADB version 03-00 or later)
1	`apname`	`adb_clt_ap_name`
2	`extrcoutpath`	`adb_jdbc_exc_trc_out_path`
3	`extrcinfomax`	`adb_jdbc_info_max`
4	`extrccacheinfomax`	`adb_jdbc_cache_info_max`
5	`extrcoutlv`	`adb_jdbc_trc_out_lv`

(b) Value to be specified in the user argument (specifying the authorization identifier)

The user argument specifies the authorization identifier that is used to connect to the HADB server.

For the naming rules for authorization identifiers, see the topic Specifying names in the manual HADB SQL Reference.

You can use other methods of specifying the authorization identifier used to connect to the HADB server. For the specification priorities, see 7.3.3 Connection information priorities.

If the getConnection method is executed with no authorization identifier specified, the method throws an SQLException.

If null is specified, the JDBC driver assumes that specification of an authorization identifier was omitted.

If a character string with a length of zero is specified, the JDBC driver throws an SQLException.

(c) Value to be specified in the password argument (specifying the password)

The password argument specifies a password for the authorization identifier that is to be used to connect to the HADB server.

If null or a character string with a length of zero is specified, the JDBC driver assumes that specification of a password was omitted.

(d) Values to be specified in the info argument (specifying the user properties)

The following table lists and describes the information that can be specified in the info argument (information that can be specified in user properties).

Table 7‒3: Information that can be specified in the `info` argument (information that can be specified in user properties)
No.	Property name	Description
1	`user`	Specifies the authorization identifier to be used to connect to the HADB server. For the naming rules for authorization identifiers, see the topic Specifying names in the manual HADB SQL Reference. You can use other methods of specifying the authorization identifier to be used to connect to the HADB server. For the specification priorities, see 7.3.3 Connection information priorities. If the `getConnection` method is executed with no authorization identifier specified, the method throws an `SQLException`. If `null` is specified, the JDBC driver assumes that specification of an authorization identifier was omitted. If a character string with a length of zero is specified, the JDBC driver throws an `SQLException`.
2	`password`	Specifies a password for the authorization identifier being used to connect to the HADB server. If `null` is specified, or if a character string with a length of zero is specified, the JDBC driver assumes that no password is specified.
3	`encodelang`	Specifies the conversion character set to be used for character encoding conversion processing when the `String` class is used to transfer data with the HADB server. For details about this property and its permitted values, see Table 7‒2: Properties that can be specified in the url argument. If the specified conversion character set name is not supported by Java Virtual Machine (JVM), the JDBC driver throws an `SQLException` when a connection is established with the HADB server. If this specification is omitted, the specification of `encodelang` for the connection URL is applied.
4	`methodtrace`	Specifies whether JDBC interface method traces are to be obtained. For details about this property and its permitted values, see Table 7‒2: Properties that can be specified in the url argument. If this specification is omitted, the specification of `methodtrace` for the connection URL is applied.
5	`tracenum`	Specifies the number of JDBC interface method trace entries. For details about this property and its permitted values, see Table 7‒2: Properties that can be specified in the url argument. If this specification is omitted, the specification of `tracenum` for the connection URL is applied.
6	`sqlwarningkeep`	Specifies whether warning information returned from the HADB server is to be retained. For details about this property and its permitted values, see Table 7‒2: Properties that can be specified in the url argument. If this specification is omitted, the specification of `sqlwarningkeep` for the connection URL is applied.
7	`adb_clt_rpc_srv_host`	Specifies the host name of the HADB server at the connection destination. Functionally, this property is the same as the `adb_clt_rpc_srv_host` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_srv_host` operand in the client definition.
8	`adb_clt_rpc_srv_port`	Specifies the port number of the HADB server that is used for communication between the HADB client and the HADB server. Functionally, this property is the same as the `adb_clt_rpc_srv_port` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_srv_port` operand in the client definition.
9	`adb_clt_rpc_con_wait_time`	Specifies the maximum amount of time to wait for HADB server connection processing to be completed. Functionally, this property is the same as the `adb_clt_rpc_con_wait_time` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_con_wait_time` operand in the client definition.
10	`adb_clt_rpc_sql_wait_time`	Specifies the following wait times: How long a HADB client waits for the HADB server to respond to a processing request. How long to wait to secure processing real threads if a shortage occurs when multiple `SELECT` statements are executed concurrently in the same connection. Functionally, this property is the same as the `adb_clt_rpc_sql_wait_time` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_rpc_sql_wait_time` operand in the client definition.
11	`adb_clt_ap_name`	Specifies the identification information (application identifier) for the application program that is to connect to the HADB server. Because application identifiers are converted to Java Virtual Machine's (JVM) default conversion character set, we recommend that you use a name consisting of only single-byte alphanumeric characters that do not depend on the conversion character set. You can use other methods of specifying the application identifier. For the specification priorities, see 7.3.3 Connection information priorities. If the application program has connected to the HADB server without its application identifier having been specified anywhere, `********` will be set as the application identifier. Functionally, this property is the same as the `adb_clt_ap_name` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_ap_name` operand in the client definition.
12	`adb_clt_group_name`	Specifies the name of the client group to which the application belongs. Functionally, this property is the same as the `adb_clt_group_name` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_group_name` operand in the client definition.
13	`adb_clt_fetch_size`	Specifies the maximum number of rows that are to be sent as retrieval results from the HADB server to the HADB client by a single `FETCH` process. Functionally, this property is the same as the `adb_clt_fetch_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_fetch_size` operand in the client definition.
14	`adb_dbbuff_wrktbl_clt_blk_num`	Specifies the number of local work table buffer pages. Functionally, this property is the same as the `adb_dbbuff_wrktbl_clt_blk_num` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_dbbuff_wrktbl_clt_blk_num` operand in the client definition.
15	`adb_sql_exe_max_rthd_num`	Specifies the maximum number of SQL processing real threads. Functionally, this property is the same as the `adb_sql_exe_max_rthd_num` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_max_rthd_num` operand in the client definition.
16	`adb_sql_exe_hashgrp_area_size`	Specifies the size (in kilobytes) of the hash grouping area. Functionally, this property is the same as the `adb_sql_exe_hashgrp_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashgrp_area_size` operand in the client definition.
17	`adb_sql_exe_hashtbl_area_size`	Specifies the size (in megabytes) of the hash table area. Functionally, this property is the same as the `adb_sql_exe_hashtbl_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashtbl_area_size` operand in the client definition.
18	`adb_sql_exe_hashflt_area_size`	Specifies the size (in megabytes) of the hash filter area. Functionally, this property is the same as the `adb_sql_exe_hashflt_area_size` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_exe_hashflt_area_size` operand in the client definition.
19	`adb_sql_prep_delrsvd_use_srvdef`	Specifies whether reserved words are to be unregistered if specified as such in the `adb_sql_prep_delrsvd_words` operand in the server definition. Functionally, this property is the same as the `adb_sql_prep_delrsvd_use_srvdef` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_sql_prep_delrsvd_use_srvdef` operand in the client definition.
20	`adb_clt_trn_iso_lv`	Specifies the transaction isolation level. Functionally, this property is the same as the `adb_clt_trn_iso_lv` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_trn_iso_lv` operand in the client definition.
21	`adb_clt_trn_access_mode`	Specifies the transaction access mode. Functionally, this property is the same as the `adb_clt_trn_access_mode` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_trn_access_mode` operand in the client definition.
22	`adb_clt_sql_text_out`	Specifies whether SQL statements issued by the HADB client are to be output to the client message log files and the server message log files. Functionally, this property is the same as the `adb_clt_sql_text_out` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_sql_text_out` operand in the client definition.
23	`adb_clt_sql_order_mode`	Specifies the sort order for character string data in a `SELECT` statement in which the `ORDER BY` clause is specified. Functionally, this property is the same as the `adb_clt_sql_order_mode` operand in the client definition. For details about this property and its permitted values, see the description of the `adb_clt_sql_order_mode` operand in the client definition.
24	`adb_sql_prep_dec_div_rs_prior`	Specifies the minimum scaling value of the result of a division operation (arithmetic operation) specified in an SQL statement when the data type of the result is `DECIMAL`. Functionally, this property is the same as the `adb_sql_prep_dec_div_rs_prior` operand. For details about this property and its permitted values, see the description of the `adb_sql_prep_dec_div_rs_prior` operand in the client definition.
25	`adb_jdbc_exc_trc_out_path`	Specifies the absolute path of the directory to which exception trace logs are to be output.	For details about these properties and their permitted values, see (b) Setup for acquisition of the exception trace log (setting properties) in (1) Methods to be acquired and setup for log acquisition in 7.7.2 Exception trace log.
26	`adb_jdbc_info_max`	Specifies the maximum number of information items to be output to one file.
27	`adb_jdbc_cache_info_max`	Specifies the maximum number of information items to be stored in memory.
28	`adb_jdbc_trc_out_lv`	Specifies the trace acquisition level.

Note

You can use other methods of specifying these properties. For details about other specification methods and priorities, see 7.3.3 Connection information priorities.
If null is specified for any property, the JDBC driver assumes that specification of that property was omitted.

Note

The property names of user properties were changed in HADB 03-00, as shown below. The previous property names are still supported, but if you have upgraded your HADB to version 03-00 or later, we recommend that you change the property names.

No.	Property name before change (property name used in HADB versions earlier than 03-00)	Property name after change (property name used in HADB version 03-00 or later)
1	`apname`	`adb_clt_ap_name`
2	`host`	`adb_clt_rpc_srv_host`
3	`port`	`adb_clt_rpc_srv_port`

To Page Top