1 package org.apache.torque;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import java.sql.Connection;
20
21 import org.apache.commons.configuration.Configuration;
22
23 import org.apache.torque.adapter.DB;
24 import org.apache.torque.manager.AbstractBaseManager;
25 import org.apache.torque.map.DatabaseMap;
26
27 /***
28 * A static facade wrapper around the Torque implementation (which is in
29 * {@link org.apache.torque.TorqueInstance}).
30 * <br/>
31 *
32 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
33 * @author <a href="mailto:magnus@handtolvur.is">Magn?s ??r Torfason</a>
34 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
35 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
36 * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
37 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
38 * @author <a href="mailto:kschrader@karmalab.org">Kurt Schrader</a>
39 * @version $Id: Torque.java 239636 2005-08-24 12:38:09Z henning $
40 */
41 public abstract class Torque
42 {
43 /***
44 * The prefix for all configuration keys used by Torque
45 */
46 public static final String TORQUE_KEY = "torque";
47
48 /***
49 * the prefix for configuring the database adapters and the default database
50 */
51 public static final String DATABASE_KEY = "database";
52
53 /***
54 * The key used to configure the name of the default database
55 */
56 public static final String DEFAULT_KEY = "default";
57
58 /***
59 * Name of property that specifies the default map builder and map.
60 * @deprecated is not used any more. Use DATABASE_KEY and
61 * DEFAULT_KEY instead
62 */
63 public static final String DATABASE_DEFAULT
64 = DATABASE_KEY + "." + DEFAULT_KEY;
65
66 /***
67 * A prefix for <code>Manager</code> properties in the configuration.
68 */
69 public static final String MANAGER_PREFIX = "managed_class.";
70
71 /***
72 * A <code>Service</code> property determining its implementing
73 * class name .
74 */
75 public static final String MANAGER_SUFFIX = ".manager";
76
77 /***
78 * property to determine whether caching is used.
79 */
80 public static final String CACHE_KEY = "manager.useCache";
81
82 /***
83 * The single instance of {@link TorqueInstance} used by the
84 * static API presented by this class.
85 */
86 private static TorqueInstance torqueSingleton = null;
87
88 /***
89 * C'tor for usage with the Stratum Lifecycle.
90 *
91 * @todo Should be made private or protected once Stratum is removed.
92 */
93 public Torque()
94 {
95 }
96
97 /***
98 * Retrieves the single {@link org.apache.torque.TorqueInstance}
99 * used by this class.
100 *
101 * @return Our singleton.
102 */
103 public static TorqueInstance getInstance()
104 {
105 if (torqueSingleton == null)
106 {
107 torqueSingleton = new TorqueInstance();
108 }
109 return torqueSingleton;
110 }
111
112 /***
113 * Initialization of Torque with a properties file.
114 *
115 * @param configFile The absolute path to the configuration file.
116 * @throws TorqueException Any exceptions caught during processing will be
117 * rethrown wrapped into a TorqueException.
118 */
119 public static void init(String configFile)
120 throws TorqueException
121 {
122 getInstance().init(configFile);
123 }
124
125 /***
126 * Initialization of Torque with a properties file.
127 *
128 * @param conf The Torque configuration.
129 * @throws TorqueException Any exceptions caught during processing will be
130 * rethrown wrapped into a TorqueException.
131 */
132 public static void init(Configuration conf)
133 throws TorqueException
134 {
135 getInstance().init(conf);
136 }
137
138 /***
139 * Determine whether Torque has already been initialized.
140 *
141 * @return true if Torque is already initialized
142 */
143 public static boolean isInit()
144 {
145 return getInstance().isInit();
146 }
147
148 /***
149 * Sets the configuration for Torque and all dependencies.
150 *
151 * @param conf the Configuration
152 */
153 public static void setConfiguration(Configuration conf)
154 {
155 getInstance().setConfiguration(conf);
156 }
157
158 /***
159 * Get the configuration for this component.
160 *
161 * @return the Configuration
162 */
163 public static Configuration getConfiguration()
164 {
165 return getInstance().getConfiguration();
166 }
167
168 /***
169 * This method returns a Manager for the given name.
170 *
171 * @param name name of the manager
172 * @return a Manager
173 */
174 public static AbstractBaseManager getManager(String name)
175 {
176 return getInstance().getManager(name);
177 }
178
179 /***
180 * This methods returns either the Manager from the configuration file,
181 * or the default one provided by the generated code.
182 *
183 * @param name name of the manager
184 * @param defaultClassName the class to use if name has not been configured
185 * @return a Manager
186 */
187 public static AbstractBaseManager getManager(String name,
188 String defaultClassName)
189 {
190 return getInstance().getManager(name, defaultClassName);
191 }
192
193 /***
194 * Shuts down the service.
195 *
196 * This method halts the IDBroker's daemon thread in all of
197 * the DatabaseMap's. It also closes all SharedPoolDataSourceFactories
198 * and PerUserPoolDataSourceFactories initialized by Torque.
199 * @exception TorqueException if a DataSourceFactory could not be closed
200 * cleanly. Only the first exception is rethrown, any following
201 * exceptions are logged but ignored.
202 */
203 public static void shutdown()
204 throws TorqueException
205 {
206 getInstance().shutdown();
207 }
208
209 /***
210 * Returns the default database map information.
211 *
212 * @return A DatabaseMap.
213 * @throws TorqueException Any exceptions caught during processing will be
214 * rethrown wrapped into a TorqueException.
215 */
216 public static DatabaseMap getDatabaseMap()
217 throws TorqueException
218 {
219 return getInstance().getDatabaseMap();
220 }
221
222 /***
223 * Returns the database map information. Name relates to the name
224 * of the connection pool to associate with the map.
225 *
226 * @param name The name of the database corresponding to the
227 * <code>DatabaseMap</code> to retrieve.
228 * @return The named <code>DatabaseMap</code>.
229 * @throws TorqueException Any exceptions caught during processing will be
230 * rethrown wrapped into a TorqueException.
231 */
232 public static DatabaseMap getDatabaseMap(String name)
233 throws TorqueException
234 {
235 return getInstance().getDatabaseMap(name);
236 }
237
238 /***
239 * Register a MapBuilder
240 *
241 * @param className the MapBuilder
242 */
243 public static void registerMapBuilder(String className)
244 {
245 getInstance().registerMapBuilder(className);
246 }
247
248 /***
249 * This method returns a Connection from the default pool.
250 *
251 * @return The requested connection.
252 * @throws TorqueException Any exceptions caught during processing will be
253 * rethrown wrapped into a TorqueException.
254 */
255 public static Connection getConnection()
256 throws TorqueException
257 {
258 return getInstance().getConnection();
259 }
260
261 /***
262 * This method returns a Connecton using the given database name.
263 *
264 * @param name The database name.
265 * @return a database connection
266 * @throws TorqueException Any exceptions caught during processing will be
267 * rethrown wrapped into a TorqueException.
268 */
269 public static Connection getConnection(String name)
270 throws TorqueException
271 {
272 return getInstance().getConnection(name);
273 }
274
275 /***
276 * This method returns a Connecton using the given parameters.
277 * You should only use this method if you need user based access to the
278 * database!
279 *
280 * @param name The database name.
281 * @param username The name of the database user.
282 * @param password The password of the database user.
283 * @return A Connection.
284 * @throws TorqueException Any exceptions caught during processing will be
285 * rethrown wrapped into a TorqueException.
286 */
287 public static Connection getConnection(String name, String username,
288 String password)
289 throws TorqueException
290 {
291 return getInstance().getConnection(name, username, password);
292 }
293 /***
294 * Returns database adapter for a specific connection pool.
295 *
296 * @param name A pool name.
297 * @return The corresponding database adapter.
298 * @throws TorqueException Any exceptions caught during processing will be
299 * rethrown wrapped into a TorqueException.
300 */
301 public static DB getDB(String name) throws TorqueException
302 {
303 return getInstance().getDB(name);
304 }
305
306 /***
307 * Returns the name of the default database.
308 *
309 * @return name of the default DB, or null if Torque is not initialized yet
310 */
311 public static String getDefaultDB()
312 {
313 return getInstance().getDefaultDB();
314 }
315
316 /***
317 * Closes a connection.
318 *
319 * @param con A Connection to close.
320 */
321 public static void closeConnection(Connection con)
322 {
323 getInstance().closeConnection(con);
324 }
325
326 /***
327 * Sets the current schema for a database connection
328 *
329 * @param name The database name.
330 * @param schema The current schema name
331 * @throws TorqueException Any exceptions caught during processing will be
332 * rethrown wrapped into a TorqueException.
333 */
334 public static void setSchema(String name, String schema)
335 throws TorqueException
336 {
337 getInstance().setSchema(name, schema);
338 }
339
340 /***
341 * This method returns the current schema for a database connection
342 *
343 * @param name The database name.
344 * @return The current schema name. Null means, no schema has been set.
345 * @throws TorqueException Any exceptions caught during processing will be
346 * rethrown wrapped into a TorqueException.
347 */
348 public static String getSchema(String name)
349 throws TorqueException
350 {
351 return getInstance().getSchema(name);
352 }
353 }