DataSource Objects and Database URLs

This chapter describes how to connect to a database using a DataSource object provided by tbJDBC, and explains database URLs.

DataSource objects indicate all resources in a database, and the concept of data sources was first introduced as the extended API of the JDBC 2.0 standard. A DataSource described in this chapter corresponds to a database.

DataSource Objects

The default interface defined in javax.sql.DataSource is as follows:

public interface DataSource
{
    Connection getConnection() throws SQLException;
    Connection getConnection(String username, String password) throws SQLException;
    ...
}

Tibero provides the com.tmax.tibero.jdbc.ext package, to provide methods for specifying properties of DataSource objects.

DataSource Object Properties

The following properties can be set for DataSource objects.

Property	Type	Description
databaseName	String	Name of a database that resides in the server.
dataSourceName	String	Name of the DataSource.
description	String	Description of the DataSource.
networkProtocol	String	Name of the network protocol used to communicate with the server. (Default value: TCP)
password	String	Password to connect to the server.
portNumber	int	Port number of the server listener.
serverName	String	Name of the database.
user	String	User name used to access the server.

The following are the methods for specifying and retrieving the properties of DataSource objects.

• public String getDatabaseName()

• public void setDatabaseName(String databaseName)

• public String getDataSourceName()

• public void setDataSourceName(String dataSourceName)

• public String getDescription()

• public void setDescription(String description)

• public String getNetworkProtocol()

• public void setNetworkProtocol(String networkProtocol)

• public String getPassword()

• public void setPassword(String password)

• public int getPortNumber()

• public void setPortNumber(int portNumber)

• public String getServerName()

• public void setServerName(String serverName)

• public String getUser()

• public void setUser(String user)

---

Additional DataSource Object Properties

The following properties can be additionally specified for DataSource objects.

Property	Type	Description
driverType	String	JDBC driver type.
login_timeout	int	Socket read time. Timeout period starts when a socket is first created and ends when the database connection finishes. If no response is received within the specified time, a timeout occurs. If set to 0, no timeout occurs. (Unit: millisecond, default value: 0)
logWriter	java.io.PrintWriter	Log writer for the DataSource object.
maxStatements	int	Maximum number of statements to be stored in the application cache.
read_timeout	int	Socket read timeout after creating the database connection. If no response is received within the specified time, a timeout occurs. If set to 0, no timeout occurs. (Unit: millisecond, default value: 0)
program_name	String	Program name. (Default value: JDBC Thin Client)
self_keepalive	String	Option to enable the SELF KEEP ALIVE function. This function checks if the connection target has a network access problem based on the settings of self_keepidle, self_keepintvl, and self_keepcnt. If the entire checking process fails, the network connection is forcibly terminated. (Default value: false)
self_keepidle	int	Maximum period of time to determine whether the network status is normal if the processing time is not updated after the network was normally used to process connections and DB requests/responses. After the specified period, the process of checking the network connection starts. This is applicable only when self_keepalive is set to true. (Unit: second, default value: 60)
self_keepintvl	int	Interval at which to check the network connection and the wait time when checking. This is applicable only when self_keepalive is set to true. (Unit: second, default value: 10)
self_keepcnt	int	Number of times to check the network connection. Tibero assumes that the connection failed only after the specified number of consecutive unsuccessful attempts. This is applicable only when self_keepalive is set to true. (Default value: 3)
URL	String	Database URL used to connect to the database.

The following are the methods for specifying and retrieving additional properties of DataSource objects.

• public String getDriverType()

• public void setDriverType(String driverType)

• public int getLoginTimeout()

• public void setLoginTimeout(int time)

• public PrintWriter getLogWriter()

• public void setLogWriter(PrintWriter writer)

• public int getMaxStatements()

• public void setMaxStatements(int maxStatements)

• public int getReadTimeout()

• public void setReadTimeout(int readTimeout)

• public String getProgramName()

• public void setProgramName(String name)

• public boolean getSelfKeepalive()

• public void setSelfKeepalive(boolean keepalive)

• public int getSelfKeepidle()

• public void setSelfKeepidle(int keepidle)

• public int getSelfKeepintvl()

• public void setSelfKeepintvl(int keepintvl)

• public int getSelfKeepcnt()

• public void setSelfKeepcnt(int keepcnt)

• public String getURL()

• public void setURL(String url)

---

Connecting to the Database Using a DataSource Object

Connecting to the database with a DataSource object can be performed either with or without JNDI. JNDI (Java Naming and Directory Interface)is the API used for a Java application to access a naming or directory service such as DNS or NDS.

Connecting to the database without JNDI

The following is the most common example of how to connect to the database by using a DataSource object without JNDI.

After creating the TbDataSource object, specify the default properties.

TbDataSource ds = new TbDataSource();

ds.setDriverType("thin"); 
ds.setServerName("tmaxh4"); 
ds.setNetworkProtocol("tcp");
ds.setDatabaseName("tibero"); 
ds.setPortNumber(8888); 
ds.setUser("tibero"); 
ds.setPassword("tmax");

Connection conn = ds.getConnection();

Connecting to the database with JNDI

The following example shows how to connect to the database with JNDI.

1. Create a TbDataSource object, and then specify its default properties.

TbDataSource ds = new TbDataSource();

ds.setDriverType("thin"); 
ds.setServerName("tmaxh4"); 
ds.setNetworkProtocol("tcp"); 
ds.setDatabaseName("tibero"); 
ds.setPortNumber(8888); 
ds.setUser("tibero"); 
ds.setPassword("tmax");

1. Register the initialized DataSource object.

Context ctx = new InitialContext(); 
ctx.bind("tibero/webdb", ds);

If InitialContext() is called, a context object that refers to the JNDI is created, and if ctx.bind() is called, the DataSource object and the JNDI name are connected to each other. This means that connecting to the database can be performed using only the 'tibero/webdb', which has been connected previously, as shown in the following.

TbDataSource ds = (TbDataSource)ctx.lookup("tibero/webdb"); 
Connection conn = ds.getConnection();

---

Database URLs and Database Specifiers

As shown in the following, database Uniform Resource Locators (URLs) are strings.

jdbc:tibero:thin:@database_sepcifier

The user name and password can also be included as follows:

jdbc:tibero:thin:user/password@database_sepcifier

The database specifier provided by Tibero can be used as follows:

hostname:port:[service_name]

A description type is also provided to specify multiple database connections.

(DESCRIPTION= 
(LOAD_BALANCE=ON) 
(FAILOVER=ON) 
(PROTOCOL=TCP) 
(ADDRESS_LIST=
 (ADDRESS=(HOST=dbsvr1)(PORT=8629)) 
 (ADDRESS=(HOST=dbsvr2)(PORT=7629))
    ...
))

In the previous example, LOAD_BALANCE and FAILOVER are optional. For ADDRESS_LIST, one or more addresses must be specified.