uk.co.weft.dbutil
Class ConnectionPool

java.lang.Object
  uk.co.weft.dbutil.ConnectionPool

public abstract class ConnectionPool

extends java.lang.Object

The handler for a pool of database connections. Holds and serves connections by a combined key of url!username!password, so can pool connections to several databases for several users simultaneously. Security implications: database passwords are stored in memory for the lifetime of the pool and could potentially be recovered from a core dump. However, as this runs server-side, that isn't too serious.

This is a prototype class: all methods are class methods. Do *not* attempt to create new instances!

ConnectionPool.getConnection() returns a ConnectionFish which is a wrapper round a java.sql.Connection. A fish which is not returned to the pool will eventually die; however, it's unwise to rely on this in situations where connections may be being requested in quick succession. For every call you make to ConnectionPool.getConnection() you should make a call to ConnectionPool.releaseConnection(). NOTE that you should not explicitly close a connection obtained from the pool. You should simply return it to the pool.

Version:

$Revision: 1.21.4.1 $ This revision: $Author: simon $

  $Log: ConnectionPool.java,v $
  Revision 1.21.4.1  2005/12/23 10:48:32  simon
  Brute force tidy up after CVS server crash: this time it should work.

  Revision 1.21  2004/03/31 15:00:52  simon
  Bugfix: long hunt for a LinkTableWidget bug, involving much
  adding of debug messages, but also a significant change in logic
  in Form - essentially, if we don't know what widgetset we came
  from, don't call preprocess on any.

  Revision 1.20  2003/08/20 09:38:35  simon
  Code cleanup with eclipse; mostly removal of exccessive includes

  Revision 1.19  2003/08/18 11:05:30  simon
  Documentation changes.

  Revision 1.18  2003/06/24 15:35:04  simon
  Bug fix: protect against null pointer exceptions if no username or
  password in getConnection

  Revision 1.17  2001/06/29 13:12:39  simon
  Working around an Oracle-related issue where transactions were not getting
  closed properly in all cases. Thanks to Dave Orr.

  Revision 1.16  2001/03/02 11:31:00  simon
  New todo note; no change in executable code.

  Revision 1.15  2000/09/19 10:31:15  simon
  Major changes rationalising Contexts. There is now no Context but Context,
  and dbutil is its Package

  Revision 1.14  2000/07/28 13:13:07  simon
  Further work on the connection pool leak problem; this time I think it's
  fixed. After much tightening up of code the problem was eventually
  isolated to AuthenticatedForm.preForm(), which did a getConnection()
  without a corresponding releaseConnection(). Now fixed.

  Revision 1.13  2000/07/06 09:49:56  simon
  Deprecated dontCloseStatements option to releaseConnection() as it appears
  to be implicated in undead fish bug.

  Revision 1.12  2000/07/05 10:31:46  simon
  Minor tweak: If I can't get a new fish, but I've got a pool to put it
  in, then that's almost certainly the DBMS run out of connections, so
  say that explicitly.

  Revision 1.11  2000/07/05 09:45:46  simon
  Real clamp-down on the dead-fish bug. Shoal instituted as a class, and
  access to the contents of the shoal now only through synchronized methods.
  Should remove the risk of a fish being issued and killed at the same time.

  Revision 1.10  2000/06/27 19:13:47  simon
  Nasty! IntegerColumnDescriptor and friends were returning zero when they
  should have returned DataNull. John Robinson pointed this bug out last
  Autumn, and I thought he'd fixed it; but if he had his fixes didn't make
  it into the CVS. In ConnectionPool, ensured that newly issued fish have
  consistent (on) autocommit state.

  Revision 1.9  2000/06/19 20:32:29  simon
  More work on dead fish problems.

  Revision 1.8  2000/06/16 13:56:51  simon
  More work on ensuring connections don't spawn out of control and die
  nicely.

  Revision 1.7  2000/05/31 18:06:56  simon
  Work to clean up java.sql.Statements left open by higher level classes.
  ConnectionFish and ConnectionPool now co-operate to close statements
  left open unless explicitly asked not to.

  Revision 1.6  2000/05/01 15:44:07  simon
  Improved documentation to connection pool code: no actual code changes.

  Revision 1.5  1999/10/20 12:53:00  simon
  Intermediate commit while tracking down pool maintenance problem.
  Essentially fish are not being reissued nearly as often as they
  should be, although they appear to be correctly returned to the
  pool. This commit has better logging.

  Revision 1.4  1999/08/29 22:25:04  simon
  Final commit before delivery of bthomepage. Late changes include
    * Integration of Spider and Compiler configuration mechanisms
    * Case insensitive search
    * Page preview mechanism via CompiledPage.java
    * Confirm before delete
    * Confirm after store, delete
    * URLs in ResultFormatter tables are links

  Revision 1.3  1999/08/15 17:09:09  simon
  Major changes, primarily to htform: the action despatcher has now
  been built in Form, supported by a new class ActionWidget. This of
  course has required changes in classes built on Form, and
  particularly in AuthenticatedForm and TableWrapperForm, which are
  both now much simpler and cleaner.

  Revision 1.2  1999/07/19 18:18:07  simon
  checkpoint at first nearly working version of BT Homepage editing
  suite. Primary changes in dbutil are: substantial improvements to the
  connection pool; and making Context a direct subclass of Hashtable,
  rather than a wrapper around it.

  Revision 1.1  1999/07/14 18:04:59  simon
  The Great Re-engineering

  What had been a simple little package to produce hypertext forms has
  grown remarkably. The original motivations were to handle sessions
  more elegantly and to further abstract database handling. The
  database handling classes have been moved into a new, independent,
  packags, dbutil, which, in addition to automatically handling
  synchronisation of data between the application and database layers,
  is also intended to maintain an efficient, secure pool of database
  connections.


  

