Torque


1   package org.apache.torque;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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 }
428
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags