Package uk.co.weft.dbutil

A data source abstraction package implementing pooled connections to (primarily SQL) data sources.

See:
Description

Interface Summary

Authenticator	an interface describing an agent which can authenticate a context
DataStoreDescriptor	An object representation of an abstract data store.

Class Summary

BitColumnDescriptor	A descriptor for an bit column
BooleanColumnDescriptor	A descriptor for an boolean column
Calendar	A simple specialisation of a GregorianCalendar which doesn't make a complete balls-up of rendering itself as a string.
CharacterColumnDescriptor	A descriptor for a character column.
ClobColumnDescriptor	CLOBs are large chunks of text which may be stored in or returned by a database.
ColumnDescriptor	A cache to hold the essential features of a database column.
ConnectionFish	A fish is something that swims in a pool, obviously.
ConnectionPool	The handler for a pool of database connections.
Context	A namespace in which to hold arbitrary values.
Contexts	A collection of contexts; at minimum, a wrapper around Vector.
Currency	An amount of money.
DataNull	An object representing a null data value, rather than a null object This is useful where you actually WANT a null item, rather than a Java null which tends to be used as a sentinel.
DateColumnDescriptor	A descriptor for an date column.
IntegerColumnDescriptor	A descriptor for an integer column
ISO8601Calendar	A simple specialisation of a GregorianCalendar which renders itself as a string in ISO8601 format.
JDBCAuthenticator	an authenticator which authenticates against a JDBC data source
JDBCUserKluge	JDBC does not provide any unified or portable way to deal with adding modifying and deleting user accounts, but in an application its often important that a user should be able to change their password; this is an attempt to provide a consistent, database independent API for creating, modifying and deleting database-layer user accounts.
ObjectColumnDescriptor	A descriptor for a column where we really don't know how to handle it.
PoolStatistics	A class to provide an interface through which an application can monitor the performance of the connection pool.
RealColumnDescriptor	A descriptor for a real-number column
RSContexts	A wrapper (at this stage not very clever) around a ResultSet.
TableDescriptor	An object representation of a database table.
TimeColumnDescriptor	A descriptor for an time column
TimeStampColumnDescriptor	A descriptor for a TimeStamp column

Exception Summary

ConnectionPoolException	An exception inidcating a failure of the connection pool.
DataAuthException	An exception raised when rights of access to data cannot be authenticatedted appropriately.
DataFormatException	An exception raised when data cannot be formatted appropriately for its column.
DataStoreException	A general purpose data storage exception.

Package uk.co.weft.dbutil Description

A data source abstraction package implementing pooled connections to (primarily SQL) data sources.

The Pool model

Connections ('fish') are issued to user processes which are expected to return them. If the fish is never returned this isn't a disaster, because the garbage collector will cope, and the pool manager does not track fish when they are out of the pool. However, as the cost of establishing a connection is quite high, user processes are encouraged to return fish to the pool for re-use. Also, of course, holding open a connection that isn't being used is a resource issue.

The pool organises fish by data source, username and password. A fish will only be re-issued to a context which specifies the same datasource, username, and password as that against which it was originally issued. Thus there are no security risks of maintaining a pool of open authenticated connections. In any case, connections do not stay open for ever. If a connection remains unused in the pool for more than a limited time (currently five minutes) it is cleaned up by the pool cleaner process.

The data storage model

The idea behind the dbutil design is to abstract data storage so that the same data storage and retrieval methods can be used with SQL databases, object databases, LDAP servers, CSV text files, mail files and so on - although so far only the SQL part of this has been built. It is assumed that there are four primitive data store operations: store, fetch, match, and drop.

• A store operation will store those values named in the namespace represented by the context object which have named storage locations in the storage object, against the key value passed.
• A fetch operation populates the context with name-value pairs taken from the data object by applying the key.
• A match operation retrieves a set of contexts from the store which match the context passed - i.e. for each name in the context passed, they have the same value as the value in the context passed. This set comes back as a ContextGroup; however, a context group need not instantiate all it's contexts immediately. The underlying problem here is we don't necessarily want to schlurp the whole query result into memory, but at the same time the underlying interface through which we will mostly get it (JDBC) does not hold results indefinitely. So a ContextGroup can be treated as valid only for a short time - unless you 'freeze' it.
• A drop operations drops from the storage object information matching the key. In the relational model, the storage object is a table, and the locations are its rows.

These operations - and no others - should eventually be implemented for all types of data store.

Using dbutil with MS SQL Server

Of the various JDBC drivers available for MS SQL Server, the DataDirect driver works with Jacquard 'out of the box'. If you use the free Microsoft driver for SQLServer, you must set the property 'SelectMethod' to 'cursor'. I'm a little unhappy about this and am not certain it will work correctly in all cases, but if you don't it won't work at all.

Example:

jdbc:microsoft:sqlserver://my.server:1433;DatabaseName=MYDB;SelectMethod=cursor;ProgamName=myprogram

Copyright and License

The following is the whole of your license and warranty to use this package:

[Note: this is the 'BSD License' as endorsed by OpenSource.org.]

Copyright (c) 1998,1999, Simon Brooke. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of Simon Brooke. nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SIMON BROOKE OR OTHER CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

© Simon Brooke, Carlinscraig, Auchencairn, DG7 1QU, Scotland.