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