xbn.db
Class DBConnDirect

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.db.DBConnDirect

All Implemented Interfaces:

Debuggable

Direct Known Subclasses:

DBConnection

public class DBConnDirect

extends XBNObject

implements Debuggable

Convenience class for handling a single database connection. See java.sql.Connection.

Source code: DBConnDirect.java

This class most importantly provides functionality for automatic and dynamic debugging output. It also provides automatic and accurate detection of whether the database connection is truly inaccessible, or if you just made a silly sql error.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

DBConnDirect(Connection c_onnection, String s_verificationSelect, Outputter optr_dbg)
Create a DBConnDirect.

DBConnDirect(String s_verificationSelect)
Create a DBConnDirect.

DBConnDirect(String s_verificationSelect, Outputter optr_dbg)
Create a DBConnDirect.

Method Summary

void	crashIfNotVerified(String s_callingFunc) If the connection cannot be verified, crash with a descriptive AssertException.
void	dbg(String s_message) Output a line of text.
void	dbgnl(String s_message) Output a line of text without an ending newline.
void	disconnect() Disconnect from the database.
protected void	finalize() For internal use only.
Connection	getConnection() Get the java.sql.Connection for direct manipulation.
Connection	getConnectionAndSeparate() Get the java.sql.Connection for direct manipulation, and eleminate all references in this class to it.
Outputter	getOptrDbg() Get the Outputter object for direct manipulation.
String	getVerificationSelect() Get the trivial sql that verifies the connection is currently and truly connected to the database.
boolean	isConnected() Is the connection currently and actually open to the database?
boolean	isVerified() Verify connection with a trivial select query.
boolean	isVerified(String s_funcForAX) Verify connection with a trivial select query, but, if desired (and only in the case of an SQLException), a AssertException is thrown to display a descriptive error message.
protected void	prepareVerificationSelect(String s_callingFunc) For internal use only.
void	setConnection(Connection c_onnection) Set the internal java.sql.Connection to the one provided.
void	setOptrDbg(Outputter optr_dbg) Set the Outputter object.
protected void	throwAXDbg(String s_funcMsg) Throw an AssertException, but debug it first.
void	throwSQLX(String s_classFuncError) Throws an SQLException (and logs it).
String	toString() Get some information about this DBConnDirect.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DBConnDirect

public DBConnDirect(String s_verificationSelect)

Create a DBConnDirect.

Equal to DBConnDirect(s_verificationSelect, (new Outputter()))

DBConnDirect

public DBConnDirect(String s_verificationSelect,
                    Outputter optr_dbg)

Create a DBConnDirect.

It is expected that you set the connection before doing anything else with this class.

Parameters:

s_verificationSelect - Trivial select query used for verification of the connection, used in isVerified. This query is executed to verify both the connection and itself. If it throws an SQLException for any reason, this is thrown, and the connection is disconnected.

optr_dbg - The Outputter to use for debugging output. May not be null.

DBConnDirect

public DBConnDirect(Connection c_onnection,
                    String s_verificationSelect,
                    Outputter optr_dbg)
             throws SQLException

Create a DBConnDirect.

Parameters:

c_onnection - The database connection. Must be non-null, and actually connected to the database. See setConnection.

s_verificationSelect - Passed directly to the two-parameter constructor.

optr_dbg - Passed directly to the two-parameter constructor.

Method Detail

disconnect

public final void disconnect()
                      throws SQLException

Disconnect from the database. To reconnect again, provide a new connection to setConnection.

getConnection

public Connection getConnection()

Get the java.sql.Connection for direct manipulation. See java.sql.Connection.

Use with caution. You can screw things up if you know what you're doing.

getConnectionAndSeparate

public Connection getConnectionAndSeparate()

Get the java.sql.Connection for direct manipulation, and eleminate all references in this class to it.

Use this when you want the DBConnDirect to create the connection (perhaps for debugging purposes), but nothing else. Normally, when setting this to null, the finalize function is called, which disconnects the connection. Eliminating all internal references to this connection will prevent this, and you can now safely null out this DBConnDirect object, and continue to use the returned connection.

If you still want the connection to be referenced by this object, use getConnection.

After this function is called, this class is in such a state, as if you called disconnect.

setConnection

public final void setConnection(Connection c_onnection)
                         throws SQLException

Set the internal java.sql.Connection to the one provided.

Parameters:

c_onnection - The database connection. Must be non-null and connected. Also, the verification select query must be verified in it.

isConnected

public final boolean isConnected()

Is the connection currently and actually open to the database?

Returns:

true If the connection object is not null and isVerified is true.
false If the connection is null, or if the connection is not null, but isVerified returns false.

