View Javadoc

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  
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 }