|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcox.jmatt.java.MathTools.util.MathDBC
public class MathDBC
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.Driver
s 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.
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.
Establishing JNDI is well outside the scope of MathTools! If, however, JNDI is present it may be used for database access via DataSource
s. 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 |
---|
public MathDBC()
Method Detail |
---|
public void reset()
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!!
pDriver
- The name of the JDBC Driver to create.
Driver
was created, false otherwise.public static final void closeAll()
public final void close_All()
closeAll()
.
public void setProperty(java.lang.String pKey, java.lang.String pValue)
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.
pKey
- The name of the property to be added.pValue
- The value of the property to set, or null to remove it.public void addProperties(java.util.Properties pNewProps)
Properties
object to the internal connection properties.
pNewProps
- The Properties object to add.public java.sql.Connection getConnection(java.lang.String pURL, java.lang.String pName, java.lang.String pPassword)
Driver
is set this method prints an Error level
message and returns null.
pURL
- The URL of the database to connect to.pName
- The username to use.pPassword
- The password to use.
public java.sql.Connection getConnection(java.lang.String pURL)
Driver
is set this method prints an Error level message and
returns null.
pURL
- The URL of the database desired.public boolean isDataSourceAvailable(java.lang.String pDatabase)
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.
pDatabase
- The Database to attempt using JNDI.public void setDSContext(javax.naming.Context pContext)
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.
pContext
- The javax.naming.Context
used for DataSource
instances, or null to clear it.public java.sql.Connection getDSConnection()
DataSource
. This is the zero-argument method. Any errors are reported at Error level. If no DataSource has been
established this method returns null.
public java.sql.Connection getDSConnection(java.lang.String pName, java.lang.String pPass)
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.
pName
- The username for the connection.pPass
- The password for the connection.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |