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