Torque


1   package org.apache.torque.avalon;
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.avalon.framework.component.Component;
26  import org.apache.torque.Database;
27  import org.apache.torque.TorqueException;
28  import org.apache.torque.adapter.DB;
29  import org.apache.torque.manager.AbstractBaseManager;
30  import org.apache.torque.map.DatabaseMap;
31  import org.apache.torque.map.MapBuilder;
32  
33  /**
34   * Avalon role interface for Torque.
35   *
36   * @author <a HREF="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
37   * @author <a HREF="mailto:tv@apache.org">Thomas Vandahl</a>
38   * @version $Id: Torque.java 493449 2007-01-06 11:46:50Z tv $
39   */
40  public interface Torque
41          extends Component
42  {
43      /**
44       * The avalon role.
45       */
46      String   ROLE = Torque.class.getName();
47  
48      /*
49       * ========================================================================
50       *
51       * Torque Methods, accessible from the Component
52       *
53       * ========================================================================
54       */
55  
56      /**
57       * Determine whether Torque has already been initialized.
58       *
59       * @return true if Torque is already initialized
60       */
61      boolean isInit();
62  
63      /**
64       * Get the configuration for this component.
65       *
66       * @return the Configuration
67       */
68      org.apache.commons.configuration.Configuration getConfiguration();
69  
70      /**
71       * This method returns a Manager for the given name.
72       *
73       * @param name name of the manager
74       * @return a Manager
75       */
76      AbstractBaseManager getManager(String   name);
77  
78      /**
79       * This methods returns either the Manager from the configuration file,
80       * or the default one provided by the generated code.
81       *
82       * @param name name of the manager
83       * @param defaultClassName the class to use if name has not been configured
84       * @return a Manager
85       */
86      AbstractBaseManager getManager(String   name, String   defaultClassName);
87  
88      /**
89       * Returns the default database map information.
90       *
91       * @return A DatabaseMap.
92       * @throws TorqueException Any exceptions caught during processing will be
93       *         rethrown wrapped into a TorqueException.
94       */
95      DatabaseMap getDatabaseMap() throws TorqueException;
96  
97      /**
98       * Returns the database map information. Name relates to the name
99       * of the connection pool to associate with the map.
100      *
101      * @param name The name of the database corresponding to the
102      *        <code>DatabaseMap</code> to retrieve.
103      * @return The named <code>DatabaseMap</code>.
104      * @throws TorqueException Any exceptions caught during processing will be
105      *         rethrown wrapped into a TorqueException.
106      */
107     DatabaseMap getDatabaseMap(String   name) throws TorqueException;
108 
109     /**
110      * Register a MapBuilder
111      *
112      * @param className the MapBuilder
113      */
114     void registerMapBuilder(String   className);
115 
116     /**
117      * Register a MapBuilder
118      *
119      * @param builder the instance of the MapBuilder
120      * 
121      */
122     void registerMapBuilder(MapBuilder builder);
123     
124     /**
125      * Get a MapBuilder
126      *
127      * @param className of the MapBuilder
128      * @return A MapBuilder, not null
129      * @throws TorqueException if the Map Builder cannot be instantiated
130      * 
131      */
132     MapBuilder getMapBuilder(String   className)
133         throws TorqueException;
134     
135     /**
136      * This method returns a Connection from the default pool.
137      *
138      * @return The requested connection.
139      * @throws TorqueException Any exceptions caught during processing will be
140      *         rethrown wrapped into a TorqueException.
141      */
142     Connection   getConnection() throws TorqueException;
143 
144     /**
145      *
146      * @param name The database name.
147      * @return a database connection
148      * @throws TorqueException Any exceptions caught during processing will be
149      *         rethrown wrapped into a TorqueException.
150      */
151     Connection   getConnection(String   name) throws TorqueException;
152 
153     /**
154      * This method returns a Connecton using the given parameters.
155      * You should only use this method if you need user based access to the
156      * database!
157      *
158      * @param name The database name.
159      * @param username The name of the database user.
160      * @param password The password of the database user.
161      * @return A Connection.
162      * @throws TorqueException Any exceptions caught during processing will be
163      *         rethrown wrapped into a TorqueException.
164      */
165     Connection   getConnection(String   name, String   username, String   password)
166             throws TorqueException;
167 
168     /**
169      * Returns database adapter for a specific connection pool.
170      *
171      * @param name A pool name.
172      * @return The corresponding database adapter.
173      * @throws TorqueException Any exceptions caught during processing will be
174      *         rethrown wrapped into a TorqueException.
175      */
176     DB getDB(String   name) throws TorqueException;
177 
178     /**
179      * Returns the name of the default database.
180      *
181      * @return name of the default DB
182      */
183     String   getDefaultDB();
184 
185     /**
186      * Closes a connection.
187      *
188      * @param con A Connection to close.
189      */
190     void closeConnection(Connection   con);
191 
192     /**
193      * Sets the current schema for a database connection
194      *
195      * @param name The database name.
196      * @param schema The current schema name
197      * @throws TorqueException Any exceptions caught during processing will be
198      *         rethrown wrapped into a TorqueException.
199      */
200     void setSchema(String   name, String   schema) throws TorqueException;
201 
202     /**
203      * This method returns the current schema for a database connection
204      *
205      * @param name The database name.
206      * @return The current schema name. Null means, no schema has been set.
207      * @throws TorqueException Any exceptions caught during processing will be
208      *         rethrown wrapped into a TorqueException.
209      */
210     String   getSchema(String   name) throws TorqueException;
211 
212     /**
213      * Returns the database for the key <code>databaseName</code>.
214      *
215      * @param databaseName the key to get the database for.
216      * @return the database for the specified key, or null if the database
217      *         does not exist.
218      * @throws TorqueException if Torque is not yet initialized.
219      */
220     Database getDatabase(String   databaseName) throws TorqueException;
221 
222     /**
223      * Returns a Map containing all Databases registered to Torque.
224      * The key of the Map is the name of the database, and the value is the
225      * database instance. <br/>
226      * Note that in the very special case where a new database which
227      * is not configured in Torque's configuration gets known to Torque
228      * at a later time, the returned map may change, and there is no way to
229      * protect you against this.
230      *
231      * @return a Map containing all Databases known to Torque, never null.
232      * @throws TorqueException if Torque is not yet initialized.
233      */
234     Map   getDatabases() throws TorqueException;
235 
236     /**
237      * Returns the database for the key <code>databaseName</code>.
238      * If no database is associated to the specified key,
239      * a new database is created, mapped to the specified key, and returned.
240      *
241      * @param databaseName the key to get the database for.
242      * @return the database associated with specified key, or the newly created
243      *         database, never null.
244      */
245     Database getOrCreateDatabase(String   databaseName);
246 }
247
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags