01: /**
02: * $RCSfile$
03: * $Revision: 9758 $
04: * $Date: 2008-01-12 17:54:08 -0800 (Sat, 12 Jan 2008) $
05: *
06: * Copyright (C) 2004 Jive Software. All rights reserved.
07: *
08: * This software is published under the terms of the GNU Public License (GPL),
09: * a copy of which is included in this distribution.
10: */package org.jivesoftware.database;
11:
12: import java.sql.Connection;
13: import java.sql.SQLException;
14:
15: /**
16: * Abstract class that defines the connection provider framework. Other classes
17: * extend this abstract class to make connection to actual data sources.<p>
18: * <p/>
19: * It is expected that each subclass be a JavaBean, so that properties of
20: * the connection provider are exposed through bean introspection.
21: *
22: * @author Jive Software
23: */
24: public interface ConnectionProvider {
25:
26: /**
27: * Returns true if this connection provider provides connections out
28: * of a connection pool. Implementing and using connection providers that
29: * are pooled is strongly recommended, as they greatly increase the speed
30: * of Jive.
31: *
32: * @return true if the Connection objects returned by this provider are
33: * pooled.
34: */
35: public boolean isPooled();
36:
37: /**
38: * Returns a database connection. When a Jive component is done with a
39: * connection, it will call the close method of that connection. Therefore,
40: * connection pools with special release methods are not directly
41: * supported by the connection provider infrastructure. Instead, connections
42: * from those pools should be wrapped such that calling the close method
43: * on the wrapper class will release the connection from the pool.
44: *
45: * @return a Connection object.
46: * @throws SQLException is an SQL error occured while retrieving the connection.
47: */
48: public Connection getConnection() throws SQLException;
49:
50: /**
51: * Starts the connection provider. For some connection providers, this
52: * will be a no-op. However, connection provider users should always call
53: * this method to make sure the connection provider is started.
54: */
55: public void start();
56:
57: /**
58: * This method should be called whenever properties have been changed so
59: * that the changes will take effect.
60: */
61: public void restart();
62:
63: /**
64: * Tells the connection provider to destroy itself. For many connection
65: * providers, this will essentially result in a no-op. However,
66: * connection provider users should always call this method when changing
67: * from one connection provider to another to ensure that there are no
68: * dangling database connections.
69: */
70: public void destroy();
71: }
|