org.csstudio.platform.utility.rdb
Class RDBUtil

java.lang.Object
  org.csstudio.platform.utility.rdb.RDBUtil

public abstract class RDBUtil
extends java.lang.Object

Obtain database connection for various RDB systems.

This utility supports an auto-reconnect feature to handle database timeouts: getConnection() will test if the connection is still active. If not, it automatically re-connects.

While this simplifies the code for clients that need to perform transactions every once in a while over a long run time, the connection test can be expensive for a short flurry of transactions. It can therefore be suppressed via setAutoReconnect().

Note that versions 1.6.0 and earlier of this plugin defaulted to turning auto-commit off. Since 1.6.0, it uses the original JDBC default with auto-commit enabled, so code that needs transactions is supposed to disable auto-commit for the transaction, then commit or roll back, and re-enable auto-commit.

This change can cause problems in database dialects that consider it an error to call commit without specifically disabling auto-commit.

Author:

Kay Kasemir, Xihui Chen, Lana Abadie (PostgreSQL, autocommit)

RDBUtil

protected RDBUtil(java.lang.String url,
                  java.lang.String user,
                  java.lang.String password,
                  RDBUtil.Dialect dialect,
                  boolean autoReconnect)
           throws java.lang.Exception

Constructor for derived classes.

Parameters:

url - Database URL

user - ... user

password - ... password

dialect -

Throws:

java.lang.Exception - on error

See Also:

connect(String, String, String)

connect

@Deprecated
public static RDBUtil connect(java.lang.String url)
                       throws java.lang.Exception

Deprecated. Use the version with autoReconnect: connect(String, boolean)

Connect with only a url.

Throws:

java.lang.Exception

connect

@Deprecated
public static RDBUtil connect(java.lang.String url,
                                         java.lang.String user,
                                         java.lang.String password)
                       throws java.lang.Exception

Deprecated. Use the version with autoReconnect: connect(String, String, String, boolean)

Connect to the database.

Throws:

java.lang.Exception

connect

public static RDBUtil connect(java.lang.String url,
                              boolean autoReconnect)
                       throws java.lang.Exception

Connect with only a url.

Parameters:

url - URL

autoReconnect - Handle reconnect?

Throws:

java.lang.Exception

See Also:

#connect(String, String, String, Boolean)

connect

public static RDBUtil connect(java.lang.String url,
                              java.lang.String user,
                              java.lang.String password,
                              boolean autoReconnect)
                       throws java.lang.Exception

Connect to the database.

The URL format depends on the database dialect.

For MySQL resp. Oracle, the formats are:

     jdbc:mysql://[host]:[port]/[database]?user=[user]&password=[password]
     jdbc:oracle:thin:[user]/[password]@//[host]:[port]/[database]
  

For Oracle, the port is usually 1521.

Parameters:

url - Database URL

user - User name or null if part of URL

password - Password or null if part of URL

autoReconnect - If true, reconnect to RDB automatically in case of lost connection

Returns:

RDBUtil

Throws:

java.lang.Exception - on error

See Also:

close()

getDialect

public RDBUtil.Dialect getDialect()

Returns:

Dialect info.

do_connect

protected abstract java.sql.Connection do_connect(java.lang.String url,
                                                  java.lang.String user,
                                                  java.lang.String password)
                                           throws java.lang.Exception

Derived class must implement to create the database connection.

Parameters:

url - RDB URL

user - User name or null if part of url

password - Password or null if part of url

Returns:

JDBC connection

Throws:

java.lang.Exception - on error

setAutoReconnect

public void setAutoReconnect(boolean auto_reconnect)
                      throws java.lang.Exception

Temporarily disable or later re-enable the auto-reconnect feature.

Parameters:

auto_reconnect - false to disable, true to re-enable

Throws:

java.lang.Exception - if this RDBUtil was not created with auto-reconnect support

getConnection

public java.sql.Connection getConnection()
                                  throws java.lang.Exception

Get the JDBC connection. This method will try to return a connection that's valid after network errors or RDB timeouts by checking the validity of the connection and re-connecting if necessary.

It cannot really distinguish between a connection that was closed on purpose, or one that happens to be closed because of a previous network error that caused this very routine to close the connection and then attempt a re-connect - which failed and left the connection as null.

Returns:

SQL connection. In auto-reconnect mode this should never be null: Either a valid connection or an exception.

Throws:

java.lang.Exception - when necessary re-connection fails

close

public void close()

Close the RDB connection.

getConnectionTestQuery

protected abstract java.lang.String getConnectionTestQuery()

Derived classes must implement this to provide a statement that's suitable for testing the connection state.

Returns:

SQL for statement that gives a cheap way of testing the connection state

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

String representation for debugging