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