cox.jmatt.java.MathTools.util
Class MathDBC

java.lang.Object
  extended by cox.jmatt.java.MathTools.util.MathDBC

public class MathDBC
extends java.lang.Object

This class provides MathTools access to JDBC-compliant databases. Since MathTools is a single-user desktop application the majority of the equipment here utilizes java.sql.Drivers and requires direct access to the JDBC drivers. This is done via the MathClassLoader which is used automatically and transparently any time a driver is set. Setting a driver via the setDriver() method causes the driver to be created. Once that is done a Connection can be established using nothing but the URL, the URL and two Strings, or the URL and a Properties object.

Successfully-created Connections are added to a static internal List. Once the application is finished a call to closeAll() or its instance version closes ALL the Connections. ScriptPanel does this automatically as does MTApplet but other scripting apps or Applets that override MTApplet's destroy() method must do this manually.

Establishing the Connection is the extent of what MathDBC does; once the database connection is made the user takes over. No control or safety measures are established for committing transactions; this must be handled manually. This is true for Connections established using a Driver or DataSource; the only post-creation work done is from closeAll().

As stated previously CapCom's MathClassLoader is used for locating Drivers. MathTools has no native JDBC drivers so the URLLoaderPanel must be pointed to the JAR containing one or the MathClassLoader set manually.

Connecting and Resetting

Creating a Connection absolutely requires a String URL. Period! This is the only globally mandatory parameter, though. A Connection can be created with only this. There is also a method that uses the URL, a username and a password. Or the URL and a Properties object can be used.

In order to use a Properties object to get a Connection, properties must be set. The setProperty() method does this. After initial creation or after the reset() method is called there is no internal Properties object. The first time a property is set, even if its value is null (remove), the internal Properties object is created and will be used. Individual properties can be removed by setting their value to null but the internal Properties object remains or is defined, even if all content is removed.

The reset() method does exactly that. It clears all internally-tracked things other than Connections: the current ClassLoader, the Properties object used for connecting, the Driver, and the internal DataSource. This method is, in fact, the ONLY way to get rid of the Properties object or a DataSource. Use with caution!

NOTE: The reset() method does NOT close Connections! That is the closeAll() method's function. Nor does closeAll() clear any internal settings, it simply closes all current Connections and clears the internal static list.

JNDI and DataSources

Establishing JNDI is well outside the scope of MathTools! If, however, JNDI is present it may be used for database access via DataSources. The isAvailable() method accepts a String argument used to look up the DataSource in the JNDI Context lookup() call. If this call succeeds and returns a non-null DataSource it is maintained internally until the next call to isAvailable().

Once established, the internal DataSource is used in both getDSConnection() methods. The Connection returned is identical to those returned by the DriverManager methods and each is tracked internally and is subject to closeAll(). The reset() method DOES clear out any DataSources and can be used to start from scratch if necessary.

By default MathDBC uses CapCom.getNamingContext() if it is set. If not, or if the CapCom's Context is set to null it uses the zero-argument InitialContext. The reset() method resets to the CapCom Context but the setDSContext() method can be used to set the Context to null and force the IntialContext() option. Of course setDSContext() can also be used to set a naming Context if one is available!


Constructor Summary
MathDBC()
          Standard scripting constructor.
 
Method Summary
 void addProperties(java.util.Properties pNewProps)
          Add the contents of a Properties object to the internal connection properties.
 void close_All()
          Instance version of closeAll().
static void closeAll()
          Close ALL connections.
 java.sql.Connection getConnection(java.lang.String pURL)
          Connect to the specified database URL.
 java.sql.Connection getConnection(java.lang.String pURL, java.lang.String pName, java.lang.String pPassword)
          Attempt to get a connection from a database URL, a username and a password.
 java.sql.Connection getDSConnection()
          Get a Connection from a DataSource.
 java.sql.Connection getDSConnection(java.lang.String pName, java.lang.String pPass)
          Get a Connection from a DataSource using the provided username and password.
 boolean isDataSourceAvailable(java.lang.String pDatabase)
          Use this method to test whether or not the JNDI DataSource API is available.
 void reset()
          This method resets everything BUT existing Connections.
 boolean setDriver(java.lang.String pDriver)
          This method attempts to create the specified JDBC Driver.
 void setDSContext(javax.naming.Context pContext)
          Use this method to set the JNDI Context used for DataSource lookup.
 void setProperty(java.lang.String pKey, java.lang.String pValue)
          Set a property to be used in the getConnection(String, Properties) method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MathDBC

