1 package org.apache.torque.dsfactory;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import javax.sql.DataSource;
20 import org.apache.commons.configuration.Configuration;
21 import org.apache.torque.TorqueException;
22
23 /***
24 * A factory that returns a DataSource.
25 *
26 * @author <a href="mailto:jmcnally@apache.org">John McNally</a>
27 * @author <a href="mailto:fischer@seitenbau.de">Thomas Fischer</a>
28 * @version $Id: DataSourceFactory.java 239636 2005-08-24 12:38:09Z henning $
29 */
30 public interface DataSourceFactory
31 {
32 /***
33 * Key for the configuration which contains DataSourceFactories
34 */
35 public static final String DSFACTORY_KEY = "dsfactory";
36
37 /***
38 * Key for the configuration which contains the fully qualified name
39 * of the factory implementation class
40 */
41 public static final String FACTORY_KEY = "factory";
42
43 /***
44 * @return the <code>DataSource</code> configured by the factory.
45 * @throws TorqueException if the source can't be returned
46 */
47 DataSource getDataSource() throws TorqueException;
48
49 /***
50 * Initialize the factory.
51 *
52 * @param configuration where to load the factory settings from
53 * @throws TorqueException Any exceptions caught during processing will be
54 * rethrown wrapped into a TorqueException.
55 */
56 void initialize(Configuration configuration)
57 throws TorqueException;
58
59 /***
60 * Sets the current schema for the database connection
61 *
62 * @param schema The current schema name
63 */
64 void setSchema(String schema);
65
66 /***
67 * This method returns the current schema for the database connection
68 *
69 * @return The current schema name. Null means, no schema has been set.
70 * @throws TorqueException Any exceptions caught during processing will be
71 * rethrown wrapped into a TorqueException.
72 */
73 String getSchema();
74
75 /***
76 * A hook which is called when the resources of the associated DataSource
77 * can be released.
78 * After close() is called, the other methods may not work any more
79 * (e.g. getDataSource() might return null).
80 * It is not guaranteed that this method does anything. For example,
81 * we do not want to close connections retrieved via JNDI, so the
82 * JndiDataSouurceFactory does not close these connections
83 *
84 * @throws TorqueException Any exceptions caught during processing will be
85 * rethrown wrapped into a TorqueException.
86 */
87 void close()
88 throws TorqueException;
89
90 }