001: package org.apache.torque;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.sql.Connection;
023: import java.util.Map;
024:
025: import org.apache.commons.configuration.Configuration;
026: import org.apache.torque.adapter.DB;
027: import org.apache.torque.manager.AbstractBaseManager;
028: import org.apache.torque.map.DatabaseMap;
029: import org.apache.torque.map.MapBuilder;
030:
031: /**
032: * A static facade wrapper around the Torque implementation (which is in
033: * {@link org.apache.torque.TorqueInstance}).
034: * <br/>
035: *
036: * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
037: * @author <a href="mailto:magnus@handtolvur.is">Magn�s ��r Torfason</a>
038: * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
039: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
040: * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
041: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
042: * @author <a href="mailto:kschrader@karmalab.org">Kurt Schrader</a>
043: * @version $Id: Torque.java 493449 2007-01-06 11:46:50Z tv $
044: */
045: public class Torque {
046: /**
047: * The prefix for all configuration keys used by Torque.
048: */
049: public static final String TORQUE_KEY = "torque";
050:
051: /**
052: * The prefix for configuring the database adapters
053: * and the default database.
054: */
055: public static final String DATABASE_KEY = "database";
056:
057: /**
058: * The key used to configure the name of the default database.
059: */
060: public static final String DEFAULT_KEY = "default";
061:
062: /**
063: * Name of property that specifies the default map builder and map.
064: * @deprecated is not used any more. Use DATABASE_KEY and
065: * DEFAULT_KEY instead
066: */
067: public static final String DATABASE_DEFAULT = DATABASE_KEY + "."
068: + DEFAULT_KEY;
069:
070: /**
071: * A prefix for <code>Manager</code> properties in the configuration.
072: */
073: public static final String MANAGER_PREFIX = "managed_class.";
074:
075: /**
076: * A <code>Service</code> property determining its implementing
077: * class name .
078: */
079: public static final String MANAGER_SUFFIX = ".manager";
080:
081: /**
082: * property to determine whether caching is used.
083: */
084: public static final String CACHE_KEY = "manager.useCache";
085:
086: /**
087: * The single instance of {@link TorqueInstance} used by the
088: * static API presented by this class.
089: */
090: private static TorqueInstance torqueSingleton = null;
091:
092: /**
093: * C'tor for usage with the Stratum Lifecycle.
094: *
095: * TODO: Should be made private or protected once Stratum is removed.
096: */
097: public Torque() {
098: }
099:
100: /**
101: * Retrieves the single {@link org.apache.torque.TorqueInstance}
102: * used by this class.
103: *
104: * @return Our singleton.
105: */
106: public static TorqueInstance getInstance() {
107: if (torqueSingleton == null) {
108: torqueSingleton = new TorqueInstance();
109: }
110: return torqueSingleton;
111: }
112:
113: /**
114: * Sets the single {@link org.apache.torque.TorqueInstance}
115: * used by this class. This is used by the Avalon component
116: * to make sure that only one instance of Torque exists
117: *
118: * @param instance Our singleton.
119: */
120: public static synchronized void setInstance(TorqueInstance instance) {
121: torqueSingleton = instance;
122: }
123:
124: /**
125: * Initialization of Torque with a properties file.
126: *
127: * @param configFile The absolute path to the configuration file.
128: * @throws TorqueException Any exceptions caught during processing will be
129: * rethrown wrapped into a TorqueException.
130: */
131: public static void init(String configFile) throws TorqueException {
132: getInstance().init(configFile);
133: }
134:
135: /**
136: * Initialization of Torque with a properties file.
137: *
138: * @param conf The Torque configuration.
139: * @throws TorqueException Any exceptions caught during processing will be
140: * rethrown wrapped into a TorqueException.
141: */
142: public static void init(Configuration conf) throws TorqueException {
143: getInstance().init(conf);
144: }
145:
146: /**
147: * Determine whether Torque has already been initialized.
148: *
149: * @return true if Torque is already initialized
150: */
151: public static boolean isInit() {
152: return getInstance().isInit();
153: }
154:
155: /**
156: * Sets the configuration for Torque and all dependencies.
157: *
158: * @param conf the Configuration
159: */
160: public static void setConfiguration(Configuration conf) {
161: getInstance().setConfiguration(conf);
162: }
163:
164: /**
165: * Get the configuration for this component.
166: *
167: * @return the Configuration
168: */
169: public static Configuration getConfiguration() {
170: return getInstance().getConfiguration();
171: }
172:
173: /**
174: * This method returns a Manager for the given name.
175: *
176: * @param name name of the manager
177: * @return a Manager
178: */
179: public static AbstractBaseManager getManager(String name) {
180: return getInstance().getManager(name);
181: }
182:
183: /**
184: * This methods returns either the Manager from the configuration file,
185: * or the default one provided by the generated code.
186: *
187: * @param name name of the manager
188: * @param defaultClassName the class to use if name has not been configured
189: * @return a Manager
190: */
191: public static AbstractBaseManager getManager(String name,
192: String defaultClassName) {
193: return getInstance().getManager(name, defaultClassName);
194: }
195:
196: /**
197: * Shuts down the service.
198: *
199: * This method halts the IDBroker's daemon thread in all of
200: * the DatabaseMap's. It also closes all SharedPoolDataSourceFactories
201: * and PerUserPoolDataSourceFactories initialized by Torque.
202: * @exception TorqueException if a DataSourceFactory could not be closed
203: * cleanly. Only the first exception is rethrown, any following
204: * exceptions are logged but ignored.
205: */
206: public static void shutdown() throws TorqueException {
207: getInstance().shutdown();
208: }
209:
210: /**
211: * Returns the default database map information.
212: *
213: * @return A DatabaseMap.
214: * @throws TorqueException Any exceptions caught during processing will be
215: * rethrown wrapped into a TorqueException.
216: */
217: public static DatabaseMap getDatabaseMap() throws TorqueException {
218: return getInstance().getDatabaseMap();
219: }
220:
221: /**
222: * Returns the database map information. Name relates to the name
223: * of the connection pool to associate with the map.
224: *
225: * @param name The name of the database corresponding to the
226: * <code>DatabaseMap</code> to retrieve.
227: * @return The named <code>DatabaseMap</code>.
228: * @throws TorqueException Any exceptions caught during processing will be
229: * rethrown wrapped into a TorqueException.
230: */
231: public static DatabaseMap getDatabaseMap(String name)
232: throws TorqueException {
233: return getInstance().getDatabaseMap(name);
234: }
235:
236: /**
237: * Register a MapBuilder
238: *
239: * @param className the MapBuilder
240: */
241: public static void registerMapBuilder(String className) {
242: getInstance().registerMapBuilder(className);
243: }
244:
245: /**
246: * Register a MapBuilder
247: *
248: * @param builder the instance of the MapBuilder
249: *
250: */
251: public static void registerMapBuilder(MapBuilder builder) {
252: getInstance().registerMapBuilder(builder);
253: }
254:
255: /**
256: * Get a MapBuilder
257: *
258: * @param className of the MapBuilder
259: * @return A MapBuilder, not null
260: * @throws TorqueException if the Map Builder cannot be instantiated
261: *
262: */
263: public static MapBuilder getMapBuilder(String className)
264: throws TorqueException {
265: return getInstance().getMapBuilder(className);
266: }
267:
268: /**
269: * This method returns a Connection from the default pool.
270: *
271: * @return The requested connection.
272: * @throws TorqueException Any exceptions caught during processing will be
273: * rethrown wrapped into a TorqueException.
274: */
275: public static Connection getConnection() throws TorqueException {
276: return getInstance().getConnection();
277: }
278:
279: /**
280: * This method returns a Connecton using the given database name.
281: *
282: * @param name The database name.
283: * @return a database 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)
288: throws TorqueException {
289: return getInstance().getConnection(name);
290: }
291:
292: /**
293: * This method returns a Connecton using the given parameters.
294: * You should only use this method if you need user based access to the
295: * database!
296: *
297: * @param name The database name.
298: * @param username The name of the database user.
299: * @param password The password of the database user.
300: * @return A Connection.
301: * @throws TorqueException Any exceptions caught during processing will be
302: * rethrown wrapped into a TorqueException.
303: */
304: public static Connection getConnection(String name,
305: String username, String password) throws TorqueException {
306: return getInstance().getConnection(name, username, password);
307: }
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: return getInstance().getDB(name);
319: }
320:
321: /**
322: * Returns the name of the default database.
323: *
324: * @return name of the default DB, or null if Torque is not initialized yet
325: */
326: public static String getDefaultDB() {
327: return getInstance().getDefaultDB();
328: }
329:
330: /**
331: * Closes a connection.
332: *
333: * @param con A Connection to close.
334: */
335: public static void closeConnection(Connection con) {
336: getInstance().closeConnection(con);
337: }
338:
339: /**
340: * Sets the current schema for a database connection
341: *
342: * @param name The database name.
343: * @param schema The current schema name
344: * @throws TorqueException Any exceptions caught during processing will be
345: * rethrown wrapped into a TorqueException.
346: */
347: public static void setSchema(String name, String schema)
348: throws TorqueException {
349: getInstance().setSchema(name, schema);
350: }
351:
352: /**
353: * This method returns the current schema for a database connection
354: *
355: * @param name The database name.
356: * @return The current schema name. Null means, no schema has been set.
357: * @throws TorqueException Any exceptions caught during processing will be
358: * rethrown wrapped into a TorqueException.
359: */
360: public static String getSchema(String name) throws TorqueException {
361: return getInstance().getSchema(name);
362: }
363:
364: /**
365: * Returns the database for the given key.
366: *
367: * @param name The database name.
368: * @return the Database for the given name, or null if no database exists
369: * for the given name.
370: * @throws TorqueException if Torque is not yet initialized.
371: */
372: public static Database getDatabase(String name)
373: throws TorqueException {
374: return getInstance().getDatabase(name);
375: }
376:
377: /**
378: * Returns a Map containing all Databases registered to Torque.
379: * The key of the Map is the name of the database, and the value is the
380: * database instance. <br/>
381: * Note that in the very special case where a new database which
382: * is not configured in Torque's configuration gets known to Torque
383: * at a later time, the returned map may change, and there is no way to
384: * protect you against this. However, Databases should be initialized
385: * in the init() method, so this will not happen if Torque is used
386: * properly.
387: *
388: * @return a Map containing all Databases known to Torque, never null.
389: * @throws TorqueException if Torque is not yet initialized.
390: */
391: public static Map getDatabases() throws TorqueException {
392: return getInstance().getDatabases();
393: }
394: }
|