public MathDBC()
Standard scripting constructor. Nothing special.

Method Detail

reset

public void reset()
This method resets everything BUT existing Connections. Any previously-created Drivers are still available.


setDriver

public boolean setDriver(java.lang.String pDriver)

This method attempts to create the specified JDBC Driver. Any Exceptions are reported at DEBUG level. Since MathTools has no intrinsic JDBC Drivers this method automatically uses the MathClassLoader. The first time it is called, or after reset(), it will re-load the MathClassLoader. If the supplied String is null or blank nothing else happens.

CRITICAL NOTE: MathDBC handles drivers manually, without DriverManager. (Because it did not want to behave!!) One and only ONE Driver is active at any time; setting a new one replaces the previous one! Use carefully!!

Parameters:
pDriver - The name of the JDBC Driver to create.
Returns:
true if the Driver was created, false otherwise.

closeAll

public static final void closeAll()
Close ALL connections. Any errors are reported at DEBUG level.


close_All

public final void close_All()
Instance version of closeAll().


setProperty

public void setProperty(java.lang.String pKey,
                        java.lang.String pValue)
Set a property to be used in the getConnection(String, Properties) method. If the internal Properties object is null it will be created. If pKey is null or blank this method returns silently. If pValue is null or blank the current value for the key given, if it exists, is removed. CRITICAL NOTE: Even if pValue is null this method creates a Properties object if there was not one before.

Parameters:
pKey - The name of the property to be added.
pValue - The value of the property to set, or null to remove it.

addProperties

public void addProperties(java.util.Properties pNewProps)
Add the contents of a Properties object to the internal connection properties.

Parameters:
pNewProps - The Properties object to add.

getConnection

public java.sql.Connection getConnection(java.lang.String pURL,
                                         java.lang.String pName,
                                         java.lang.String pPassword)
Attempt to get a connection from a database URL, a username and a password. Any errors are reported at ERROR level and no string validation is done. If a Connection is successfully created it is added to an internal List of open connections. If no Driver is set this method prints an Error level message and returns null.

Parameters:
pURL - The URL of the database to connect to.
pName - The username to use.
pPassword - The password to use.
Returns:
The requested Connection or null if it failed.

getConnection

public java.sql.Connection getConnection(java.lang.String pURL)
Connect to the specified database URL. Any properties set will be sent in. If no Driver is set this method prints an Error level message and returns null.

Parameters:
pURL - The URL of the database desired.

isDataSourceAvailable

public boolean isDataSourceAvailable(java.lang.String pDatabase)
Use this method to test whether or not the JNDI DataSource API is available. If the supplied string is null or blank the method returns false and no checking is actually done. Any errors are reported at DEBUG level. This method DOES clear any previously-set DataSource before attempting to create a new one.

Parameters:
pDatabase - The Database to attempt using JNDI.

setDSContext

public void setDSContext(javax.naming.Context pContext)
Use this method to set the JNDI Context used for DataSource lookup. Setting it to null clears it and the next call to isDSAvailable() results in a zero-argument InitialContext being used. To reset to the default (CapCom.getNamingContext()) use the reset() method.

Parameters:
pContext - The javax.naming.Context used for DataSource instances, or null to clear it.

getDSConnection

public java.sql.Connection getDSConnection()
Get a Connection from a DataSource. This is the zero-argument method. Any errors are reported at Error level. If no DataSource has been established this method returns null.


getDSConnection

public java.sql.Connection getDSConnection(java.lang.String pName,
                                           java.lang.String pPass)
Get a Connection from a DataSource using the provided username and password. Any errors are reported at Error level. If no DataSource has been established this method returns null. No String-checking is done before attempting the connection.

Parameters:
pName - The username for the connection.
pPass - The password for the connection.