getVerificationSelect

public String getVerificationSelect()

Get the trivial sql that verifies the connection is currently and truly connected to the database.

See isVerified, isVerified and crashIfNotVerified.

This should be a trivial select query, only used to verify whether or not the connection is still active. The result of this query will never be seen. Therefore, it should be the most un-complicated, speediest, least-memory-hogging, trivial select query you can think of.

For example, in the Oracle platform, you might consider the following, in descending order of goodness:

select 'x' from dual
select sysdate from dual
select count(*) from tab

Examples for other platforms...?

Returns:

The sql of the verification select query. This is equal to s_verificationSelect, exactly as provided to the constructor.

isVerified

public boolean isVerified()

Verify connection with a trivial select query. If the query throws an SQLException for any reason, the connection is to be considered un-verified. Equal to

isVerified(null);

What if java is connected to the database, but then the connection is shut down, or restarted from within the database, outside of java? In this case, java still thinks that it's connections are valid. There's no way that this shutdown or restart can be communicated to java, so the connection remains "open" even though it's now pointing to...nothing. Literally, null.

So, when this situation occurs, how is it possible to tell the difference between an SQLException being thrown because of a genuine problem with your sql (or code), and one being thrown simply because the database is not accessible? It is possible by running a select query so trivial, that, most likely, any exception being thrown is not because of a problem with the query, but probably something more fundamental.

That's the purpose of this function. It's not an exact science, but it'll do.

Returns:

true if the query does not throw new an SQLException.
false if the query throws an SQLException for any reason.

isVerified

public boolean isVerified(String s_funcForAX)

Verify connection with a trivial select query, but, if desired (and only in the case of an SQLException), a AssertException is thrown to display a descriptive error message. This should only be used for the sake of debugging, in the small case that the database is properly connected, but you have supplied a faulty query.

In most cases, use isVerified or crashIfNotVerified;

Parameters:

s_funcForAX - If you want an AssertException to be thrown when the connection cannot be verified, pass in a function name to be displayed in the potential error message. If null, then no exception will be thrown, rather false will be returned.

Returns:

true If the query does not throw an SQLException.
false If the query causes an SQLException for any reason and s_funcForAX is null.

Throws:

AssertException - If the query throws an SQLException for any reason.
AssertException If the connection is not connected, as determined by isConnected

crashIfNotVerified

public void crashIfNotVerified(String s_callingFunc)

If the connection cannot be verified, crash with a descriptive AssertException.

Equal to isVerified(s_callingFunc)

getOptrDbg

public final Outputter getOptrDbg()

Description copied from interface: Debuggable

Get the Outputter object for direct manipulation.

Set with setOutputter.

Specified by:

getOptrDbg in interface Debuggable

setOptrDbg

public final void setOptrDbg(Outputter optr_dbg)

Description copied from interface: Debuggable

Set the Outputter object.

Get with getOutputter.

Specified by:

setOptrDbg in interface Debuggable

Following copied from interface: xbn.output.Debuggable

Parameters:

out_putter - The Outputter object. May not be null.

dbg

public final void dbg(String s_message)

Description copied from interface: Debuggable

Output a line of text.

Specified by:

dbg in interface Debuggable

Following copied from interface: xbn.output.Debuggable

Parameters:

s_message - The message to output.

dbgnl

public final void dbgnl(String s_message)

Description copied from interface: Debuggable

Output a line of text without an ending newline.

Specified by:

dbgnl in interface Debuggable

Following copied from interface: xbn.output.Debuggable

Parameters:

s_message - The message to output.

toString

public String toString()

Get some information about this DBConnDirect.

Overrides:

toString in class Object

throwSQLX

public void throwSQLX(String s_classFuncError)
               throws SQLException

Throws an SQLException (and logs it). If configured, it is confirmed whether the DBConnDirect is connected and verified, according to isConnected and isVerified. If either of these return false, then add a message onto the end of the exception message.

finalize

protected void finalize()
                 throws Throwable

For internal use only.

If isConnected equals true, then disconnect. Then call java.lang.Object.finalize.

Automatically called by the Java Runtime Environment when this is set to null.

Overrides:

finalize in class Object

throwAXDbg

protected final void throwAXDbg(String s_funcMsg)

Throw an AssertException, but debug it first.

prepareVerificationSelect

protected final void prepareVerificationSelect(String s_callingFunc)

For internal use only.

Attempts to create the java.sql.PreparedStatement for the verification select query, and then execute it. If it fails with an SQLException, the connection is disconnected. This is called by setConnection and DBConnDirect.connect().