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