View Javadoc

1   package org.apache.turbine.services.db;
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.torque.Torque;
22  import org.apache.torque.adapter.DB;
23  import org.apache.torque.map.DatabaseMap;
24  import org.apache.turbine.util.TurbineException;
25  
26  /***
27   * This class provides a common front end to all database - related
28   * services in Turbine. This class contains static methods that you
29   * can call to access the methods of system's configured service
30   * implementations.
31   * <p>
32   * <b> This class is deprecated you should use org.apache.torque.Torque</b>
33   *
34   * Connection dbConn = null;
35   * try
36   * {
37   *     dbConn = Torque.getConnection();
38   *     // Do something with the connection here...
39   * }
40   * catch (Exception e)
41   * {
42   *     // Either from obtaining the connection or from your application code.
43   * }
44   * finally
45   * {
46   *     Torque.closeConnection(dbConn);
47   * }
48   * </pre></code></blockquote>
49   *
50   * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
51   * @version $Id: TurbineDB.java 264148 2005-08-29 14:21:04Z henning $
52   * @deprecated As of Turbine 2.2, use org.apache.torque.Torque
53   */
54  public abstract class TurbineDB
55  {
56      ///////////////////////////////////////////////////////////////////////////
57      // Database maps
58      ///////////////////////////////////////////////////////////////////////////
59  
60      /***
61       * Returns the map name for the default database.
62       *
63       * @return the map name for the default database.
64       */
65      public static String getDefaultMap()
66      {
67          // Required due to the nasty coupling between
68          // torque in 2.x and the db related services.
69          // This is only called once in the peer so the
70          // hit of catching the exception will only happen
71          // once and while running torque from the command
72          // line it won't incur an unbearable wait.
73          return Torque.getDefaultDB();
74      }
75  
76      /***
77       * Returns the default database map information.
78       *
79       * @return A DatabaseMap.
80       * @throws TurbineException Any exceptions caught during processing will be
81       *         rethrown wrapped into a TurbineException.
82       */
83      public static DatabaseMap getDatabaseMap() throws TurbineException
84      {
85          try
86          {
87              return Torque.getDatabaseMap();
88          }
89          catch (Exception ex)
90          {
91              throw new TurbineException(ex);
92          }
93      }
94  
95      /***
96       * Returns the database map information. Name relates to the name
97       * of the connection pool to associate with the map.
98       *
99       * @param name The name of the <code>DatabaseMap</code> to
100      * retrieve.
101      * @return The named <code>DatabaseMap</code>.
102      * @throws TurbineException Any exceptions caught during processing will be
103      *         rethrown wrapped into a TurbineException.
104      */
105     public static DatabaseMap getDatabaseMap(String name)
106             throws TurbineException
107     {
108         try
109         {
110             return Torque.getDatabaseMap(name);
111         }
112         catch (Exception ex)
113         {
114             throw new TurbineException(ex);
115         }
116     }
117 
118     ///////////////////////////////////////////////////////////////////////////
119     // Connection pooling
120     ///////////////////////////////////////////////////////////////////////////
121 
122     /***
123      * Returns the pool name for the default database.
124      *
125      * @return the pool name for the default database.
126      */
127     public static String getDefaultDB()
128     {
129         // Required due to the nasty coupling between
130         // torque in 2.x and the db related services.
131         // This is only called once in the peer so the
132         // hit of catching the exception will only happen
133         // once and while running torque from the command
134         // line it won't incur an unbearable wait.
135         return Torque.getDefaultDB();
136     }
137 
138     /***
139      * This method returns a DBConnection from the default pool.
140      *
141      * @return The requested connection.
142      * @throws Exception Any exceptions caught during processing will be
143      *         rethrown wrapped into a TurbineException.
144      */
145     public static Connection getConnection() throws Exception
146     {
147         return Torque.getConnection();
148     }
149 
150     /***
151      * This method returns a DBConnection from the pool with the
152      * specified name. The pool must be specified in the property file using
153      * the following syntax:
154      *
155      * <pre>
156      * database.[name].driver
157      * database.[name].url
158      * database.[name].username
159      * database.[name].password
160      * </pre>
161      *
162      * @param name The name of the pool to get a connection from.
163      * @return     The requested connection.
164      * @throws Exception Any exceptions caught during processing will be
165      *         rethrown wrapped into a TurbineException.
166      */
167     public static Connection getConnection(String name) throws Exception
168     {
169         return Torque.getConnection(name);
170     }
171 
172     /***
173      * Release a connection back to the database pool.
174      *
175      * @param dbconn the connection to release
176      * @throws Exception A generic exception.
177      */
178     public static void releaseConnection(Connection dbconn) throws Exception
179     {
180         Torque.closeConnection(dbconn);
181     }
182 
183     ///////////////////////////////////////////////////////////////////////////
184     // DB Adapters
185     ///////////////////////////////////////////////////////////////////////////
186 
187     /***
188      * Returns the database adapter for the default connection pool.
189      *
190      * @return The database adapter.
191      * @throws Exception Any exceptions caught during processing will be
192      *         rethrown wrapped into a TurbineException.
193      */
194     public static DB getDB() throws Exception
195     {
196         return Torque.getDB(Torque.getDefaultDB());
197     }
198 
199     /***
200      * Returns database adapter for a specific connection pool.
201      *
202      * @param name A pool name.
203      * @return     The corresponding database adapter.
204      * @throws Exception Any exceptions caught during processing will be
205      *         rethrown wrapped into a TurbineException.
206      */
207     public static DB getDB(String name) throws Exception
208     {
209         return Torque.getDB(name);
210     }
211 }