01: /*
02: * @(#) ConnectionProvider 1.0 02/08/01
03: */
04: package org.smartlib.pool.core;
05:
06: import java.sql.*;
07:
08: /**
09: * This interface is used to wrap the SmartPool to an existing connection pool.
10: *
11: * <p>To wrap the SmartPool to an existing pool, provide an instance of
12: * this interface in the configuration file. SmartPool will then draw
13: * connection from this pool rather then drawing raw connections to the
14: * pool. </p>
15: *
16: * <p>Also if the SmartPool is wrapped around another pool
17: * it will draw a connection on every call by calling
18: * ConnectionProvider.getConnection().</p>
19: *
20: * <p>Similarly when you call Connection.close(), SmartPool returns the
21: * connection back to the original pool immediately by calling
22: * ConnectionProvider.returnConnection().</p>
23: *
24: * <p>In short when this feature is used, SmartPool is just another layer of
25: * indirection. SmartPool does not maintain any pool. This has been
26: * specifically designed to do so. This is because the external pool to which
27: * SmartPool is wrapped is expected to do all the pooling. SmartPool can be
28: * used to detect leaks and monitor live connections etc. <p>
29: *
30: */
31:
32: /* Note from the Author: I realized this when I tested this feature against an
33: * Application Server DataSource pool and to my surprise (I call my self
34: * a J2EE expert :) ) I discovered that the application server requires the
35: * connection to be returned to the pool.
36: * The Application Server manages the state of the connections and thus it is
37: * imperative to return the connection back to the Application Server after
38: * each use.
39: */
40:
41: public interface ConnectionProvider {
42:
43: /**
44: * <p>This method implementation should fetch the connection.
45: * This method is expected to block if a connection is not available untill
46: * a connection a available.</p>
47: *
48: * <p>Whatever preprocessing you want to do, do it here. SmartPool will not
49: * manuplate the connection state in anyway.</p>
50: * e.g. of preprocessing:<br>
51: * <li> 1. Testing if the connection is valid.
52: * <li> 2. con.setAutoCommit(false|true)
53: *
54: * <p>If you throw any Exception while doing this, SmartPool will wrap this
55: * exception with ConnectionPoolException and throw it back to you in the
56: * SmartPoolFactory.getConnection() method. So better behave your self and
57: * handle all the cases here itself.</p>
58: *
59: *
60: */
61: public Connection getConnection() throws Exception;
62:
63: /**
64: *<p>This method implementation should release the connection.</p>
65: *
66: * <p>Whatever postprocessing you want to do, do it here.</p>
67: * e.g. of postprocessing<br>
68: * <li> 1. if (!conn.getAutoCommit()) conn.commit();
69: *
70: * <p>If you throw any Exception while doing this, SmartPool will wrap this
71: * exception with SQLException and throw it back to you in the
72: * Connection.close() method. So better behave your self and
73: * handle all the cases here itself.</p>
74: *
75: */
76: public void returnConnection(Connection conn) throws Exception;
77:
78: }
|