This isn't so much a design as a list of why we made the decisions we did. If you disagree with anything then feel free to let us know...

Logging

Goals: 1) not replicate the work that has gone into other logging projects, 2) make it fast, 3) make it pluggable so you're not tied to a particular solution.

Solution: use Jakarta Common's ultra thin logger. This will automatically log to Log4J or JDK 1.4's logger. If you want it to log somwehere else then you just need to write a simple wrapper.

Good: it's already written, it's robust, it works.

Bad: nothing really :)

Proxy

To get transparent control when people close a connection we need to proxy the Connection object itself. This is easy enough to do: create an object called ProxyConnection which contains a real Connection and delegate everthing (except the close method) to the Connection. The trouble with this solution is that the API to the Connection object changes with each release of the JDK. This means you have to constantly update the proxy and deploy different versions for different JDKs. Not nice.

JDK 1.3 introduces the Proxy class that does a lot of this delegation for you using reflection. This makes it really easy and means that when the API changes everything still works. Unfortunately, it won't work with JDK 1.2. So we have patched up some hand written proxies that work with JDK 1.2 only. They are contained within a different source tree to the main code. When you use Ant to build your jar (and you specify that you are targetting JDK 1.2) then it copies over these patched classes before compilation. This is not an ideal solution, but at least it should go away over time when we eventually drop support for JDK 1.2 (which we're not in a rush to do, by the way).

Using reflection is slower. No doubt about it. Quick tests have shown that it might add 1 or 2 milliseconds to each database call. I suggest that this isn't really significant and that the ease of use and maintainability outweigh this slight delay.