View Javadoc

1   package org.apache.torque;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.sql.Connection;
20  
21  import org.apache.commons.configuration.Configuration;
22  
23  import org.apache.torque.adapter.DB;
24  import org.apache.torque.manager.AbstractBaseManager;
25  import org.apache.torque.map.DatabaseMap;
26  
27  /***
28   * A static facade wrapper around the Torque implementation (which is in
29   * {@link org.apache.torque.TorqueInstance}).
30   * <br/>
31   *
32   * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
33   * @author <a href="mailto:magnus@handtolvur.is">Magn?s ??r Torfason</a>
34   * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
35   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
36   * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
37   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
38   * @author <a href="mailto:kschrader@karmalab.org">Kurt Schrader</a>
39   * @version $Id: Torque.java 239636 2005-08-24 12:38:09Z henning $
40   */
41  public abstract class Torque
42  {
43      /***
44       * The prefix for all configuration keys used by Torque
45       */
46      public static final String TORQUE_KEY = "torque";
47  
48      /***
49       * the prefix for configuring the database adapters and the default database
50       */
51      public static final String DATABASE_KEY = "database";
52  
53      /***
54       * The key used to configure the name of the default database
55       */
56      public static final String DEFAULT_KEY = "default";
57  
58      /***
59       * Name of property that specifies the default map builder and map.
60       * @deprecated is not used any more. Use DATABASE_KEY and
61       *             DEFAULT_KEY instead
62       */
63      public static final String DATABASE_DEFAULT
64              = DATABASE_KEY + "." + DEFAULT_KEY;
65  
66      /***
67       * A prefix for <code>Manager</code> properties in the configuration.
68       */
69      public static final String MANAGER_PREFIX = "managed_class.";
70  
71      /***
72       * A <code>Service</code> property determining its implementing
73       * class name .
74       */
75      public static final String MANAGER_SUFFIX = ".manager";
76  
77      /***
78       * property to determine whether caching is used.
79       */
80      public static final String CACHE_KEY = "manager.useCache";
81  
82      /***
83       * The single instance of {@link TorqueInstance} used by the
84       * static API presented by this class.
85       */
86      private static TorqueInstance torqueSingleton = null;
87  
88      /***
89       * C'tor for usage with the Stratum Lifecycle.
90       *
91       * @todo Should be made private or protected once Stratum is removed.
92       */
93      public Torque()
94      {
95      }
96  
97      /***
98       * Retrieves the single {@link org.apache.torque.TorqueInstance}
99       * used by this class.
100      *
101      * @return Our singleton.
102      */
103     public static TorqueInstance getInstance()
104     {
105         if (torqueSingleton == null)
106         {
107             torqueSingleton = new TorqueInstance();
108         }
109         return torqueSingleton;
110     }
111 
112     /***
113      * Initialization of Torque with a properties file.
114      *
115      * @param configFile The absolute path to the configuration file.
116      * @throws TorqueException Any exceptions caught during processing will be
117      *         rethrown wrapped into a TorqueException.
118      */
119     public static void init(String configFile)
120         throws TorqueException
121     {
122         getInstance().init(configFile);
123     }
124 
125     /***
126      * Initialization of Torque with a properties file.
127      *
128      * @param conf The Torque configuration.
129      * @throws TorqueException Any exceptions caught during processing will be
130      *         rethrown wrapped into a TorqueException.
131      */
132     public static void init(Configuration conf)
133         throws TorqueException
134     {
135         getInstance().init(conf);
136     }
137 
138     /***
139      * Determine whether Torque has already been initialized.
140      *
141      * @return true if Torque is already initialized
142      */
143     public static boolean isInit()
144     {
145         return getInstance().isInit();
146     }
147 
148     /***
149      * Sets the configuration for Torque and all dependencies.
150      *
151      * @param conf the Configuration
152      */
153     public static void setConfiguration(Configuration conf)
154     {
155         getInstance().setConfiguration(conf);
156     }
157 
158     /***
159      * Get the configuration for this component.
160      *
161      * @return the Configuration
162      */
163     public static Configuration getConfiguration()
164     {
165         return getInstance().getConfiguration();
166     }
167 
168     /***
169      * This method returns a Manager for the given name.
170      *
171      * @param name name of the manager
172      * @return a Manager
173      */
174     public static AbstractBaseManager getManager(String name)
175     {
176         return getInstance().getManager(name);
177     }
178 
179     /***
180      * This methods returns either the Manager from the configuration file,
181      * or the default one provided by the generated code.
182      *
183      * @param name name of the manager
184      * @param defaultClassName the class to use if name has not been configured
185      * @return a Manager
186      */
187     public static AbstractBaseManager getManager(String name,
188             String defaultClassName)
189     {
190         return getInstance().getManager(name, defaultClassName);
191     }
192 
193     /***
194      * Shuts down the service.
195      *
196      * This method halts the IDBroker's daemon thread in all of
197      * the DatabaseMap's. It also closes all SharedPoolDataSourceFactories
198      * and PerUserPoolDataSourceFactories initialized by Torque.
199      * @exception TorqueException if a DataSourceFactory could not be closed
200      *            cleanly. Only the first exception is rethrown, any following
201      *            exceptions are logged but ignored.
202      */
203     public static void shutdown()
204         throws TorqueException
205     {
206         getInstance().shutdown();
207     }
208 
209     /***
210      * Returns the default database map information.
211      *
212      * @return A DatabaseMap.
213      * @throws TorqueException Any exceptions caught during processing will be
214      *         rethrown wrapped into a TorqueException.
215      */
216     public static DatabaseMap getDatabaseMap()
217         throws TorqueException
218     {
219         return getInstance().getDatabaseMap();
220     }
221 
222     /***
223      * Returns the database map information. Name relates to the name
224      * of the connection pool to associate with the map.
225      *
226      * @param name The name of the database corresponding to the
227      *        <code>DatabaseMap</code> to retrieve.
228      * @return The named <code>DatabaseMap</code>.
229      * @throws TorqueException Any exceptions caught during processing will be
230      *         rethrown wrapped into a TorqueException.
231      */
232     public static DatabaseMap getDatabaseMap(String name)
233         throws TorqueException
234     {
235         return getInstance().getDatabaseMap(name);
236     }
237 
238     /***
239      * Register a MapBuilder
240      *
241      * @param className the MapBuilder
242      */
243     public static void registerMapBuilder(String className)
244     {
245         getInstance().registerMapBuilder(className);
246     }
247 
248     /***
249      * This method returns a Connection from the default pool.
250      *
251      * @return The requested connection.
252      * @throws TorqueException Any exceptions caught during processing will be
253      *         rethrown wrapped into a TorqueException.
254      */
255     public static Connection getConnection()
256         throws TorqueException
257     {
258         return getInstance().getConnection();
259     }
260 
261     /***
262      * This method returns a Connecton using the given database name.
263      *
264      * @param name The database name.
265      * @return a database connection
266      * @throws TorqueException Any exceptions caught during processing will be
267      *         rethrown wrapped into a TorqueException.
268      */
269     public static Connection getConnection(String name)
270         throws TorqueException
271     {
272         return getInstance().getConnection(name);
273     }
274 
275     /***
276      * This method returns a Connecton using the given parameters.
277      * You should only use this method if you need user based access to the
278      * database!
279      *
280      * @param name The database name.
281      * @param username The name of the database user.
282      * @param password The password of the database user.
283      * @return A 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, String username,
288             String password)
289             throws TorqueException
290     {
291         return getInstance().getConnection(name, username, password);
292     }
293     /***
294      * Returns database adapter for a specific connection pool.
295      *
296      * @param name A pool name.
297      * @return The corresponding database adapter.
298      * @throws TorqueException Any exceptions caught during processing will be
299      *         rethrown wrapped into a TorqueException.
300      */
301     public static DB getDB(String name) throws TorqueException
302     {
303         return getInstance().getDB(name);
304     }
305 
306     /***
307      * Returns the name of the default database.
308      *
309      * @return name of the default DB, or null if Torque is not initialized yet
310      */
311     public static String getDefaultDB()
312     {
313         return getInstance().getDefaultDB();
314     }
315 
316     /***
317      * Closes a connection.
318      *
319      * @param con A Connection to close.
320      */
321     public static void closeConnection(Connection con)
322     {
323         getInstance().closeConnection(con);
324     }
325 
326     /***
327      * Sets the current schema for a database connection
328      *
329      * @param name The database name.
330      * @param schema The current schema name
331      * @throws TorqueException Any exceptions caught during processing will be
332      *         rethrown wrapped into a TorqueException.
333      */
334     public static void setSchema(String name, String schema)
335             throws TorqueException
336     {
337         getInstance().setSchema(name, schema);
338     }
339 
340     /***
341      * This method returns the current schema for a database connection
342      *
343      * @param name The database name.
344      * @return The current schema name. Null means, no schema has been set.
345      * @throws TorqueException Any exceptions caught during processing will be
346      *         rethrown wrapped into a TorqueException.
347      */
348     public static String getSchema(String name)
349         throws TorqueException
350     {
351         return getInstance().getSchema(name);
352     }
353 }