Author:

Simon Brooke (simon@weft.co.uk)

See Also:

ConnectionFish

Field Summary

static java.lang.String	dbPassMagicToken Deprecated. use DBPASSMAGICTOKEN
static java.lang.String	DBPASSMAGICTOKEN a magic token to use to retrieve a database password from a context
static java.lang.String	dbUrlMagicToken Deprecated. use DBURLMAGICTOKEN
static java.lang.String	DBURLMAGICTOKEN a magic token to use to retrieve a database URL from a context
static java.lang.String	dbUserMagicToken Deprecated. use DBUSERMAGICTOKEN
static java.lang.String	DBUSERMAGICTOKEN a magic token to use to retrieve a database username from a context

Constructor Summary

ConnectionPool()

Method Summary

static java.lang.Integer	genKey(java.lang.String u, java.lang.String n, java.lang.String p) generate a unique hash key for this combination of url, username and password
static java.sql.Connection	getConnection(java.lang.String url, java.lang.String user, java.lang.String pass) issue a valid connection (actually a fish) matching this pattern.
static PoolStatistics	getStatistics() get a copy of my statistics object
static void	releaseConnection(java.sql.Connection fish) Accept this connection and try to put it in the pool.
static void	releaseConnection(java.sql.Connection c, boolean dontCloseStatements) Deprecated. setting dontCloseStatements to true may be associated with connection pool leaks: use with great caution.
protected static void	unlink(ConnectionFish fish) This is paranoia; if a fish is closed we really need to check that it is removed from the pool.

Methods inherited from class java.lang.Object

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

Field Detail

DBURLMAGICTOKEN

public static final java.lang.String DBURLMAGICTOKEN

a magic token to use to retrieve a database URL from a context

See Also:

Constant Field Values

DBUSERMAGICTOKEN

public static final java.lang.String DBUSERMAGICTOKEN

a magic token to use to retrieve a database username from a context

See Also:

Constant Field Values

DBPASSMAGICTOKEN

public static final java.lang.String DBPASSMAGICTOKEN

a magic token to use to retrieve a database password from a context

See Also:

Constant Field Values

dbUrlMagicToken

public static final java.lang.String dbUrlMagicToken

Deprecated. use DBURLMAGICTOKEN

a magic token to use to retrieve a database URL from a context

See Also:

Constant Field Values

dbUserMagicToken

public static final java.lang.String dbUserMagicToken

Deprecated. use DBUSERMAGICTOKEN

a magic token to use to retrieve a database username from a context

See Also:

Constant Field Values

dbPassMagicToken

public static final java.lang.String dbPassMagicToken

Deprecated. use DBPASSMAGICTOKEN

a magic token to use to retrieve a database password from a context

See Also:

Constant Field Values

Constructor Detail

ConnectionPool

public ConnectionPool()

Method Detail

genKey

public static java.lang.Integer genKey(java.lang.String u,
                                       java.lang.String n,
                                       java.lang.String p)

generate a unique hash key for this combination of url, username and password

getConnection

public static java.sql.Connection getConnection(java.lang.String url,
                                                java.lang.String user,
                                                java.lang.String pass)
                                         throws DataStoreException

issue a valid connection (actually a fish) matching this pattern. You are strongly advised to make one call to releaseConnection(), q.v. for every call to getConnection. If you don't, the fish will ultimately time out on you and die anyway, but nevertheless Web systems in particular can quickly run up huge numbers of open connections and you are strongly advised to free them explicitly. Fish when issued always have autocommit set TODO: this hasn't happened yet, but it will: what happens if an application programmer releases a connection into the pool, and then closes it?. At present I'm trapping here for this and just dying if it happens; but wouldn't it be better if ConnectionFish trapped all the methods of Connection, and simply refused to execute them if the fish was in the pool?

Parameters:

url - the database url for this connection

user - the database username for this connection

pass - the database password for this connection

Throws:

DataStoreException - if too many open connections or dead fish in pool

releaseConnection

public static void releaseConnection(java.sql.Connection fish)
                              throws DataStoreException

Accept this connection and try to put it in the pool. Close any remaining open statements.

Throws:

DataStoreException

releaseConnection

public static void releaseConnection(java.sql.Connection c,
                                     boolean dontCloseStatements)
                              throws DataStoreException

Deprecated. setting dontCloseStatements to true may be associated with connection pool leaks: use with great caution.

Accept this connection and try to put it in the pool. Close any remaining open statements on the fish unless dontCloseStatements is true. Note that dontCloseStatements is a pretty desperate hack - the fish is going to be reissued, and when it's released again those statements are going to be closed, so you better finish using them quick anyway.

Throws:

DataStoreException

unlink

protected static void unlink(ConnectionFish fish)

This is paranoia; if a fish is closed we really need to check that it is removed from the pool. A fish souldn't be closed while it's in the pool, but let's be careful. If the fish has already been unlinked (e.g. by the SuckerFish) this will do no harm.

See Also:

ConnectionFish.close()

getStatistics

public static PoolStatistics getStatistics()

get a copy of my statistics object